مشاركة عبر

مرجع مهام ACR: ‏YAML

  • مقالة

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

تحتوي هذه المقالة على مرجع لإنشاء ملفات YAML لمهام متعددة الخطوات لـ ACR Tasks. إذا كنت ترغب في مقدمة لـ ACR Tasks، راجع نظرة عامة على ACR Tasks.

تنسيق ملف acr-task.yaml

تدعم ACR Tasks إعلان المهام متعدد الخطوات في بناء جملة YAML القياسية. أنت تحدد خطوات المهمة في ملف YAML. يمكنك بعد ذلك تشغيل المهمة يدوياً عن طريق تمرير الملف إلى الأمر az acr run. أو استخدم الملف لإنشاء مهمة مع az acr task create التي يتم تشغيلها تلقائيا على تثبيت Git أو تحديث صورة أساسية أو جدول زمني. على الرغم من أن هذه المقالة تشير إلى acr-task.yamlعلى أنه الملف الذي يحتوي على الخطوات، إلا أن ACR Tasks تدعم أي اسم ملف صالح مع ملحق مدعوم.

العناصر الأساسية acr-task.yaml ذات المستوى الأعلى هي خصائص المهمة وأنواع الخطوات وخصائص الخطوة:

  • تنطبق خصائص المهمة على كافة الخطوات خلال تنفيذ المهمة. هناك العديد من خصائص المهام العمومية، بما في ذلك:
    • version
    • stepTimeout
    • workingDirectory
  • تمثل أنواع خطوات المهام أنواع الإجراءات التي يمكن تنفيذها في مهمة. هناك ثلاثة أنواع من الخطوات:
    • build
    • push
    • cmd
  • خصائص خطوة المهمة هي المعلمات التي تنطبق على خطوة فردية. هناك العديد من خصائص الخطوات، بما في ذلك:
    • startDelay
    • timeout
    • when
    • ...وأكثر من ذلك بكثير.

يتبع التنسيق الأساسي لملف acr-task.yaml، بما في ذلك بعض خصائص الخطوة الشائعة. على الرغم من أنه لا يمثل تمثيلاً شاملاً لجميع خصائص الخطوة المتاحة أو استخدام نوع الخطوة، إلا أنه يوفر نظرة عامة سريعة على تنسيق الملف الأساسي.

version: # acr-task.yaml format version.
stepTimeout: # Seconds each step may take.
steps: # A collection of image or container actions.
  - build: # Equivalent to "docker build," but in a multi-tenant environment
  - push: # Push a newly built or retagged image to a registry.
    when: # Step property that defines either parallel or dependent step execution.
  - cmd: # Executes a container, supports specifying an [ENTRYPOINT] and parameters.
    startDelay: # Step property that specifies the number of seconds to wait before starting execution.

ملحقات اسم ملف المهمة المعتمدة

حجزت ACR Tasks عدة ملحقات لاسم الملف، بما في ذلك .yaml، الذي سيتم معالجته كملف مهمة. يعتبر أي ملحق غير موجود في القائمة التالية من قبل ACR Tasks ملف Dockerfile: .yaml, .yml, .toml, .json, .sh, .bash, .zsh, .ps1, .ps, .cmd, .bat, .ts, .js, .php, .py, .rb, .lua

YAML هو تنسيق الملف الوحيد المعتمد حالياW من قبل ACR Tasks. ملحقات اسم الملف الأخرى محجوزة للدعم المستقبلي المحتمل.

تشغيل مهام العينة

هناك العديد من ملفات مهام العينة المشار إليها في الأقسام التالية من هذه المقالة. مهام العينة في مستودع GitHub العام، Azure-Samples/acr-tasks. يمكنك تشغيلها مع الأمر Azure CLI‏ az acr run. أوامر العينة مشابهة لما يلي:

az acr run -f build-push-hello-world.yaml https://github.com/Azure-Samples/acr-tasks.git

يفترض تنسيق أوامر العينة أنك قمت بتكوين سجل افتراضي في Azure CLI، لذلك تم حذف المعلمة --registry. لتكوين تسجيل افتراضي، استخدم الأمر az config مع الأمر set الذي يقبل زوج قيم المفاتيح defaults.acr=REGISTRY_NAME.

على سبيل المثال، لتكوين CLI Azure مع تسجيل افتراضي يسمى "myregistry":

az config set defaults.acr=myregistry

خصائص المهمة

خصائص المهمة عادة تظهر في أعلى ملف acr-task.yaml، وهي الخصائص العمومية التي تنطبق خلال التنفيذ الكامل لخطوات المهمة. يمكن تجاوز بعض هذه الخصائص العمومية ضمن خطوة فردية.

