Resursfunktioner för ARM-mallar

Resource Manager innehåller följande funktioner för att hämta resursvärden i din Azure Resource Manager-mall (ARM-mall):

• extensionResourceId
• lista*
• pickZones
• leverantörer (inaktuella)
• hänvisning
• referenser
• resourceId
• subscriptionResourceId
• managementGroupResourceId
• tenantResourceId

Information om hur du hämtar värden från parametrar, variabler eller den aktuella distributionen finns i funktioner för distributionsvärde.

Information om hur du hämtar omfångsvärden för distribution finns i omfångsfunktioner.

extensionResourceId

extensionResourceId(baseResourceId, resourceType, resourceName1, [resourceName2], ...)

Returnerar resurs-ID för en tilläggsresurs. En tilläggsresurs är en resurstyp som tillämpas på en annan resurs för att lägga till dess funktioner.

Använd funktionen i extensionResourceId Bicep.

Parametrar

Fortsätt att lägga till resursnamn som parametrar när resurstypen innehåller fler segment.

Returvärde

Det grundläggande formatet för resurs-ID:t som returneras av den här funktionen är:

{scope}/providers/{extensionResourceProviderNamespace}/{extensionResourceType}/{extensionResourceName}

Omfångssegmentet varierar beroende på vilken basresurs som utökas. ID:t för en prenumeration har till exempel andra segment än ID:t för en resursgrupp.

När tilläggsresursen tillämpas på en resurs returneras resurs-ID:t i följande format:

/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{baseResourceProviderNamespace}/{baseResourceType}/{baseResourceName}/providers/{extensionResourceProviderNamespace}/{extensionResourceType}/{extensionResourceName}

När tilläggsresursen tillämpas på en resursgrupp är det returnerade formatet:

/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{extensionResourceProviderNamespace}/{extensionResourceType}/{extensionResourceName}

Ett exempel på hur du använder den här funktionen med en resursgrupp visas i nästa avsnitt.

När tilläggsresursen tillämpas på en prenumeration är det returnerade formatet:

/subscriptions/{subscriptionId}/providers/{extensionResourceProviderNamespace}/{extensionResourceType}/{extensionResourceName}

När tilläggsresursen tillämpas på en hanteringsgrupp är det returnerade formatet:

/providers/Microsoft.Management/managementGroups/{managementGroupName}/providers/{extensionResourceProviderNamespace}/{extensionResourceType}/{extensionResourceName}

Ett exempel på hur du använder den här funktionen med en hanteringsgrupp visas i nästa avsnitt.

extensionResourceId-exempel

I följande exempel returneras resurs-ID:t för ett resursgruppslås:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "lockName": {
      "type": "string"
    }
  },
  "variables": {},
  "resources": [],
  "outputs": {
    "lockResourceId": {
      "type": "string",
      "value": "[extensionResourceId(resourceGroup().Id , 'Microsoft.Authorization/locks', parameters('lockName'))]"
    }
  }
}

En anpassad principdefinition som distribueras till en hanteringsgrupp implementeras som en tilläggsresurs. Om du vill skapa och tilldela en princip distribuerar du följande mall till en hanteringsgrupp.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-08-01/managementGroupDeploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "metadata": {
    "_generator": {
      "name": "bicep",
      "version": "0.5.6.12127",
      "templateHash": "1532257987028557958"
    }
  },
  "parameters": {
    "targetMG": {
      "type": "string",
      "metadata": {
        "description": "Target Management Group"
      }
    },
    "allowedLocations": {
      "type": "array",
      "defaultValue": [
        "australiaeast",
        "australiasoutheast",
        "australiacentral"
      ],
      "metadata": {
        "description": "An array of the allowed locations, all other locations will be denied by the created policy."
      }
    }
  },
  "variables": {
    "mgScope": "[tenantResourceId('Microsoft.Management/managementGroups', parameters('targetMG'))]",
    "policyDefinitionName": "LocationRestriction"
  },
  "resources": [
    {
      "type": "Microsoft.Authorization/policyDefinitions",
      "apiVersion": "2020-03-01",
      "name": "[variables('policyDefinitionName')]",
      "properties": {
        "policyType": "Custom",
        "mode": "All",
        "parameters": {},
        "policyRule": {
          "if": {
            "not": {
              "field": "location",
              "in": "[parameters('allowedLocations')]"
            }
          },
          "then": {
            "effect": "deny"
          }
        }
      }
    },
    {
      "type": "Microsoft.Authorization/policyAssignments",
      "apiVersion": "2020-03-01",
      "name": "location-lock",
      "properties": {
        "scope": "[variables('mgScope')]",
        "policyDefinitionId": "[extensionResourceId(variables('mgScope'), 'Microsoft.Authorization/policyDefinitions', variables('policyDefinitionName'))]"
      },
      "dependsOn": [
        "[extensionResourceId(managementGroup().id, 'Microsoft.Authorization/policyDefinitions', variables('policyDefinitionName'))]"
      ]
    }
  ]
}

Inbyggda principdefinitioner är resurser på klientorganisationsnivå. Ett exempel på hur du distribuerar en inbyggd principdefinition finns i tenantResourceId.

lista*

list{Value}(resourceName or resourceIdentifier, apiVersion, functionValues)

Syntaxen för den här funktionen varierar beroende på namnet på liståtgärderna. Varje implementering returnerar värden för resurstypen som stöder en liståtgärd. Åtgärdsnamnet måste börja med list och kan ha ett suffix. Några vanliga användningar är list, listKeys, listKeyValueoch listSecrets.

Använd funktionen i list* Bicep.

Parametrar

Giltiga användningsområden

Listfunktionerna kan användas i egenskaperna för en resursdefinition. Använd inte en listfunktion som exponerar känslig information i utdataavsnittet i en mall. Utdatavärden lagras i distributionshistoriken och kan hämtas av en obehörig användare.

