API Dynatrace Managed: Cluster API v1 وv2 وEnvironment API ومخططات Settings المتاحة

API Dynatrace Managed: Cluster API v1 وv2 وEnvironment API وعناوين URL والرموز والصلاحيات وقائمة مخططات Settings في إصدارك بـ curl.
API Dynatrace Managed : Cluster API v1 et v2, Environment API et schémas Settings disponibles

أنت تؤتمت عنقود Managed، ويبدأ كل سكربت بالسؤال نفسه: أي عنوان URL أستدعي، وبأي رمز، وهل هذه النقطة موجودة فعلًا في إصداري؟ إن API Dynatrace Managed ليست واجهة واحدة بل عائلتان تعيشان جنبًا إلى جنب: Cluster API التي تدير العنقود من Cluster Management Console (CMC)، وEnvironment API التي تعمل داخل بيئة.

الخلط بينهما مكلف في العبء التشغيلي: رمز عنقود يُرسل إلى نقطة بيئة، وعنوان SaaS منسوخ من درس، ومخطط Settings لم يظهر بعد في إصدارك. والنتيجة: أخطاء 401 و404 ومسارات أتمتة تفشل ليلًا.

هدف هذا الدليل المرجعي: أن تعرف في دقائق أي API تستدعي، وبأي رمز وصلاحية، وكيف تسرد مخططات Settings المتاحة فعلًا في عنقودك. المحتوى صالح لـ Dynatrace Managed وحده؛ وتُشار الفروق مع SaaS.

عائلتا API Dynatrace Managed

تميّز وثائق Managed بوضوح بين نطاقين. تعمل Cluster API على العنقود كله، حتى لو استضاف عدة بيئات. وتعمل Environment API على بيئة محددة يعرّفها معرّفها في عنوان URL.

المعيار Cluster API (v1 وv2) Environment API (v1 وv2 وconfig v1)
النطاق العنقود كله: العقد والبيئات والمستخدمون والترخيص ورموز العنقود بيئة واحدة: الكيانات والمقاييس والمشكلات وSettings ورموز البيئة
عنوان URL الأساسي https://{cluster}/api/cluster/v2/… وhttps://{cluster}/api/v1.0/onpremise/… https://{cluster}/e/{environment-id}/api/v2/…
أين يُنشأ الرمز CMC، Settings > API tokens، قسم Cluster tokens داخل البيئة، صفحة Access Tokens
الصلاحيات المعتادة ServiceProviderAPI، ClusterTokenManagement settings.read، apiTokens.write، إلخ.
الوثائق التفاعلية قائمة المستخدم في CMC، Cluster API v1 أو Cluster API v2 مستكشف API الخاص بالبيئة

لأتمتة الإدارة بالكامل (إنشاء بيئات بالجملة وإدارة المستخدمين) راجع أيضًا الدرس أتمتة الإدارة عبر API Cluster. وهنا نركّز على الخريطة والأخطاء الشائعة.

المتطلبات المسبقة

  • عنقود Dynatrace Managed وصلاحية مدير على CMC.
  • رمز عنقود بالصلاحية ServiceProviderAPI (قراءة البيئات والعقد والمستخدمين والترخيص وإدارتها).
  • رمز بيئة بالنطاق settings.read لسرد المخططات.
  • curl وjq على الجهاز الذي يستدعي API.

يُرسل الرمزان في الترويسة Authorization: Api-Token …. وعند الرفض يفصّل دليل استكشاف أخطاء رمز API في Dynatrace تشخيص 401 و403 و404.

الخطوة 1: أنشئ الرموز الصحيحة

رمز العنقود

في CMC افتح Settings > API tokens، ثم في قسم Cluster tokens اختر Generate token. الصلاحيات الموثقة لإعداد العنقود هي:

الاسم المعروض قيمة API الاستخدام
Cluster token management ClusterTokenManagement إدارة رموز العنقود عبر Tokens API
Service Provider API ServiceProviderAPI عمليات إدارة العنقود (البيئات والمستخدمون والعقد والترخيص)
Read settings settings.read قراءة إعدادات مستوى العنقود (API v2)
Write settings settings.write كتابة إعدادات مستوى العنقود (API v2)

توصي Dynatrace برمز لكل استخدام، بنطاق واحد إن أمكن: فعند التسرب يبقى نطاق الضرر محدودًا.

رمز إدارة رموز البيئة

تقترح الصفحة نفسها قسم Environment token management tokens. يُستخدم هذا الرمز لإنشاء رموز في بيئة معينة عبر API. وهو صالح 24 ساعة فقط، بسبب أثره المحتمل على جميع البيئات.

رمز البيئة

في البيئة، صفحة Access Tokens، اختر Generate new token وحدد settings.read. انسخه فورًا: فلن يُعرض ثانية.

الخطوة 2: جدول مرجعي لنقاط Cluster API

هذه هي النقاط الأكثر استخدامًا يوميًا، وكلها مُتحقَّق منها في وثائق Managed. وتتطلب كلها الصلاحية ServiceProviderAPI، عدا الرموز (ClusterTokenManagement).

