دالات الموارد لقوالب ARM

مقالة
03/18/2024

يوفر Resource Manager الدالات التالية للحصول على قيم الموارد في قالب Azure Resource Manager (قالب ARM):

extensionResourceId
list*
pickZones
providers (deprecated)
reference
مراجع
resourceId
subscriptionResourceId
managementGroupResourceId
tenantResourceId

للحصول على قيم من المعلمات أو المتغيرات أو النشر الحالي، راجع دالات قيمة النشر.

للحصول على قيم نطاق التوزيع، راجع وظائف النطاق.

تلميح

نوصي باستخدام Bicep لأنها تقدم نفس الإمكانات التي توفرها نماذج ARM ولأن البنية أسهل في الاستخدام. لمعرفة المزيد، راجع دوال resource.

extensionResourceId

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

إرجاع معرف المورد لمورد ملحق. مورد الملحق هو نوع مورد يتم تطبيقه على مورد آخر لإضافته إلى قدراته.

في Bicep، استخدم دالة extensionResourceId.

المعلمات

المعلمة‬	المطلوب	نوع	‏‏الوصف
baseResourceId	‏‏نعم‬	سلسلة	معرّف المورد للمورد الذي تم تطبيق مورد الملحق عليه.
resourceType	‏‏نعم‬	سلسلة	نوع مورد الامتداد بما في ذلك مساحة اسم مزود المورد.
resourceName1	‏‏نعم‬	سلسلة	اسم مورد الملحق.
resourceName2	لا	سلسلة	مقطع اسم المورد التالي، إذا لزم الأمر.

استمر في إضافة أسماء الموارد كمعلمات عندما يتضمن نوع المورد مزيدًا من المقاطع.

قيمة الإرجاع

التنسيق الأساسي لمعرف المورد الذي تم إرجاعه بواسطة هذه الدالة هو:

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

يختلف مقطع النطاق حسب المورد الأساسي الذي يتم توسيعه. على سبيل المثال، يحتوي معرف اشتراك على مقاطع مختلفة عن معرف مجموعة موارد.

عند تطبيق مورد الملحق على مورد، يتم إرجاع معرف المورد بالتنسيق التالي:

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

عند تطبيق مورد الملحق على مجموعة موارد، يكون التنسيق الذي تم إرجاعه هو:

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

يتم عرض مثال لاستخدام هذه الدالة مع مجموعة موارد في القسم التالي.

عندما يتم تطبيق مورد الملحق على اشتراك، يكون التنسيق الذي تم إرجاعه هو:

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

عند تطبيق مورد الملحق على مجموعة إدارة، يكون التنسيق الذي تم إرجاعه هو:

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

يتم عرض مثال لاستخدام هذه الدالة مع مجموعة إدارة في القسم التالي.

extensionResourceId example

يعرض المثال التالي معرّف المورد لقفل مجموعة الموارد.

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

يتم تطبيق تعريف نهج مخصص تم توزيعه في مجموعة إدارة كمورد ملحق. لإنشاء سياسة وتعيينها، انشر القالب التالي إلى مجموعة إدارة.

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

تعريفات النهج المضمنة هي موارد على مستوى المستأجر. للحصول على مثال لنشر تعريف نهج مضمن، راجع tenantResourceId.

list*

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

يختلف بناء جملة هذه الدالة حسب اسم عمليات القائمة. يقوم كل تطبيق بإرجاع قيم لنوع المورد الذي يدعم عملية القائمة. يجب أن يبدأ اسم العملية بـ list ثم قد يكون لاحقة. بعض الاستخدامات الشائعة هي list وlistKeys وlistKeyValue وlistSecrets.

في Bicep، استخدم دالة list *.

المعلمات

المعلمة‬	المطلوب	نوع	‏‏الوصف
resourceName أو resourceIdentifier	‏‏نعم‬	سلسلة	المعرف الفريد للمورد.
apiVersion	‏‏نعم‬	سلسلة	إصدار API من حالة وقت تشغيل المورد. عادة، في الشكل، yyyy-mm-dd.
functionValues	لا	كائن	كائن يحتوي على قِيَم الدالة. قم بتوفير هذا العنصر فقط للدوال التي تدعم تلقي عنصر بقيم معلمات، مثل `listAccountSas` على حساب التخزين. يتم عرض مثال على تمرير قِيم الدالة في هذه المقالة.

الاستخدامات الصالحة

يمكن استخدام دالة القائمة في خصائص تعريف المورد. لا تستخدم دالة القائمة التي تعرض معلومات حساسة في قسم المخرجات بالقالب. يتم تخزين قِيَم الإخراج في محفوظات التوزيع ويمكن استردادها بواسطة مستخدم ضار.

عند استخدامها مع تكرار الخاصية، يمكنك استخدام دالات القائمة input لأن التعبير تم تعيينه إلى خاصية المورد. لا يمكنك استخدامها مع count لأنه يجب تحديد العدد قبل حل دالة القائمة.

