Funkcje zasobów dla szablonów usługi ARM

  • Artykuł

Usługa Resource Manager udostępnia następujące funkcje umożliwiające uzyskiwanie wartości zasobów w szablonie usługi Azure Resource Manager (szablon usługi ARM):

Aby uzyskać wartości z parametrów, zmiennych lub bieżącego wdrożenia, zobacz Funkcje wartości wdrożenia.

Aby uzyskać wartości zakresu wdrożenia, zobacz Funkcje zakresu.

Napiwek

Zalecamy Bicep , ponieważ oferuje te same możliwości co szablony usługi ARM, a składnia jest łatwiejsza w użyciu. Aby dowiedzieć się więcej, zobacz funkcje zasobów .

extensionResourceId

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

Zwraca identyfikator zasobu dla zasobu rozszerzenia. Zasób rozszerzenia to typ zasobu, który jest stosowany do innego zasobu w celu dodania do jego możliwości.

W pliku Bicep użyj funkcji extensionResourceId .

Parametry

Parametr Wymagania Type Opis
baseResourceId Tak string Identyfikator zasobu, do którego jest stosowany zasób rozszerzenia.
resourceType Tak string Typ zasobu rozszerzenia, w tym przestrzeń nazw dostawcy zasobów.
resourceName1 Tak string Nazwa zasobu rozszerzenia.
resourceName2 Nie. string W razie potrzeby następny segment nazw zasobów.

Kontynuuj dodawanie nazw zasobów jako parametrów, gdy typ zasobu zawiera więcej segmentów.

Wartość zwracana

Podstawowy format identyfikatora zasobu zwróconego przez tę funkcję to:

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

Segment zakresu zależy od rozszerzonego zasobu podstawowego. Na przykład identyfikator subskrypcji ma inne segmenty niż identyfikator grupy zasobów.

Po zastosowaniu zasobu rozszerzenia do zasobu identyfikator zasobu jest zwracany w następującym formacie:

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

Po zastosowaniu zasobu rozszerzenia do grupy zasobów zwracany format to:

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

Przykład użycia tej funkcji z grupą zasobów jest wyświetlany w następnej sekcji.

Po zastosowaniu zasobu rozszerzenia do subskrypcji zwracany format to:

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

Po zastosowaniu zasobu rozszerzenia do grupy zarządzania zwracany format to:

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

Przykład użycia tej funkcji z grupą zarządzania jest wyświetlany w następnej sekcji.

extensionResourceId — przykład

Poniższy przykład zwraca identyfikator zasobu dla blokady grupy zasobów.

{
  "$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'))]"
    }
  }
}

Niestandardowa definicja zasad wdrożona w grupie zarządzania jest implementowana jako zasób rozszerzenia. Aby utworzyć i przypisać zasady, wdróż następujący szablon w grupie zarządzania.

{
  "$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'))]"
      ]
    }
  ]
}

Wbudowane definicje zasad to zasoby na poziomie dzierżawy. Aby zapoznać się z przykładem wdrażania wbudowanej definicji zasad, zobacz tenantResourceId.

Listy*

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

Składnia tej funkcji różni się w zależności od nazwy operacji listy. Każda implementacja zwraca wartości dla typu zasobu, który obsługuje operację listy. Nazwa operacji musi zaczynać się od list i może mieć sufiks. Niektóre typowe zastosowania to list, , listKeyslistKeyValuei listSecrets.

W aplikacji Bicep użyj funkcji list* .

Parametry

Parametr Wymagania Type Opis
resourceName lub resourceIdentifier Tak string Unikatowy identyfikator zasobu.
apiVersion Tak string Wersja interfejsu API stanu środowiska uruchomieniowego zasobów. Zazwyczaj w formacie rrrr-mm-dd.
functionValues Nie. obiekt Obiekt, który ma wartości dla funkcji. Udostępniaj ten obiekt tylko dla funkcji, które obsługują odbieranie obiektu z wartościami parametrów, takimi jak listAccountSas na koncie magazynu. Przykład przekazywania wartości funkcji jest pokazany w tym artykule.

Prawidłowe zastosowania

Funkcje listy mogą być używane we właściwościach definicji zasobu. Nie używaj funkcji listy, która uwidacznia poufne informacje w sekcji danych wyjściowych szablonu. Wartości wyjściowe są przechowywane w historii wdrożenia i mogą być pobierane przez złośliwego użytkownika.

W przypadku użycia z iteracją właściwości można użyć funkcji listy, input ponieważ wyrażenie jest przypisane do właściwości zasobu. Nie można ich używać, count ponieważ liczba musi zostać określona przed rozwiązaniem funkcji list.

Implementacje

Możliwe zastosowania programu list* przedstawiono w poniższej tabeli.