När det används med egenskaps-iteration kan du använda listfunktionerna för input eftersom uttrycket har tilldelats till resursegenskapen. Du kan inte använda dem med count eftersom antalet måste fastställas innan listfunktionen har lösts.

Implementeringar

Möjliga användningsområden för list* visas i följande tabell.

För att avgöra vilka resurstyper som har en liståtgärd har du följande alternativ:

• Visa REST API-åtgärderna för en resursprovider och leta efter liståtgärder. Lagringskonton har till exempel åtgärden listKeys.

• Använd Cmdleten Get-AzProviderOperation PowerShell. I följande exempel hämtas alla liståtgärder för lagringskonton:

  Get-AzProviderOperation -OperationSearchString "Microsoft.Storage/*" | where {$_.Operation -like "*list*"} | FT Operation
  

• Använd följande Azure CLI-kommando för att endast filtrera liståtgärderna:

  az provider operation show --namespace Microsoft.Storage --query "resourceTypes[?name=='storageAccounts'].operations[].name | [?contains(@, 'list')]"
  

Returvärde

Det returnerade objektet varierar beroende på vilken list funktion du använder. Till exempel listKeys returnerar för ett lagringskonto följande format:

{
  "keys": [
    {
      "keyName": "key1",
      "permissions": "Full",
      "value": "{value}"
    },
    {
      "keyName": "key2",
      "permissions": "Full",
      "value": "{value}"
    }
  ]
}

Andra list funktioner har olika returformat. Om du vill se formatet för en funktion tar du med den i avsnittet utdata som du ser i exempelmallen.

Kommentarer

Ange resursen med hjälp av antingen resursnamnet eller resourceId funktionen. När du använder en list funktion i samma mall som distribuerar den refererade resursen använder du resursnamnet.

Om du använder en list funktion i en resurs som är villkorligt distribuerad utvärderas funktionen även om resursen inte distribueras. Du får ett fel om list funktionen refererar till en resurs som inte finns. if Använd funktionen för att se till att funktionen endast utvärderas när resursen distribueras. if Se funktionen för en exempelmall som använder if och list med en villkorligt distribuerad resurs.

Listexempel

I följande exempel används listKeys när du anger ett värde för distributionsskript.

"storageAccountSettings": {
  "storageAccountName": "[variables('storageAccountName')]",
  "storageAccountKey": "[listKeys(resourceId('Microsoft.Storage/storageAccounts', variables('storageAccountName')), '2019-06-01').keys[0].value]"
}

I nästa exempel visas en list funktion som tar en parameter. I det här fallet är listAccountSasfunktionen . Skicka ett objekt för förfallotiden. Förfallotiden måste vara i framtiden.

"parameters": {
  "accountSasProperties": {
    "type": "object",
    "defaultValue": {
      "signedServices": "b",
      "signedPermission": "r",
      "signedExpiry": "2020-08-20T11:00:00Z",
      "signedResourceTypes": "s"
    }
  }
},
...
"sasToken": "[listAccountSas(parameters('storagename'), '2018-02-01', parameters('accountSasProperties')).accountSasToken]"

pickZones

pickZones(providerNamespace, resourceType, location, [numberOfZones], [offset])

Avgör om en resurstyp stöder zoner för den angivna platsen eller regionen. Den här funktionen stöder endast zonindeliga resurser. Zonredundanta tjänster returnerar en tom matris. Mer information finns i Azure-tjänster som stöder tillgänglighetszoner.

Använd funktionen i pickZones Bicep.

Parametrar

Returvärde

En matris med de zoner som stöds. När du använder standardvärdena för offset och numberOfZonesreturnerar en resurstyp och region som stöder zoner följande matris:

[
    "1"
]

När parametern numberOfZones är inställd på 3 returneras:

[
    "1",
    "2",
    "3"
]

När resurstypen eller regionen inte stöder zoner returneras en tom matris. En tom matris returneras också för zonredundanta tjänster.

[
]

Kommentarer

Det finns olika kategorier för Azure Tillgänglighetszoner – zonindelad och zonredundant. Funktionen pickZones kan användas för att returnera en tillgänglighetszon för en zonindelad resurs. För zonredundanta tjänster (ZRS) returnerar funktionen en tom matris. Zonindeliga resurser har vanligtvis en zones egenskap på den översta nivån i resursdefinitionen. Information om vilken kategori av stöd som finns för tillgänglighetszoner finns i Azure-tjänster som stöder tillgänglighetszoner.

För att avgöra om en viss Azure-region eller plats stöder tillgänglighetszoner anropar pickZones du funktionen med en zonindelad resurstyp, till exempel Microsoft.Network/publicIPAddresses. Om svaret inte är tomt stöder regionen tillgänglighetszoner.

pickZones-exempel

Följande mall visar tre resultat för att använda pickZones funktionen:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {},
  "functions": [],
  "variables": {},
  "resources": [],
  "outputs": {
    "supported": {
      "type": "array",
      "value": "[pickZones('Microsoft.Compute', 'virtualMachines', 'westus2')]"
    },
    "notSupportedRegion": {
      "type": "array",
      "value": "[pickZones('Microsoft.Compute', 'virtualMachines', 'westus')]"
    },
    "notSupportedType": {
      "type": "array",
      "value": "[pickZones('Microsoft.Cdn', 'profiles', 'westus2')]"
    }
  }
}

Utdata från föregående exempel returnerar tre matriser.

Du kan använda svaret från pickZones för att avgöra om du vill ange null för zoner eller tilldela virtuella datorer till olika zoner. I följande exempel anges ett värde för zonen baserat på tillgängligheten för zoner:

"zones": {
  "value": "[if(not(empty(pickZones('Microsoft.Compute', 'virtualMachines', 'westus2'))), string(add(mod(copyIndex(),3),1)), json('null'))]"
},

Azure Cosmos DB är inte en zonindelad resurs, men du kan använda pickZones funktionen för att avgöra om zonredundans ska aktiveras för georeplikering. Skicka resurstypen Microsoft.Storage/storageAccounts för att avgöra om zonredundans ska aktiveras:

"resources": [
  {
    "type": "Microsoft.DocumentDB/databaseAccounts",
    "apiVersion": "2021-04-15",
    "name": "[variables('accountName_var')]",
    "location": "[parameters('location')]",
    "kind": "GlobalDocumentDB",
    "properties": {
      "consistencyPolicy": "[variables('consistencyPolicy')[parameters('defaultConsistencyLevel')]]",
      "locations": [
        {
          "locationName": "[parameters('primaryRegion')]",
          "failoverPriority": 0,
          "isZoneRedundant": "[if(empty(pickZones('Microsoft.Storage', 'storageAccounts', parameters('primaryRegion'))), bool('false'), bool('true'))]",
        },
        {
          "locationName": "[parameters('secondaryRegion')]",
          "failoverPriority": 1,
          "isZoneRedundant": "[if(empty(pickZones('Microsoft.Storage', 'storageAccounts', parameters('secondaryRegion'))), bool('false'), bool('true'))]",
        }
      ],
      "databaseAccountOfferType": "Standard",
      "enableAutomaticFailover": "[parameters('automaticFailover')]"
    }
  }
]

Leverantörer

Funktionen providers har blivit inaktuell i ARM-mallar. Vi rekommenderar inte längre att du använder den. Om du använde den här funktionen för att hämta en API-version för resursprovidern rekommenderar vi att du anger en specifik API-version i mallen. Om du använder en dynamiskt returnerad API-version kan mallen brytas om egenskaperna ändras mellan versionerna.

I Bicep providers är funktionen inaktuell.

Åtgärden [providers ](/rest/api/resources/providers) är fortfarande tillgänglig via REST-API:et. Den kan användas utanför en ARM-mall för att hämta information om en resursprovider.

hänvisning

I mallarna utan symboliska namn:

reference(resourceName or resourceIdentifier, [apiVersion], ['Full'])

I mallarna med symboliska namn:

reference(symbolicName or resourceIdentifier, [apiVersion], ['Full'])

Returnerar ett objekt som representerar en resurss körningstillstånd. Utdata och beteende för reference funktionen är starkt beroende av hur varje resursprovider (RP) implementerar sina PUT- och GET-svar. Information om hur du returnerar en matris med objekt som representerar en resurssamlingars körningstillstånd finns i referenser.

Bicep tillhandahåller reference funktionen, men i de flesta fall krävs inte funktionen. Använd i stället det symboliska namnet för resursen. Mer information finns i reference.

Parametrar

Returvärde

Varje resurstyp returnerar olika egenskaper för reference funktionen. Funktionen returnerar inte ett enda, fördefinierat format. Det returnerade värdet skiljer sig också beroende på argumentets 'Full' värde. Om du vill se egenskaperna för en resurstyp returnerar du objektet i avsnittet utdata enligt exemplet.

Kommentarer

Funktionen reference hämtar körningstillståndet för antingen en tidigare distribuerad resurs eller en resurs som distribuerats i den aktuella mallen. Den här artikeln visar exempel för båda scenarierna.

Vanligtvis använder reference du funktionen för att returnera ett visst värde från ett objekt, till exempel blobslutpunkts-URI eller fullständigt kvalificerat domännamn.

"outputs": {
  "BlobUri": {
    "type": "string",
    "value": "[reference(resourceId('Microsoft.Storage/storageAccounts', parameters('storageAccountName'))).primaryEndpoints.blob]"
  },
  "FQDN": {
    "type": "string",
    "value": "[reference(resourceId('Microsoft.Network/publicIPAddresses', parameters('ipAddressName'))).dnsSettings.fqdn]"
  }
}

Använd 'Full' när du behöver resursvärden som inte ingår i egenskapsschemat. Om du till exempel vill ange åtkomstprinciper för key vault hämtar du identitetsegenskaperna för en virtuell dator.

