الوحدة 4 من مسار Monaco SaaS: نشر Monaco SaaS، من المشاريع وقوالب JSON حتى التشغيل التجريبي (dry-run) الذي يتحقق من المستودع قبل أي استدعاء لواجهة API.
المسار: Monaco SaaS · الوحدة 4 · المدة: نحو 50 دقيقة · المستوى: متوسط
الأهداف:
- تنظيم مستودع في مشاريع وملفات YAML وقوالب JSON
- كتابة إعداد من نوع Settings (
schemaوscope) ومعاملاته - التصريح بتبعية بين إعدادين
- التحقق بالأمر
monaco deploy --dry-runثم استهداف مشروع أو بيئة
المتطلبات المسبقة: تثبيت Monaco وجاهزية ملف بيان (manifest) (الوحدة 2)، ويفضَّل أن تكون قد قرأت تصديرًا (الوحدة 3)، وبيئة اختبار Dynatrace SaaS.
التصدير مجرد نقطة انطلاق: فائدة الإعداد ككود هي إعادة النشر، بالمطابقة نفسها أو مع اختلافات، على بيئة أخرى. تغطي هذه الوحدة نشر Monaco SaaS: كيف يقرأ Monaco مستودعًا، وكيف يرتّب الإعدادات، وكيف تتحقق من النتيجة دون كسر شيء. بالنسبة لمهندس SRE، هذه اللحظة التي يتوقف فيها الإعداد عن كونه إجراءً يدويًا ويصبح تغييرًا مراجَعًا ومختبَرًا وقابلًا للتكرار. المحتوى صالح لـ Dynatrace SaaS فقط.
نشر Monaco SaaS: المشاريع وملفات YAML وقوالب المستودع
يقوم Monaco على ثلاثة عناصر تصفها الوثائق الرسمية: ملف البيان (manifest) والمشاريع والإعدادات. يربط كل إعداد ملفين:
- ملف YAML يعطي المعرّف والنوع والاسم والقالب والمعاملات؛
- قالب JSON يحتوي الحمولة المرسلة إلى واجهة API، مع مواضع
{{ .nom }}تملؤها المعاملات.
يصرّح ملف البيان بالمشاريع (اسم ومسار) وبالبيئات المستهدفة مجمّعة في مجموعات. هذا مثال دليل البدء في الوثائق: مشروع واحد وبيئة واحدة، ومصادقة برمز منصة (platform token) يُقرأ من متغير بيئة.

نقطتان للتذكّر. أولًا، مسار المشروع البسيط يساوي اسمه إن حُذف، وتُكتب المسارات بشرطات مائلة أمامية أيًّا كان النظام. ثانيًا، المشروع من نوع grouping يحمّل كل مجلد فرعي بوصفه مشروعًا مستقلًا: يصبح general/infrastructure وgeneral/zones هما general.infrastructure وgeneral.zones.
كتابة إعداد YAML وقالبه
يبدأ ملف الإعداد بـ configs، وهي قائمة. يتطلب كل عنصر id وtype وconfig. المعرّف id محلي في Monaco: يجب أن يكون فريدًا للنوع نفسه والمشروع نفسه، ولا يطابق المعرّف الذي تمنحه Dynatrace. داخل config نجد template (القالب) وskip (عدم النشر إذا كانت القيمة true) وparameters.
مثال من الوثائق، إعداد من نوع SLO مع قائمة وسوم:
configs:
- id: my-sample-slo
config:
name: mySampleSLO
parameters:
tags:
type: list
values: ["service:myService", "dt.owner:myTeam"]
template: slo.json
skip: false
type: slo-v2
في القالب، يستعيد "name": "{{ .name }}" و"tags": {{ .tags }} هذه القيم. تُكتب القائمة دون أقواس إضافية في JSON. توصي الوثائق بإبقاء القوالب بسيطة والاكتفاء بصيغة المتغيرات هذه.
أنواع المعاملات
| النوع | الاستخدام |
|---|---|
value |
قيمة ثابتة؛ صيغة مختصرة ممكنة للقيمة المفردة (threshold: 15) |
environment |
يقرأ متغير بيئة (name وdefault اختياري)؛ يفشل النشر إذا كان المتغير مفقودًا ولا يوجد default |
reference |
يحيل إلى إعداد آخر (project وconfigType وconfigId وproperty) |
compound |
يجمع معاملات أخرى في سلسلة نصية (format وreferences) |
list |
قائمة قيم (values) |
file |
يحمّل محتوى ملف (ابتداءً من Monaco 2.14.0) |
لا يُقيَّم المعامل إلا إذا أشار إليه إعداد سيُنشر. لذلك لا يمنع متغير بيئة مفقود نشرًا لا يستخدمه.
كائنات Settings والنطاق (scope) والتبعيات
بالنسبة لكائن Settings، يأخذ الحقل type كتلة settings فيها schema وschemaVersion اختياري وscope. يمكن أن يكون scope قيمة أو إحالة أو environment الذي يستهدف البيئة كاملة. تتيح الإحالة إلى معرّف إعداد آخر ضبط كيان أنشأه Monaco للتو. تعطي الوثائق هذا المثال: تطبيق ويب ثم إعدادات RUM الخاصة به.

