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

API Dynatrace SaaS: Environment API v2 وSettings 2.0 وواجهة المنصة وOAuth في جدول، مع المخططات المفيدة وأمثلة curl وأخطاء الترقيم.
API Dynatrace SaaS : la carte complète des API et des schémas Settings 2.0

عليك أتمتة إعداد، أو استخراج مقاييس لتقرير SLO، أو ربط أداة داخلية بـ Dynatrace. وسرعان ما يعود السؤال نفسه: أي واجهة API أستدعي، وبأي عنوان URL وأي رمز؟ إن API Dynatrace SaaS ليست كتلة واحدة، بل عدة عائلات لا تتشارك العنوان ولا طريقة المصادقة.

الخطأ في اختيار العائلة يكلّف وقتًا: 401 على رمز صالح، و403 لغياب النطاق (scope) الصحيح، وقائمة مبتورة لأن الترقيم (pagination) أُهمل. هذا العبء المتكرر يؤخر الإصلاحات ويطيل زمن الحل (MTTR) حين تنكسر الأتمتة في منتصف المناوبة.

هدف هذا المقال: أن يمنحك خريطة مرجعية لواجهات Dynatrace SaaS، ويريك كيف تسرد بنفسك مخططات Settings 2.0، ويعلّق على أكثر المخططات فائدة بأمثلة curl دقيقة. جزء كبير من Environment API v2 موجود أيضًا في Dynatrace Managed؛ أما واجهة المنصة (AppEngine وGrail) فخاصة بـ SaaS.

عائلات API Dynatrace SaaS في جدول واحد

احتفظ بعنوانين لكل بيئة: {env-id}.live.dynatrace.com لـ Environment API الكلاسيكية، و{env-id}.apps.dynatrace.com لخدمات المنصة. يلخص الجدول التالي الأساسيات.

العائلة عنوان URL الأساسي المصادقة النطاقات المعتادة الاستخدام
Environment API v2 https://{env-id}.live.dynatrace.com/api/v2/ Api-Token (رمز وصول) metrics.read، entities.read، problems.read، apiTokens.read المقاييس والكيانات والمشكلات والرموز
Settings 2.0 …/api/v2/settings/ Api-Token أو رمز منصة أو OAuth settings.read، settings.write (في OAuth: settings:schemas:read، settings:objects:read، settings:objects:write) كل الإعدادات الحديثة
Configuration API v1 …/api/config/v1/ Api-Token ReadConfig، WriteConfig إعدادات قديمة لم تُرحَّل
واجهة المنصة https://{env-id}.apps.dynatrace.com/platform/ Authorization: Bearer (OAuth أو رمز منصة) storage:logs:read، storage:buckets:read، app-engine:apps:run، openpipeline:configurations:read استعلامات Grail (DQL) وAppEngine وOpenPipeline
Account Management https://api.dynatrace.com/iam/v1/ Bearer عبر عميل OAuth account-uac-read، account-uac-write، iam-policies-management المستخدمون والمجموعات والسياسات

يُحصل على رمز OAuth من https://sso.dynatrace.com/sso/oauth2/token بتدفق client_credentials. ولتشخيص حالات الرفض راجع دليلنا لـ استكشاف أخطاء رمز API في Dynatrace.

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

  • بيئة Dynatrace SaaS (أو Managed للجزء الخاص بـ Environment API وSettings).
  • رمز وصول بالصلاحية settings.read على الأقل، إضافة إلى metrics.read وentities.read للأمثلة التالية.
  • لواجهة المنصة: عميل OAuth بالنطاقين storage:logs:read وstorage:buckets:read.
  • curl وjq؛ والأسرار في متغيرات بيئة، لا في المستودع أبدًا.
export DT_ENV="https://abc12345.live.dynatrace.com"
export DT_TOKEN="dt0c01.XXXX.YYYY"   # never versioned

الخطوة 1: اسرد مخططات Settings 2.0

يصف Settings 2.0 كل إعداد بمخطط (schemaId) وكل نسخة بكائن. بدل البحث عن قائمة جامدة، استعلم عن بيئتك أنت: فهي تعيد بالضبط المخططات المتاحة لديك مع إصدارها.

curl -s "$DT_ENV/api/v2/settings/schemas" \
  -H "Authorization: Api-Token $DT_TOKEN" | jq '.totalCount, .items[0]'

رد مختصر:

{
  "items": [
    {
      "displayName": "Built-in container monitoring rules",
      "latestSchemaVersion": "1.4.2",
      "maturity": "GENERAL_AVAILABILITY",
      "multiObject": true,
      "ordered": false,
      "ownerBasedAccessControl": true,
      "schemaId": "builtin:container.built-in-monitoring-rule"
    }
  ],
  "totalCount": 1
}