{
  "type": "Microsoft.KeyVault/vaults",
  "apiVersion": "2022-07-01",
  "name": "vaultName",
  "properties": {
    "tenantId": "[subscription().tenantId]",
    "accessPolicies": [
      {
        "tenantId": "[reference(resourceId('Microsoft.Compute/virtualMachines', variables('vmName')), '2019-03-01', 'Full').identity.tenantId]",
        "objectId": "[reference(resourceId('Microsoft.Compute/virtualMachines', variables('vmName')), '2019-03-01', 'Full').identity.principalId]",
        "permissions": {
          "keys": [
            "all"
          ],
          "secrets": [
            "all"
          ]
        }
      }
    ],
    ...

Giltiga användningsområden

Funktionen reference kan bara användas i utdataavsnittet i en mall eller distribution och egenskapsobjekt för en resursdefinition. Det kan inte användas för resursegenskaper som type, name, locationeller andra egenskaper på den översta nivån för resursdefinitionen. När det används med egenskaps-iteration kan du använda reference funktionen för input eftersom uttrycket har tilldelats till resursegenskapen.

Du kan inte använda reference funktionen för att ange värdet count för egenskapen i en kopieringsloop. Du kan använda för att ange andra egenskaper i loopen. Referensen blockeras för egenskapen count eftersom den egenskapen måste fastställas innan reference funktionen har lösts.

Om du vill använda reference funktionen eller någon list* funktion i utdataavsnittet i en kapslad mall måste du ange expressionEvaluationOptions att använda utvärdering av inre omfång eller använda en länkad i stället för en kapslad mall.

Om du använder reference funktionen i en resurs som är villkorligt distribuerad utvärderas funktionen även om resursen inte distribueras. Du får ett fel om reference funktionen refererar till en resurs som inte finns. if Använd funktionen för att se till att funktionen endast utvärderas när resursen distribueras. if Se funktionen för en exempelmall som använder if och reference med en villkorligt distribuerad resurs.

Implicit beroende

Genom att använda reference funktionen deklarerar du implicit att en resurs är beroende av en annan resurs om den refererade resursen etableras i samma mall och du refererar till resursen med dess namn (inte resurs-ID). Du behöver inte också använda egenskapen dependsOn . Funktionen utvärderas inte förrän den refererade resursen har slutfört distributionen.

Resursnamn, symboliskt namn eller identifierare

När du refererar till en resurs som distribueras i samma mall för inget symboliskt namn anger du resursens namn.

"value": "[reference(parameters('storageAccountName'))]"

När du refererar till en resurs som distribueras i samma mall för symboliskt namn anger du resursens symboliska namn.

"value": "[reference('myStorage').primaryEndpoints]"

Eller

"value": "[reference('myStorage', '2022-09-01', 'Full').location]"

När du refererar till en resurs som inte har distribuerats i samma mall anger du resurs-ID och apiVersion.

"value": "[reference(resourceId(parameters('storageResourceGroup'), 'Microsoft.Storage/storageAccounts', parameters('storageAccountName')), '2022-09-01')]"

För att undvika tvetydigheter om vilken resurs du refererar till kan du ange en fullständigt kvalificerad resursidentifierare.

"value": "[reference(resourceId('Microsoft.Network/publicIPAddresses', parameters('ipAddressName')))]"

När du skapar en fullständigt kvalificerad referens till en resurs är ordningen för att kombinera segment från typen och namnet inte bara en sammanlänkning av de två. Efter namnområdet använder du i stället en sekvens med typ-/namnpar från minst specifika till mest specifika:

{resource-provider-namespace}/{parent-resource-type}/{parent-resource-name}[/{child-resource-type}/{child-resource-name}]

Till exempel:

Microsoft.Compute/virtualMachines/myVM/extensions/myExt är korrekt Microsoft.Compute/virtualMachines/extensions/myVM/myExt är inte korrekt

För att förenkla skapandet av alla resurs-ID:t använder du funktionerna resourceId() som beskrivs i det här dokumentet i stället för concat() funktionen.

Hämta hanterad identitet

Hanterade identiteter för Azure-resurser är tilläggsresurstyper som skapas implicit för vissa resurser. Eftersom den hanterade identiteten inte uttryckligen definieras i mallen måste du referera till den resurs som identiteten tillämpas på. Använd Full för att hämta alla egenskaper, inklusive den implicit skapade identiteten.

Mönstret är:

"[reference(resourceId(<resource-provider-namespace>, <resource-name>), <API-version>, 'Full').Identity.propertyName]"

Om du till exempel vill hämta huvud-ID:t för en hanterad identitet som tillämpas på en virtuell dator använder du:

"[reference(resourceId('Microsoft.Compute/virtualMachines', variables('vmName')),'2019-12-01', 'Full').identity.principalId]",

Om du vill hämta klient-ID:t för en hanterad identitet som tillämpas på en VM-skalningsuppsättning använder du:

"[reference(resourceId('Microsoft.Compute/virtualMachineScaleSets',  variables('vmNodeType0Name')), 2019-12-01, 'Full').Identity.tenantId]"

Referensexempel

Följande exempel distribuerar en resurs och refererar till den:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "storageAccountName": {
      "type": "string"
    },
    "location": {
      "type": "string",
      "defaultValue": "[resourceGroup().location]"
    }
  },
  "resources": [
    {
      "type": "Microsoft.Storage/storageAccounts",
      "apiVersion": "2022-09-01",
      "name": "[parameters('storageAccountName')]",
      "location": "[parameters('location')]",
      "sku": {
        "name": "Standard_LRS"
      },
      "kind": "Storage",
      "tags": {},
      "properties": {
      }
    }
  ],
  "outputs": {
    "referenceOutput": {
      "type": "object",
      "value": "[reference(parameters('storageAccountName'))]"
    },
    "fullReferenceOutput": {
      "type": "object",
      "value": "[reference(parameters('storageAccountName'), '2022-09-01', 'Full')]"
    }
  }
}

Föregående exempel returnerar de två objekten. Egenskapsobjektet har följande format:

{
   "creationTime": "2017-10-09T18:55:40.5863736Z",
   "primaryEndpoints": {
     "blob": "https://examplestorage.blob.core.windows.net/",
     "file": "https://examplestorage.file.core.windows.net/",
     "queue": "https://examplestorage.queue.core.windows.net/",
     "table": "https://examplestorage.table.core.windows.net/"
   },
   "primaryLocation": "southcentralus",
   "provisioningState": "Succeeded",
   "statusOfPrimary": "available",
   "supportsHttpsTrafficOnly": false
}

Det fullständiga objektet har följande format:

{
  "apiVersion":"2022-09-01",
  "location":"southcentralus",
  "sku": {
    "name":"Standard_LRS",
    "tier":"Standard"
  },
  "tags":{},
  "kind":"Storage",
  "properties": {
    "creationTime":"2021-10-09T18:55:40.5863736Z",
    "primaryEndpoints": {
      "blob":"https://examplestorage.blob.core.windows.net/",
      "file":"https://examplestorage.file.core.windows.net/",
      "queue":"https://examplestorage.queue.core.windows.net/",
      "table":"https://examplestorage.table.core.windows.net/"
    },
    "primaryLocation":"southcentralus",
    "provisioningState":"Succeeded",
    "statusOfPrimary":"available",
    "supportsHttpsTrafficOnly":false
  },
  "subscriptionId":"<subscription-id>",
  "resourceGroupName":"functionexamplegroup",
  "resourceId":"Microsoft.Storage/storageAccounts/examplestorage",
  "referenceApiVersion":"2021-04-01",
  "condition":true,
  "isConditionTrue":true,
  "isTemplateResource":false,
  "isAction":false,
  "provisioningOperation":"Read"
}

