الإخراج في Bicep

توضح هذه المقالة كيفية تعريف قيم الإخراج في ملف Bicep. يمكنك استخدام المخرجات عندما تحتاج إلى إرجاع القيم من الموارد الموزعة. تقتصر على 64 إخراجا في ملف Bicep. لمزيد من المعلومات، راجع حدود القالب.

تعريف المخرجات

بناء الجملة لتعريف قيمة إخراج هو:

output <name> <data-type or type-expression> = <value>

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

يوضح المثال التالي كيفية إرجاع خاصية من مورد تم توزيعه. في المثال، publicIP هو الاسم الرمزي لعنوان IP العام الذي تم نشره في ملف Bicep. تحصل قيمة الإخراج على اسم المجال المؤهل بالكامل لعنوان IP العام.

output hostname string = publicIP.properties.dnsSettings.fqdn

يوضح المثال التالي كيفية إرجاع المخرجات من أنواع مختلفة.

output stringOutput string = deployment().name
output integerOutput int = length(environment().authentication.audiences)
output booleanOutput bool = contains(deployment().name, 'demo')
output arrayOutput array = environment().authentication.audiences
output objectOutput object = subscription()

إذا كنت بحاجة إلى إخراج خاصية تحتوي على واصلة في الاسم، فاستخدم الأقواس حول الاسم بدلاً من تدوين النقطة. على سبيل المثال، ['property-name'] بدلاً من .property-name.

var user = {
  'user-name': 'Test Person'
}

output stringOutput string = user['user-name']

يوضح المثال التالي كيفية استخدام تعبير النوع:

param foo 'a' | 'b' = 'a'

output out 'a' | 'b' = foo

لمزيد من المعلومات، راجع أنواع البيانات المعرفة من قبل المستخدم.

استخدام مصممي الديكور

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

يوجد مصممي الديكور في sys namespace. إذا كنت بحاجة إلى تمييز مصمم ديكور عن عنصر آخر يحمل نفس الاسم، فاكتب في مقدمة مصمم الديكور sys. على سبيل المثال، إذا كان ملف Bicep يتضمن معلمة باسم description، يجب إضافة مساحة الاسم sys عند استخدام مصمم ديكور الوصف.

@sys.description('The name of the instance.')
param name string
@sys.description('The description of the instance to display.')
param description string

‏‏الوصف

لإضافة شرح، أضف وصفا لإعلانات الإخراج. على سبيل المثال:

@description('Conditionally output the endpoint.')
output endpoint string = deployStorage ? myStorageAccount.properties.primaryEndpoints.blob : ''

يمكن استخدام نص بتنسيق Markdown لنص الوصف.

مميز

راجع نوع بيانات الاتحاد ذات العلامات المخصصة.

قيود العدد الصحيح

يمكنك تعيين القيم الدنيا والحد الأقصى لمخرجات العدد الصحيح. يمكنك تعيين قيد أو كليهما.

var thisMonth = 3

@minValue(1)
@maxValue(12)
output month int = thisMonth

قيود المدى

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

يوضح المثال التالي إخراجين. أحد المخرجات هو لاسم حساب التخزين الذي يجب أن يحتوي على 3-24 حرفا. الإخراج الآخر هو صفيف يجب أن يكون من 1-5 عناصر.

var accountName = uniqueString(resourceGroup().id)
var appNames = [
  'SyncSphere'
  'DataWhiz'
  'FlowMatrix'
]

@minLength(3)
@maxLength(24)
output storageAccountName string = accountName

@minLength(1)
@maxLength(5)
output applicationNames array = appNames

بيانات التعريف

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

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

var obj = {}
@description('Configuration values that are applied when the application starts.')
@metadata({
  source: 'database'
  contact: 'Web team'
})
output settings object = obj

عند تزويد @metadata() مصمم الديكور بخاصية تتعارض مع مصمم ديكور آخر، فإن هذا المصمم دائما له الأسبقية على أي شيء في @metadata() مصمم الديكور. لذلك، الخاصية المتعارضة @metadata() داخل القيمة زائدة عن الحاجة وسيتم استبدالها. لمزيد من المعلومات، راجع لا توجد بيانات تعريف متعارضة.

