عليك أتمتة إعداد، أو استخراج مقاييس لتقرير 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"
كيف تتحقق من أنه يعمل
- يعيد
GET /api/v2/settings/schemasقيمةtotalCountغير صفرية: الرمز والعنوان سليمان. - يسرد
GET /api/v2/settings/objects?schemaIds=builtin:alerting.profile&scopes=environmentالملف الافتراضي على الأقل. - يرد
POSTمعvalidateOnly=trueدون خطأ تحقق. - في الواجهة يظهر الكائن المنشأ في شاشة الإعدادات المقابلة (مثل ملفات التنبيه).
أخطاء شائعة
الترقيم عبر 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 علامة تجارية لمالكها. الأمثلة للاستئناس: تحقق منها في الوثائق الرسمية قبل استخدامها في الإنتاج.