Följande exempelmall refererar till ett lagringskonto som inte har distribuerats i den här mallen. Lagringskontot finns redan i samma prenumeration:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "storageResourceGroup": {
      "type": "string"
    },
    "storageAccountName": {
      "type": "string"
    }
  },
  "resources": [],
  "outputs": {
    "ExistingStorage": {
      "type": "object",
      "value": "[reference(resourceId(parameters('storageResourceGroup'), 'Microsoft.Storage/storageAccounts', parameters('storageAccountName')), '2021-04-01')]"
    }
  }
}

referenser

references(symbolic name of a resource collection, ['Full', 'Properties])

Funktionen references fungerar på samma sätt som reference. I stället för att returnera ett objekt som presenterar en resurss körningstillstånd references returnerar funktionen en matris med objekt som representerar en resurssamlings körningstillstånd. Den här funktionen kräver språkversion 2.0 för ARM-mallar och med symboliskt namn aktiverat:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "languageVersion": "2.0",
  "contentVersion": "1.0.0.0",
  ...
}

I Bicep finns det ingen explicit references funktion. I stället används symbolisk samlingsanvändning direkt, och under kodgenereringen översätter Bicep den till en ARM-mall som använder ARM-mallfunktionen references . Mer information finns i Referensresurs-/modulsamlingar.

Parametrar

Returvärde

En matris med resurssamlingen. Varje resurstyp returnerar olika egenskaper för reference funktionen. Det returnerade värdet skiljer sig också beroende på argumentets 'Full' värde. Mer information finns i referens.

Utdataordningen references för är alltid ordnad i stigande ordning baserat på kopieringsindexet. Därför visas den första resursen i samlingen med index 0 först, följt av index 1 och så vidare. Till exempel [worker-0, worker-1, worker-2, ...].

I föregående exempel, om worker-0 och worker-2 distribueras medan worker-1 inte beror på ett falskt villkor, utelämnar utdata references från den nondeployed resursen och visar de distribuerade, sorterade efter deras nummer. Utdata references för kommer att vara [worker-0, worker-2, ...]. Om alla resurser utelämnas returnerar funktionen en tom matris.

Giltiga användningsområden

Funktionen references kan inte användas i resurskopieringsloopar eller Bicep för loop. Tillåts till exempel references inte i följande scenario:

{
  resources: {
    "resourceCollection": {
       "copy": { ... },
       "properties": {
         "prop": "[references(...)]"
       }
    }
  }
}

Om du vill använda references funktionen eller någon list* funktion i utdataavsnittet i en kapslad mall måste du ange expressionEvaluationOptions att använda utvärdering av inre omfång eller använda en länkad i stället för en kapslad mall.

Implicit beroende

Genom att references använda funktionen deklarerar du implicit att en resurs är beroende av en annan resurs. Du behöver inte också använda egenskapen dependsOn . Funktionen utvärderas inte förrän den refererade resursen har slutfört distributionen.

Referensexempel

I följande exempel distribueras en resurssamling och refererar till den resurssamlingen:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "languageVersion": "2.0",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "location": {
      "type": "string",
      "defaultValue": "[resourceGroup().location]",
      "metadata": {
        "description": "Location for all resources."
      }
    },
    "numWorkers": {
      "type": "int",
      "defaultValue": 4,
      "metadata": {
        "description": "The number of workers"
      }
    }
  },
  "resources": {
    "containerWorkers": {
      "copy": {
        "name": "containerWorkers",
        "count": "[length(range(0, parameters('numWorkers')))]"
      },
      "type": "Microsoft.ContainerInstance/containerGroups",
      "apiVersion": "2023-05-01",
      "name": "[format('worker-{0}', range(0, parameters('numWorkers'))[copyIndex()])]",
      "location": "[parameters('location')]",
      "properties": {
        "containers": [
          {
            "name": "[format('worker-container-{0}', range(0, parameters('numWorkers'))[copyIndex()])]",
            "properties": {
              "image": "mcr.microsoft.com/azuredocs/aci-helloworld",
              "ports": [
                {
                  "port": 80,
                  "protocol": "TCP"
                }
              ],
              "resources": {
                "requests": {
                  "cpu": 1,
                  "memoryInGB": 2
                }
              }
            }
          }
        ],
        "osType": "Linux",
        "restartPolicy": "Always",
        "ipAddress": {
          "type": "Public",
          "ports": [
            {
              "port": 80,
              "protocol": "TCP"
            }
          ]
        }
      }
    },
    "containerController": {
      "type": "Microsoft.ContainerInstance/containerGroups",
      "apiVersion": "2023-05-01",
      "name": "controller",
      "location": "[parameters('location')]",
      "properties": {
        "containers": [
          {
            "name": "controller-container",
            "properties": {
              "command": [
                "echo",
                "[format('Worker IPs are {0}', join(map(references('containerWorkers', 'full'), lambda('w', lambdaVariables('w').properties.ipAddress.ip)), ','))]"
              ],
              "image": "mcr.microsoft.com/azuredocs/aci-helloworld",
              "ports": [
                {
                  "port": 80,
                  "protocol": "TCP"
                }
              ],
              "resources": {
                "requests": {
                  "cpu": 1,
                  "memoryInGB": 2
                }
              }
            }
          }
        ],
        "osType": "Linux",
        "restartPolicy": "Always",
        "ipAddress": {
          "type": "Public",
          "ports": [
            {
              "port": 80,
              "protocol": "TCP"
            }
          ]
        }
      },
      "dependsOn": [
        "containerWorkers"
      ]
    }
  },
  "outputs": {
    "workerIpAddresses": {
      "type": "string",
      "value": "[join(map(references('containerWorkers', 'full'), lambda('w', lambdaVariables('w').properties.ipAddress.ip)), ',')]"
    },
    "containersFull": {
      "type": "array",
      "value": "[references('containerWorkers', 'full')]"
    },
    "container": {
      "type": "array",
      "value": "[references('containerWorkers')]"
    }
  }
}