سدود

راجع رفع مستوى الخطأ.

المخرجات الشرطية

عندما تعتمد القيمة المراد إرجاعها على شرط في النشر، استخدم ? عامل التشغيل .

output <name> <data-type> = <condition> ? <true-value> : <false-value>

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

لتحديد الإخراج الشرطي في Bicep،، استخدم عامل التشغيل ?. يُرجع المثال التالي إما عنوان URL لنقطة النهاية أو سلسلة فارغة بناءً على شرط.

param deployStorage bool = true
param storageName string
param location string = resourceGroup().location

resource myStorageAccount 'Microsoft.Storage/storageAccounts@2023-04-01' = if (deployStorage) {
  name: storageName
  location: location
  kind: 'StorageV2'
  sku:{
    name:'Standard_LRS'
    tier: 'Standard'
  }
  properties: {
    accessTier: 'Hot'
  }
}

output endpoint string = deployStorage ? myStorageAccount.properties.primaryEndpoints.blob : ''

عدد المخرجات الديناميكية

في بعض السيناريوهات، لا تعرف عدد مثيلات القيمة التي تريد إرجاعها عند إنشاء القالب. يمكنك إرجاع عدد متغير من القيم باستخدام التعبير for.

output <name> <data-type> = [for <item> in <collection>: {
  ...
}]

المثال التالي يتكرر عبر مصفوفة.

param nsgLocation string = resourceGroup().location
param orgNames array = [
  'Contoso'
  'Fabrikam'
  'Coho'
]

resource nsg 'Microsoft.Network/networkSecurityGroups@2023-11-01' = [for name in orgNames: {
  name: 'nsg-${name}'
  location: nsgLocation
}]

output deployedNSGs array = [for (name, i) in orgNames: {
  orgName: name
  nsgName: nsg[i].name
  resourceId: nsg[i].id
}]

للمزيد من المعلومات، راجع تكرار حلقي في Bicep.

مخرجات من الوحدات النمطية

للحصول على قيمة مخرجات من وحدة نمطية، استخدم الصيغة التالية:

<module-name>.outputs.<property-name>

يوضح المثال التالي كيفية تعيين عنوان IP على موازن التحميل عن طريق استرداد قيمة من وحدة نمطية.

module publicIP 'modules/public-ip-address.bicep' = {
  name: 'public-ip-address-module'
}

resource loadBalancer 'Microsoft.Network/loadBalancers@2023-11-01' = {
  name: loadBalancerName
  location: location
  properties: {
    frontendIPConfigurations: [
      {
        name: 'name'
        properties: {
          publicIPAddress: {
            id: publicIP.outputs.resourceId
          }
        }
      }
    ]
    // ...
  }
}

الحصول على قيم الإخراج

عندما ينجح التوزيع، يتم إرجاع قيم المخرجات تلقائيّاً في نتائج التوزيع.

للحصول على قيم المخرجات من محفوظات النشر، يمكنك استخدام Azure CLI أو Azure PowerShell النصي.

(Get-AzResourceGroupDeployment `
  -ResourceGroupName <resource-group-name> `
  -Name <deployment-name>).Outputs.resourceID.value

az deployment group show \
  -g <resource-group-name> \
  -n <deployment-name> \
  --query properties.outputs.resourceID.value

فرز العناصر في المخرجات

في JSON، العنصر هو مجموعة غير مرتبة من أزواج صفرية أو أكبر من المفاتيح/القيم. يمكن أن يكون الترتيب مختلفًا اعتمادًا على عمليات التنفيذ. على سبيل المثال، تقوم دالة Bicep items() بفرز العناصر بالترتيب الأبجدي. في أماكن أخرى، يمكن الاحتفاظ بالترتيب الأصلي. وبسبب هذا عدم الحتمية، تجنب وضع أي افتراضات حول ترتيب مفاتيح الكائنات عند كتابة التعليمات البرمجية، والتي تتفاعل مع معلمات التوزيع والمخرجات.

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

• لمعرفة المزيد عن الخصائص المتوفرة للمخرجات، راجع فهم بنية Bicep وبناء الجملة.