دالات الموارد لقوالب ARM
يوفر 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
و name
location
و وخصائص المستوى الأعلى الأخرى لتعريف المورد. عند استخدامها مع تكرار الخاصية، يمكنك استخدام الدالة 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 .