Merge pull request #274900 from mumian/0509-function-objectkeys

ARM/Bicep function objectKeys

Author: denrea

articles/azure-resource-manager/bicep/bicep-functions-object.md

@@ -3,7 +3,7 @@ title: Bicep functions - objects
 description: Describes the functions to use in a Bicep file for working with objects.
 ms.topic: conceptual
 ms.custom: devx-track-bicep
-ms.date: 01/11/2024
+ms.date: 05/21/2024
 ---
 
 # Object functions for Bicep
@@ -31,7 +31,7 @@ Namespace: [sys](bicep-functions.md#namespaces-for-functions).
 
 ### Example
 
-The following example shows how to use contains with different types:
+The following example shows how to use `contains` with different types:
 
 ```bicep
 param stringToTest string = 'OneTwoThree'
@@ -119,15 +119,15 @@ Namespace: [sys](bicep-functions.md#namespaces-for-functions).
 |:--- |:--- |:--- |:--- |
 | arg1 |Yes |array or object |The first value to use for finding common elements. |
 | arg2 |Yes |array or object |The second value to use for finding common elements. |
-| additional arguments |No |array or object |Additional values to use for finding common elements. |
+| additional arguments |No |array or object |More values to use for finding common elements. |
 
 ### Return value
 
 An array or object with the common elements.
 
 ### Example
 
-The following example shows how to use intersection with arrays and objects:
+The following example shows how to use `intersection` with arrays and objects:
 
 ```bicep
 param firstObject object = {
@@ -301,7 +301,7 @@ If you need to include a parameter value or variable in the JSON object, use the
 
 ### Example
 
-The following example shows how to use the json function. Notice that you can pass in **null** for an empty object.
+The following example shows how to use the `json` function. Notice that you can pass in **null** for an empty object.
 
 ```bicep
 param jsonEmptyObject string = 'null'
@@ -353,7 +353,7 @@ An int.
 
 ### Example
 
-The following example shows how to use length with an array and string:
+The following example shows how to use `length` with an array and string:
 
 ```bicep
 param arrayToTest array = [
@@ -385,11 +385,49 @@ The output from the preceding example with the default values is:
 | stringLength | Int | 13 |
 | objectLength | Int | 4 |
 
+## objectKeys
+
+`objectKeys(object)`
+
+Returns the keys from an object, where an object is a collection of key-value pairs.
+
+Namespace: [sys](bicep-functions.md#namespaces-for-functions).
+
+### Parameters
+
+| Parameter | Required | Type | Description |
+|:--- |:--- |:--- |:--- |
+| object |Yes |object |The object, which is a collection of key-value pairs. |
+
+### Return value
+
+An array.
+
+### Example
+
+The following example shows how to use `objectKeys` with an object:
+
+```bicep
+var obj = { a: 1, b: 2 }
+
+output keyArray array = objectKeys(obj)
+```
+
+The output from the preceding example is:
+
+| Name | Type | Value |
+| ---- | ---- | ----- |
+| keyArray | Array | [ "a", "b" ] |
+
+**keyArray** returns a list of keys of the input object.
+
+[!INCLUDE [JSON object ordering](../../../includes/resource-manager-object-ordering-bicep.md)]
+
 ## shallowMerge
 
 `shallowMerge(inputArray)`
 
-Combines an array of objects, where only the top-level objects are merged. This means that if the objects being merged contain nested objects, those nested object aren't deeply merged; instead, they're replaced entirely by the corresponding property from the merging object.
+Combines an array of objects, where only the top-level objects are merged. This means that if the objects being merged contain nested objects, those nested object aren't deeply merged. Instead, they're replaced entirely by the corresponding property from the merging object.
 
 Namespace: [sys](bicep-functions.md#namespaces-for-functions).
 
@@ -422,7 +460,7 @@ The output from the preceding example with the default values is:
 | firstOutput | object | {"one":"a","two":"c"}|
 | secondOutput | object | {"one":"a","nested":{"b":2},"two":"b"} |
 
-**firstOutput** shows the properties from the merging objects are combined into a new object. If there are conflicting properties (i.e., properties with the same name), the property from the last object being merged usually takes precedence.
+**firstOutput** shows the properties from the merging objects are combined into a new object. If there are conflicting properties (that is, properties with the same name), the property from the last object being merged usually takes precedence.
 
 **secondOutput** shows the shallow merge doesn't recursively merge these nested objects. Instead, the entire nested object is replaced by the corresponding property from the merging object.
 
@@ -440,7 +478,7 @@ Namespace: [sys](bicep-functions.md#namespaces-for-functions).
 |:--- |:--- |:--- |:--- |
 | arg1 |Yes |array or object |The first value to use for joining elements. |
 | arg2 |Yes |array or object |The second value to use for joining elements. |
-| additional arguments |No |array or object |Additional values to use for joining elements. |
+| additional arguments |No |array or object |More values to use for joining elements. |
 
 ### Return value
 
@@ -450,15 +488,15 @@ An array or object.
 
 The union function uses the sequence of the parameters to determine the order and values of the result.
 
-For arrays, the function iterates through each element in the first parameter and adds it to the result if it isn't already present. Then, it repeats the process for the second parameter and any additional parameters. If a value is already present, it's earlier placement in the array is preserved.
+For arrays, the function iterates through each element in the first parameter and adds it to the result if it isn't already present. Then, it repeats the process for the second parameter and any other parameters. If a value is already present, it's earlier placement in the array is preserved.
 
 For objects, property names and values from the first parameter are added to the result. For later parameters, any new names are added to the result. If a later parameter has a property with the same name, that value overwrites the existing value. The order of the properties isn't guaranteed.
 
 The union function merges not only the top-level elements but also recursively merges any nested objects within them. Nested array values aren't merged. See the second example in the following section.
 
 ### Example
 
-The following example shows how to use union with arrays and objects:
+The following example shows how to use `union` with arrays and objects:
 
 ```bicep
 param firstObject object = {

articles/azure-resource-manager/bicep/bicep-functions.md

@@ -3,7 +3,7 @@ title: Bicep functions
 description: Describes the functions to use in a Bicep file to retrieve values, work with strings and numerics, and retrieve deployment information.
 ms.topic: conceptual
 ms.custom: devx-track-bicep
-ms.date: 05/10/2024
+ms.date: 05/21/2024
 ---
 
 # Bicep functions
@@ -121,6 +121,7 @@ The following functions are available for working with objects. All of these fun
 * [items](./bicep-functions-object.md#items)
 * [json](./bicep-functions-object.md#json)
 * [length](./bicep-functions-object.md#length)
+* [objectKeys](./bicep-functions-object.md#objectkeys)
 * [shallowMerge](./bicep-functions-object.md#shallowmerge)
 * [union](./bicep-functions-object.md#union)
 

articles/azure-resource-manager/templates/template-functions-object.md

@@ -3,7 +3,7 @@ title: Template functions - objects
 description: Describes the functions to use in an Azure Resource Manager template (ARM template) for working with objects.
 ms.topic: conceptual
 ms.custom: devx-track-arm-template
-ms.date: 01/11/2024
+ms.date: 05/21/2024
 ---
 
 # Object functions for ARM templates
@@ -44,7 +44,7 @@ In Bicep, use the [contains](../bicep/bicep-functions-object.md#contains) functi
 
 ### Example
 
-The following example shows how to use contains with different types:
+The following example shows how to use `contains` with different types:
 
 :::code language="json" source="~/resourcemanager-templates/azure-resource-manager/functions/array/contains.json":::
 
@@ -154,7 +154,7 @@ An array or object with the common elements.
 
 ### Example
 
-The following example shows how to use intersection with arrays and objects.
+The following example shows how to use `intersection` with arrays and objects.
 
 :::code language="json" source="~/resourcemanager-templates/azure-resource-manager/functions/array/intersection.json":::
 
@@ -369,7 +369,7 @@ An int.
 
 ### Example
 
-The following example shows how to use length with an array and string:
+The following example shows how to use `length` with an array and string:
 
 :::code language="json" source="~/resourcemanager-templates/azure-resource-manager/functions/array/length.json":::
 
@@ -409,6 +409,56 @@ The output from the preceding example is:
 | ---- | ---- | ----- |
 | emptyOutput | Bool | True |
 
+## objectKeys
+
+`objectKeys(object)`
+
+Returns the keys from an object, where an object is a collection of key-value pairs.
+
+In Bicep, use the [objectKeys](../templates/template-functions-object.md#objectkeys) function.
+
+### Parameters
+
+| Parameter | Required | Type | Description |
+|:--- |:--- |:--- |:--- |
+| object |Yes |object |The object, which is a collection of key-value pairs. |
+
+### Return value
+
+An array.
+
+### Example
+
+The following example shows how to use `objectKeys` with an object:
+
+```json
+{
+  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
+  "contentVersion": "1.0.0.0",
+  "variables": {
+    "obj": {
+      "a": 1,
+      "b": 2
+    }
+  },
+  "resources": [],
+  "outputs": {
+    "keyArray": {
+      "type": "array",
+      "value": "[objectKeys(variables('obj'))]"
+    }
+  }
+}
+```
+
+The output from the preceding example is:
+
+| Name | Type | Value |
+| ---- | ---- | ----- |
+| keyArray | Array | [ "a", "b" ] |
+
+[!INCLUDE [JSON object ordering](../../../includes/resource-manager-object-ordering-arm-template.md)]
+
 ## shallowMerge
 
 `shallowMerge(inputArray)`
@@ -522,7 +572,7 @@ The union function merges not only the top-level elements but also recursively m
 
 ### Example
 
-The following example shows how to use union with arrays and objects:
+The following example shows how to use `union` with arrays and objects:
 
 :::code language="json" source="~/resourcemanager-templates/azure-resource-manager/functions/array/union.json":::
 

articles/azure-resource-manager/templates/template-functions.md

@@ -220,6 +220,7 @@ Resource Manager provides several functions for working with objects.
 * [items](template-functions-object.md#items)
 * [json](template-functions-object.md#json)
 * [length](template-functions-object.md#length)
+* [objectKeys](template-functions-object.md#objectkeys)
 * [null](template-functions-object.md#null)
 * [shallowMerge](template-functions-object.md#shallowmerge)
 * [union](template-functions-object.md#union)