العائلة الطريقة والمسار الإصدار
البيئات GET / POST /api/cluster/v2/environments v2
بيئة محددة GET / PUT / DELETE /api/cluster/v2/environments/{id} v2
العقد المعروفة GET /api/v1.0/onpremise/cluster v1
إعداد العقد GET /api/v1.0/onpremise/cluster/configuration v1
المستخدمون GET /api/v1.0/onpremise/users v1
مجموعات المستخدمين GET /api/v1.0/onpremise/groups v1
الترخيص (تصدير) GET /api/cluster/v2/license/consumption v2
رموز العنقود GET / POST /api/cluster/v2/tokens v2

تغطي Cluster API v1 أيضًا صيانة العنقود، والوكيل (proxy) الإنترنتي (بما في ذلك لكل مركز بيانات في التوافر العالي)، وسياسة كلمات المرور، وشهادات SSL، وإطلاق التحديثات. وتضيف v2 مواقع وعقد Synthetic الخاصة، وجلسات المستخدمين، والوصول عن بعد، وحالة Log Monitoring. والقائمة الدقيقة تتوقف على إصدارك: ووثائق CMC التفاعلية هي المرجع.

بعض التفاصيل المفيدة:

  • الاستدعاء GET /api/cluster/v2/environments مقسم إلى صفحات: pageSize (100 افتراضيًا و1000 كحد أقصى) وnextPageKey وsort (name و-name وcreationDate…) وfilter، مثل name(prod).
  • يعيد POST /api/cluster/v2/environments?createToken=true، إضافة إلى البيئة، رمز إدارة رموز (apiTokens.read وapiTokens.write وTenantTokenManagement) يمكن استخدامه في البيئة الجديدة.
  • يعيد تصدير الترخيص ملف ZIP (application/octet-stream) ولا يعمل إلا مع الترخيص الكلاسيكي (classic licensing): وإلا جاء الرد 422.

لإدارة الحصص لكل بيئة راجع إدارة عدة بيئات وحصص الترخيص في CMC.

الخطوة 3: استدعِ Cluster API بـ curl

export DT_CLUSTER="https://managed.example.com"
export DT_CLUSTER_TOKEN="dt0c01.XXXX..."   # cluster token, ServiceProviderAPI

# List environments (name and ID), sorted by name
curl -s "$DT_CLUSTER/api/cluster/v2/environments?pageSize=100&sort=name" \
  -H "Authorization: Api-Token $DT_CLUSTER_TOKEN" \
  -H "accept: application/json" | jq '.environments[] | {id, name, state}'

# List known nodes and their version
curl -s "$DT_CLUSTER/api/v1.0/onpremise/cluster" \
  -H "Authorization: Api-Token $DT_CLUSTER_TOKEN" \
  | jq '.[] | {id, buildVersion, operationState}'

يعيد الأمر الثاني لكل عقدة الحقول id وbuildVersion وoperationState. وهو أبسط وسيلة لمعرفة إصدار عنقودك قبل استخدام نقطة حديثة. أما أسماء حقول الرد الأول (environments وstate) فتحقق منها في إصدارك عبر مستكشف CMC.

الخطوة 4: اسرد مخططات Settings في إصدارك

تتطور مخططات Settings 2.0 مع كل إصدار. وقد لا يوجد بعد في عنقودك مخطط موثق لـ SaaS. لا تخمّن: اطلب القائمة من البيئة.

export DT_ENV="https://managed.example.com/e/abc12345-6789"
export DT_ENV_TOKEN="dt0c01.YYYY..."   # environment token, settings.read

curl -s "$DT_ENV/api/v2/settings/schemas?fields=schemaId,displayName,latestSchemaVersion,maturity" \
  -H "Authorization: Api-Token $DT_ENV_TOKEN" \
  | jq -r '.items[] | [.schemaId, .latestSchemaVersion, .maturity] | @tsv' | sort

الرد كائن SchemaList: مصفوفة items وعداد totalCount. ويقبل المعامل fields القيم schemaId وdisplayName وmaturity وlatestSchemaVersion وmultiObject وordered وownerBasedAccessControl. وتأخذ maturity القيمة PREVIEW أو EARLY_ADOPTER أو GENERAL_AVAILABILITY: وفي أتمتة الإنتاج فضّل المخططات GA.

مثال للتحقق من وجود مخطط قبل استخدامه في Terraform أو Monaco:

curl -s "$DT_ENV/api/v2/settings/schemas?fields=schemaId" \
  -H "Authorization: Api-Token $DT_ENV_TOKEN" \
  | jq -e '.items[] | select(.schemaId == "builtin:alerting.profile")' \
  && echo "schema available" || echo "schema absent on this version"

بعد ذلك يسرد GET /api/v2/settings/objects?schemaIds=… (النطاق settings.read) الكائنات الموجودة لهذا المخطط. وإذا مر الاستدعاء عبر ActiveGate يصبح العنوان https://{activegate}:9999/e/{environment-id}/api/v2/….

