أنواع البيانات في Bicep

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

الأنواع المدعومة

ضمن Bicep، يمكنك استخدام أنواع البيانات التالية:

• صفيف
• bool
• الباحث
• object
• secureObject - المشار إليه بواسطة مصمم الديكور في Bicep
• secureString - المشار إليه بواسطة مصمم الديكور في Bicep
• string

الصفائف

تبدأ الصفائف بقوس أيسر ([) وتنتهي بقوس أيمن (]). في Bicep، يمكن تعريف صفيف في سطر واحد أو أسطر متعددة. يتم استخدام الفواصل (,) بين القيم في إعلانات سطر واحد، ولكن لا يتم استخدامها في إعلانات متعددة الأسطر، يمكنك مزج ومطابقة إعلانات سطر واحد ومتعددة الأسطر. يتطلب الإعلان متعدد الأسطر إصدار Bicep CLI 0.7.X أو أعلى.

var multiLineArray = [
  'abc'
  'def'
  'ghi'
]

var singleLineArray = ['abc', 'def', 'ghi']

var mixedArray = ['abc', 'def'
    'ghi']

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

يوضح المثال التالي صفيف من الأعداد الصحيحة و صفيف أنواع مختلفة.

var integerArray = [
  1
  2
  3
]

var mixedArray = [
  resourceGroup().name
  1
  true
  'example string'
]

تستند الصفائف في Bicep إلى قيمة صفرية. في المثال التالي، يتم تقييم التعبير exampleArray[0] إلى 1، والتعبير exampleArray[2] إلى 3. يمكن أن يكون فهرس المفهرس تعبيرا آخر. يتم تقييم التعبير exampleArray[index] إلى 2. لا يُسمح بمفهرسات الأعداد الصحيحة إلا عند التعبير عن أنواع الصفائف.

var index = 1

var exampleArray = [
  1
  2
  3
]

تحصل على الخطأ التالي عندما يكون الفهرس خارج الحدود:

The language expression property array index 'x' is out of bounds

لتجنب هذا الاستثناء، يمكنك استخدام عامل التشغيل المنطقي Or كما هو موضح في المثال التالي:

param emptyArray array = []
param numberArray array = [1, 2, 3]

output foo bool = empty(emptyArray) || emptyArray[0] == 'bar'
output bar bool = length(numberArray) <= 3 || numberArray[3] == 4

القيم المنطقية

عند تحديد القيم المنطقية، استخدم true أو false. لا يُوضع حول القيمة علامات اقتباس.

param exampleBool bool = true

الأعداد الصحيحة

عند تحديد قيم أعداد صحيحة، لا تستخدم علامات الاقتباس.

param exampleInt int = 1

أعداد Bicep الصحيحة هي أعداد صحيحة 64 بت. عند تمريرها كمعلمات مضمنة، يمكن تقييد نطاق القيم بواسطة SDK أو أداة سطر الأوامر التي تستخدمها للتوزيع. على سبيل المثال، عند استخدام PowerShell لتوزيع Bicep، يمكن أن تتراوح أنواع الأعداد الصحيحة من -2147483648 إلى 2147483647. لتجنب هذا التقييد، حدد قيم أعداد صحيحة كبيرة في ملف معلمة. تطبق أنواع الموارد حدودها الخاصة لخصائص الأعداد الصحيحة.

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

output foo 1 = 1

يمكن تعريف نوع القيمة الحرفية للعدد الصحيح إما مضمنا، كما هو موضح في المثال السابق، أو في عبارة type.

type oneType = 1

output foo oneType = 1
output bar oneType = 2

في المثال السابق، يؤدي تعيين 2 إلى شريط إلى خطأ BCP033 - توقع قيمة من النوع "1" ولكن القيمة المقدمة من النوع "2".

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

output bar 1 | 2 | 3 = 3

لا يتم حاليًا دعم تنسيقات الفاصلة العائمة أو الفاصلة العشرية أو الثنائية.

كائنات

تبدأ العناصر بقوس متعرج أيسر ({) وتنتهي بقوس متعرج أيمن (}). في Bicep، يمكن تعريف كائن في سطر واحد أو أسطر متعددة. تتكون كل خاصية في عنصر من مفتاح وقيمة. يتم فصل المفتاح والقيمة بنقطتين (:). عنصر يسمح بأي خاصية من أي نوع. تستخدم الفواصل (,) بين الخصائص للإعلانات أحادية السطر، ولكن لا يتم استخدامها بين الخصائص للإعلانات متعددة الأسطر. يمكنك خلط ومطابقة إعلانات سطر واحد ومتعددة الأسطر. يتطلب الإعلان متعدد الأسطر إصدار Bicep CLI 0.7.X أو أعلى.

param singleLineObject object = {name: 'test name', id: '123-abc', isCurrent: true, tier: 1}

param multiLineObject object = {
  name: 'test name'
  id: '123-abc'
  isCurrent: true
  tier: 1
}

param mixedObject object = {name: 'test name', id: '123-abc', isCurrent: true
    tier: 1}

في Bicep، من المسموح استخدام علامات الاقتباس اختياريًا على مفاتيح خصائص العنصر:

var test = {
  'my - special. key': 'value'
}

في المثال السابق، يتم استخدام علامات الاقتباس عندما تحتوي مفاتيح خصائص العنصر على أحرف خاصة. على سبيل المثال المسافة، أو '-'، أو '.'. يوضح المثال التالي كيفية استخدام الاستنتاج في مفاتيح خصائص العنصر.

var stringVar = 'example value'
var objectVar = {
  '${stringVar}': 'this value'
}

يتم استخدام موصلات الخاصية للوصول إلى خصائص عنصر. وتم إنشاؤها باستخدام عامل التشغيل ..

var a = {
  b: 'Dev'
  c: 42
  d: {
    e: true
  }
}

output result1 string = a.b // returns 'Dev'
output result2 int = a.c // returns 42
output result3 bool = a.d.e // returns true

يمكن استخدام موصلات الخاصية مع أي عنصر، بما في ذلك المعلمات والمتغيّرات الخاصة بأنواع العناصر والقيم الحرفية لها. يعد استخدام موصل خاصية في تعبير من نوع بخلاف العنصر استخدامًا خطأ.

يمكنك أيضًا استخدام بناء الجملة [] للوصول إلى خاصية. يعمل المثال التالي على إرجاع Development.

var environmentSettings = {
  dev: {
    name: 'Development'
  }
  prod: {
    name: 'Production'
  }
}

output accessorResult string = environmentSettings['dev'].name

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

تحصل على الخطأ التالي عند الوصول إلى خاصية غير موجودة لعنصر:

The language expression property 'foo' doesn't exist

لتجنب الاستثناء، يمكنك استخدام عامل التشغيل المنطقي و كما هو موضح في المثال التالي:

param objectToTest object = {
  one: 1
  two: 2
  three: 3
}

output bar bool = contains(objectToTest, 'four') && objectToTest.four == 4

السلاسل

في Bicep، يتم وضع علامة على السلاسل بعلامات اقتباس فردية، ويجب الإعلان عنها في سطر واحد. يُسمح بجميع أحرف Unicode التي لها نقاط رموز بين 0 و10FFFF.

param exampleString string = 'test value'

يسرد الجدول التالي مجموعة الأحرف المحجوزة التي يجب تخطيها بشرطة مائلة للخلف (\):