تطبيقات

يتم عرض الاستخدامات المحتملة list* في الجدول التالي.

نوع المورد	اسم الوظيفة
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/openidConnectProviders	listSecrets
Microsoft.ApiManagement/service/subscriptions	listSecrets
مايكروسوفت.AppConfiguration/configurationStores	ListKeys
مايكروسوفت 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/registries	listCredentials
Microsoft.ContainerRegistry/registries	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/registries/tasks	listDetails
Microsoft.ContainerService/managedClusters	listClusterAdminCredential
Microsoft.ContainerService/managedClusters	listClusterMonitoringUserCredential
Microsoft.ContainerService/managedClusters	listClusterUserCredential
Microsoft.ContainerService/managedClusters/accessProfiles	listCredential
Microsoft.DataBox/jobs	listCredentials
Microsoft.DataFactory/datafactories/gateways	listauthkeys
Microsoft.DataFactory/factories/integrationruntimes	listauthkeys
Microsoft.DataLakeAnalytics/accounts/storageAccounts/Containers	listSasTokens
Microsoft.DataShare/accounts/shares	listSynchronizations
Microsoft.DataShare/accounts/shareSubscriptions	listSourceShareSynchronizationSettings
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	listConnectionInfo
Microsoft.DomainRegistration/topLevelDomains	listAgreements
Microsoft.EventHub/namespaces/authorizationRules	listKeys
Microsoft.EventHub/namespaces/disasterRecoveryConfigs/authorizationRules	listKeys
Microsoft.EventHub/namespaces/eventhubs/authorizationRules	listKeys
Microsoft.ImportExport/jobs	listBitLockerKeys
Microsoft.Kusto/Clusters/Databases	ListPrincipals
Microsoft.LabServices/labs/users	list
Microsoft.LabServices/labs/virtualMachines	list
Microsoft.Logic/integrationAccounts/agreements	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.MachineLearning/webServices	listkeys
Microsoft.MachineLearning/Workspaces	listworkspacekeys
Microsoft.Maps/accounts	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/Namespaces/authorizationRules	listkeys
Microsoft.NotificationHubs/Namespaces/NotificationHubs/authorizationRules	listkeys
مساحات عمل Microsoft.OperationalInsights	list
مساحات عمل Microsoft.OperationalInsights	listKeys
Microsoft.PolicyInsights/remediations	listDeployments
Microsoft.RedHatOpenShift/openShiftClusters	listCredentials
Microsoft.Relay/namespaces/authorizationRules	listKeys
Microsoft.Relay/namespaces/disasterRecoveryConfigs/authorizationRules	listKeys
Microsoft.Relay/namespaces/HybridConnections/authorizationRules	listKeys
مايكروسوفت.ترحيل/مساحات الأسماء/WcfRelays/التخويلالصون	listkeys
Microsoft.Search/searchServices	listAdminKeys
Microsoft.Search/searchServices	listQueryKeys
Microsoft.ServiceBus/namespaces/authorizationRules	listKeys
Microsoft.ServiceBus/namespaces/disasterRecoveryConfigs/authorizationRules	listKeys
Microsoft.ServiceBus/namespaces/queues/authorizationRules	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/managers	listActivationKey
Microsoft.StorSimple/managers	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	list
Microsoft.Web/sites/config	list
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	list
Microsoft.Web/sites/slots/config	list
microsoft.web/sites/slots/functions	listSecrets

لتحديد أنواع الموارد التي لها عملية قائمة، تتوفر لديك الخيارات التالية:

عرض عمليات REST API لموفر مورد والبحث عن عمليات القائمة. على سبيل المثال، تحتوي حسابات التخزين على عملية listKeys.
استخدم Get-AzProviderOperation في PowerShell cmdlet. يحصل المثال التالي على جميع عمليات القائمة لحسابات التخزين:
```
Get-AzProviderOperation -OperationSearchString "Microsoft.Storage/*" | where {$_.Operation -like "*list*"} | FT Operation
```

استخدم أمر Azure CLI التالي لتصفية عمليات القائمة فقط:

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

قيمة الإرجاع

يختلف العنصر الذي تم إرجاعه حسب الدالة list التي تستخدمها. على سبيل المثال، ترجع listKeys لحساب التخزين التنسيق التالي:

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

دالات list أخرى لها تنسيقات إرجاع مختلفة. للاطلاع على تنسيق دالة، قم بتضمينها في قسم المخرجات كما هو موضح في نموذج المثال.

الملاحظات

حدد المورد باستخدام اسم المورد أو الدالة resourceId. عند استخدام دالة list في نفس القالب الذي يوزع المورد المشار إليه، استخدم اسم المورد.