Föregående exempel returnerar de tre objekten.

"outputs": {
  "workerIpAddresses": {
    "type": "String",
    "value": "20.66.74.26,20.245.100.10,13.91.86.58,40.83.249.30"
  },
  "containersFull": {
    "type": "Array",
    "value": [
      {
        "apiVersion": "2023-05-01",
        "condition": true,
        "copyContext": {
          "copyIndex": 0,
          "copyIndexes": {
            "": 0,
            "containerWorkers": 0
          },
          "name": "containerWorkers"
        },
        "copyLoopSymbolicName": "containerWorkers",
        "deploymentResourceLineInfo": {
          "lineNumber": 30,
          "linePosition": 25
        },
        "existing": false,
        "isAction": false,
        "isConditionTrue": true,
        "isTemplateResource": true,
        "location": "westus",
        "properties": {
          "containers": [
            {
              "name": "worker-container-0",
              "properties": {
                "environmentVariables": [],
                "image": "mcr.microsoft.com/azuredocs/aci-helloworld",
                "instanceView": {
                  "currentState": {
                    "detailStatus": "",
                    "startTime": "2023-07-31T19:25:31.996Z",
                    "state": "Running"
                  },
                  "restartCount": 0
                },
                "ports": [
                  {
                    "port": 80,
                    "protocol": "TCP"
                  }
                ],
                "resources": {
                  "requests": {
                    "cpu": 1.0,
                    "memoryInGB": 2.0
                  }
                }
              }
            }
          ],
          "initContainers": [],
          "instanceView": {
            "events": [],
            "state": "Running"
          },
          "ipAddress": {
            "ip": "20.66.74.26",
            "ports": [
              {
                "port": 80,
                "protocol": "TCP"
              }
            ],
            "type": "Public"
          },
          "isCustomProvisioningTimeout": false,
          "osType": "Linux",
          "provisioningState": "Succeeded",
          "provisioningTimeoutInSeconds": 1800,
          "restartPolicy": "Always",
          "sku": "Standard"
        },
        "provisioningOperation": "Create",
        "references": [],
        "resourceGroupName": "demoRg",
        "resourceId": "Microsoft.ContainerInstance/containerGroups/worker-0",
        "scope": "",
        "subscriptionId": "",
        "symbolicName": "containerWorkers[0]"
      },
      ...
    ]
  },
  "containers": {
    "type": "Array",
    "value": [
      {
        "containers": [
          {
            "name": "worker-container-0",
            "properties": {
              "environmentVariables": [],
              "image": "mcr.microsoft.com/azuredocs/aci-helloworld",
              "instanceView": {
                "currentState": {
                  "detailStatus": "",
                  "startTime": "2023-07-31T19:25:31.996Z",
                  "state": "Running"
                },
                "restartCount": 0
              },
              "ports": [
                {
                  "port": 80,
                  "protocol": "TCP"
                }
              ],
              "resources": {
                "requests": {
                  "cpu": 1.0,
                  "memoryInGB": 2.0
                }
              }
            }
          }
        ],
        "initContainers": [],
        "instanceView": {
          "events": [],
          "state": "Running"
        },
        "ipAddress": {
          "ip": "20.66.74.26",
          "ports": [
            {
              "port": 80,
              "protocol": "TCP"
            }
          ],
          "type": "Public"
        },
        "isCustomProvisioningTimeout": false,
        "osType": "Linux",
        "provisioningState": "Succeeded",
        "provisioningTimeoutInSeconds": 1800,
        "restartPolicy": "Always",
        "sku": "Standard"
      },
      ...
    ]
  }
}

resursgrupp

Se funktionen resourceGroup scope .

Använd funktionen i resourceGroup scope Bicep.

resursId

resourceId([subscriptionId], [resourceGroupName], resourceType, resourceName1, [resourceName2], ...)

Returnerar den unika identifieraren för en resurs. Du använder den här funktionen när resursnamnet är tvetydigt eller inte har etablerats i samma mall. Formatet för den returnerade identifieraren varierar beroende på om distributionen sker inom omfånget för en resursgrupp, prenumeration, hanteringsgrupp eller klientorganisation.

Använd funktionen i resourceId Bicep.

Parametrar

Fortsätt att lägga till resursnamn som parametrar när resurstypen innehåller fler segment.

Returvärde

Resurs-ID:t returneras i olika format i olika omfång:

• Resursgruppsomfång:

  /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}
  

• Prenumerationsomfång:

  /subscriptions/{subscriptionId}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}
  

• Hanteringsgrupp eller klientomfång:

  /providers/{resourceProviderNamespace}/{resourceType}/{resourceName}
  

Undvik förvirring genom att inte använda resourceId när du arbetar med resurser som distribuerats till prenumerationen, hanteringsgruppen eller klientorganisationen. Använd i stället den ...Id funktion som är utformad för omfånget.