الحقول التي يجب حفظها: schemaId يُستخدم في كل الاستدعاءات اللاحقة، وlatestSchemaVersion يبيّن الإصدار الحالي، وmultiObject يقول هل يمكن لعدة كائنات أن تتعايش، وmaturity يميّز PREVIEW وEARLY_ADOPTER وGENERAL_AVAILABILITY. الإصدارات تتطور: اقرأ دائمًا إصدارات بيئتك.

للحصول على التعريف الكامل لمخطط (الخصائص والأنواع والقيود):

curl -s "$DT_ENV/api/v2/settings/schemas/builtin:alerting.profile" \
  -H "Authorization: Api-Token $DT_TOKEN" | jq '.properties | keys'

الخطوة 2: المخططات الأكثر فائدة

إليك مختارات من المخططات الموثقة لـ SaaS وManaged وActiveGate البيئة. كلها تُقرأ بالصلاحية settings.read.

schemaId ما الذي يضبطه لماذا هو مفيد
builtin:alerting.profile ملفات تنبيه المشكلات تصفية من يُبلَّغ ومتى بحسب الخطورة
builtin:management-zones مناطق الإدارة تقسيم البيئة والصلاحيات حسب الفريق
builtin:anomaly-detection.metric-events أحداث المقاييس تنبيهات مخصصة على عتبة أو خط أساس
builtin:anomaly-detection.services اكتشاف شذوذ الخدمات ضبط الحساسية على أزمنة الاستجابة والإخفاقات
builtin:failure-detection.environment.parameters معاملات اكتشاف الإخفاقات تحديد ما يُعد خطأ في الخدمة
builtin:logmonitoring.log-storage-settings قواعد تخزين السجلات التحكم فيما يُستوعب، أي في التكلفة
builtin:networkzones.zones مناطق الشبكة توجيه حركة OneAgent إلى ActiveGate المناسب

تتحكم هذه المخططات مباشرة في جودة تنبيهاتك. ملف تنبيه واسع جدًا يوقظ المناوب بلا داع؛ وحدث مقياس سيئ المعايرة يترك تدهورًا في SLO يمر. وإدارتها بالإصدارات، مثلًا مع Dynatrace Monaco، تجعل كل تغيير قابلًا للمراجعة.

الخطوة 3: اقرأ كائنات Settings واكتبها

يتطلب سرد كائنات مخطط معاملين: schemaIds وscopes. يشير النطاق environment إلى الإعداد العام؛ ويمكن لكائن أن يستهدف كيانًا (مثل مضيف).

curl -s "$DT_ENV/api/v2/settings/objects?schemaIds=builtin:management-zones&scopes=environment&pageSize=100" \
  -H "Authorization: Api-Token $DT_TOKEN" \
  | jq '.items[] | {objectId, summary, schemaVersion}'

يعيد كل كائن خصوصًا objectId وschemaId وschemaVersion وscope وvalue وsummary. وتتم الكتابة عبر POST /api/v2/settings/objects بالصلاحية settings.write. ابدأ دائمًا بتحقق تجريبي:

curl -s -X POST "$DT_ENV/api/v2/settings/objects?validateOnly=true" \
  -H "Authorization: Api-Token $DT_TOKEN" \
  -H "Content-Type: application/json" \
  -d @objet.json

الجسم مصفوفة كائنات تحمل schemaId وscope وvalue (إضافة إلى schemaVersion إن أردت تثبيت الإصدار). مع validateOnly=true يفحص Dynatrace المحتوى دون حفظ شيء: وهي الممارسة المثالية في مسار CI.

الخطوة 4: استعلم عن البيانات عبر Environment API وGrail

للمقاييس الكلاسيكية تأخذ نقطة النهاية /api/v2/metrics/query معامل metricSelector:

curl -s -G "$DT_ENV/api/v2/metrics/query" \
  -H "Authorization: Api-Token $DT_TOKEN" \
  --data-urlencode "metricSelector=builtin:host.cpu.usage" \
  --data-urlencode "from=now-2h"

تُقرأ الكيانات عبر /api/v2/entities مع entitySelector، والمشكلات عبر /api/v2/problems (النطاق problems.read).

من جهة منصة SaaS تمر استعلامات DQL على Grail عبر واجهة الاستعلام، برمز Bearer:

curl -s -X POST "https://abc12345.apps.dynatrace.com/platform/storage/query/v1/query:execute" \
  -H "Authorization: Bearer $DT_OAUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "fetch logs | filter loglevel == \"ERROR\" | limit 10"}'

