معرف كيان Dynatrace (entity ID) هو المفتاح الذي تطلبه تقريبًا كل عملية أتمتة: نطاق (scope) كائن Settings، ومرشح SLO، ومحدد تنبيه، ومعامل وحدة Terraform أو Monaco. لا يكفي اسم مضيف أو خدمة: فهو يتغير، ويتكرر من بيئة إلى أخرى، وليس فريدًا. أما المعرف فيعيّن كيانًا محددًا، مثل SERVICE-1125C375A187D27A.
يفترض أن يستغرق العثور عليه عشر ثوان. وعمليًا يضيع الوقت غالبًا في نسخ معرف خاطئ، أو جلب خمسين نتيجة بدل نتيجة واحدة، أو كتابة استعلام لا يعمل إلا على منصة واحدة. وكل عبء نوفره هنا يعني أدلة تشغيل (runbooks) أوثق وأتمتة لا تنكسر عند أول إعادة تسمية.
يغطي هذا الدليل ثلاث طرق: واجهة Monitored entities v2 مع entitySelector (Managed وSaaS)، وDQL في Notebook (SaaS فقط، Grail)، والانتقال بين الاثنتين بـ classicEntitySelector().
ما هو معرف كيان Dynatrace
كل كائن مراقَب (مضيف أو عملية أو خدمة أو تطبيق أو اختبار اصطناعي…) هو كيان، له نوع ومعرّف. يأخذ المعرف الشكل TYPE-IDENTIFIANT: HOST-… وSERVICE-… وHTTP_CHECK-… وSYNTHETIC_TEST-…. أما الاسم المعروض (displayName في API وentity.name في DQL) فتسمية؛ والمعرف هو ما تنتظره واجهات API.
مثال ملموس: لإعلان key requests عبر Settings API، يجب أن يحتوي الحقل scope على معرف الخدمة، وتحيل الوثائق تحديدًا إلى الاستدعاء GET entities list للعثور عليه.
المتطلبات المسبقة
- لواجهة API: رمز بالنطاق
entities.read. والخطأ 401 أو 403 في هذه المرحلة يندرج في استكشاف أخطاء رمز API. - عنوان URL الأساسي:
https://{votre-domaine}/e/{id-environnement}في Managed، وhttps://{id-environnement}.live.dynatrace.comفي SaaS. وعبر ActiveGate:https://{domaine-activegate}:9999/e/{id-environnement}. - لـ DQL (SaaS): الصلاحية
storage:entities:read.
الطريقة 1: API وentitySelector (Managed وSaaS)
الخطوة 1: ابحث بالنوع والاسم
يتطلب الاستدعاء GET /api/v2/entities أحد معيارين: النوع (type("…")) أو المعرف (entityId("…")). ثم نضيف الاسم:
curl -s -G "$DT_URL/api/v2/entities" \
-H "Authorization: Api-Token $DT_TOKEN" \
--data-urlencode 'entitySelector=type("SERVICE"),entityName.equals("AuthenticationService")' \
--data-urlencode 'from=now-7d'
ثلاث تفاصيل مهمة:
- الصيغة
entityName("…")وحدها تجري CONTAINS، غير حساس لحالة الأحرف افتراضيًا. وentityName.equals("…")يشترط التساوي، وentityName.startsWith("…")بادئة، وentityName.in("a","b")قائمة. وللمقارنة الحساسة لحالة الأحرف:caseSensitive(entityName.equals("…")). - بدون
fromيشمل البحث الأيام الثلاثة الأخيرة (now-3d). فالكيان الذي انطفأ الأسبوع الماضي لا يظهر: وسّع النافذة. - إذا احتوت القيمة على قوس أو فاصلة فضعها بين علامتي اقتباس.