• Använd funktionen för resurser påsubscriptionResourceId prenumerationsnivå.
• Använd funktionen för managementGroupResourceIdresurser på hanteringsgruppsnivå. extensionResourceId Använd funktionen för att referera till en resurs som implementeras som ett tillägg till en hanteringsgrupp. Anpassade principdefinitioner som distribueras till en hanteringsgrupp är till exempel tillägg för hanteringsgruppen. tenantResourceId Använd funktionen för att referera till resurser som distribueras till klientorganisationen men som är tillgängliga i hanteringsgruppen. Till exempel implementeras inbyggda principdefinitioner som resurser på klientnivå.
• Använd funktionen för tenantResourceIdresurser på klientnivå. Använd tenantResourceId för inbyggda principdefinitioner eftersom de implementeras på klientorganisationsnivå.

Kommentarer

Antalet parametrar som du anger varierar beroende på om resursen är en överordnad eller underordnad resurs och om resursen finns i samma prenumeration eller resursgrupp.

Om du vill hämta resurs-ID:t för en överordnad resurs i samma prenumeration och resursgrupp anger du resursens typ och namn.

"[resourceId('Microsoft.ServiceBus/namespaces', 'namespace1')]"

Om du vill hämta resurs-ID:t för en underordnad resurs bör du vara uppmärksam på antalet segment i resurstypen. Ange ett resursnamn för varje segment av resurstypen. Segmentets namn motsvarar den resurs som finns för den delen av hierarkin.

"[resourceId('Microsoft.ServiceBus/namespaces/queues/authorizationRules', 'namespace1', 'queue1', 'auth1')]"

Ange resursgruppens namn för att hämta resurs-ID:t för en resurs i samma prenumeration men en annan resursgrupp.

"[resourceId('otherResourceGroup', 'Microsoft.Storage/storageAccounts', 'examplestorage')]"

Om du vill hämta resurs-ID:t för en resurs i en annan prenumeration och resursgrupp anger du prenumerations-ID och resursgruppsnamn.

"[resourceId('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx', 'otherResourceGroup', 'Microsoft.Storage/storageAccounts','examplestorage')]"

Ofta måste du använda den här funktionen när du använder ett lagringskonto eller ett virtuellt nätverk i en alternativ resursgrupp. I följande exempel visas hur du använder en resurs från en extern resursgrupp:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "location": {
      "type": "string"
    },
    "virtualNetworkName": {
      "type": "string"
    },
    "virtualNetworkResourceGroup": {
      "type": "string"
    },
    "subnet1Name": {
      "type": "string"
    },
    "nicName": {
      "type": "string"
    }
  },
  "variables": {
    "subnet1Ref": "[resourceId(parameters('virtualNetworkResourceGroup'), 'Microsoft.Network/virtualNetworks/subnets', parameters('virtualNetworkName'), parameters('subnet1Name'))]"
  },
  "resources": [
    {
      "type": "Microsoft.Network/networkInterfaces",
      "apiVersion": "2022-11-01",
      "name": "[parameters('nicName')]",
      "location": "[parameters('location')]",
      "properties": {
        "ipConfigurations": [
          {
            "name": "ipconfig1",
            "properties": {
              "privateIPAllocationMethod": "Dynamic",
              "subnet": {
                "id": "[variables('subnet1Ref')]"
              }
            }
          }
        ]
      }
    }
  ]
}

Exempel på resurs-ID

I följande exempel returneras resurs-ID:t för ett lagringskonto i resursgruppen:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "resources": [],
  "outputs": {
    "sameRGOutput": {
      "type": "string",
      "value": "[resourceId('Microsoft.Storage/storageAccounts','examplestorage')]"
    },
    "differentRGOutput": {
      "type": "string",
      "value": "[resourceId('otherResourceGroup', 'Microsoft.Storage/storageAccounts','examplestorage')]"
    },
    "differentSubOutput": {
      "type": "string",
      "value": "[resourceId('11111111-1111-1111-1111-111111111111', 'otherResourceGroup', 'Microsoft.Storage/storageAccounts','examplestorage')]"
    },
    "nestedResourceOutput": {
      "type": "string",
      "value": "[resourceId('Microsoft.SQL/servers/databases', 'serverName', 'databaseName')]"
    }
  }
}

Utdata från standardvärdena från föregående exempel är:

prenumeration

Mer information finns i omfångsfunktionensubscription.

I Bicep använder du omfångsfunktionensubscription.

subscriptionResourceId

subscriptionResourceId([subscriptionId], resourceType, resourceName1, [resourceName2], ...)

Returnerar den unika identifieraren för en resurs som distribueras på prenumerationsnivå.

Använd funktionen i subscriptionResourceId Bicep.

Parametrar

Fortsätt att lägga till resursnamn som parametrar när resurstypen innehåller fler segment.

Returvärde

Identifieraren returneras i följande format:

/subscriptions/{subscriptionId}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}

Kommentarer

Du använder den här funktionen för att hämta resurs-ID för resurser som distribueras till prenumerationen i stället för en resursgrupp. Det returnerade ID:t skiljer sig från det värde som returneras av resourceId funktionen eftersom det inte returnerar ett resursgruppsvärde.

subscriptionResourceID-exempel

Följande mall tilldelar en inbyggd roll. Du kan distribuera den till en resursgrupp eller en prenumeration. Den använder subscriptionResourceId funktionen för att hämta resurs-ID för inbyggda roller:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "principalId": {
      "type": "string",
      "metadata": {
        "description": "The principal to assign the role to"
      }
    },
    "builtInRoleType": {
      "type": "string",
      "allowedValues": [
        "Owner",
        "Contributor",
        "Reader"
      ],
      "metadata": {
        "description": "Built-in role to assign"
      }
    },
    "roleNameGuid": {
      "type": "string",
      "defaultValue": "[newGuid()]",
      "metadata": {
        "description": "A new GUID used to identify the role assignment"
      }
    }
  },
  "variables": {
    "Owner": "[subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '8e3af657-a8ff-443c-a75c-2fe8c4bcb635')]",
    "Contributor": "[subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'b24988ac-6180-42a0-ab88-20f7382dd24c')]",
    "Reader": "[subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'acdd72a7-3385-48ef-bd42-f606fba81ae7')]"
  },
  "resources": [
    {
      "type": "Microsoft.Authorization/roleAssignments",
      "apiVersion": "2022-04-01",
      "name": "[parameters('roleNameGuid')]",
      "properties": {
        "roleDefinitionId": "[variables(parameters('builtInRoleType'))]",
        "principalId": "[parameters('principalId')]"
      }
    }
  ]
}