إذا كنت تستخدم دالة list في مورد تم نشره بشكل شرطي، فسيتم تقييم الدالة حتى إذا لم يتم نشر المورد. تحصل على خطأ إذا كانت الدالة list تشير إلى مورد غير موجود. استخدم الدالة if للتأكد من تقييم الدالة فقط عند نشر المورد. راجع الوظيفة if لقالب نموذج يستخدم if وlist مع مورد نشر مشروط.

مثال القائمة

يستخدم المثال التالي listKeys عند تعيين قيمة لبرامج التوزيع النصية.

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

يعرض المثال التالي دالة list التي تأخذ معلمة. في هذه الحالة، الدالة هي listAccountSas. تمرير كائن لوقت انتهاء الصلاحية. يجب أن يكون وقت انتهاء الصلاحية في المستقبل.

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

يحدد ما إذا كان نوع المورد يدعم مناطق للموقع أو المنطقة المحددة. تدعم هذه الدالة الموارد المناطقية فقط. خدمات المنطقة المكررة ترجع صفيفًا فارغًا. لمزيد من المعلومات، راجع خدمات Azure التي تدعم مناطق التوفر.

في Bicep، استخدم دالة pickZones.

المعلمات

المعلمة‬	المطلوب	نوع	‏‏الوصف
providerNamespace	‏‏نعم‬	سلسلة	مساحة اسم موفر المورد لنوع المورد للتحقق من دعم المنطقة.
resourceType	‏‏نعم‬	سلسلة	نوع المورد للتحقق من دعم المنطقة.
موقع	‏‏نعم‬	سلسلة	المنطقة التي يجب التحقق فيها من دعم المنطقة.
numberOfZones	لا	integer	عدد المناطق المنطقية التي يجب إرجاعها. الإعداد الافتراضي هو 1. يجب أن يكون الرقم عدداً صحيحاً موجباً من 1 إلى 3. استخدم 1 للموارد المخصصة لمناطق واحدة. بالنسبة للموارد متعددة المناطق، يجب أن تكون القيمة أقل من عدد المناطق المدعومة أو مساوية لها.
إزاحة	لا	integer	الإزاحة من منطقة البداية المنطقية. تقوم الوظيفة بإرجاع خطأ إذا تجاوزت الإزاحة بالإضافة إلى numberOfZones عدد المناطق المدعومة.

قيمة الإرجاع

مجموعة مع المناطق المدعومة. عند استخدام القيم الافتراضية للإزاحة وnumberOfZones، يقوم نوع المورد والمنطقة التي تدعم المناطق بإرجاع الصفيف التالي:

[
    "1"
]

عندما يتم ضبط المعلمة numberOfZones على 3، فإنها ترجع:

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

عندما لا يدعم نوع المورد أو المنطقة المناطق، يتم إرجاع مصفوفة فارغة. يتم أيضًا إرجاع مصفوفة فارغة لخدمات المنطقة الاحتياطية.

[
]

الملاحظات

هناك فئات مختلفة لمناطق توافر Azure - مناطق مناطقية واحتياطية. يمكن استخدام الدالة pickZones لإرجاع منطقة توفر لمورد منطقة. بالنسبة لخدمات المنطقة المكررة (ZRS)، ترجع الدالة صفيفًا فارغًا. الموارد المناطقية عادة ما تحتوي على خاصية zones في المستوى الأعلى من تعريف المورد. لتحديد فئة الدعم لمناطق التوفر، راجع خدمات Azure التي تدعم مناطق التوفر.

لتحديد ما إذا كانت منطقة أو موقع Azure معين يدعم مناطق التوفر، استدعِ الدالة pickZones ذات نوع مورد منطقة، مثل Microsoft.Network/publicIPAddresses. إذا كانت الاستجابة غير فارغة، فإن المنطقة تدعم مناطق التوفر.

pickZones example

يعرض القالب التالي ثلاث نتائج لاستخدام الدالة pickZones.

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

يُرجع الإخراج من الأمثلة السابقة ثلاث مصفوفات.

Name	نوع	القيمة‬
مدعومة	صفيف	[ "1" ]
notSupportedRegion	صفيف	[]
notSupportedType	صفيف	[]

يمكنك استخدام الاستجابة من pickZones لتحديد ما إذا كنت تريد توفير قِيَم خالية للمناطق أو تعيين أجهزة ظاهرية لمناطق مختلفة. يعيّن المثال التالي قيمة المنطقة بناءً على توفر المناطق.

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

لا يعد Azure Cosmos DB موردا مناطقيا، ولكن يمكنك استخدام الدالة pickZones لتحديد ما إذا كان يجب تمكين تكرار المنطقة للتبسيط الجغرافي. قم بتمرير نوع مورد Microsoft.Storage/storageAccounts لتحديد ما إذا كان سيتم تمكين التكرار في المنطقة أم لا.

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

الموفرون