Typ zasobu Nazwa funkcji
Microsoft.Addons/supportProviders listsupportplaninfo
Microsoft.AnalysisServices/servers listGatewayStatus
Microsoft.ApiManagement/service/authorizationServers listSecrets
Microsoft.ApiManagement/service/gateways listKeys
Microsoft.ApiManagement/service/identityProviders listSecrets
Microsoft.ApiManagement/service/namedValues listValue
Microsoft.ApiManagement/service/openid Połączenie Providers listSecrets
Microsoft.ApiManagement/service/subscriptions listSecrets
Microsoft.AppConfiguration/configurationStores ListKeys
Microsoft.AppPlatform/Spring listTestKeys
Microsoft.Automation/automationAccounts listKeys
Microsoft.Batch/batchAccounts listKeys
Microsoft.BatchAI/workspaces/experiments/jobs listoutputfiles
Microsoft.BotService/botServices/channels listChannelWithKeys
Microsoft.Cache/redis listKeys
Microsoft.CognitiveServices/accounts listKeys
Microsoft.ContainerRegistry/rejestry listCredentials
Microsoft.ContainerRegistry/rejestry listUsages
Microsoft.ContainerRegistry/registries/agentpools listQueueStatus
Microsoft.ContainerRegistry/registries/buildTasks listSourceRepositoryProperties
Microsoft.ContainerRegistry/registries/buildTasks/steps listBuildArguments
Microsoft.ContainerRegistry/registries/taskruns listDetails
Microsoft.ContainerRegistry/registries/webhooks listEvents
Microsoft.ContainerRegistry/registries/runs listLogSasUrl
Microsoft.ContainerRegistry/rejestry/zadania listDetails
Microsoft.ContainerService/managedClusters listCluster Administracja Credential
Microsoft.ContainerService/managedClusters listClusterMonitoringUserCredential
Microsoft.ContainerService/managedClusters listClusterUserCredential
Microsoft.ContainerService/managedClusters/accessProfiles listCredential
Microsoft.DataBox/jobs listCredentials
Microsoft.DataFactory/datafactories/gateways listauthkeys
Microsoft.DataFactory/factory/integrationruntimes listauthkeys
Microsoft.DataLakeAnalytics/accounts/storageAccounts/Containers listSasTokens
Microsoft.DataShare/accounts/shares listSynchronizations
Microsoft.DataShare/accounts/shareSubscriptions listSourceShareSynchronization Ustawienia
Microsoft.DataShare/accounts/shareSubscriptions listSynchronizationDetails
Microsoft.DataShare/accounts/shareSubscriptions listSynchronizations
Microsoft.Devices/iotHubs listKeys
Microsoft.Devices/iotHubs/iotHubKeys listKeys
Microsoft.Devices/provisioningServices/keys listKeys
Microsoft.Devices/provisioningServices listKeys
Microsoft.DevTestLab/labs ListVhds
Microsoft.DevTestLab/labs/schedules ListApplicable
Microsoft.DevTestLab/labs/users/serviceFabrics ListApplicableSchedules
Microsoft.DevTestLab/labs/virtualMachines ListApplicableSchedules
Microsoft.DocumentDB/databaseAccounts listKeys
Microsoft.DocumentDB/databaseAccounts/notebookWorkspaces list Połączenie ionInfo
Microsoft.DomainRegistration/topLevelDomains listAgreements
Microsoft.EventHub/przestrzenie nazw/authorizationRules listKeys
Microsoft.EventHub/przestrzenie nazw/disasterRecoveryConfigs/authorizationRules listKeys
Microsoft.EventHub/namespaces/eventhubs/authorizationRules listKeys
Microsoft.ImportExport/jobs listBitLockerKeys
Microsoft.Kusto/Clusters/Databases ListPrincipals
Microsoft.LabServices/labs/users lista
Microsoft.LabServices/labs/virtualMachines lista
Microsoft.Logic/integrationAccounts/agreement listContentCallbackUrl
Microsoft.Logic/integrationAccounts/assemblies listContentCallbackUrl
Microsoft.Logic/integrationAccounts listCallbackUrl
Microsoft.Logic/integrationAccounts listKeyVaultKeys
Microsoft.Logic/integrationAccounts/maps listContentCallbackUrl
Microsoft.Logic/integrationAccounts/partners listContentCallbackUrl
Microsoft.Logic/integrationAccounts/schemas listContentCallbackUrl
Microsoft.Logic/workflows listCallbackUrl
Microsoft.Logic/workflows listSwagger
Microsoft.Logic/workflows/runs/actions listExpressionTraces
Microsoft.Logic/workflows/runs/actions/repetitions listExpressionTraces
Microsoft.Logic/workflows/triggers listCallbackUrl
Microsoft.Logic/workflows/versions/triggers listCallbackUrl
Microsoft.Machine Edukacja/webServices listkeys
Microsoft.Machine Edukacja/Workspaces listworkspacekeys
Microsoft. Mapy/konta listKeys
Microsoft.Media/mediaservices/assets listContainerSas
Microsoft.Media/mediaservices/assets listStreamingLocators
Microsoft.Media/mediaservices/streamingLocators listContentKeys
Microsoft.Media/mediaservices/streamingLocators listPaths
Microsoft.Network/applicationSecurityGroups listIpConfigurations
Microsoft.NotificationHubs/Przestrzenie nazw/authorizationRules listkeys
Microsoft.NotificationHubs/Przestrzenie nazw/NotificationHubs/authorizationRules listkeys
Microsoft.Operational Szczegółowe informacje/workspaces lista
Microsoft.Operational Szczegółowe informacje/workspaces listKeys
Microsoft.Policy Szczegółowe informacje/korygowania listDeployments
Microsoft.RedHatOpenShift/openShiftClusters listCredentials
Microsoft.Relay/przestrzenie nazw/authorizationRules listKeys
Microsoft.Relay/przestrzenie nazw/disasterRecoveryConfigs/authorizationRules listKeys
Microsoft.Relay/przestrzenie nazw/Hybrydowe Połączenie ions/authorizationRules listKeys
Microsoft.Relay/przestrzenie nazw/WcfRelays/authorizationRules listkeys
Microsoft.Search/searchServices list Administracja Keys
Microsoft.Search/searchServices listQueryKeys
Microsoft.ServiceBus/namespaces/authorizationRules listKeys
Microsoft.ServiceBus/przestrzenie nazw/disasterRecoveryConfigs/authorizationRules listKeys
Microsoft.ServiceBus/przestrzenie nazw/kolejki/autoryzacjaRules listKeys
Microsoft.SignalRService/SignalR listKeys
Microsoft.Storage/storageAccounts listAccountSas
Microsoft.Storage/storageAccounts listKeys
Microsoft.Storage/storageAccounts listServiceSas
Microsoft.StorSimple/managers/devices listFailoverSets
Microsoft.StorSimple/managers/devices listFailoverTargets
Microsoft.StorSimple/menedżerowie listActivationKey
Microsoft.StorSimple/menedżerowie listPublicEncryptionKey
Microsoft.Synapse/workspaces/integrationRuntimes listAuthKeys
Microsoft.Web/connectionGateways ListStatus
microsoft.web/connections listconsentlinks
Microsoft.Web/customApis listWsdlInterfaces
microsoft.web/locations listwsdlinterfaces
microsoft.web/apimanagementaccounts/apis/connections listconnectionkeys
microsoft.web/apimanagementaccounts/apis/connections listSecrets
microsoft.web/sites/backups lista
Microsoft.Web/sites/config lista
microsoft.web/sites/functions listKeys
microsoft.web/sites/functions listSecrets
microsoft.web/sites/hybridconnectionnamespaces/relays listKeys
microsoft.web/sites listsyncfunctiontriggerstatus
microsoft.web/sites/slots/functions listSecrets
microsoft.web/sites/slots/backups lista
Microsoft.Web/sites/slots/config lista
microsoft.web/sites/slots/functions listSecrets