الخاصية نوع اختياري ‏‏الوصف تجاوز معتمد القيمة الافتراضية
version سلسلة ‏‏نعم‬ إصدار الملف acr-task.yaml كما تم تحليله بواسطة خدمة ACR Tasks. بينما تسعى ACR Tasks للحفاظ على التوافق مع الإصدارات السابقة، فإن هذه القيمة تسمح لـ ACR Tasks بالحفاظ على التوافق ضمن إصدار محدد. إذا لم يكن محددًا، فسيتم تعيينه افتراضياً على أحدث إصدار. لا بلا
stepTimeout int (ثوانٍ) ‏‏نعم‬ الحد الأقصى لعدد الثواني التي يمكن أن تستغرقها الخطوة. إذا تم تحديد الخاصية stepTimeout على مهمة، فسيتم تعيين الخاصية الافتراضية timeout لجميع الخطوات. إذا تم تحديد الخاصية timeout على خطوة، فسيتم تجاوز الخاصية stepTimeout التي توفرها المهمة.

يجب أن يساوي مجموع قيم مهلة الخطوة لمهمة قيمة خاصية تشغيل المهمة timeout (على سبيل المثال، تعيين بواسطة تمرير --timeout إلى الأمر az acr task create). إذا كانت قيمة تشغيل المهام timeout أصغر، فإنها تأخذ الأولوية.		 ‏‏نعم‬ 600 (10 دقائق)
workingDirectory سلسلة ‏‏نعم‬ دليل العمل للحاوية أثناء وقت التشغيل. إذا تم تحديد الخاصية على مهمة، فسيتم تعيين الخاصية الافتراضية workingDirectory لجميع الخطوات. إذا تم تحديدها في خطوة، فسيتم تجاوز الخاصية التي توفرها المهمة. ‏‏نعم‬ c:\workspaceفي Windows أو /workspace في Linux
env [سلسلة، سلسلة، ...] ‏‏نعم‬ صفيف سلاسل بتنسيق key=value لتعريف متغيرات البيئة للمهمة. إذا تم تحديد الخاصية على مهمة، فسيتم تعيين الخاصية الافتراضية env لجميع الخطوات. إذا تم تحديدها في خطوة، فسيتم تجاوز أي متغيرات للبيئة موروثة من المهمة. ‏‏نعم‬ بلا
secrets [سرية، سرية، ...] ‏‏نعم‬ صفيف من الكائنات السرية. لا بلا
networks [شبكة، شبكة، ...] ‏‏نعم‬ صفيف من كائنات الشبكة. لا بلا
volumes [حجم، حجم، ...] ‏‏نعم‬ صفيف من كائنات وحدة التخزين. تحديد وحدات التخزين ذات المحتوى المصدر التي سيتم إدخالها إلى خطوة. لا بلا

سري

الكائن السري له الخصائص التالية.

الخاصية نوع اختياري ‏‏الوصف‬ القيمة الافتراضية
id سلسلة لا معرّف السر. بلا
keyvault سلسلة ‏‏نعم‬ عنوان URL السري لـ Azure Key Vault. بلا
clientID سلسلة ‏‏نعم‬ معرف العميل الخاص بالهوية المدارة التي تم تعيينها من قبل المستخدم لموارد Azure. بلا

الشبكة

كائن شبكة الاتصال له الخصائص التالية.

الخاصية نوع اختياري ‏‏الوصف‬ القيمة الافتراضية
name سلسلة لا اسم الشبكة. بلا
driver سلسلة ‏‏نعم‬ برنامج التشغيل لإدارة الشبكة. بلا
ipv6 منطقي ‏‏نعم‬ ما إذا تم تمكين شبكة IPv6. false
skipCreation منطقي ‏‏نعم‬ ما إذا كان سيتم تخطي إنشاء الشبكة. false
isDefault منطقي ‏‏نعم‬ ما إذا كانت الشبكة شبكة افتراضية تم توفيرها مع Azure Container Registry. false

وحدة التخزين

كائن وحدة التخزين له الخصائص التالية.

الخاصية نوع اختياري ‏‏الوصف‬ القيمة الافتراضية
name سلسلة لا اسم وحدة التخزين المُدخلة. يمكن أن تحتوي على أحرف أبجدية رقمية فقط، و'-'، و'_'. بلا
secret سلسلة الخريطة [سلسلة] لا كل مفتاح من مفاتيح الخريطة هو اسم ملف تم إنشاؤه وملئه في وحدة التخزين. كل قيمة هي إصدار السلسلة من السر. يجب أن تكون القيم السرية بترميز Base64. بلا

أنواع خطوات المهام

تدعم ACR Tasks ثلاثة أنواع من الخطوات. يدعم كل نوع خطوة خصائص متعددة، مفصلة في المقطع لكل نوع خطوة.