تم إيقاف وظيفة الموفرين في قوالب ARM. لم نعد نوصي باستخدامها. إذا استخدمت هذه الدالة للحصول على إصدار API لموفر الموارد، فإننا نوصي بتوفير إصدار محدد لواجهة برمجة التطبيقات في قالبك. يمكن أن يؤدي استخدام إصدار API الذي يتم إرجاعه ديناميكيا إلى توقف قالبك إذا تغيرت الخصائص بين الإصدارات.

في Bicep، تم إلغاء دالة Provider.

لا تزال عملية الموفرين متاحة من خلال واجهة برمجة تطبيقات REST. يمكن استخدامه خارج قالب ARM للحصول على معلومات بشأن مزود الموارد.

reference

في القوالب التي لا تحتوي على أسماء رمزية:

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

في القوالب ذات الأسماء الرمزية:

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

إرجاع كائن يمثل حالة وقت تشغيل المورد. يعتمد إخراج وسلوك الدالة reference بشكل كبير على كيفية تنفيذ كل موفر موارد (RP) استجابات PUT و GET الخاصة به. لإرجاع صفيف من الكائنات التي تمثل حالات وقت تشغيل مجموعات الموارد، راجع المراجع.

يوفر Bicep الدالة المرجعية، ولكن في معظم الحالات، لا تكون الدالة المرجعية مطلوبة. يوصى باستخدام الاسم الرمزي للمورد بدلا من ذلك. راجع المرجع.

المعلمات

المعلمة‬	المطلوب	نوع	‏‏الوصف
resourceName/resourceIdentifier أو رمزيName/resourceIdentifier	‏‏نعم‬	سلسلة	في القوالب التي لا تحتوي على أسماء رمزية، حدد اسم المورد أو معرفه الفريد. عند الإشارة إلى مورد في القالب الحالي، قم بتوفير اسم المورد فقط كمعامل. عند الإشارة إلى مورد تم نشره مسبقًا أو عندما يكون اسم المورد غامضًا، قم بتوفير معرف المورد. في القوالب ذات الأسماء الرمزية، حدد اسما رمزيا أو معرفا فريدا لمورد. عند الإشارة إلى مورد في القالب الحالي، قم بتوفير الاسم الرمزي للمورد كمعلمة فقط. عند الرجوع إلى مورد تم نشره مسبقا، قم بتوفير معرف المورد.
apiVersion	لا	سلسلة	نسخة API من المورد المحدد. هذه المعلمة مطلوبة عندما لا يتم توفير المورد في نفس القالب. عادة، في الشكل، yyyy-mm-dd. للحصول على إصدارات API صالحة لموردك، انظر مرجع القالب.
«كامل»	لا	سلسلة	القيمة التي تحدد ما إذا كان سيتم إرجاع كائن المورد بالكامل. إذا لم تحدد `'Full'`، فسيتم إرجاع كائن خصائص المورد فقط. يتضمن الكائن الكامل قيمًا مثل معرف المورد والموقع.

قيمة الإرجاع

يقوم كل نوع مورد بإرجاع خصائص مختلفة للدالة المرجعية. لا تقوم الوظيفة بإرجاع تنسيق واحد محدد مسبقًا. أيضًا، تختلف القيمة التي تم إرجاعها بناءً على قيمة الوسيطة 'Full'. للاطلاع على خصائص نوع المورد، قم بإرجاع الكائن في قسم المخرجات كما هو موضح في المثال.

الملاحظات

تسترد الدالة المرجعية حالة وقت التشغيل إما لمورد تم نشره مسبقًا أو لمورد تم نشره في القالب الحالي. تعرض هذه المقالة أمثلة لكلا السيناريوهين.

عادةً ما تستخدم الدالة reference لإرجاع قيمة معينة من كائن، مثل URI لنقطة نهاية البيانات الثنائية الكبيرة أو اسم المجال المؤهل بالكامل.

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

استخدم 'Full' عندما تحتاج إلى قيم موارد ليست جزءًا من مخطط الخصائص. على سبيل المثال، لتعيين سياسات الوصول إلى مخزن المفاتيح، احصل على خصائص الهوية لجهاز ظاهري.

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

الاستخدامات الصالحة

reference يمكن استخدام الدالة فقط في قسم المخرجات من قالب أو عنصر توزيع وخصائص تعريف مورد. لا يمكن استخدامه لخصائص المورد مثل typeو namelocation و وخصائص المستوى الأعلى الأخرى لتعريف المورد. عند استخدامها مع تكرار الخاصية، يمكنك استخدام الدالة reference لـ input لأن التعبير تم تعيينه إلى خاصية المورد.

لا يمكنك استخدام الدالة reference لتعيين قيمة الخاصية count في حلقة نسخ. يمكنك استخدام لتعيين خصائص أخرى في الحلقة. تم حظر المرجع لخاصية العد لأنه يجب تحديد هذه الخاصية قبل حل الدالة reference.