Aby określić, które typy zasobów mają operację listy, dostępne są następujące opcje:

  • Wyświetl operacje interfejsu API REST dla dostawcy zasobów i poszukaj operacji listy. Na przykład konta magazynu mają operację listKeys.

  • Użyj polecenia cmdlet Get-AzProviderOperation programu PowerShell. Poniższy przykład pobiera wszystkie operacje listy dla kont magazynu:

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

  • Użyj następującego polecenia interfejsu wiersza polecenia platformy Azure, aby filtrować tylko operacje listy:

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

Wartość zwracana

Zwrócony obiekt różni się w zależności od używanej list funkcji. Na przykład dla listKeys konta magazynu zwraca następujący format:

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

Inne list funkcje mają różne formaty zwracane. Aby wyświetlić format funkcji, dołącz ją do sekcji danych wyjściowych, jak pokazano w przykładowym szablonie.

Uwagi

Określ zasób przy użyciu nazwy zasobu lub funkcji resourceId. W przypadku korzystania z list funkcji w tym samym szablonie, który wdraża przywołyny zasób, użyj nazwy zasobu.

Jeśli używasz list funkcji w zasobie, który jest wdrażany warunkowo, funkcja jest oceniana nawet wtedy, gdy zasób nie został wdrożony. Jeśli funkcja odwołuje się do zasobu, który nie istnieje, występuje błąd list . if Użyj funkcji , aby upewnić się, że funkcja jest oceniana tylko podczas wdrażania zasobu. Zobacz funkcję if dla przykładowego szablonu, który używa if elementu i list z warunkowo wdrożonym zasobem.

Przykład listy

W poniższym przykładzie użyto listKeys ustawienia wartości dla skryptów wdrażania.

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

W następnym przykładzie pokazano list funkcję, która przyjmuje parametr. W tym przypadku funkcja to listAccountSas. Przekaż obiekt przez czas wygaśnięcia. Czas wygaśnięcia musi być w przyszłości.

"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])