يحتوي الرد على totalCount وpageSize (50 افتراضيًا) وعلى nextPageKey إن بقيت نتائج. وللصفحة التالية مرّر nextPageKey وحده: فالوثائق تشترط عندئذ حذف كل المعاملات الأخرى.
الخطوة 2: دقّق حين لا يكفي الاسم
هل تحمل عدة خدمات الاسم نفسه (واحدة لكل بيئة اختبار، وواحدة لكل عنقود)؟ اجمع المعايير؛ ولا تُعاد إلا الكيانات التي تستوفيها كلها:
# by tag
type("SERVICE"),entityName.equals("checkout"),tag("env:prod")
# by management zone
type("SERVICE"),entityName.equals("checkout"),mzName("Payments")
# by relationship: services running on a given host
type("SERVICE"),fromRelationships.runsOnHost(type("HOST"),entityName.equals("web-01"))
# excluding
type("HOST"),not(tag("Infrastructure:Linux"))
لمعرفة الخصائص والعلاقات التي يعرضها نوع ما، استدعِ GET /api/v2/entityTypes/{type} وانظر إلى properties وfromRelationships وtoRelationships. ويضيف المعامل fields حقولًا إلى الرد، مثل fields=+lastSeenTms,+properties.serviceTechnologyTypes.
الخطوة 3: استخرج المعرف بشكل نظيف
curl -s -G "$DT_URL/api/v2/entities" \
-H "Authorization: Api-Token $DT_TOKEN" \
--data-urlencode 'entitySelector=type("HOST"),entityName.startsWith("web-")' \
| jq -r '.entities[] | "\(.entityId)\t\(.displayName)"'
لديك معرف بالفعل وتريد التحقق مما يقابله؟ يعيد GET /api/v2/entities/{entityId} تفاصيل الكيان، بالنطاق نفسه entities.read.
حدود يجب تذكرها: لا يتجاوز المحدد 2000 حرف ولا يستهدف إلا نوع كيان واحدًا في الطلب. والكيانات المحذوفة (الاختبارات الاصطناعية والتطبيقات وcustom devices…) مستبعدة افتراضيًا؛ ويعيدها deletedEntities.include().
الطريقة 2: DQL في Notebook (SaaS)
في Dynatrace SaaS افتح Notebook واكتب fetch dt.entity.: يقترح الإكمال التلقائي أنواع الكيانات. ويحتوي كل سجل افتراضيًا على المعرف والاسم.
fetch dt.entity.service
| filter entity.name == "AuthenticationService"
| fields id, entity.name
لاكتشاف الحقول المتاحة لنوع ما يعطي describe dt.entity.service قائمتها. وللتصفية بحسب العلاقات توصي الوثائق بإعادة استخدام محدد كلاسيكي، أسرع وأكمل من expand/lookup في DQL الأصلية (المحدودة بـ 100 معرف لكل نوع ولكل سجل):
fetch dt.entity.host
| filter in(id, classicEntitySelector("type(host),toRelationship.isProcessOf(type(PROCESS_GROUP_INSTANCE),softwareTechnologies(JAVA))"))
| fields id, entity.name
تحذيران خاصان بـ Grail. أولًا، لا يطبق Grail مناطق الإدارة (management zones): فكل من يملك storage:entities:read يرى جميع الكيانات. ثانيًا، ومنذ الإصدار 1.334، تعلن الوثائق انتقالًا إلى تخزين Smartscape الجديد وتنصح بعدم استخدام استعلامات الكيانات الكلاسيكية؛ ونموذج Smartscape on Grail يُستعلم بـ smartscapeNodes، مثل smartscapeNodes HOST | fields id, type | limit 10. اختبر استعلاماتك على هذا النموذج قبل تثبيتها في dashboard. ولاستعلامات يومية أخرى راجع استعلامات DQL للتشغيل.
الطريقة 3: في Managed ابقَ على API
لا يملك Dynatrace Managed Grail ولا DQL. والطريقة الموثقة تبقى API v2 مع entitySelector: الصياغة نفسها والنطاق نفسه والترقيم نفسه، بعنوان https://{votre-domaine}/e/{id-environnement}/api/v2/entities. ويُستخدم المحدد نفسه لاحقًا في SLO وmetric selector وواجهات الإعداد، ما يجعله استثمارًا مجديًا. ونظرة شاملة على النقاط في واجهات API Dynatrace Managed.
أفضل الممارسات
- ابحث بـ
entityName.equalsبدلentityNameوحدها: فـ CONTAINS الافتراضي يجلب متشابهات جزئية. - افحص
totalCountدائمًا: السكربت الذي ينتظر نتيجة واحدة يجب أن يفشل إن تلقى اثنتين. - خزّن المعرف في إعدادك ككود، لكن احتفظ بجانبه بالمحدد الذي أنتجه لتتمكن من إعادة توليده.
- امنح رمز البحث النطاق
entities.readوحده، بلا صلاحية كتابة.
كيف تتحقق من أنه يعمل
أعد الاستدعاء بالمحدد entityId("…") والمعرف المحصَّل: يجب أن يحتوي الرد على كيان واحد بالضبط، بـ displayName المتوقع وlastSeenTms حديث. وفي DQL يجب أن يعيد fetch dt.entity.service | filter id == "SERVICE-…" سجلًا واحدًا. وإن لم يعد شيء فوسّع النافذة الزمنية: ربما لم يُرَ الكيان منذ ثلاثة أيام.
المراجع الرسمية: Entity selector وQuery monitored entities in Grail.
الأسئلة الشائعة
لماذا لا تجد API كيانًا ما زلت أراه في تقرير قديم؟
بدون المعامل from يقتصر البحث على الأيام الثلاثة الأخيرة. أضف from=now-30d، ولبعض الأنواع (الاختبارات الاصطناعية والتطبيقات) أضف deletedEntities.include().
هل أستطيع طلب مضيفات وخدمات في الاستدعاء نفسه؟
لا، فالمحدد يستهدف نوعًا واحدًا في الطلب. أجرِ استدعاءين، أو مرّ عبر علاقة (fromRelationships وtoRelationships) للحصول على النوع المجاور.
هل تصفّي مناطق الإدارة نتائج DQL؟
لا. توضح الوثائق أن Grail لا يطبق مرشحات مناطق الإدارة على الكيانات؛ والصلاحية storage:entities:read هي التي تمنح الوصول إلى المجموع.
الخلاصة
ردة فعل جيدة: ابحث عن المعرف عبر API بمحدد دقيق، وتأكد من رجوع نتيجة واحدة، ثم أعد استخدام المحدد نفسه حيثما يقبله Dynatrace. وفي SaaS يصل DQL وclassicEntitySelector() بين Notebooks والمحددات، مع إبقاء عين على الانتقال إلى Smartscape on Grail.
span.observer مدوّنة مجتمعية مستقلة وغير تابعة لشركة Dynatrace LLC. Dynatrace علامة تجارية لمالكها. قد تتطور الصياغات والحدود بحسب الإصدار والمنصة (SaaS أو Managed): تحقق منها في الوثائق الرسمية.