لاستخدام الدالة reference أو أي دالة list* في قسم المخرجات من قالب متداخل، يجب تعيين expressionEvaluationOptions لاستخدام تقييم النطاق الداخلي أو استخدام قالب مرتبط بدلاً من قالب متداخل.

إذا كنت تستخدم الدالة reference في مورد تم نشره بشروط، فسيتم تقييم الدالة حتى إذا لم يتم نشر المورد. تحصل على خطأ إذا كانت الدالة reference تشير إلى مورد غير موجود. استخدم الدالة if للتأكد من تقييم الدالة فقط عند نشر المورد. راجع الوظيفة if لقالب نموذج يستخدم if وreference مع مورد نشر مشروط.

التبعية الضمنية

باستخدام دالة reference، فإنك تعلن ضمنيًا أن موردًا واحدًا يعتمد على مورد آخر إذا تم توفير المورد المشار إليه في نفس القالب وقمت بالإشارة إلى المورد من خلال اسمه (وليس معرّف المورد). لا تحتاج أيضًا إلى استخدام خاصية dependsOn. لا يتم تقييم الدالة حتى ينتهي المورد المشار إليه من النشر.

اسم المورد أو الاسم الرمزي أو المعرف

عند الرجوع إلى مورد تم نشره في نفس قالب الاسم الرمزي بلا، قم بتوفير اسم المورد.

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

عند الرجوع إلى مورد تم نشره في نفس قالب الاسم الرمزي، قم بتوفير الاسم الرمزي للمورد.

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

أو

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

عند الإشارة إلى مورد لم يتم نشره في نفس القالب، قم بتوفير معرف المورد وapiVersion.

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

لتجنب الغموض حول المورد الذي تشير إليه، يمكنك توفير معرف مورد مؤهل بالكامل.

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

عند إنشاء مرجع مؤهل بالكامل لمورد، فإن ترتيب دمج الأجزاء من النوع والاسم ليس مجرد سلسلة من الاثنين. بدلاً من ذلك، بعد مساحة الاسم، استخدم تسلسل أزواج النوع/الاسم من الأقل تحديدًا إلى الأكثر تحديدًا:

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

على سبيل المثال:

Microsoft.Compute/virtualMachines/myVM/extensions/myExt هو الصحيح وMicrosoft.Compute/virtualMachines/extensions/myVM/myExt ليس صحيحًا

لتبسيط إنشاء أي معرف مورد، استخدم الدالات resourceId() الموضحة في هذا المستند بدلاً من concat().

الحصول على هوية مدارة

الهويات المدارة لموارد Azure هي أنواع موارد ملحقة يتم إنشاؤها ضمنيًا لبعض الموارد. نظرًا إلى عدم تحديد الهوية المُدارة بشكل صريح في القالب، يجب الرجوع إلى المورد الذي تم تطبيق الهوية عليه. تُستخدم Full للحصول على جميع الخصائص، بما في ذلك الهوية المنشأة ضمنيًا.

النمط هو:

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

على سبيل المثال، للحصول على معرف الأساسي لهوية مدارة يتم تطبيقها على جهاز ظاهري، استخدم:

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

أو للحصول على مُعرف المستأجر لهوية مُدارة تم تطبيقها على مجموعة كبيرة من الأجهزة الظاهرية، استخدم:

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

مثال مرجعي

المثال التالي ينشر موردًا ويشير إلى هذا المورد.

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

يقوم المثال السابق بإرجاع الكائنين. كائن الخصائص بالتنسيق التالي:

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

الكائن الكامل بالصيغة التالية:

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

يشير المثال التالي إلى حساب تخزين لم يتم نشره في هذا القالب. حساب التخزين موجود بالفعل ضمن نفس الاشتراك.

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

مراجع

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

تعمل الدالة references بشكل مماثل ل reference. بدلا من إرجاع كائن يقدم حالة وقت تشغيل مورد، references تقوم الدالة بإرجاع صفيف من الكائنات التي تمثل حالات وقت تشغيل مجموعة الموارد. تتطلب هذه الدالة إصدار 2.0 لغة قالب ARM مع تمكين الاسم الرمزي:

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

في Bicep، لا توجد دالة صريحة references . بدلا من ذلك، يتم استخدام استخدام المجموعة الرمزية مباشرة، وأثناء إنشاء التعليمات البرمجية، يترجمه Bicep إلى قالب ARM الذي يستخدم وظيفة قالب references ARM. لمزيد من المعلومات، راجع مجموعات الموارد/الوحدة النمطية المرجعية.

المعلمات