Określa, czy typ zasobu obsługuje strefy dla określonej lokalizacji lub regionu. Ta funkcja obsługuje tylko zasoby strefowe. Usługi strefowo nadmiarowe zwracają pustą tablicę. Aby uzyskać więcej informacji, zobacz Usługi platformy Azure, które obsługują Strefy dostępności.

W Bicep użyj funkcji pickZones .

Parametry

Parametr Wymagania Type Opis
providerNamespace Tak string Przestrzeń nazw dostawcy zasobów dla typu zasobu, aby sprawdzić obsługę strefy.
resourceType Tak string Typ zasobu do sprawdzania obsługi strefy.
lokalizacja Tak string Region, w którym ma być sprawdzana obsługa stref.
numberOfZones Nie. integer Liczba stref logicznych do zwrócenia. Wartość domyślna to 1. Liczba musi być dodatnią liczbą całkowitą z zakresu od 1 do 3. Użyj 1 dla zasobów z jedną strefą. W przypadku zasobów wielostrefowych wartość musi być mniejsza lub równa liczbie obsługiwanych stref.
offset Nie. integer Przesunięcie z początkowej strefy logicznej. Funkcja zwraca błąd, jeśli przesunięcie plus numberOfZones przekracza liczbę obsługiwanych stref.

Wartość zwracana

Tablica z obsługiwanymi strefami. W przypadku używania wartości domyślnych dla przesunięcia i numberOfZones, typ zasobu i region, który obsługuje strefy, zwraca następującą tablicę:

[
    "1"
]

numberOfZones Gdy parametr jest ustawiony na wartość 3, zwraca:

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

Gdy typ zasobu lub region nie obsługuje stref, zwracana jest pusta tablica. Pusta tablica jest również zwracana dla strefowo nadmiarowych usług.

[
]

Uwagi

Istnieją różne kategorie dla usługi Azure Strefy dostępności — strefowe i strefowo nadmiarowe. Funkcja pickZones może służyć do zwracania strefy dostępności dla zasobu strefowego. W przypadku strefowo nadmiarowych usług (ZRS) funkcja zwraca pustą tablicę. Zasoby strefowe zwykle mają zones właściwość na najwyższym poziomie definicji zasobu. Aby określić kategorię obsługi stref dostępności, zobacz Usługi platformy Azure, które obsługują Strefy dostępności.

Aby określić, czy dany region lub lokalizacja platformy Azure obsługuje strefy dostępności, wywołaj pickZones funkcję z typem zasobu strefowego, takim jak Microsoft.Network/publicIPAddresses. Jeśli odpowiedź nie jest pusta, region obsługuje strefy dostępności.

przykład pickZones

Poniższy szablon przedstawia trzy wyniki użycia pickZones funkcji.

{
  "$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')]"
    }
  }
}

Dane wyjściowe z powyższych przykładów zwracają trzy tablice.

Nazwisko Typ Wartość
Obsługiwane tablica [ "1" ]
notSupportedRegion tablica []
notSupportedType tablica []

Możesz użyć odpowiedzi z pickZones , aby określić, czy zapewnić wartość null dla stref, czy przypisać maszyny wirtualne do różnych stref. W poniższym przykładzie ustawiono wartość strefy na podstawie dostępności stref.

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

Usługa Azure Cosmos DB nie jest zasobem strefowym, ale możesz użyć pickZones funkcji , aby określić, czy włączyć nadmiarowość strefy dla georeplikacji. Przekaż typ zasobu Microsoft.Storage/storageAccounts, aby określić, czy włączyć nadmiarowość strefy.

"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')]"
    }
  }
]

dostawców

Funkcja providers została przestarzała w szablonach usługi ARM. Nie zalecamy już korzystania z niego. Jeśli używasz tej funkcji do pobrania wersji interfejsu API dla dostawcy zasobów, zalecamy podanie określonej wersji interfejsu API w szablonie. Użycie dynamicznie zwracanej wersji interfejsu API może spowodować przerwanie szablonu, jeśli właściwości zmienią się między wersjami.

W Bicep funkcja providers jest przestarzała.

Operacja dostawców jest nadal dostępna za pośrednictwem interfejsu API REST. Można go użyć poza szablonem usługi ARM, aby uzyskać informacje o dostawcy zasobów.

reference

W szablonach bez nazw symbolicznych:

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

W szablonach z nazwami symbolicznymi:

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

Zwraca obiekt reprezentujący stan środowiska uruchomieniowego zasobu. Dane wyjściowe i zachowanie reference funkcji bardzo zależy od tego, jak każdy dostawca zasobów implementuje odpowiedzi PUT i GET. Aby zwrócić tablicę obiektów reprezentujących stany środowiska uruchomieniowego kolekcji zasobów, zobacz odwołania.

Bicep udostępnia funkcję referencyjną, ale w większości przypadków funkcja referencyjna nie jest wymagana. Zaleca się zamiast tego użycie nazwy symbolicznej zasobu. Zobacz dokumentację.

Parametry