سلسلة الإلغاء	القيمة الممثلة	ملاحظات
\\	\
\'	'
\n	إضافة سطر (LF)
\r	رجوع إلى أول السطر (CR)
\t	حرف الجدولة
\u{x}	نقطة رمز Unicodex	x يمثل قيمة نقطة رمز سداسي عشري بين 0 و10FFFF (كلامهما شاملان). يُسمح باستخدام الأصفار البادئة. يتم إصدار نقاط الرمز التي تتجاوز FFFF كزوج بديل.
\$	$	يتم تخطيه فقط عندما يتبعه {.

// evaluates to "what's up?"
var myVar = 'what\'s up?'

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

output redColor 'red' = 'red'

يمكن تعريف نوع حرف السلسلة إما مضمنا، كما هو موضح في المثال السابق، أو في عبارة type.

type redColor = 'red'

output colorRed redColor = 'red'
output colorBlue redColor = 'blue'

في المثال السابق، يؤدي تعيين اللون الأزرق إلى colorBlue إلى خطأ BCP033 - توقع قيمة من النوع "'red'" ولكن القيمة المقدمة من النوع "'blue'".

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

type direction = 'north' | 'south' | 'east' | 'west'

output west direction = 'west'
output northWest direction = 'northwest'

جميع السلاسل في Bicep تدعم الاستنتاج. لإدراج تعبير، ضعه بين ${ و}. لا يمكن أن تمتد التعبيرات المُشار إليها في عدة أسطر.

var storageName = 'storage${uniqueString(resourceGroup().id)}'

مجموعة سلاسل خطية

في Bicep، يتم تعريف مجموعة السلاسل الخطية بين ثلاثة أحرف اقتباس مفردة (''') متبوعة اختياريًا بسطر جديد (تسلسل الفتح)، وثلاثة أحرف اقتباس مفردة (''' - تسلسل الإغلاق). تتم قراءة الأحرف التي يتم إدخالها بين تسلسل الفتح والإغلاق حرفيًا، ولا يلزم أي تخطي أو حتى يمكن الحاجة إليه.

إشعار

لأن محلل Bicep يقرأ جميع الأحرف كما هي، اعتمادًا على نهايات الأسطر من ملف Bicep، يمكن تفسير خطوط جديدة على أنها \r\n أو \n.

لا يتم دعم الاستنتاج حاليًا في مجموعة السلاسل الخطية. بسبب هذا القيد، قد تحتاج إلى استخدام الدالة concat بدلا من استخدام الاستنتاج.

لا يتم دعم مجموعة السلاسل الخطية التي تحتوي على '''.

// evaluates to "hello!"
var myVar = '''hello!'''

// evaluates to "hello!" because the first newline is skipped
var myVar2 = '''
hello!'''

// evaluates to "hello!\n" because the final newline is included
var myVar3 = '''
hello!
'''

// evaluates to "  this\n    is\n      indented\n"
var myVar4 = '''
  this
    is
      indented
'''

// evaluates to "comments // are included\n/* because everything is read as-is */\n"
var myVar5 = '''
comments // are included
/* because everything is read as-is */
'''

// evaluates to "interpolation\nis ${blocked}"
// note ${blocked} is part of the string, and is not evaluated as an expression
var myVar6 = '''interpolation
is ${blocked}'''

أنواع الاتحاد

في Bicep، يسمح نوع الاتحاد بإنشاء نوع مجمع يتكون من مجموعة من الأنواع الفرعية. يكون التعيين صالحا إذا تم السماح بأي من تعيينات النوع الفرعي الفردية. يفصل | الحرف بين أنواع فرعية فردية باستخدام شرط أو . على سبيل المثال، بناء الجملة 'a' | تعني 'ب' أن التعيين الصالح يمكن أن يكون إما 'a' أو 'b'. تتم ترجمة أنواع التوحيد إلى قيد القيمة المسموح بها في Bicep، لذلك يسمح بالأحرف الحرفية فقط كأعضاء. يمكن أن تتضمن التوحيدات أي عدد من التعبيرات الحرفية.

type color = 'Red' | 'Blue' | 'White'
type trueOrFalse = 'true' | 'false'
type permittedIntegers = 1 | 2 | 3
type oneOfSeveralObjects = {foo: 'bar'} | {fizz: 'buzz'} | {snap: 'crackle'}
type mixedTypeArray = ('fizz' | 42 | {an: 'object'} | null)[]

يجب أن تكون نقابات النوع قابلة للتقليص إلى نوع ARM واحد، مثل "سلسلة" أو "int" أو "bool". وإلا، فستحصل على رمز الخطأ BCP294 . على سبيل المثال:

type foo = 'a' | 1

يمكن استخدام أي تعبير نوع كنوع فرعي في تعريف نوع الاتحاد (بين | الأحرف). على سبيل المثال، جميع الأمثلة التالية صالحة:

type foo = 1 | 2
type bar = foo | 3
type baz = bar | (4 | 5) | 6

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

يدعم Bicep نوع بيانات الاتحاد المخصص ذو العلامات، والذي يستخدم لتمثيل قيمة يمكن أن تكون واحدة من عدة أنواع مختلفة. للإعلان عن نوع بيانات اتحاد مخصص تم وضع علامة عليه، يمكنك استخدام @discriminator() مصمم. مطلوب إصدار Bicep CLI 0.21.X أو أعلى لاستخدام مصمم الديكور هذا. يتشكل بناء الجملة من:

@discriminator('<property-name>')

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

type FooConfig = {
  type: 'foo'
  value: int
}

type BarConfig = {
  type: 'bar'
  value: bool
}

@discriminator('type')
param ServiceConfig  FooConfig | BarConfig | { type: 'baz', *: string } = { type: 'bar', value: true }

يتم التحقق من قيمة المعلمة استنادا إلى قيمة الخاصية المميزة. على سبيل المثال، في المثال السابق، إذا كانت معلمة serviceConfig من نوع foo، يتم التحقق من صحتها باستخدام نوع FooConfig. وبالمثل، إذا كانت المعلمة من شريط النوع، يتم التحقق من صحتها باستخدام نوع BarConfig. ينطبق هذا النمط على أنواع أخرى أيضا.

هناك بعض القيود مع نوع الاتحاد.

• يجب أن تكون أنواع الاتحاد قابلة للخفض إلى نوع Azure Resource Manager (ARM) واحد. التعريف التالي غير صحيح:

  type foo = 'a' | 1
  

• يسمح بالأحرف الحرفية فقط كأعضاء.

• يجب أن تكون كافة القيم الحرفية من نفس نوع البيانات البدائية (على سبيل المثال، كافة السلاسل أو كافة الأعداد الصحيحة).

يمكن استخدام بناء جملة نوع الاتحاد في أنواع البيانات المعرفة من قبل المستخدم.

السلاسل والعناصر الآمنة

تستخدم السلسلة الآمنة نفس تنسيق السلسلة، ويستخدم العنصر الآمن نفس تنسيق العنصر. باستخدام Bicep، يمكنك إضافة @secure() مصمم الديكور إلى سلسلة أو كائن.

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

يظهر المثال التالي اثنين من المعلمات الآمنة:

@secure()
param password string

@secure()
param configValues object

إمكانية تعيين نوع البيانات

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

الأنواع	any	error	string	number	int	bool	null	object	array	المورد المسمى	الوحدة النمطية المسماة	scope
any	X		X	X	X	X	X	X	X	X	X	X
error
string	X		X
number	X			X	X
int	X				X
bool	X					X
null	X						X
object	X							X
array	X								X
resource	X									X
module	X										X
scope												?
المورد المسمى	س							?		?
الوحدة النمطية المسماة	س							?			?

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

لمعرفة المزيد حول بنية وبناء الجملة في Bicep، راجع هيكل ملف Bicep.