الدرس: إنشاء أداة Kusto في Azure SRE Agent

في هذا الدرس، تنشئ أداة Kusto متوافقة تشغل استعلامات KQL دقيقة بنتائج حتمية وقابلة للتكرار. عندما يطرح المستخدمون أسئلة مثل "أرني أخطاء من الأيام السبعة الماضية"، يقوم الوكيل باستبدال المعامل وإجراء استعلامك الدقيق على قاعدة بيانات Azure Data Explorer.

في هذا البرنامج التعليمي، تتعلم كيفية:

• إنشاء أداة Kusto في لوحة الوكيل
• تعريف استعلام KQL مميز
• اختبر الاستعلام في البوابة
• قم بتوصيل الأداة بوكيل مخصص وتحقق منها في ساحة اللعب

الوقت المقدر: 15 دقيقة

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

قبل أن تبدأ، تأكد من أن لديك المتطلبات التالية:

• مجموعة Azure Data Explorer مع دور AllDatabasesViewer الممنوح لهوية الوكيل المدارة. لمزيد من المعلومات، راجع متطلبات أدوات كوستو.
• تم تكوين موصل Kusto. لمزيد من المعلومات، راجع إعداد موصل Kusto.
• الوصول إلى Builder في بوابة Azure SRE Agent.

التوجه إلى لوحة العميل

افتح لوحة الوكلاء حيث تنشئ وتدير الأدوات.

1. افتح بوابة وكيل SRE.
2. اختر وكيلك.
3. اختر Builder في التنقل الأيسر.
4. اختر الوكيل كانفاس.

افتح نموذج إنشاء الأدوات

ابدأ عملية إنشاء الأدوات من شريط الأدوات.

1. اختر قائمة الإنشاء المنسدلة في شريط الأدوات العلوي.
2. اختر أداة>Kusto.

املأ تفاصيل الأداة

أكمل النموذج مع تكوين أداتك.

الحقل	قيمة	الوصف
اسم الأداة	QueryAppLogs	كيف يشير الوكيل إلى هذه الأداة.
الوصف	"استعلام جدول AppLogs عن الأخطاء في النطاق الزمني المحدد"	متى يجب على الوكيل استخدام هذه الأداة.
موصل	(اختر موصل كوستو)	اتصال Azure Data Explorer للاستخدام.
قاعدة بيانات	(تم تعبيله تلقائيا من رابط الموصل)	اسم قاعدة بياناتك.
استفسار	انظر المثال الآتي.	استفسار KQL الخاص بك مع المعلمات.

أدخل المثال التالي في الاستعلام:

AppLogs
| where Timestamp > ago(##timeRange##)
| where Level == "Error"
| order by Timestamp desc
| take 10

الصياغة ##timeRange## تنشئ معاملة. عندما يسأل أحدهم "إظهار أخطاء من آخر 24 ساعة"، يقوم الوكيل بملء التعويض timeRange = 24h.

أضف المعامل

حدد المعامل الذي يستخدمه استعلامك.

1. انتقل إلى قسم المعلمات .
2. اختر إضافة معامل.
3. أدخل القيم التالية:
   • الاسم: timeRange
   • النوع: سلسلة
   • الوصف: "إلى أي مدى يجب النظر إلى الوراء (على سبيل المثال، 1 ساعة، 24 ساعة، 7 أد)"

يظهر المعامل في جدول المعاملات أسفل استفسارك.

اختبر الاستعلام

تحقق من نجاح الاستعلام قبل الحفظ.

1. اختر اختبار في أسفل النموذج.
2. أدخل قيمة اختبار ل timeRange (على سبيل المثال، 7d).
3. تحقق من تنفيذ الاستعلام بنجاح.

ترى وقت التنفيذ وعلامة صح خضراء تؤكد تشغيل الاستعلام. حتى لو أعاد الاستعلام صفوفا صفرا، فإن علامة التحقق تعني أن صياغة الاستعلام صحيحة.

أنشئ الأداة

اختر إنشاء لحفظ أداة Kusto الخاصة بك.

أضف الأداة إلى وكيل مخصص

لقد أنشأت أداتك لكنك لم تربطها بوكيل مخصص. قم بتثبيت الأداة حتى يتمكن الوكيل من استخدامها.

1. في عرض كانفاس، ابحث عن وكيل التخصيص الخاص بك.
2. اختر الزر + على الجانب الأيمن من بطاقة الوكيل المخصص.
3. اختر إضافة الأدوات الموجودة.
4. افحص أداة Kusto الخاصة بك من القائمة.
5. اختر إضافة الأدوات.

عدد الأدوات على بطاقة الوكيل المخصص يزداد بعد الإضافة.

تحقق من الأداة في ساحة اللعب

تأكد من أن الوكيل يستدعي أداة Kusto بشكل صحيح.

1. اختر اختبار الملعب في التنقل الأيسر.
2. اختر وكيل التخصيص الخاص بك من القائمة المنسدلة.
3. اسأل: "أرني أخطاء من الأيام السبعة الماضية"
4. يقوم الوكيل بتفعيل أداتك باستخدام timeRange = 7d.

يجب أن ترى الوكيل يتصل بأداة Kusto الخاصة بك ويعيد نتائج الاستعلام. الاستعلام الدقيق الذي كتبته يعمل على مجموعة العنقود.

صياغة المعلمات

استخدم ##parameterName## أو $parameterName لتحديد المعلمات المؤقتة في استفساراتك:

query: |-
  AppExceptions
  | where TimeGenerated > ago(##timeRange##)
  | where ServiceName == "$serviceName"

كلا التركيبتين تعملان بنفس الطريقة. يقوم الوكيل باستبدال القيم أثناء وقت التشغيل.

أنماط التنفيذ

الجدول التالي يصف أوضاع التنفيذ المتاحة لأدوات كوستو.

وضع	استخدم عندما
Query	حدد الاستعلام الداخلي في YAML (الأكثر شيوعا).
Function	تخزين منطق الاستعلام كدالة على عنقود Azure Data Explorer.
Script	ضع الاستعلام في ملف خارجي .kql .

# Function mode example
spec:
  type: KustoTool
  mode: Function
  function: GetRecentErrors

# Script mode example
spec:
  type: KustoTool
  mode: Script
  file: queries/complex-analysis.kql

مثال: أداة الارتباط بالنشر

التعريف التالي ل YAML ينشئ أداة Kusto تربط عمليات النشر مع خدمة ونطاق زمني محدد.

api_version: azuresre.ai/v2
kind: ExtendedAgentTool
metadata:
  name: get-recent-deployments
spec:
  type: KustoTool
  connector: devops-logs
  mode: Query
  database: deployments
  description: "Get deployments in a time range for a service"
  toolMode: Auto
  query: |-
    Deployments
    | where TimeGenerated > ago(##timeRange##)
    | where ServiceName == "##serviceName##"
    | project TimeGenerated, Version, DeployedBy, Environment
    | order by TimeGenerated desc
  parameters:
    - name: serviceName
      type: string
      description: "Name of the service"
    - name: timeRange
      type: string
      description: "How far back to look (e.g., 1h, 24h)"

تعديل أو حذف أداة

يمكنك تعديل أو إزالة الأدوات بعد الإنشاء.

تحرير

1. في لوحة الوكيل، اختر عقدة الأداة لفتح لوحة المعلومات.
2. اختر أيقونة التحرير (قلم رصاص) في رأس اللوحة.
3. يفتح مربع التحرير مع الإعدادات الحالية. عدل الاستعلام أو المعاملات أو الموصل.
4. حَدِّد حِفظ.

حذف

1. اختر عقدة الأداة لفتح لوحة المعلومات.
2. اختر قائمة ⋯ (المزيد من الأفعال) في رأس اللوحة.
3. اختر أداة الحذف.
4. أكد الحذف في الحوار.

ملحوظة

عندما تحذف أداة، تقوم بإزالتها فورا من أي وكلاء مخصصين يستخدمون الأداة.

الخطوة التالية

اختبر أداتك في ساحة اللعب

المحتوى ذو الصلة

• أدوات كوستو
• إنشاء أداة بايثون
• وكلاء الجمارك