Parametr Wymagania Type Opis
resourceName/resourceIdentifier lub symbolicName/resourceIdentifier Tak string W szablonach bez nazw symbolicznych określ nazwę lub unikatowy identyfikator zasobu. Podczas odwoływania się do zasobu w bieżącym szablonie podaj tylko nazwę zasobu jako parametr. W przypadku odwoływania się do wcześniej wdrożonego zasobu lub gdy nazwa zasobu jest niejednoznaczna, podaj identyfikator zasobu.
W szablonach z nazwami symbolicznymi określ nazwę symboliczną lub unikatowy identyfikator zasobu. Podczas odwoływania się do zasobu w bieżącym szablonie podaj tylko nazwę symboliczną zasobu jako parametr. W przypadku odwoływania się do wcześniej wdrożonego zasobu podaj identyfikator zasobu.
apiVersion Nie. string Wersja interfejsu API określonego zasobu. Ten parametr jest wymagany, gdy zasób nie jest aprowizowany w ramach tego samego szablonu. Zazwyczaj w formacie rrrr-mm-dd. Aby uzyskać prawidłowe wersje interfejsu API dla zasobu, zobacz dokumentację szablonu.
"Pełny" Nie. string Wartość określająca, czy zwracać pełny obiekt zasobu. Jeśli nie określisz 'Full'parametru , zwracany jest tylko obiekt właściwości zasobu. Pełny obiekt zawiera wartości, takie jak identyfikator zasobu i lokalizacja.

Wartość zwracana

Każdy typ zasobu zwraca różne właściwości funkcji referencyjnej. Funkcja nie zwraca pojedynczego, wstępnie zdefiniowanego formatu. Zwracana wartość różni się również na podstawie wartości argumentu 'Full' . Aby wyświetlić właściwości typu zasobu, zwróć obiekt w sekcji danych wyjściowych, jak pokazano w przykładzie.

Uwagi

Funkcja referencyjna pobiera stan środowiska uruchomieniowego wcześniej wdrożonego zasobu lub zasobu wdrożonego w bieżącym szablonie. W tym artykule przedstawiono przykłady dla obu scenariuszy.

Zazwyczaj funkcja służy reference do zwracania określonej wartości z obiektu, takiego jak identyfikator URI punktu końcowego obiektu blob lub w pełni kwalifikowana nazwa domeny.

"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]"
  }
}

Użyj 'Full' wartości, jeśli potrzebujesz wartości zasobów, które nie są częścią schematu właściwości. Aby na przykład ustawić zasady dostępu do magazynu kluczy, pobierz właściwości tożsamości dla maszyny wirtualnej.

{
  "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"
          ]
        }
      }
    ],
    ...

Prawidłowe zastosowania

Funkcja reference może być używana tylko w sekcji danych wyjściowych szablonu lub wdrożenia i obiektu właściwości definicji zasobu. Nie można jej używać dla właściwości zasobów, takich jak type, namelocation i inne właściwości najwyższego poziomu definicji zasobu. W przypadku użycia z iteracją właściwości można użyć reference funkcji , input ponieważ wyrażenie jest przypisane do właściwości zasobu.

Nie można użyć reference funkcji, aby ustawić wartość count właściwości w pętli kopiowania. Możesz użyć polecenia , aby ustawić inne właściwości w pętli. Odwołanie jest zablokowane dla właściwości count, ponieważ ta właściwość musi zostać określona przed rozwiązaniem reference funkcji.

Aby użyć reference funkcji lub dowolnej list* funkcji w sekcji danych wyjściowych szablonu zagnieżdżonego, należy ustawić expressionEvaluationOptions parametr , aby używać oceny zakresu wewnętrznego lub użyć połączonego zamiast szablonu zagnieżdżonego.

Jeśli używasz reference funkcji w zasobie, który jest wdrażany warunkowo, funkcja jest oceniana nawet wtedy, gdy zasób nie został wdrożony. Jeśli funkcja odwołuje się do zasobu, który nie istnieje, występuje błąd reference . if Użyj funkcji , aby upewnić się, że funkcja jest oceniana tylko podczas wdrażania zasobu. Zobacz funkcję if dla przykładowego szablonu, który używa if elementu i reference z warunkowo wdrożonym zasobem.

Zależność niejawna

Korzystając z reference funkcji, niejawnie deklarujesz, że jeden zasób zależy od innego zasobu, jeśli przywoływanego zasobu jest aprowizowane w ramach tego samego szablonu i odwołujesz się do zasobu według jego nazwy (a nie identyfikatora zasobu). Nie musisz również używać dependsOn właściwości . Funkcja nie jest oceniana do momentu ukończenia wdrożenia przywołytowanego zasobu.

Nazwa zasobu, nazwa symboliczna lub identyfikator

W przypadku odwoływania się do zasobu wdrożonego w tym samym szablonie none-symbolicznej nazwy podaj nazwę zasobu.

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