ما لا يوجد في Managed

تستهدف أمثلة كثيرة منشورة منصة SaaS. قبل نسخ استدعاء، تأكد أنه لا يعتمد على أحد هذه المكونات، وهي غائبة عن Managed:

  • واجهات المنصة (عناوين *.apps.dynatrace.com/platform/…)، ورموز المنصة ومصادقة OAuth المرتبطة بها؛
  • Grail واستعلامات DQL عبر واجهة التخزين؛
  • AppEngine وتطبيقات Dynatrace وWorkflows المنصة وNotebooks أو Dashboards الجيل الجديد؛
  • Account Management API (api.dynatrace.com/iam/v1/…): في Managed يمر المستخدمون والمجموعات عبر Cluster API v1.

وصفحة المصادقة في وثائق Managed نفسها تحيل إلى قائمة الوظائف غير المتاحة في Managed لرموز المنصة. في Managed التزم بـ Environment API v1 وv2 وواجهة الإعداد v1 وCluster API.

كيف تتحقق من أنه يعمل

  1. يعيد GET /api/v1.0/onpremise/cluster الرمز 200 وقائمة العقد: رمز العنقود وعنوان URL سليمان.
  2. يعيد GET /api/cluster/v2/environments بيئاتك: الصلاحية ServiceProviderAPI موجودة.
  3. يعيد GET /e/{id}/api/v2/settings/schemas قيمة totalCount أكبر من صفر: رمز البيئة يحمل settings.read.
  4. رمز عنقود يُرسل إلى /e/{id}/api/v2/… يجب أن يفشل: وهذا طبيعي، فعائلتا الرموز منفصلتان.

أفضل الممارسات

  • رمز لكل استخدام: رمز ServiceProviderAPI للجرد، وآخر لإدارة الرموز، ولكل منهما تاريخ انتهاء.
  • أدر قائمة المخططات بالإصدارات: صدّرها بعد كل تحديث للعنقود وقارنها بالسابقة. فتظهر المخططات الجديدة بلا ضجيج.
  • احترم حدود المعدل: باعد بين تكرارات الحلقات على كل البيئات، خصوصًا في تعدد المستأجرين.
  • ركّز الأسرار: لا رمز في مستودع ولا في سجلات مسار CI.
  • صلاحيات الوصول: طابق المجموعات المنشأة عبر API مع النموذج الموصوف في المستخدمون والمجموعات والصلاحيات في Managed.

الأسئلة الشائعة

ما الفرق بين Cluster API v1 وv2؟

هما مجموعتان متكاملتان من النقاط، وكلتاهما فعالة. تغطي v1 (/api/v1.0/onpremise/…) العقد والصيانة والوكيل والمستخدمين والمجموعات والشهادات. وتغطي v2 (/api/cluster/v2/…) البيئات والرموز والترخيص وSynthetic. وتُستخدم الاثنتان بحسب الكائن المستهدف.

هل يستطيع رمز بيئة استدعاء Cluster API؟

لا. تتطلب Cluster API رمز عنقود منشأً في CMC. وبالعكس، لا يصلح رمز العنقود للاستعلام عن كيانات بيئة أو مقاييسها.

كيف أعرف هل يوجد في بيئتي مخطط Settings رأيته في وثائق SaaS؟

استدعِ GET /e/{id}/api/v2/settings/schemas وابحث عن schemaId. وإن كان غائبًا فربما يصل مع إصدار لاحق للعنقود؛ تحقق من ملاحظات إصدار Managed.

الخلاصة

تختصر API Dynatrace Managed في ثلاث ردود أفعال: Cluster API للعنقود برمز من CMC؛ وEnvironment API تحت /e/{id}/api/v2 لبقية الأمور؛ وقائمة مخططات Settings تُستعلم من إصدارك نفسه قبل أي أتمتة. وبالجدول المرجعي أعلاه واستدعاءات curl تتوقف سكربتاتك عن التخمين وتصبح تحديثات عنقودك متوقعة.

المرجع الرسمي: Cluster API (وثائق Managed) وSettings API، قائمة المخططات.

span.observer مدوّنة مجتمعية مستقلة وغير تابعة لشركة Dynatrace LLC. Dynatrace علامة تجارية لمالكها. تتطور النقاط والصلاحيات وأسماء الشاشات بحسب الإصدارات: تحقق منها في الوثائق الرسمية لعنقودك.

Total
0
Shares
Leave a Reply

Your email address will not be published. Required fields are marked *

Previous Post
API Dynatrace SaaS : la carte complète des API et des schémas Settings 2.0

API Dynatrace SaaS: الخريطة الكاملة للواجهات ومخططات Settings 2.0

Next Post
Dashboard Dynatrace SaaS : construire des tableaux de bord DQL sur Grail, avec 3 exemples complets

dashboard Dynatrace SaaS: بناء لوحات معلومات DQL على Grail مع 3 أمثلة كاملة

Related Posts