المعلمة‬	المطلوب	نوع	‏‏الوصف
اسم رمزي لمجموعة موارد	‏‏نعم‬	سلسلة	اسم رمزي لمجموعة موارد تم تعريفها في القالب الحالي. `references` لا تدعم الدالة الرجوع إلى الموارد الخارجية للقالب الحالي.
"كامل"، "خصائص"	لا	سلسلة	القيمة التي تحدد ما إذا كان سيتم إرجاع صفيف من كائنات الموارد الكاملة. القيمة الافتراضية هي `'Properties'`. إذا لم تحدد `'Full'`، يتم إرجاع كائنات خصائص الموارد فقط. يتضمن الكائن الكامل قيمًا مثل معرف المورد والموقع.

قيمة الإرجاع

صفيف من مجموعة الموارد. يقوم كل نوع مورد بإرجاع خصائص مختلفة للدالة reference . أيضًا، تختلف القيمة التي تم إرجاعها بناءً على قيمة الوسيطة 'Full'. لمزيد من المعلومات، راجع المرجع.

يتم ترتيب إخراج references دائما بترتيب تصاعدي استنادا إلى فهرس النسخ. لذلك، يتم عرض المورد الأول في المجموعة ذات الفهرس 0 أولا، متبوعا بالفهرس 1، وهكذا. على سبيل المثال، [worker-0, worker-1, worker-2, ...].

في المثال السابق، إذا تم نشر العامل-0 والعامل-2 بينما العامل-1 لا يرجع إلى شرط خاطئ، فسيحذف إخراج references المورد غير المنشور ويعرض الموارد المنشورة، مرتبة حسب أرقامها. سيكون ناتج references [worker-0, worker-2, ...]. إذا تم حذف كافة الموارد، ترجع الدالة صفيفا فارغا.

الاستخدامات الصالحة

references لا يمكن استخدام الدالة ضمن حلقات نسخ الموارد أو Bicep للتكرار الحلقي. على سبيل المثال، references غير مسموح به في السيناريو التالي:

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

لاستخدام الدالة references أو أي دالة list* في قسم المخرجات من قالب متداخل، يجب تعيين expressionEvaluationOptions لاستخدام تقييم النطاق الداخلي أو استخدام قالب مرتبط بدلاً من قالب متداخل.

التبعية الضمنية

باستخدام الدالة references ، فإنك تعلن ضمنيا أن موردا واحدا يعتمد على مورد آخر. لا تحتاج أيضًا إلى استخدام خاصية dependsOn. لا يتم تقييم الدالة حتى ينتهي المورد المشار إليه من النشر.

مثال مرجعي

ينشر المثال التالي مجموعة موارد، ويشير إلى مجموعة الموارد هذه.

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

يقوم المثال السابق بإرجاع الكائنات الثلاثة.

"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

راجع وظيفة نطاق مجموعة الموارد.

في Bicep، استخدم دالة النطاق resourcegroup.

resourceId

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

إرجاع المعرف الفريد للمورد. يمكنك استخدام هذه الدالة عندما يكون اسم المورد غامضًا أو غير متوفر في نفس القالب. يختلف تنسيق المعرف الذي تم إرجاعه بناءً على ما إذا كان النشر يحدث في نطاق مجموعة موارد أو اشتراك أو مجموعة إدارة أو مستأجر.

في Bicep، استخدم دالة resourceId.

المعلمات

المعلمة‬	المطلوب	نوع	‏‏الوصف
subscriptionId	لا	السلسلة (بتنسيق GUID)	القيمة الافتراضية هي الاشتراك الحالي. حدد هذه القيمة عندما تحتاج إلى استرداد مورد في اشتراك آخر. لا تُقدم هذه القيمة إلا عند النشر في نطاق مجموعة موارد أو اشتراك.
resourceGroupName	لا	سلسلة	القيمة الافتراضية هي مجموعة الموارد الحالية. حدد هذه القيمة عندما تحتاج إلى استرداد مورد في مجموعة موارد أخرى. لا تُقدم هذه القيمة إلا عند النشر في نطاق مجموعة موارد.
resourceType	‏‏نعم‬	سلسلة	نوع المورد بما في ذلك مساحة اسم موفر المورد.
resourceName1	‏‏نعم‬	سلسلة	اسم المورد.
resourceName2	لا	سلسلة	مقطع اسم المورد التالي، إذا لزم الأمر.

استمر في إضافة أسماء الموارد كمعلمات عندما يتضمن نوع المورد مزيدًا من المقاطع.

قيمة الإرجاع

يتم إرجاع معرف المورد بتنسيقات مختلفة في نطاقات مختلفة:

نطاق مجموعة الموارد:

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

نطاق الاشتراك:

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

مجموعة الإدارة أو نطاق المستأجر:

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

لتجنب الالتباس، نوصي بعدم استخدام resourceId عند العمل مع الموارد التي تم نشرها في الاشتراك أو مجموعة الإدارة أو المستأجر. بدلاً من ذلك، استخدم وظيفة المعرف المصممة للنطاق.