W przypadku odwoływania się do zasobu wdrożonego w tym samym szablonie o tej samej nazwie symbolicznej podaj symboliczną nazwę zasobu.

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

Or

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

W przypadku odwoływania się do zasobu, który nie został wdrożony w tym samym szablonie, podaj identyfikator zasobu i apiVersion.

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

Aby uniknąć niejednoznaczności co do którego zasobu odwołujesz się, możesz podać w pełni kwalifikowany identyfikator zasobu.

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

Podczas konstruowania w pełni kwalifikowanego odwołania do zasobu kolejność łączenia segmentów z typu i nazwy nie jest po prostu łączeniem tych dwóch segmentów. Zamiast tego, po przestrzeni nazw, należy użyć sekwencji par typów/nazw z najmniej specyficznych do najbardziej specyficznych:

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

Na przykład:

Microsoft.Compute/virtualMachines/myVM/extensions/myExtjest poprawna, jest niepoprawna Microsoft.Compute/virtualMachines/extensions/myVM/myExt

Aby uprościć tworzenie dowolnego identyfikatora zasobu, użyj resourceId() funkcji opisanych w tym dokumencie zamiast concat() funkcji.

Uzyskiwanie tożsamości zarządzanej

Tożsamości zarządzane dla zasobów platformy Azure to typy zasobów rozszerzeń tworzone niejawnie dla niektórych zasobów. Ponieważ tożsamość zarządzana nie jest jawnie zdefiniowana w szablonie, należy odwołać się do zasobu, do którego jest stosowana tożsamość. Użyj Full polecenia , aby pobrać wszystkie właściwości, w tym niejawnie utworzoną tożsamość.

Wzorzec to:

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

Aby na przykład uzyskać identyfikator podmiotu zabezpieczeń dla tożsamości zarządzanej, która jest stosowana do maszyny wirtualnej, użyj:

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

Aby uzyskać identyfikator dzierżawy dla tożsamości zarządzanej, która jest stosowana do zestawu skalowania maszyn wirtualnych, użyj:

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

Przykład odwołania

W poniższym przykładzie wdrożono zasób i odwołuje się do tego zasobu.

{
  "$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')]"
    }
  }
}

Powyższy przykład zwraca dwa obiekty. Obiekt properties ma następujący 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
}

Pełny obiekt ma następujący 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"
}

Poniższy przykładowy szablon odwołuje się do konta magazynu, które nie zostało wdrożone w tym szablonie. Konto magazynu już istnieje w ramach tej samej subskrypcji.

{
  "$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')]"
    }
  }
}

odwołania

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

Funkcja references działa podobnie jak reference. Zamiast zwracać obiekt przedstawiający stan środowiska uruchomieniowego zasobu, references funkcja zwraca tablicę obiektów reprezentujących stany środowiska uruchomieniowego kolekcji zasobów. Ta funkcja wymaga wersji 2.0 języka szablonu usługi ARM i z włączoną nazwą symboliczną:

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

W Bicep nie ma jawnej references funkcji. Zamiast tego użycie kolekcji symbolicznej jest stosowane bezpośrednio, a podczas generowania kodu Bicep tłumaczy go na szablon usługi ARM, który korzysta z funkcji szablonu references usługi ARM. Aby uzyskać więcej informacji, zobacz Odwołania do kolekcji zasobów/modułów.

Parametry

Parametr Wymagania Type Opis
Symboliczna nazwa kolekcji zasobów Tak string Symboliczna nazwa kolekcji zasobów zdefiniowanej w bieżącym szablonie. Funkcja references nie obsługuje odwoływania się do zasobów zewnętrznych z bieżącym szablonem.
"Full", "Properties" Nie. string Wartość określająca, czy zwracać tablicę pełnych obiektów zasobów. Domyślna wartość to 'Properties'. Jeśli nie określisz 'Full'parametru , zwracane są tylko obiekty właściwości zasobów. Pełny obiekt zawiera wartości, takie jak identyfikator zasobu i lokalizacja.

Wartość zwracana

Tablica kolekcji zasobów. Każdy typ zasobu zwraca różne właściwości funkcji reference . Zwracana wartość różni się również na podstawie wartości argumentu 'Full' . Aby uzyskać więcej informacji, zobacz dokumentację.

Kolejność danych wyjściowych references elementu jest zawsze rozmieszczana w kolejności rosnącej na podstawie indeksu kopiowania. W związku z tym pierwszy zasób w kolekcji z indeksem 0 jest wyświetlany jako pierwszy, po którym następuje indeks 1 itd. Na przykład [worker-0, worker-1, worker-2, ...].

W poprzednim przykładzie, jeśli proces roboczy-0 i proces roboczy-2 są wdrażane, podczas gdy proces roboczy-1 nie jest spowodowany fałszywym warunkiem, dane wyjściowe references polecenia spowodują pominięcie niedróżnie wdrożonego zasobu i wyświetlenie wdrożonych zasobów uporządkowanych według ich liczb. Dane wyjściowe references to [worker-0, worker-2, ...]. Jeśli wszystkie zasoby zostaną pominięte, funkcja zwróci pustą tablicę.