نوع الخطوة ‏‏الوصف
build إنشاء صورة حاوية باستخدام docker build بناء جملة مألوف.
push ينفذ docker push من الصور المبنية حديثاً أو التي أعيد وضع علامات عليها إلى سجل حاوية. يتم اعتماد Azure Container Registry والسجلات الخاصة الأخرى وDocker Hub العامة.
cmd تشغيل حاوية كأمر، مع تمرير المعلمات إلى [ENTRYPOINT] الخاص بالحاوية. يدعم نوع الخطوة cmd معلمات مثل env، وdetach وخيارات أوامر مألوفة docker run أخرى، مما يتيح الوحدة والاختبار الوظيفي مع تنفيذ حاوية متزامنة.

الإنشاء

بناء صورة حاوية. يمثل نوع الخطوة build وسيلة متعددة المستأجرين وآمنة للتشغيل docker build في السحابة كخطوة بدائية من الدرجة الأولى.

بناء الجملة: بنية

version: v1.1.0
steps:
  - [build]: -t [imageName]:[tag] -f [Dockerfile] [context]
    [property]: [value]

قم بتشغيل الأمر az acr runللحصول على إصدار docker.

az acr run -r $ACR_NAME --cmd "docker version" /dev/null

أضف متغير DOCKER_BUILDKIT=1 البيئة في ملف yaml لتمكينه buildkit واستخدامه secret مع buildkit.

يدعم نوع الخطوة build المعلمات في الجدول التالي. يدعم نوع الخطوة build أيضاً جميع خيارات البنية للأمر docker build مثل تعيين متغيرات --build-arg وقت البنية.

المعلمة ‏‏الوصف‬ اختياري
-t | --image يحدد المؤهلين تأهيلاً كاملاً image:tag من الصورة المبنية.

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

على عكس az acr build، لا يوفر تشغيل ACR Tasks سلوك الدفع الافتراضي. مع ACR Tasks، يفترض السيناريو الافتراضي القدرة على إنشاء صورة والتحقق من صحتها ثم دفعها. انظر دفع لكيفية دفع الصور المبنية اختيارياً.		 ‏‏نعم‬
-f | --file تحديد ملف Dockerfile الذي تم تمريره إلى docker build. إذا لم يتم التحديد، فسيتم افتراض Dockerfile الافتراضي في جذر السياق. لتحديد Dockerfile، قم بتمرير اسم الملف المرتبط بجذر السياق. ‏‏نعم‬
context الدليل الجذر الذي تم تمريره إلى docker build. يتم تعيين الدليل الجذر لكل مهمة على دليل عمل مشترك، ويتضمن جذر دليل Git المستنسخ المرتبط. لا

الخصائص: البنية

نوع الخطوة build يدعم الخصائص التالية. ابحث عن تفاصيل هذه الخصائص في قسم خصائص خطوة المهمة بهذه المقالة.

خصائص النوع مطلوب
detach قيمة منطقية اختياري
disableWorkingDirectoryOverride قيمة منطقية اختياري
entryPoint سلسلة اختياري
env [سلسلة، سلسلة، ...] اختياري
expose [سلسلة، سلسلة، ...] اختياري
id سلسلة اختياري
ignoreErrors قيمة منطقية اختياري
isolation سلسلة اختياري
keep قيمة منطقية اختياري
network كائن اختياري
ports [سلسلة، سلسلة، ...] اختياري
pull قيمة منطقية اختياري
repeat العدد الصحيح اختياري
retries العدد الصحيح اختياري
retryDelay int (ثوانٍ) اختياري
secret كائن اختياري
startDelay int (ثوانٍ) اختياري
timeout int (ثوانٍ) اختياري
volumeMount كائن اختياري
when [سلسلة، سلسلة، ...] اختياري
workingDirectory سلسلة اختياري

أمثلة: البنية

صورة البنية - السياق في الجذر

az acr run -f build-hello-world.yaml https://github.com/AzureCR/acr-tasks-sample.git

version: v1.1.0
steps:
  - build: -t $Registry/hello-world -f hello-world.dockerfile .

صورة البنية - السياق في الدليل الفرعي

version: v1.1.0
steps:
  - build: -t $Registry/hello-world -f hello-world.dockerfile ./subDirectory

متغير ديناميكي يمر في مهام ACR

عند العمل مع مهام سجل حاوية Azure (ACR)، قد تجد نفسك بحاجة إلى تمرير قيم مختلفة إلى عملية الإنشاء دون تغيير تعريف المهمة باستخدام العلامة --setaz acr task run مع الأمر .

مثال: تعيين علامة الصورة في وقت التشغيل

لنفترض أن لديك مهمة ACR معرفة في acr-task.yml ملف مع عنصر نائب لعلامة الصورة:

steps:
  - build: -t $Registry/hello-world:{{.Values.tag}}

يمكنك تشغيل المهمة وتعيين tag المتغير إلى v2 في وقت التشغيل باستخدام أمر Azure CLI التالي:

az acr task run --registry myregistry --name mytask --set tag=v2

سيبدأ هذا الأمر مهمة ACR المسماة mytask وينشئ الصورة باستخدام العلامة v2 ، ويتجاوز العنصر النائب في acr-task.yml الملف.

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

الدفع

دفع واحدة أو أكثر من الصور المبنية أو التي أعيد وضع علامات عليها إلى سجل الحاوية. يدعم الدفع إلى السجلات الخاصة مثل Azure Container Registry، أو إلى Docker Hub العام.

بناء الجملة: دفع

يدعم نوع الخطوة push مجموعة من الصور. يعتمد بناء جملة مجموعة YAML التنسيقات المضمنة والمتداخلة. عادةً ما يتم تمثيل دفع صورة واحدة باستخدام بناء جملة مضمّن:

version: v1.1.0
steps:
  # Inline YAML collection syntax
  - push: ["$Registry/hello-world:$ID"]

لزيادة قابلية القراءة، استخدم بناء الجملة المتداخل عند دفع صور متعددة:

version: v1.1.0
steps:
  # Nested YAML collection syntax
  - push:
    - $Registry/hello-world:$ID
    - $Registry/hello-world:latest

الخصائص: دفع

نوع الخطوة push يدعم الخصائص التالية. ابحث عن تفاصيل هذه الخصائص في قسم خصائص خطوة المهمة بهذه المقالة.

الخاصية النوع مطلوب
env [سلسلة، سلسلة، ...] اختياري
id سلسلة اختياري
ignoreErrors قيمة منطقية اختياري
startDelay int (ثوانٍ) اختياري
timeout int (ثوانٍ) اختياري
when [سلسلة، سلسلة، ...] اختياري

أمثلة: دفع

دفع صور متعددة

az acr run -f build-push-hello-world.yaml https://github.com/Azure-Samples/acr-tasks.git

version: v1.1.0
steps:
  - build: -t $Registry/hello-world:$ID -f hello-world.dockerfile .
  - push: 
    - $Registry/hello-world:$ID

إنشاء صورة ودفعها وتشغيلها

az acr run -f build-run-hello-world.yaml https://github.com/Azure-Samples/acr-tasks.git

version: v1.1.0
steps:
  - build: -t $Registry/hello-world:$ID -f hello-world.dockerfile .
  - push:
    - $Registry/hello-world:$ID
  - cmd: $Registry/hello-world:$ID

cmd

نوع الخطوة cmd يشغل حاوية.

بناء الجملة: cmd

version: v1.1.0
steps:
  - [cmd]: [containerImage]:[tag (optional)] [cmdParameters to the image]

الخصائص: cmd

نوع الخطوة cmd يدعم الخصائص التالية:

الخاصية النوع مطلوب
detach قيمة منطقية اختياري
disableWorkingDirectoryOverride قيمة منطقية اختياري
entryPoint سلسلة اختياري
env [سلسلة، سلسلة، ...] اختياري
expose [سلسلة، سلسلة، ...] اختياري
id سلسلة اختياري
ignoreErrors قيمة منطقية اختياري
isolation سلسلة اختياري
keep قيمة منطقية اختياري
network كائن اختياري
ports [سلسلة، سلسلة، ...] اختياري
pull قيمة منطقية اختياري
repeat العدد الصحيح اختياري
retries العدد الصحيح اختياري
retryDelay int (ثوانٍ) اختياري
secret كائن اختياري
startDelay int (ثوانٍ) اختياري
timeout int (ثوانٍ) اختياري
volumeMount كائن اختياري
when [سلسلة، سلسلة، ...] اختياري
workingDirectory سلسلة اختياري

يمكنك العثور على تفاصيل هذه الخصائص في قسم خصائص خطوة المهمة بهذه المقالة.

أمثلة: cmd

تشغيل صورة hello-world

ينفذ هذا الأمر ملف المهمة hello-world.yaml الذي يشير إلى صورة hello-world على Docker Hub.

az acr run -f hello-world.yaml https://github.com/Azure-Samples/acr-tasks.git

version: v1.1.0
steps:
  - cmd: mcr.microsoft.com/hello-world

تشغيل صورة bash وصدى "hello world"

ينفذ هذا الأمر ملف المهمة bash-echo.yaml الذي يشير إلى صورة bash على Docker Hub.

az acr run -f bash-echo.yaml https://github.com/Azure-Samples/acr-tasks.git