تنشئ هذه الإحالة تبعية. ينشر Monaco الإعدادات بالترتيب، ويسبق الإعداد المعتمَد عليه الإعداد التابع. تؤدي دورة تبعيات (cycle) إلى فشل النشر بخطأ. توجد الحقول insertAfter (ترتيب الكائنات في المخططات المرتّبة) وpermission أيضًا في Settings؛ وتوضح الوثائق أن بعض المخططات لا تقبلها.
للصيغة المختصرة للإحالة تكفي مصفوفة: [ project, configType, configId, property ]. يمكن حذف المستويات العليا: دون configType يُستخدم المشروع الحالي. بالنسبة لإعداد Settings، يطابق configType معرّف المخطط (schema).
اختلافات حسب البيئة
تعدّل الحقول الاختيارية environmentOverrides وgroupOverrides قيمة ما لبيئة أو مجموعة، مثلًا skip: true لاستبعاد إعداد من الإنتاج. وهي أداة الترقية من dev إلى prod التي يتناولها المسار لاحقًا.
التحقق ثم النشر
الأمر هو monaco deploy <manifest.yaml>. خياراته، كما قُرئت في شيفرة المستودع dynatrace-configuration-as-code (GitHub) وفي صفحة مرجع الأوامر:

--dry-run(-d): يتحقق من بنية ملف البيان والمشاريع والإعدادات، ويحلّ المعاملات ويولّد القوالب. لا يتصل بـ Dynatrace: يبقى خطأ HTTP 400 ممكنًا عند النشر الفعلي إذا كان محتوى JSON غير صالح؛--environment(-e) أو--group(-g)، وهما متنافيان: دون أيٍّ منهما تُستهدف كل البيئات؛--project(-p): ينشر هذا المشروع فقط والإعدادات التي يعتمد عليها؛--continue-on-error(-c): يواصل رغم الخطأ، مع خطر أخطاء متتالية في الإعدادات التابعة.
دون وسيط ملف، ينتظر الأمر ملف بيان بامتداد .yaml. ينتهي التشغيل التجريبي الناجح بالرسالة «Validation finished without errors»، وفق دليل البدء.
تمرين تطبيقي
يُنفَّذ على بيئة اختبار Dynatrace SaaS. الأوامر التالية هي أوامر الوثائق؛ ولم تُنفَّذ لإعداد هذه الوحدة.
الخطوة 1 — إنشاء شجرة المجلدات
mkdir -p monaco-getting-started/project-example/slo
cd monaco-getting-started/project-example/slo
touch slo.json slo.yaml
cd ../..
touch manifest.yaml
النتيجة المتوقعة: شجرة المجلدات في اللقطة الأولى.
الخطوة 2 — تعبئة الملفات
انسخ ملف البيان من اللقطة، وملف YAML الخاص بـ SLO، وقالب slo.json يستعيد {{ .name }} و{{ .tags }}. يوفّر دليل البدء القالب الكامل. يجب أن يحمل رمز المنصة النطاقات slo:slos:read وslo:slos:write وslo:objective-templates:read لهذا المثال.
الخطوة 3 — تصدير المتغيرات
export DT_ENV_URL="https://<votre-environnement>.apps.dynatrace.com"
export PLATFORM_TOKEN="<votre-jeton>"
لا تضع الرمز أبدًا في ملف خاضع للتحكم بالإصدارات. النتيجة المتوقعة: المتغيران ظاهران في الصدفة (shell) وليس في المستودع.
الخطوة 4 — التحقق
monaco deploy --dry-run manifest.yaml
النتيجة المتوقعة: يُسرد المشروع والبيئة، ثم «Validation finished without errors». اكسر JSON القالب عمدًا لملاحظة الفشل، ثم صحّحه.
الخطوة 5 — النشر ثم الاستهداف
monaco deploy manifest.yaml -p my-slo-project -e development-environment
النتيجة المتوقعة: يظهر SLO في بيئة الاختبار. أعد تشغيل الأمر: يجب أن يُحدَّث الكائن لا أن يُكرَّر.
اختبار قصير
- ماذا يحتوي قالب JSON؟ أ) معرّفات البيئات ب) الحمولة المرسلة إلى واجهة API مع متغيرات ج) رمز API د) قائمة المشاريع
- ما الذي لا يستطيع
--dry-runاكتشافه؟ أ) YAML سيئ التكوين ب) قالب ليس JSON ج) محتوى JSON ترفضه واجهة API في Dynatrace د) معامل غير موجود - كيف يُصرَّح بأن كائن Settings يعتمد على تطبيق أنشأه Monaco؟ أ) بـ
scopeمن نوعreferenceب) باسم مطابق ج) بالخيار-cد) بملف بيان ثانٍ - ماذا يحدث عند وجود دورة تبعيات؟ أ) يتجاهلها Monaco ب) يفشل النشر بخطأ ج) يختار Monaco الترتيب الأبجدي د) يفشل التشغيل التجريبي فقط
الإجابات
- ب) يصف YAML الإعداد، ويحمل القالب JSON الخاص بواجهة API.
- ج) لا يتصل التشغيل التجريبي بـ Dynatrace؛ والنشر الفعلي وحده يكشف JSON المرفوض.
- أ) تجعل الإحالة الإعداد المُحال إليه يُنشر أولًا.
- ب) تشير الوثائق إلى أن النشر يفشل بخطأ.
للمزيد
- Dynatrace Monaco: الإعداد ككود خطوة بخطوة
- Monaco أم Terraform: أي أداة لإعداد Dynatrace؟
- مخططات Settings في واجهة API الخاصة بـ Dynatrace SaaS، للعثور على
schemaالمناسب - بنية ملف YAML للإعداد في Monaco
← الوحدة 3: تصدير Monaco SaaS · فهرس المسار · الوحدة 5: OAuth في Monaco SaaS →
الأسئلة الشائعة
هل يضمن التشغيل التجريبي نجاح النشر؟
لا. يتحقق من البنية ومن توليد القوالب، لكنه لا يتصل بـ Dynatrace. قد ترفض واجهة API محتوى JSON يراه Monaco صالحًا.
هل يلزم اسم في كل إعداد؟
في الأنواع api نعم: الاسم يحدد الكائن. ومنذ Monaco 2.7.0 أصبح اختياريًا لبقية الأنواع، التي تُعرَّف بإحداثياتها (المشروع والنوع والمعرّف) أو بـ originObjectId.
كيف أنشر إلى بيئة واحدة فقط؟
بالخيار --environment (أو --group لمجموعة). يستبعد الخياران أحدهما الآخر.
أصبحت تعرف الآن كيف تنظّم مستودعًا وتصرّح بالتبعيات وتتحقق قبل النشر. تتناول الوحدة التالية المصادقة عبر OAuth ورمز المنصة، والأسرار، والحذف.
span.observer مدوّنة مجتمعية مستقلة وغير تابعة لشركة Dynatrace LLC. Dynatrace علامة تجارية لشركة Dynatrace LLC. لا يحل هذا المسار محل دورات وشهادات Dynatrace University الرسمية. تحقق دائمًا من القيم (المنافذ والإصدارات والأحجام) في الوثائق الرسمية الخاصة بإصدارك.