Prawidłowe zastosowania

Funkcji references nie można używać w pętlach kopiowania zasobów ani w pętli Bicep. Na przykład references nie jest dozwolone w następującym scenariuszu:

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

Aby użyć references funkcji lub dowolnej list* funkcji w sekcji danych wyjściowych szablonu zagnieżdżonego, należy ustawić expressionEvaluationOptions parametr , aby używać oceny zakresu wewnętrznego lub użyć połączonego zamiast szablonu zagnieżdżonego.

Zależność niejawna

Korzystając z references funkcji, niejawnie deklarujesz, że jeden zasób zależy od innego zasobu. Nie musisz również używać dependsOn właściwości . Funkcja nie jest oceniana do momentu ukończenia wdrożenia przywołytowanego zasobu.

Przykład odwołania

Poniższy przykład wdraża kolekcję zasobów i odwołuje się do tej kolekcji zasobów.

{
  "$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')]"
    }
  }
}

Powyższy przykład zwraca trzy obiekty.

"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"
      },
      ...
    ]
  }
}

resourceGroup

Zobacz funkcję zakresu resourceGroup.

W Bicep użyj funkcji zakresu grupy zasobów.

resourceId

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

Zwraca unikatowy identyfikator zasobu. Ta funkcja jest używana, gdy nazwa zasobu jest niejednoznaczna lub nie jest aprowizowana w ramach tego samego szablonu. Format zwróconego identyfikatora różni się w zależności od tego, czy wdrożenie odbywa się w zakresie grupy zasobów, subskrypcji, grupy zarządzania lub dzierżawy.

W Bicep użyj funkcji resourceId .

Parametry

Parametr Wymagania Type Opis
subscriptionId Nie. string (w formacie GUID) Wartość domyślna to bieżąca subskrypcja. Określ tę wartość, gdy musisz pobrać zasób w innej subskrypcji. Podaj tę wartość tylko podczas wdrażania w zakresie grupy zasobów lub subskrypcji.
resourceGroupName Nie. string Wartość domyślna to bieżąca grupa zasobów. Określ tę wartość, gdy musisz pobrać zasób w innej grupie zasobów. Podaj tę wartość tylko podczas wdrażania w zakresie grupy zasobów.
resourceType Tak string Typ zasobu, w tym przestrzeń nazw dostawcy zasobów.
resourceName1 Tak string Nazwa zasobu.
resourceName2 Nie. string W razie potrzeby następny segment nazw zasobów.

Kontynuuj dodawanie nazw zasobów jako parametrów, gdy typ zasobu zawiera więcej segmentów.

Wartość zwracana

Identyfikator zasobu jest zwracany w różnych formatach w różnych zakresach:

  • Zakres grupy zasobów:

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

  • Zakres subskrypcji:

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

  • Zakres grupy zarządzania lub dzierżawy:

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

Aby uniknąć nieporozumień, zalecamy, aby nie używać resourceId ich podczas pracy z zasobami wdrożonym w subskrypcji, grupie zarządzania lub dzierżawie. Zamiast tego należy użyć funkcji ID, która jest przeznaczona dla zakresu.

Uwagi

Liczba parametrów, które podajesz, różni się w zależności od tego, czy zasób jest zasobem nadrzędnym, czy podrzędnym, i czy zasób znajduje się w tej samej subskrypcji lub grupie zasobów.

Aby uzyskać identyfikator zasobu dla zasobu nadrzędnego w tej samej subskrypcji i grupie zasobów, podaj typ i nazwę zasobu.

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

Aby uzyskać identyfikator zasobu podrzędnego, zwróć uwagę na liczbę segmentów w typie zasobu. Podaj nazwę zasobu dla każdego segmentu typu zasobu. Nazwa segmentu odpowiada zasobowi, który istnieje dla tej części hierarchii.

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

Aby uzyskać identyfikator zasobu dla zasobu w tej samej subskrypcji, ale innej grupie zasobów, podaj nazwę grupy zasobów.

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

Aby uzyskać identyfikator zasobu dla zasobu w innej subskrypcji i grupie zasobów, podaj identyfikator subskrypcji i nazwę grupy zasobów.

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

Często należy użyć tej funkcji podczas korzystania z konta magazynu lub sieci wirtualnej w alternatywnej grupie zasobów. W poniższym przykładzie pokazano, jak można łatwo użyć zasobu z zewnętrznej grupy zasobów:

{
  "$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')]"
              }
            }
          }
        ]
      }
    }
  ]
}

Przykład identyfikatora zasobu

Poniższy przykład zwraca identyfikator zasobu dla konta magazynu w grupie zasobów:

{
  "$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')]"
    }
  }
}

Dane wyjściowe z poprzedniego przykładu z wartościami domyślnymi to:

Nazwisko Typ Wartość
sameRGOutput String /subscriptions/{current-sub-id}/resourceGroups/examplegroup/providers/Microsoft.Storage/storageAccounts/examplestorage
differentRGOutput String /subscriptions/{current-sub-id}/resourceGroups/otherResourceGroup/providers/Microsoft.Storage/storageAccounts/examplestorage
differentSubOutput String /subscriptions/11111111-1111-1111-1111-1111111111/resourceGroups/otherResourceGroup/providers/Microsoft.Storage/storageAccounts/examplestorage
nestedResourceOutput String /subscriptions/{current-sub-id}/resourceGroups/examplegroup/providers/Microsoft.SQL/servers/serverName/databases/databaseName

subskrypcja

Zobacz funkcję zakresu subskrypcji.

W aplikacji Bicep użyj funkcji zakresu subskrypcji .

subscriptionResourceId

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

Zwraca unikatowy identyfikator zasobu wdrożonego na poziomie subskrypcji.

W Bicep użyj funkcji subscriptionResourceId .

Parametry

Parametr Wymagania Type Opis
subscriptionId Nie. ciąg (w formacie GUID) Wartość domyślna to bieżąca subskrypcja. Określ tę wartość, gdy musisz pobrać zasób w innej subskrypcji.
resourceType Tak string Typ zasobu, w tym przestrzeń nazw dostawcy zasobów.
resourceName1 Tak string Nazwa zasobu.
resourceName2 Nie. string W razie potrzeby następny segment nazw zasobów.

Kontynuuj dodawanie nazw zasobów jako parametrów, gdy typ zasobu zawiera więcej segmentów.

Wartość zwracana

Identyfikator jest zwracany w następującym formacie:

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

Uwagi

Ta funkcja służy do pobierania identyfikatora zasobu dla zasobów wdrożonych w subskrypcji , a nie grupy zasobów. Zwrócony identyfikator różni się od wartości zwracanej przez funkcję resourceId , nie uwzględniając wartości grupy zasobów.

przykład subscriptionResourceID

Poniższy szablon przypisuje wbudowaną rolę. Można go wdrożyć w grupie zasobów lub subskrypcji. Używa subscriptionResourceId funkcji , aby uzyskać identyfikator zasobu dla ról wbudowanych.

{
  "$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], ...)

Zwraca unikatowy identyfikator zasobu wdrożonego na poziomie grupy zarządzania.

W Bicep użyj funkcji managementGroupResourceId .

Parametry

Parametr Wymagania Type Opis
managementGroupResourceId Nie. ciąg (w formacie GUID) Wartość domyślna to bieżąca grupa zarządzania. Określ tę wartość, gdy musisz pobrać zasób w innej grupie zarządzania.
resourceType Tak string Typ zasobu, w tym przestrzeń nazw dostawcy zasobów.
resourceName1 Tak string Nazwa zasobu.
resourceName2 Nie. string W razie potrzeby następny segment nazw zasobów.

Kontynuuj dodawanie nazw zasobów jako parametrów, gdy typ zasobu zawiera więcej segmentów.

Wartość zwracana

Identyfikator jest zwracany w następującym formacie:

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

Uwagi

Ta funkcja służy do pobierania identyfikatora zasobu dla zasobów wdrożonych w grupie zarządzania, a nie grupy zasobów. Zwrócony identyfikator różni się od wartości zwracanej przez funkcję resourceId , nie uwzględniając identyfikatora subskrypcji i wartości grupy zasobów.

przykład managementGroupResourceID

Poniższy szablon tworzy i przypisuje definicję zasad. Używa managementGroupResourceId funkcji , aby uzyskać identyfikator zasobu dla definicji zasad.

{
  "$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], ...)

Zwraca unikatowy identyfikator zasobu wdrożonego na poziomie dzierżawy.

W Bicep użyj funkcji tenantResourceId .

Parametry

Parametr Wymagania Type Opis
resourceType Tak string Typ zasobu, w tym przestrzeń nazw dostawcy zasobów.
resourceName1 Tak string Nazwa zasobu.
resourceName2 Nie. string W razie potrzeby następny segment nazw zasobów.

Kontynuuj dodawanie nazw zasobów jako parametrów, gdy typ zasobu zawiera więcej segmentów.

Wartość zwracana

Identyfikator jest zwracany w następującym formacie:

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

Uwagi

Ta funkcja służy do pobierania identyfikatora zasobu dla zasobu wdrożonego w dzierżawie. Zwrócony identyfikator różni się od wartości zwracanych przez inne funkcje identyfikatora zasobu, nie uwzględniając wartości grupy zasobów lub subskrypcji.

przykład tenantResourceId

Wbudowane definicje zasad to zasoby na poziomie dzierżawy. Aby wdrożyć przypisanie zasad odwołujące się do wbudowanej tenantResourceId definicji zasad, użyj funkcji .

{
  "$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'))]"
      }
    }
  ]
}

Następne kroki