managementGroupResourceId

managementGroupResourceId([managementGroupResourceId],resourceType, resourceName1, [resourceName2], ...)

Returnerar den unika identifieraren för en resurs som distribuerats på hanteringsgruppsnivå.

Använd funktionen i managementGroupResourceId Bicep.

Parametrar

Fortsätt att lägga till resursnamn som parametrar när resurstypen innehåller fler segment.

Returvärde

Identifieraren returneras i följande format:

/providers/Microsoft.Management/managementGroups/{managementGroupName}/providers/{resourceType}/{resourceName}

Kommentarer

Du använder den här funktionen för att hämta resurs-ID för resurser som distribueras till hanteringsgruppen i stället för en resursgrupp. Det returnerade ID:t skiljer sig från det värde som returneras av resourceId funktionen eftersom det inte innehåller något prenumerations-ID eller ett resursgruppsvärde.

managementGroupResourceID-exempel

Följande mall skapar och tilldelar en principdefinition. Den använder managementGroupResourceId funktionen för att hämta resurs-ID:t för principdefinitionen.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-08-01/managementGroupDeploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "targetMG": {
      "type": "string",
      "metadata": {
        "description": "Target Management Group"
      }
    },
    "allowedLocations": {
      "type": "array",
      "defaultValue": [
        "australiaeast",
        "australiasoutheast",
        "australiacentral"
      ],
      "metadata": {
        "description": "An array of the allowed locations, all other locations will be denied by the created policy."
      }
    }
  },
  "variables": {
    "mgScope": "[tenantResourceId('Microsoft.Management/managementGroups', parameters('targetMG'))]",
    "policyDefinitionName": "LocationRestriction"
  },
  "resources": [
    {
      "type": "Microsoft.Authorization/policyDefinitions",
      "apiVersion": "2021-06-01",
      "name": "[variables('policyDefinitionName')]",
      "properties": {
        "policyType": "Custom",
        "mode": "All",
        "parameters": {},
        "policyRule": {
          "if": {
            "not": {
              "field": "location",
              "in": "[parameters('allowedLocations')]"
            }
          },
          "then": {
            "effect": "deny"
          }
        }
      }
    },
    "location_lock": {
      "type": "Microsoft.Authorization/policyAssignments",
      "apiVersion": "2022-06-01",
      "name": "location-lock",
      "properties": {
        "scope": "[variables('mgScope')]",
        "policyDefinitionId": "[managementGroupResourceId('Microsoft.Authorization/policyDefinitions', variables('policyDefinitionName'))]"
      },
      "dependsOn": [
        "[format('Microsoft.Authorization/policyDefinitions/{0}', variables('policyDefinitionName'))]"
      ]
    }
  ]
}

tenantResourceId

tenantResourceId(resourceType, resourceName1, [resourceName2], ...)

Returnerar den unika identifieraren för en resurs som distribuerats på klientorganisationsnivå.

Använd funktionen i tenantResourceId Bicep.

Parametrar

Fortsätt att lägga till resursnamn som parametrar när resurstypen innehåller fler segment.

Returvärde

Identifieraren returneras i följande format:

/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}

Kommentarer

Du använder den här funktionen för att hämta resurs-ID:t för en resurs som distribueras till klientorganisationen. Det returnerade ID:t skiljer sig från de värden som returneras av andra resurs-ID-funktioner genom att inte inkludera resursgrupps- eller prenumerationsvärden.

tenantResourceId-exempel

Inbyggda principdefinitioner är resurser på klientorganisationsnivå. Om du vill distribuera en principtilldelning som refererar till en inbyggd principdefinition använder du tenantResourceId funktionen:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "policyDefinitionID": {
      "type": "string",
      "defaultValue": "0a914e76-4921-4c19-b460-a2d36003525a",
      "metadata": {
        "description": "Specifies the ID of the policy definition or policy set definition being assigned."
      }
    },
    "policyAssignmentName": {
      "type": "string",
      "defaultValue": "[guid(parameters('policyDefinitionID'), resourceGroup().name)]",
      "metadata": {
        "description": "Specifies the name of the policy assignment, can be used defined or an idempotent name as the defaultValue provides."
      }
    }
  },
  "resources": [
    {
      "type": "Microsoft.Authorization/policyAssignments",
      "name": "[parameters('policyAssignmentName')]",
      "apiVersion": "2022-06-01",
      "properties": {
        "scope": "[subscriptionResourceId('Microsoft.Resources/resourceGroups', resourceGroup().name)]",
        "policyDefinitionId": "[tenantResourceId('Microsoft.Authorization/policyDefinitions', parameters('policyDefinitionID'))]"
      }
    }
  ]
}

Nästa steg

• En beskrivning av avsnitten i en ARM-mall finns i Förstå strukturen och syntaxen för ARM-mallar.
• Information om hur du sammanfogar flera mallar finns i Använda länkade och kapslade mallar när du distribuerar Azure-resurser.
• Information om hur du itererar ett angivet antal gånger när du skapar en typ av resurs finns i Resursiteration i ARM-mallar.
• Information om hur du distribuerar mallen som du har skapat finns i Distribuera resurser med ARM-mallar och Azure PowerShell.