إذا لم ينته الاستعلام، يحتوي الرد على requestToken يُمرَّر إلى query:poll لجلب النتيجة. ويُطلب رمز OAuth هكذا:

curl -s -X POST "https://sso.dynatrace.com/sso/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=$DT_CLIENT_ID&client_secret=$DT_CLIENT_SECRET&scope=storage:logs:read storage:buckets:read"

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

  1. يعيد GET /api/v2/settings/schemas قيمة totalCount غير صفرية: الرمز والعنوان سليمان.
  2. يسرد GET /api/v2/settings/objects?schemaIds=builtin:alerting.profile&scopes=environment الملف الافتراضي على الأقل.
  3. يرد POST مع validateOnly=true دون خطأ تحقق.
  4. في الواجهة يظهر الكائن المنشأ في شاشة الإعدادات المقابلة (مثل ملفات التنبيه).

أخطاء شائعة

الترقيم عبر nextPageKey

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

KEY=""
while :; do
  if [ -z "$KEY" ]; then Q="schemaIds=builtin:management-zones&scopes=environment"; else Q="nextPageKey=$KEY"; fi
  R=$(curl -s "$DT_ENV/api/v2/settings/objects?$Q" -H "Authorization: Api-Token $DT_TOKEN")
  echo "$R" | jq -r '.items[].summary'
  KEY=$(echo "$R" | jq -r '.nextPageKey // empty')
  [ -z "$KEY" ] && break
done

إصدارات المخططات

يتطور المخطط: يتغير latestSchemaVersion وتظهر خصائص جديدة. وقد يُرفض ملف JSON كُتب قبل ستة أشهر. أعد قراءة تعريف المخطط قبل تعديل كائن موجود، واختبر بـ validateOnly.

تحديد المعدل

تعالج كل بيئة الطلبات بمجموعة خيوط (thread pool) وطابور انتظار. حين يمتلئان معًا، أو حين ينتظر طلب أكثر من عشر ثوان، ترد API بالخطأ 429. باعد بين الاستدعاءات، وأعد المحاولة بمهلة متزايدة، وتذكّر حد الحمولة البالغ 1 ميغابايت على معظم نقاط النهاية.

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

  • رمز لكل استخدام، بأدنى حد من النطاقات، وتاريخ انتهاء.
  • فضّل Settings 2.0 على Configuration API v1 ما إن يوجد مخطط.
  • لواجهة المنصة استخدم عملاء OAuth لا الرموز الشخصية.
  • أدر الإعداد بالإصدارات (Monaco أو Terraform Dynatrace) وتحقق منه في CI.
  • سجّل أخطاء 429 و403: فهي تنبه إلى انجراف في الحمل أو الصلاحيات قبل الحادثة.

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

أين أجد القائمة الكاملة لمخططات Settings؟

في بيئتك أنت، عبر GET /api/v2/settings/schemas. تصفها الوثائق الرسمية واحدًا واحدًا، لكن نسختك وحدها تعكس المخططات المتاحة فعلًا وإصدارها.

هل أحتاج رمز وصول أم عميل OAuth؟

تقبل Environment API v2 رمز الوصول الكلاسيكي (Api-Token). وتنتظر واجهة المنصة على apps.dynatrace.com رمز Bearer، يُحصل عليه عبر OAuth أو برمز منصة. أما Settings 2.0 فتقبل الاثنين، بأسماء نطاقات مختلفة.

هل توجد هذه الواجهات في Dynatrace Managed؟

Environment API v2 وSettings 2.0 نعم، بعنوان من الشكل https://{domaine}/e/{env-id}/api/v2/. أما واجهة المنصة وGrail فخاصتان بـ SaaS. ويضيف Managed واجهة API Cluster، المفصلة في مقالنا عن API Cluster.

الخلاصة

تصبح API Dynatrace SaaS بسيطة حين تُقرأ كخريطة: Environment API v2 للبيانات والرموز، وSettings 2.0 للإعداد، وواجهة المنصة لـ Grail وAppEngine. اسرد مخططاتك، وتحقق قبل الكتابة، واتبع nextPageKey، وعالج أخطاء 429: فتبقى أتمتتك موثوقة. وللمزيد راجع الوثائق الرسمية لـ API Dynatrace.

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

Total
0
Shares
Leave a Reply

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

Previous Post
Davis CoPilot : interroger ses données en langage naturel, limites comprises

Davis CoPilot: استعلم عن بياناتك بلغة طبيعية مع معرفة حدوده

Next Post
API Dynatrace Managed : Cluster API v1 et v2, Environment API et schémas Settings disponibles

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

Related Posts