version: v1.1.0
steps:
  - cmd: bash echo hello world

قم بتشغيل علامة صورة bash محددة

لتشغيل إصدار صورة محدد، حدد العلامة في cmd.

ينفذ هذا الأمر ملف المهمة bash-echo-3.yaml الذي يشير إلى صورة bash:3.0 على Docker Hub.

az acr run -f bash-echo-3.yaml https://github.com/Azure-Samples/acr-tasks.git

version: v1.1.0
steps:
  - cmd: bash:3.0 echo hello world

تشغيل الصور المخصصة

يشير نوع الخطوة cmd إلى الصور باستخدام docker run التنسيق القياسي. يُفترض أن الصور غير المُقدمة بسجل قد نشأت من docker.io. ويمكن تمثيل المثال السابق على قدم المساواة على النحو التالي:

version: v1.1.0
steps:
  - cmd: docker.io/bash:3.0 echo hello world

باستخدام اصطلاح مرجع الصورة القياسي docker run، يمكن لـ cmd تشغيل الصور من أي سجل خاص أو Docker Hub العام. إذا كنت تشير إلى الصور في نفس السجل الذي تنفذ فيه ACR Task، فلن تحتاج إلى تحديد أي بيانات اعتماد للتسجيل.

  • تشغيل صورة من سجل حاوية Azure. يفترض المثال التالي أن لديك سجل باسم myregistry، وصورة مخصصة myimage:mytag.

    version: v1.1.0
steps:
    - cmd: myregistry.azurecr.io/myimage:mytag

  • تعميم مرجع السجل باستخدام متغير تشغيل أو اسم مستعار

    بدلاً من الترميز المضمن لاسم السجل في ملف acr-task.yaml، يمكنك جعله أكثر قابلية للنقل باستخدام متغير تشغيل أو اسم مستعار. يتم توسيع المتغير Run.Registry أو الاسم المستعار $Registry في وقت التشغيل إلى اسم السجل الذي يتم تنفيذ المهمة فيه.

    على سبيل المثال، لتعميم المهمة السابقة بحيث يعمل في أي Azure Container Registry، قم بالرجوع إلى المتغير $Registry في اسم الصورة:

    version: v1.1.0
steps:
  - cmd: $Registry/myimage:mytag

الوصول إلى وحدات التخزين السرية

تسمح الخاصية volumes بتحديد وحدات التخزين ومحتوياتها السرية للخطوات build وcmd في المهمة. داخل كل خطوة، تسرد خاصية اختيارية volumeMounts وحدات التخزين ومسارات الحاوية المطابقة لإدخالها في الحاوية في تلك الخطوة. يتم توفير الأسرار كملفات في مسار إدخال كل وحدة تخزين.

تنفيذ مهمة وإدخال اثنين من الأسرار إلى خطوة: واحدة مخزن رئيسي وواحدة محددة على سطر الأوامر:

az acr run -f mounts-secrets.yaml --set-secret mysecret=abcdefg123456 https://github.com/Azure-Samples/acr-tasks.git

# This template demonstrates mounting a custom volume into a container at a CMD step
secrets:
  - id: sampleSecret
    keyvault: https://myacbvault2.vault.azure.net/secrets/SampleSecret # Replace with valid keyvault with access

volumes:
  - name: mysecrets
    secret:
      mysecret1: {{.Secrets.sampleSecret | b64enc}}
      mysecret2: {{.Values.mysecret | b64enc}}

steps:
  - cmd: bash cat /run/test/mysecret1 /run/test/mysecret2
    volumeMounts:
      - name: mysecrets
        mountPath: /run/test

خصائص خطوة المهمة

يدعم كل نوع خطوة خصائص متعددة مناسبة لنوعه. يُعرّف الجدول التالي جميع خصائص الخطوة المتوفرة. لا تدعم جميع أنواع الخطوات كل الخصائص. لمعرفة أيٍّ من هذه الخصائص متوفرة لكل نوع خطوة، راجع الأقسام المرجعية لنوع الخطوة cmd، والبنية، والدفع.

الخاصية نوع اختياري ‏‏الوصف‬ القيمة الافتراضية
detach منطقي ‏‏نعم‬ ما إذا كان يجب فصل الحاوية عند التشغيل. false
disableWorkingDirectoryOverride منطقي ‏‏نعم‬ ما إذا كان سيتم تعطيل وظيفة التجاوز workingDirectory أم لا. استخدم هذا في تركيبة مع workingDirectory أن يكون لديك تحكم كامل على دليل عمل الحاوية. false
entryPoint سلسلة ‏‏نعم‬ يتجاوز [ENTRYPOINT] لحاوية الخطوة. بلا
env [سلسلة، سلسلة، ...] ‏‏نعم‬ صفيف سلاسل بتنسيق key=value لتعريف متغيرات البيئة للخطوة. بلا
expose [سلسلة، سلسلة، ...] ‏‏نعم‬ صفيف المنافذ التي يتم كشفها من الحاوية. بلا
id سلسلة ‏‏نعم‬ يحدد الخطوة داخل المهمة بشكل فريد. يمكن للخطوات الأخرى في المهمة الرجوع إلى id للخطوة، مثل التحقق من التبعية مع when.