للموارد على مستوى الاشتراك، استخدم الدالة subscriptionResourceId.
بالنسبة إلى موارد مستوى مجموعة الإدارة، استخدم الوظيفة managementGroupResourceId. استخدم الوظيفة extensionResourceId للإشارة إلى مورد تم تنفيذه كملحق لمجموعة إدارة. على سبيل المثال، تعد تعريفات النهج المخصصة التي يتم نشرها في مجموعة إدارة ملحقات لمجموعة الإدارة. استخدم الدالة tenantResourceId للإشارة إلى الموارد التي تم نشرها إلى المستأجر ولكنها متوفرة في مجموعة الإدارة. على سبيل المثال، يتم تنفيذ تعريفات السياسة المضمنة كمصادر على مستوى المستأجر.
للموارد على مستوى المستأجر، استخدم الدالة tenantResourceId. استخدم tenantResourceId لتعريفات النهج المضمنة لأنها مطبقة على مستوى المستأجر.

الملاحظات

يختلف عدد المعلمات التي توفرها بناءً على ما إذا كان المورد مصدرًا رئيسيًا أم فرعيًا، وما إذا كان المورد في نفس الاشتراك أو مجموعة الموارد.

للحصول على معرف المورد لمورد أصل في نفس مجموعة الموارد والاشتراك، قم بتوفير نوع واسم المورد.

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

للحصول على معرف المورد لمورد فرعي، انتبه إلى عدد الأجزاء في نوع المورد. توفير اسم مورد لكل مقطع من نوع المورد. يتوافق اسم المقطع مع المورد الموجود لهذا الجزء من التسلسل الهرمي.

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

للحصول على معرف المورد لمورد في نفس الاشتراك ولكن مجموعة موارد مختلفة، قم بتوفير اسم مجموعة الموارد.

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

للحصول على معرف المورد لمورد في اشتراك ومجموعة موارد مختلفين، قم بتوفير معرف الاشتراك واسم مجموعة الموارد.

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

غالبًا ما تحتاج إلى استخدام هذه الدالة عند استخدام حساب تخزين أو شبكة ظاهرية في مجموعة موارد بديلة. يوضح المثال التالي كيفية استخدام مورد من مجموعة موارد خارجية بسهولة:

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

مثال معرف المورد

يقوم المثال التالي بإرجاع معرف المورد لحساب تخزين في مجموعة الموارد:

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

الناتج من المثال السابق مع القيم الافتراضية هو:

Name	نوع	القيمة‬
sameRGOutput	السلسلة‬	/subscriptions/{current-sub-id}/resourceGroups/examplegroup/providers/Microsoft.Storage/storageAccounts/examplestorage
differentRGOutput	السلسلة‬	/subscriptions/{current-sub-id}/resourceGroups/otherResourceGroup/providers/Microsoft.Storage/storageAccounts/examplestorage
differentSubOutput	السلسلة‬	/subscriptions/11111111-1111-1111-1111-111111111111/resourceGroups/otherResourceGroup/providers/Microsoft.Storage/storageAccounts/examplestorage
nestedResourceOutput	السلسلة‬	/subscriptions/{current-sub-id}/resourceGroups/examplegroup/providers/Microsoft.SQL/servers/serverName/databases/databaseName

الاشتراك

راجع وظيفة نطاق الاشتراك.

في Bicep، استخدم دالة النطاق subscription.

subscriptionResourceId

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

إرجاع المعرف الفريد لمورد تم نشره على مستوى الاشتراك.

في Bicep، استخدم دالة subscriptionResourceId.

المعلمات

المعلمة‬	المطلوب	نوع	‏‏الوصف
subscriptionId	لا	سلسلة (بتنسيق GUID)	القيمة الافتراضية هي الاشتراك الحالي. حدد هذه القيمة عندما تحتاج إلى استرداد مورد في اشتراك آخر.
resourceType	‏‏نعم‬	سلسلة	نوع المورد بما في ذلك مساحة اسم موفر المورد.
resourceName1	‏‏نعم‬	سلسلة	اسم المورد.
resourceName2	لا	سلسلة	مقطع اسم المورد التالي، إذا لزم الأمر.

استمر في إضافة أسماء الموارد كمعلمات عندما يتضمن نوع المورد مزيدًا من المقاطع.

قيمة الإرجاع

يتم إرجاع المعرف بالتنسيق التالي:

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

الملاحظات

يمكنك استخدام هذه الدالة للحصول على معرف المورد للموارد التي تم توزيعها في الاشتراك بدلاً من مجموعة الموارد. يختلف المعرف الذي تم إرجاعه عن القيمة التي تم إرجاعها بواسطة الدالة resourceId من خلال عدم تضمين قيمة مجموعة الموارد.

مثال subscriptionResourceID

يقوم القالب التالي بتعيين دور مضمن. يمكنك نشرها إما إلى مجموعة موارد أو اشتراك. يستخدم الدالة subscriptionResourceId للحصول على معرف المورد للأدوار المضمنة.

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

