Skip to content

Commit b74c35d

Browse files
prmerger-automator[bot]prmerger-automator[bot]
authored
Merge pull request #247162 from mumian/0731-references
template function references()
2 parents 0c8bcb4 + 9ca89ef commit b74c35d

File tree

2 files changed

+352
-6
lines changed

2 files changed

+352
-6
lines changed

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

Lines changed: 350 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
title: Template functions - resources
33
description: Describes the functions to use in an Azure Resource Manager template (ARM template) to retrieve values about resources.
44
ms.topic: conceptual
5-
ms.date: 05/22/2023
5+
ms.date: 08/02/2023
66
ms.custom: ignite-2022, devx-track-arm-template
77
---
88

@@ -15,6 +15,7 @@ Resource Manager provides the following functions for getting resource values in
1515
* [pickZones](#pickzones)
1616
* [providers (deprecated)](#providers)
1717
* [reference](#reference)
18+
* [references](#references)
1819
* [resourceId](#resourceid)
1920
* [subscriptionResourceId](#subscriptionresourceid)
2021
* [managementGroupResourceId](#managementgroupresourceid)
@@ -221,10 +222,10 @@ The possible uses of `list*` are shown in the following table.
221222
| Microsoft.Relay/namespaces/WcfRelays/authorizationRules | [listkeys](/rest/api/relay/wcfrelays/listkeys) |
222223
| Microsoft.Search/searchServices | [listAdminKeys](/rest/api/searchmanagement/2021-04-01-preview/admin-keys/get) |
223224
| Microsoft.Search/searchServices | [listQueryKeys](/rest/api/searchmanagement/2021-04-01-preview/query-keys/list-by-search-service) |
224-
| Microsoft.ServiceBus/namespaces/authorizationRules | [listKeys](/rest/api/servicebus/stable/namespaces-authorization-rules/list-keys) |
225-
| Microsoft.ServiceBus/namespaces/disasterRecoveryConfigs/authorizationRules | [listKeys](/rest/api/servicebus/stable/disasterrecoveryconfigs/listkeys) |
226-
| Microsoft.ServiceBus/namespaces/queues/authorizationRules | [listKeys](/rest/api/servicebus/stable/queues-authorization-rules/list-keys) |
227-
| Microsoft.ServiceBus/namespaces/topics/authorizationRules | [listKeys](/rest/api/servicebus/stable/topics%20%E2%80%93%20authorization%20rules/list-keys) |
225+
| Microsoft.ServiceBus/namespaces/authorizationRules | [listKeys](/rest/api/servicebus/controlplane-stable/namespaces-authorization-rules/list-keys) |
226+
| Microsoft.ServiceBus/namespaces/disasterRecoveryConfigs/authorizationRules | [listKeys](/rest/api/servicebus/controlplane-stable/disaster-recovery-configs/list-keys) |
227+
| Microsoft.ServiceBus/namespaces/queues/authorizationRules | [listKeys](/rest/api/servicebus/controlplane-stable/queues-authorization-rules/list-keys) |
228+
| Microsoft.ServiceBus/namespaces/topics/authorizationRules | [listKeys](/rest/api/servicebus/controlplane-stable/topics%20–%20authorization%20rules/list-keys) |
228229
| Microsoft.SignalRService/SignalR | [listKeys](/rest/api/signalr/signalr/listkeys) |
229230
| Microsoft.Storage/storageAccounts | [listAccountSas](/rest/api/storagerp/storageaccounts/listaccountsas) |
230231
| Microsoft.Storage/storageAccounts | [listKeys](/rest/api/storagerp/storageaccounts/listkeys) |
@@ -604,6 +605,350 @@ The following example template references a storage account that isn't deployed
604605

605606
:::code language="json" source="~/resourcemanager-templates/azure-resource-manager/functions/resource/reference.json":::
606607

608+
## references
609+
610+
`references(symbolic name of a resource collection, ['Full', 'Properties])`
611+
612+
The `references` function works similarly as [`reference`](#reference). Instead of returning an object presenting a resource's runtime state, the `references` function returns an array of objects representing a collection of resource's runtime states. This function requires ARM template language version `1.10-experimental` and with [symbolic name](../bicep/file.md#resources) enabled:
613+
614+
```json
615+
{
616+
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
617+
"languageVersion": "1.10-experimental",
618+
"contentVersion": "1.0.0.0",
619+
...
620+
}
621+
```
622+
623+
In Bicep, there is no explicit `references` function. Instead, symbolic collection usage is employed directly, and during code generation, Bicep translates it to an ARM template that utilizes the ARM template `references` function. The forthcoming release of Bicep will include the translation feature that converts symbolic collections to ARM templates using the `references` function.
624+
625+
### Parameters
626+
627+
| Parameter | Required | Type | Description |
628+
|:--- |:--- |:--- |:--- |
629+
| Symbolic name of a resource collection |Yes |string |Symbolic name of a resource collection that is defined in the current template. The `references` function does not support referencing resources external to the current template. |
630+
| 'Full', 'Properties' |No |string |Value that specifies whether to return an array of the full resource objects. The default value is `'Properties'`. If you don't specify `'Full'`, only the properties objects of the resources are returned. The full object includes values such as the resource ID and location. |
631+
632+
### Return value
633+
634+
An array of the resource collection. Every resource type returns different properties for the `reference` function. Also, the returned value differs based on the value of the `'Full'` argument. For more information, see [reference](#reference).
635+
636+
The output order of `references` is always arranged in ascending order based on the copy index. Therefore, the first resource in the collection with index 0 is displayed first, followed by index 1, and so on. For instance, *[worker-0, worker-1, worker-2, ...]*.
637+
638+
In the preceding example, if *worker-0* and *worker-2* are deployed while *worker-1* is not due to a false condition, the output of `references` will omit the non-deployed resource and display the deployed ones, ordered by their numbers. The output of `references` will be *[worker-0, worker-2, ...]*. If all of the resources are omitted, the function returns an empty array.
639+
640+
### Valid uses
641+
642+
The `references` function can't be used within [resource copy loops](./copy-resources.md) or [Bicep for loop](../bicep/loops.md). For example, `references` is not allowed in the following scenario:
643+
644+
```json
645+
{
646+
resources: {
647+
"resourceCollection": {
648+
"copy": { ... },
649+
"properties": {
650+
"prop": "[references(...)]"
651+
}
652+
}
653+
}
654+
}
655+
```
656+
657+
To use the `references` function or any `list*` function in the outputs section of a nested template, you must set the `expressionEvaluationOptions` to use [inner scope](linked-templates.md#expression-evaluation-scope-in-nested-templates) evaluation or use a linked instead of a nested template.
658+
659+
### Implicit dependency
660+
661+
By using the `references` function, you implicitly declare that one resource depends on another resource. You don't need to also use the `dependsOn` property. The function isn't evaluated until the referenced resource has completed deployment.
662+
663+
### Reference example
664+
665+
The following example deploys a resource collection, and references that resource collection.
666+
667+
```json
668+
{
669+
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
670+
"languageVersion": "1.10-experimental",
671+
"contentVersion": "1.0.0.0",
672+
"parameters": {
673+
"location": {
674+
"type": "string",
675+
"defaultValue": "[resourceGroup().location]",
676+
"metadata": {
677+
"description": "Location for all resources."
678+
}
679+
},
680+
"numWorkers": {
681+
"type": "int",
682+
"defaultValue": 4,
683+
"metadata": {
684+
"description": "The number of workers"
685+
}
686+
}
687+
},
688+
"resources": {
689+
"containerWorkers": {
690+
"copy": {
691+
"name": "containerWorkers",
692+
"count": "[length(range(0, parameters('numWorkers')))]"
693+
},
694+
"type": "Microsoft.ContainerInstance/containerGroups",
695+
"apiVersion": "2022-09-01",
696+
"name": "[format('worker-{0}', range(0, parameters('numWorkers'))[copyIndex()])]",
697+
"location": "[parameters('location')]",
698+
"properties": {
699+
"containers": [
700+
{
701+
"name": "[format('worker-container-{0}', range(0, parameters('numWorkers'))[copyIndex()])]",
702+
"properties": {
703+
"image": "mcr.microsoft.com/azuredocs/aci-helloworld",
704+
"ports": [
705+
{
706+
"port": 80,
707+
"protocol": "TCP"
708+
}
709+
],
710+
"resources": {
711+
"requests": {
712+
"cpu": 1,
713+
"memoryInGB": 2
714+
}
715+
}
716+
}
717+
}
718+
],
719+
"osType": "Linux",
720+
"restartPolicy": "Always",
721+
"ipAddress": {
722+
"type": "Public",
723+
"ports": [
724+
{
725+
"port": 80,
726+
"protocol": "TCP"
727+
}
728+
]
729+
}
730+
}
731+
},
732+
"containerController": {
733+
"type": "Microsoft.ContainerInstance/containerGroups",
734+
"apiVersion": "2022-09-01",
735+
"name": "controller",
736+
"location": "[parameters('location')]",
737+
"properties": {
738+
"containers": [
739+
{
740+
"name": "controller-container",
741+
"properties": {
742+
"command": [
743+
"echo",
744+
"[format('Worker IPs are {0}', join(map(references('containerWorkers', 'full'), lambda('w', lambdaVariables('w').properties.ipAddress.ip)), ','))]"
745+
],
746+
"image": "mcr.microsoft.com/azuredocs/aci-helloworld",
747+
"ports": [
748+
{
749+
"port": 80,
750+
"protocol": "TCP"
751+
}
752+
],
753+
"resources": {
754+
"requests": {
755+
"cpu": 1,
756+
"memoryInGB": 2
757+
}
758+
}
759+
}
760+
}
761+
],
762+
"osType": "Linux",
763+
"restartPolicy": "Always",
764+
"ipAddress": {
765+
"type": "Public",
766+
"ports": [
767+
{
768+
"port": 80,
769+
"protocol": "TCP"
770+
}
771+
]
772+
}
773+
},
774+
"dependsOn": [
775+
"containerWorkers"
776+
]
777+
}
778+
},
779+
"outputs": {
780+
"workerIpAddresses": {
781+
"type": "string",
782+
"value": "[join(map(references('containerWorkers', 'full'), lambda('w', lambdaVariables('w').properties.ipAddress.ip)), ',')]"
783+
},
784+
"containersFull": {
785+
"type": "array",
786+
"value": "[references('containerWorkers', 'full')]"
787+
},
788+
"container": {
789+
"type": "array",
790+
"value": "[references('containerWorkers')]"
791+
}
792+
}
793+
}
794+
```
795+
796+
The preceding example returns the three objects.
797+
798+
```json
799+
"outputs": {
800+
"workerIpAddresses": {
801+
"type": "String",
802+
"value": "20.66.74.26,20.245.100.10,13.91.86.58,40.83.249.30"
803+
},
804+
"containersFull": {
805+
"type": "Array",
806+
"value": [
807+
{
808+
"apiVersion": "2022-09-01",
809+
"condition": true,
810+
"copyContext": {
811+
"copyIndex": 0,
812+
"copyIndexes": {
813+
"": 0,
814+
"containerWorkers": 0
815+
},
816+
"name": "containerWorkers"
817+
},
818+
"copyLoopSymbolicName": "containerWorkers",
819+
"deploymentResourceLineInfo": {
820+
"lineNumber": 30,
821+
"linePosition": 25
822+
},
823+
"existing": false,
824+
"isAction": false,
825+
"isConditionTrue": true,
826+
"isTemplateResource": true,
827+
"location": "westus",
828+
"properties": {
829+
"containers": [
830+
{
831+
"name": "worker-container-0",
832+
"properties": {
833+
"environmentVariables": [],
834+
"image": "mcr.microsoft.com/azuredocs/aci-helloworld",
835+
"instanceView": {
836+
"currentState": {
837+
"detailStatus": "",
838+
"startTime": "2023-07-31T19:25:31.996Z",
839+
"state": "Running"
840+
},
841+
"restartCount": 0
842+
},
843+
"ports": [
844+
{
845+
"port": 80,
846+
"protocol": "TCP"
847+
}
848+
],
849+
"resources": {
850+
"requests": {
851+
"cpu": 1.0,
852+
"memoryInGB": 2.0
853+
}
854+
}
855+
}
856+
}
857+
],
858+
"initContainers": [],
859+
"instanceView": {
860+
"events": [],
861+
"state": "Running"
862+
},
863+
"ipAddress": {
864+
"ip": "20.66.74.26",
865+
"ports": [
866+
{
867+
"port": 80,
868+
"protocol": "TCP"
869+
}
870+
],
871+
"type": "Public"
872+
},
873+
"isCustomProvisioningTimeout": false,
874+
"osType": "Linux",
875+
"provisioningState": "Succeeded",
876+
"provisioningTimeoutInSeconds": 1800,
877+
"restartPolicy": "Always",
878+
"sku": "Standard"
879+
},
880+
"provisioningOperation": "Create",
881+
"references": [],
882+
"resourceGroupName": "demoRg",
883+
"resourceId": "Microsoft.ContainerInstance/containerGroups/worker-0",
884+
"scope": "",
885+
"subscriptionId": "",
886+
"symbolicName": "containerWorkers[0]"
887+
},
888+
...
889+
]
890+
},
891+
"containers": {
892+
"type": "Array",
893+
"value": [
894+
{
895+
"containers": [
896+
{
897+
"name": "worker-container-0",
898+
"properties": {
899+
"environmentVariables": [],
900+
"image": "mcr.microsoft.com/azuredocs/aci-helloworld",
901+
"instanceView": {
902+
"currentState": {
903+
"detailStatus": "",
904+
"startTime": "2023-07-31T19:25:31.996Z",
905+
"state": "Running"
906+
},
907+
"restartCount": 0
908+
},
909+
"ports": [
910+
{
911+
"port": 80,
912+
"protocol": "TCP"
913+
}
914+
],
915+
"resources": {
916+
"requests": {
917+
"cpu": 1.0,
918+
"memoryInGB": 2.0
919+
}
920+
}
921+
}
922+
}
923+
],
924+
"initContainers": [],
925+
"instanceView": {
926+
"events": [],
927+
"state": "Running"
928+
},
929+
"ipAddress": {
930+
"ip": "20.66.74.26",
931+
"ports": [
932+
{
933+
"port": 80,
934+
"protocol": "TCP"
935+
}
936+
],
937+
"type": "Public"
938+
},
939+
"isCustomProvisioningTimeout": false,
940+
"osType": "Linux",
941+
"provisioningState": "Succeeded",
942+
"provisioningTimeoutInSeconds": 1800,
943+
"restartPolicy": "Always",
944+
"sku": "Standard"
945+
},
946+
...
947+
]
948+
}
949+
}
950+
```
951+
607952
## resourceGroup
608953

609954
See the [resourceGroup scope function](template-functions-scope.md#resourcegroup).

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

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ title: Template functions
33
description: Describes the functions to use in an Azure Resource Manager template (ARM template) to retrieve values, work with strings and numerics, and retrieve deployment information.
44
ms.topic: conceptual
55
ms.custom: devx-track-arm-template
6-
ms.date: 05/12/2023
6+
ms.date: 08/03/2023
77
---
88

99
# ARM template functions
@@ -202,6 +202,7 @@ Resource Manager provides the following functions for getting resource values:
202202
* [pickZones](template-functions-resource.md#pickzones)
203203
* [providers (deprecated)](template-functions-resource.md#providers)
204204
* [reference](template-functions-resource.md#reference)
205+
* [references](template-functions-resource.md#references)
205206
* [resourceId](template-functions-resource.md#resourceid) - can be used at any scope, but the valid parameters change depending on the scope.
206207
* [subscriptionResourceId](template-functions-resource.md#subscriptionresourceid)
207208
* [tenantResourceId](template-functions-resource.md#tenantresourceid)

0 commit comments

Comments
 (0)