idهو أيضا اسم الحاوية قيد التشغيل. يمكن أن تشير العمليات التي يتم تشغيلها في حاويات أخرى في المهمة إلى id كاسم مضيف DNS الخاص به، أو للوصول إليه باستخدام سجلات عامل الإرساء [معرف]، على سبيل المثال.		 acb_step_%d، عندما يكون %d هو الفهرس المستندة إلى 0 للخطوة من أعلى لأسفل في ملف YAML
ignoreErrors منطقي ‏‏نعم‬ ما إذا كان يجب وضع علامة على الخطوة على أنها ناجحة بغض النظر عمّا إذا كان قد حدث خطأ أثناء تنفيذ الحاوية. false
isolation سلسلة ‏‏نعم‬ مستوى عزل الحاوية. default
keep منطقي ‏‏نعم‬ ما إذا كان يجب الاحتفاظ بحاوية الخطوة بعد التنفيذ أم لا. false
network كائن ‏‏نعم‬ يحدد الشبكة التي تعمل فيها الحاوية. بلا
ports [سلسلة، سلسلة، ...] ‏‏نعم‬ صفيف المنافذ التي يتم نشرها من الحاوية إلى المضيف. بلا
pull منطقي ‏‏نعم‬ ما إذا كان سيتم فرض سحب الحاوية قبل تنفيذها لمنع أي سلوك خاص بالتخزين المؤقت أم لا. false
privileged منطقي ‏‏نعم‬ ما إذا كان سيتم تشغيل الحاوية في الوضع المميز أم لا. false
repeat العدد الصحيح ‏‏نعم‬ عدد مرات إعادة المحاولة لتكرار تنفيذ حاوية. 0
retries العدد الصحيح ‏‏نعم‬ عدد مرات إعادة المحاولة إذا فشلت الحاوية في التنفيذ. تتم محاولة إعادة المحاولة فقط إذا كانت التعليمة البرمجية للخروج للحاوية غير صفرية. 0
retryDelay int (ثوانٍ) ‏‏نعم‬ التأخير بالثواني بين إعادة محاولة تنفيذ الحاوية. 0
secret كائن ‏‏نعم‬ يحدد سر Azure Key Vault أو الهوية المدارة لموارد Azure. بلا
startDelay int (ثوانٍ) ‏‏نعم‬ عدد الثواني لتأخير تنفيذ حاوية. 0
timeout int (ثوانٍ) ‏‏نعم‬ الحد الأقصى لعدد الثواني التي قد تُنفّذ خلالها خطوة قبل إنهائها. 600
when [سلسلة، سلسلة، ...] ‏‏نعم‬ تكوين تبعية خطوة على خطوة أخرى أو أكثر داخل المهمة. بلا
user سلسلة ‏‏نعم‬ اسم المستخدم أو UID للحاوية بلا
workingDirectory سلسلة ‏‏نعم‬ تعيين الدليل المشغَّل لخطوة. بشكل افتراضي، تقوم ACR Tasks بإنشاء دليل جذر كدليل المشغَّل. ومع ذلك، إذا كان للبنية الخاصة بك عدة خطوات، فيمكن للخطوات السابقة مشاركة البيانات الاصطناعية مع الخطوات اللاحقة عن طريق تحديد دليل العمل نفسه. c:\workspaceفي Windows أو /workspace في Linux

volumeMount

كائن volumeMount له الخصائص التالية.

الخاصية نوع اختياري ‏‏الوصف‬ القيمة الافتراضية
name سلسلة لا اسم وحدة التخزين المُدخلة. يجب أن تتطابق تماماً مع الاسم من خاصية volumes. بلا
mountPath سلسلة no المسار المطلق لإدخال الملفات في الحاوية. بلا

أمثلة: خصائص خطوة المهمة

مثال: معرف

قم ببناء صورتين، مع إنشاء صورة اختبار وظيفية. يتم تحديد كل خطوة من خلال id فريد وهو ما تشير إليه الخطوات الأخرى في خاصية when الخاصة بهم.

az acr run -f when-parallel-dependent.yaml https://github.com/Azure-Samples/acr-tasks.git