تؤدي إلى إرجاع المعرف الفريد لمورد تم توزيعه على مستوى مجموعة الإدارة.

في Bicep، استخدم الوظيفة managementGroupResourceId function.

المعلمات

المعلمة‬	المطلوب	نوع	‏‏الوصف
managementGroupResourceId	لا	سلسلة (بتنسيق GUID)	القيمة الافتراضية هي مجموعة الإدارة الحالية. حدد هذه القيمة عندما تحتاج إلى استرداد مورد في مجموعة إدارة أخرى.
resourceType	‏‏نعم‬	سلسلة	نوع المورد بما في ذلك مساحة اسم موفر المورد.
resourceName1	‏‏نعم‬	سلسلة	اسم المورد.
resourceName2	لا	سلسلة	مقطع اسم المورد التالي، إذا لزم الأمر.

استمر في إضافة أسماء الموارد كمعلمات عندما يتضمن نوع المورد مزيدًا من المقاطع.

قيمة الإرجاع

يتم إرجاع المعرف بالتنسيق التالي:

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

الملاحظات

يمكنك استخدام هذه الوظيفة للحصول على معرف المورد للموارد التي تم توزيعها إلى مجموعة الإدارة بدلاً من مجموعة الموارد. يختلف المعرف الذي تم إرجاعه عن القيمة التي تم إرجاعها بواسطة الوظيفة ResourceId من خلال عدم تضمين معرّف الاشتراك وقيمة مجموعة الموارد.

مثال managementGroupResourceID

يقوم القالب التالي بإنشاء تعريف نهج وتعيينه. يستخدم الوظيفة managementGroupResourceId للحصول على معرف المورد لتعريف النهج.

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

إرجاع المعرف الفريد لمورد تم نشره على مستوى المستأجر.

في Bicep، استخدم دالة tenantResourceId.

المعلمات

المعلمة‬	المطلوب	نوع	‏‏الوصف
resourceType	‏‏نعم‬	سلسلة	نوع المورد بما في ذلك مساحة اسم موفر المورد.
resourceName1	‏‏نعم‬	سلسلة	اسم المورد.
resourceName2	لا	سلسلة	مقطع اسم المورد التالي، إذا لزم الأمر.

استمر في إضافة أسماء الموارد كمعلمات عندما يتضمن نوع المورد مزيدًا من المقاطع.

قيمة الإرجاع

يتم إرجاع المعرف بالتنسيق التالي:

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

الملاحظات

يمكنك استخدام هذه الدالة للحصول على معرف المورد لمورد تم نشره إلى المستأجر. يختلف معرف إرجاع القيم التي تم إرجاعها بواسطة دالات معرف المورد الأخرى بواسطة عدم تضمين مجموعة الموارد أو قيم الاشتراك.

tenantResourceId example

تعريفات النهج المضمنة هي موارد على مستوى المستأجر. لنشر تعيين نهج يشير إلى تعريف سياسة مضمن، استخدم الدالة tenantResourceId.

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

الخطوات التالية

للحصول على وصف للأقسام الموجودة في قالب ARM، انظرفهم بنية قوالب ARM وهيكلها.
لدمج عدة قوالب، راجع استخدام القوالب المرتبطة والمتداخلة عند توزيع موارد Azure .
لتكرار عدد معين من المرات عند إنشاء نوع من الموارد، راجع تكرار الموارد الواردة في قوالب ARM .
لمعرفة طريقة نشر النموذج الذي قمت بإنشائه، راجع نشر الموارد باستخدام قوالب ARM وAzure PowerShell .

مشاركة عبر

دالات الموارد لقوالب ARM

extensionResourceId

المعلمات

قيمة الإرجاع

extensionResourceId example

list*

المعلمات

الاستخدامات الصالحة

تطبيقات

قيمة الإرجاع

الملاحظات

مثال القائمة

pickZones

المعلمات

قيمة الإرجاع

الملاحظات

pickZones example

الموفرون

reference

المعلمات

قيمة الإرجاع

الملاحظات

الاستخدامات الصالحة

التبعية الضمنية

اسم المورد أو الاسم الرمزي أو المعرف

الحصول على هوية مدارة

مثال مرجعي

مراجع

المعلمات

قيمة الإرجاع

الاستخدامات الصالحة

التبعية الضمنية

مثال مرجعي

resourceGroup

resourceId

المعلمات

قيمة الإرجاع

الملاحظات

مثال معرف المورد

الاشتراك

subscriptionResourceId

المعلمات

قيمة الإرجاع

الملاحظات

مثال subscriptionResourceID

managementGroupResourceId

المعلمات

قيمة الإرجاع

الملاحظات

مثال managementGroupResourceID

tenantResourceId

المعلمات

قيمة الإرجاع

الملاحظات

tenantResourceId example

الخطوات التالية

الملاحظات

الملاحظات

الموارد الإضافية