version: v1.1.0
steps:
  # build website and func-test images, concurrently
  - id: build-hello-world
    build: -t $Registry/hello-world:$ID -f hello-world.dockerfile .
    when: ["-"]
  - id: build-hello-world-test
    build: -t hello-world-test -f hello-world.dockerfile .
    when: ["-"]
  # run built images to be tested
  - id: hello-world
    cmd: $Registry/hello-world:$ID
    when: ["build-hello-world"]
  - id: func-tests
    cmd: hello-world-test
    env:
      - TEST_TARGET_URL=hello-world
    when: ["hello-world"]
  # push hello-world if func-tests are successful  
  - push: ["$Registry/hello-world:$ID"]
    when: ["func-tests"]

مثال: متى

تحدد الخاصية when تبعية الخطوة على الخطوات الأخرى داخل المهمة. يدعم قيمتين للمعلمات:

  • when: ["-"] - يشير إلى عدم وجود تبعية على الخطوات الأخرى. الخطوة التي تحدد أن when: ["-"] ستبدأ التنفيذ على الفور، وتُمكّن تنفيذ الخطوة المتزامن.
  • when: ["id1", "id2"] - يشير إلى أن الخطوة تعتمد على الخطوات التي لها المعرفات id "id1" وid "id2". لن يتم تنفيذ هذه الخطوة حتى تكتمل الخطوات "id1" و"id2".

إذا لم يتم تحديد when في إحدى الخطوات، فإن هذه الخطوة تعتمد على إكمال الخطوة السابقة في ملف acr-task.yaml.

تنفيذ خطوة تسلسلية دون when :

az acr run -f when-sequential-default.yaml https://github.com/Azure-Samples/acr-tasks.git

version: v1.1.0
steps:
    - cmd: bash echo one
    - cmd: bash echo two
    - cmd: bash echo three

تنفيذ خطوة تسلسلية مع when :

az acr run -f when-sequential-id.yaml https://github.com/Azure-Samples/acr-tasks.git

version: v1.1.0
steps:
    - id: step1
      cmd: bash echo one
    - id: step2
      cmd: bash echo two
      when: ["step1"]
    - id: step3
      cmd: bash echo three
      when: ["step2"]

بنية بصور متوازية:

az acr run -f when-parallel.yaml https://github.com/Azure-Samples/acr-tasks.git

version: v1.1.0
steps:
  # build website and func-test images, concurrently
  - id: build-hello-world
    build: -t $Registry/hello-world:$ID -f hello-world.dockerfile .
    when: ["-"]
  - id: build-hello-world-test
    build: -t hello-world-test -f hello-world.dockerfile .
    when: ["-"]

بنية بصورة متوازية واختبار تابع:

az acr run -f when-parallel-dependent.yaml https://github.com/Azure-Samples/acr-tasks.git

version: v1.1.0
steps:
  # build website and func-test images, concurrently
  - id: build-hello-world
    build: -t $Registry/hello-world:$ID -f hello-world.dockerfile .
    when: ["-"]
  - id: build-hello-world-test
    build: -t hello-world-test -f hello-world.dockerfile .
    when: ["-"]
  # run built images to be tested
  - id: hello-world
    cmd: $Registry/hello-world:$ID
    when: ["build-hello-world"]
  - id: func-tests
    cmd: hello-world-test
    env:
      - TEST_TARGET_URL=hello-world
    when: ["hello-world"]
  # push hello-world if func-tests are successful  
  - push: ["$Registry/hello-world:$ID"]
    when: ["func-tests"]

تشغيل المتغيرات

تتضمن ACR Tasks مجموعة افتراضية من المتغيرات المتوفرة لخطوات المهمة عند تنفيذها. يمكن الوصول إلى هذه المتغيرات باستخدام التنسيق {{.Run.VariableName}}، حيث يكون VariableName واحد ما يلي:

  • Run.ID
  • Run.SharedVolume
  • Run.Registry
  • Run.RegistryName
  • Run.Date
  • Run.OS
  • Run.Architecture
  • Run.Commit
  • Run.Branch
  • Run.TaskName

أسماء المتغيرات بشكل عام تشرح نفسها بنفسها. التفاصيل تتبع للمتغيرات شائعة الاستخدام. بدءًا من إصدار YAML v1.1.0، يمكنك استخدام اسم مستعار للمهمة مختصر ومحدد مسبقاً بدلاً من معظم متغيرات التشغيل. على سبيل المثال، بدلاً من {{.Run.Registry}}، استخدم الاسم المستعار $Registry.

Run.ID

كل عملية تشغيل، عبر az acr run، أو تنفيذ المهام المستند إلى التشغيل التي تم إنشاؤها من خلال az acr task create، لها معرف فريد. يمثل المعرف التشغيل الجاري تنفيذه حاليًا.

تُستخدم عادةً لوضع علامات على صورة بشكل فريد:

version: v1.1.0
steps:
    - build: -t $Registry/hello-world:$ID .

Run.SharedVolume

المعرف الفريد لوحدة تخزين مشتركة يمكن الوصول إليها بواسطة جميع خطوات المهمة. يتم إدخال وحدة التخزين c:\workspace في Windows أو في /workspace Linux.

Run.Registry

اسم الخادم المؤهل بالكامل للسجل. تُستخدم عادةً للإشارة إلى السجل بشكل عام حيث يتم تشغيل المهمة.

version: v1.1.0
steps:
  - build: -t $Registry/hello-world:$ID .

Run.RegistryName

اسم سجل الحاوية. تستخدم عادة في خطوات المهام التي لا تتطلب اسم خادم مؤهل بالكامل، على سبيل المثال، الخطوات cmd التي تقوم بتشغيل أوامر Azure CLI على السجلات.

version 1.1.0
steps:
# List repositories in registry
- cmd: az login --identity
- cmd: az acr repository list --name $RegistryName

Run.Date

وقت بدء التشغيل بالتوقيت العالمي المتفق عليه (UTC) الحالي.

Run.Commit

بالنسبة لمهمة يتم تشغيلها بواسطة تثبيت بمستودع GitHub، معرف التثبيت.

Run.Branch

بالنسبة لمهمة يتم تشغيلها بواسطة تثبيت بمستودع GitHub، اسم الفرع.

الأسماء المستعارة

اعتبارًا من v1.1.0، تدعم ACR Tasks الأسماء المستعارة المتوفرة لخطوات المهام عند تنفيذها. الأسماء المستعارة مشابهة في المفهوم إلى الأسماء المستعارة (اختصارات الأوامر) المعتمدة في bash وبعض أوامر shells الأخرى.

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

تدعم ACR Tasks العديد من الأسماء المستعارة المحددة مسبقًا وكذلك الأسماء المستعارة المخصصة التي تقوم بإنشائها.

أسماء مستعارة محددة مسبقاً

تتوفر أسماء المهام المستعارة التالية لاستخدامها بدلاً من متغيرات التشغيل:

الاسم المستعار تشغيل متغير
ID Run.ID
SharedVolume Run.SharedVolume
Registry Run.Registry
RegistryName Run.RegistryName
Date Run.Date
OS Run.OS
Architecture Run.Architecture
Commit Run.Commit
Branch Run.Branch

في خطوات المهمة، اسبق الاسم المستعار بالتوجيه $، كما في هذا المثال:

version: v1.1.0
steps:
  - build: -t $Registry/hello-world:$ID -f hello-world.dockerfile .

أسماء مستعارة للصور

يشير كل من الأسماء المستعارة التالية إلى صورة ثابتة في Microsoft Container Registry (MCR). يمكنك الرجوع إلى كل منهم في قسم cmd من ملف المهمة دون استخدام توجيه.

الاسم المستعار الصورة
acr mcr.microsoft.com/acr/acr-cli:0.5
az mcr.microsoft.com/acr/azure-cli:7ee1d7f
bash mcr.microsoft.com/acr/bash:7ee1d7f
curl mcr.microsoft.com/acr/curl:7ee1d7f

يستخدم المثال التالي للمهمة العديد من الأسماء المستعارة لمسح علامات الصور الأقدم من 7 أيام في المستودع samples/hello-world في سجل التشغيل:

version: v1.1.0
steps:
  - cmd: acr tag list --registry $RegistryName --repository samples/hello-world
  - cmd: acr purge --registry $RegistryName --filter samples/hello-world:.* --ago 7d

الاسم المستعار المخصص

حدد اسماً مستعاراً مخصصاً في ملف YAML الخاص بك واستخدمه كما هو موضح في المثال التالي. يمكن أن يحتوي الاسم المستعار على أحرف أبجدية رقمية فقط. التوجيه الافتراضي لتوسيع اسم مستعار هو الحرف $.

version: v1.1.0
alias:
  values:
    repo: myrepo
steps:
  - build: -t $Registry/$repo/hello-world:$ID -f Dockerfile .

يمكنك الارتباط بملف YAML بعيد أو محلي للحصول على تعريفات الاسم المستعار المخصصة. يرتبط المثال التالي بملف YAML في Azure Blob Storage:

version: v1.1.0
alias:
  src:  # link to local or remote custom alias files
    - 'https://link/to/blob/remoteAliases.yml?readSasToken'
[...]

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

للحصول على نظرة عامة على المهام متعددة الخطوات، راجع تشغيل مهام البناء والاختبار والتصحيح متعددة الخطوات في ACR Tasks.

للحصول على البُنى أحادية الخطوة، راجع نظرة عامة حول ACR Tasks.