واجهة برمجة تطبيقات التعقب المتقدمة

  • مقالة

ينطبق على:

تحذير

واجهة برمجة تطبيقات التتبع المتقدمة هذه هي إصدار أقدم مع قدرات محدودة. يتوفر بالفعل إصدار أكثر شمولا من واجهة برمجة تطبيقات التتبع المتقدمة التي يمكنها الاستعلام عن المزيد من الجداول في واجهة برمجة تطبيقات أمان Microsoft Graph. راجع التتبع المتقدم باستخدام واجهة برمجة تطبيقات أمان Microsoft Graph

هل تريد تجربة Defender لنقطة النهاية؟ التسجيل للحصول على إصدار تجريبي مجاني.

ملاحظة

إذا كنت أحد عملاء حكومة الولايات المتحدة، فالرجاء استخدام معرفات URI المدرجة في Microsoft Defender لنقطة النهاية لعملاء حكومة الولايات المتحدة.

تلميح

للحصول على أداء أفضل، يمكنك استخدام الخادم الأقرب إلى موقعك الجغرافي:

  • us.api.security.microsoft.com
  • eu.api.security.microsoft.com
  • uk.api.security.microsoft.com
  • au.api.security.microsoft.com
  • swa.api.security.microsoft.com

القيود

  1. يمكنك فقط تشغيل استعلام على البيانات من آخر 30 يوما.

  2. تتضمن النتائج 100,000 صف كحد أقصى.

  3. عدد عمليات التنفيذ محدود لكل مستأجر:

    • استدعاءات واجهة برمجة التطبيقات: ما يصل إلى 45 مكالمة في الدقيقة، وما يصل إلى 1500 مكالمة في الساعة.
    • وقت التنفيذ: 10 دقائق من وقت التشغيل كل ساعة و3 ساعات من وقت التشغيل في اليوم.

  4. الحد الأقصى لوقت التنفيذ لطلب واحد هو 200 ثانية.

  5. 429 تمثل الاستجابة الوصول إلى حد الحصة النسبية إما حسب عدد الطلبات أو بواسطة وحدة المعالجة المركزية. قراءة نص الاستجابة لفهم الحد الذي تم الوصول إليه.

  6. لا يمكن أن يتجاوز الحد الأقصى لحجم نتيجة الاستعلام لطلب واحد 124 ميغابايت. إذا تم تجاوزه، طلب HTTP 400 غير صحيح مع الرسالة "تجاوز تنفيذ الاستعلام حجم النتيجة المسموح به. تحسين الاستعلام الخاص بك عن طريق الحد من عدد النتائج والمحاولة مرة أخرى" يحدث.

الأذونات

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

نوع الإذن اذن اسم عرض الإذن
Application AdvancedQuery.Read.All Run advanced queries
مفوض (حساب العمل أو المؤسسة التعليمية) AdvancedQuery.Read Run advanced queries

ملاحظة

عند الحصول على رمز مميز باستخدام بيانات اعتماد المستخدم:

  • يحتاج المستخدم إلى View Data تعيين الدور في Microsoft Entra ID
  • يحتاج المستخدم إلى الوصول إلى الجهاز، استنادا إلى إعدادات مجموعة الأجهزة (راجع إنشاء مجموعات الأجهزة وإدارتها لمزيد من المعلومات)

يتم دعم إنشاء مجموعة الأجهزة في خطة Defender لنقطة النهاية 1 والخطة 2.

طلب HTTP

POST https://api.securitycenter.microsoft.com/api/advancedqueries/run

عناوين الطلبات

عنوان قيمه
التخويل الحامل {token}. مطلوب.
نوع المحتوى application/json

نص الطلب

في نص الطلب، قم بتوفير كائن JSON بالمعلمات التالية:

المعلمه نوع الوصف
الاستعلام النص الاستعلام المراد تشغيله. مطلوب.

استجابه

إذا نجحت، فترجع هذه الطريقة 200 OK، وQueryResponse object في نص الاستجابة.

المثال

مثال على الطلب

فيما يلي مثال على الطلب.

POST https://api.securitycenter.microsoft.com/api/advancedqueries/run

{
    "Query":"DeviceProcessEvents
|where InitiatingProcessFileName =~ 'powershell.exe'
|where ProcessCommandLine contains 'appdata'
|project Timestamp, FileName, InitiatingProcessFileName, DeviceId
|limit 2"
}

مثال على الاستجابة

فيما يلي مثال على الاستجابة.

ملاحظة

قد يتم اقتطاع كائن الاستجابة الموضح هنا للإيجاز. سيتم إرجاع جميع الخصائص من مكالمة فعلية.

{
    "Schema": [
        {
            "Name": "Timestamp",
            "Type": "DateTime"
        },
        {
            "Name": "FileName",
            "Type": "String"
        },
        {
            "Name": "InitiatingProcessFileName",
            "Type": "String"
        },
        {
            "Name": "DeviceId",
            "Type": "String"
        }
    ],
    "Results": [
        {
            "Timestamp": "2020-02-05T01:10:26.2648757Z",
            "FileName": "csc.exe",
            "InitiatingProcessFileName": "powershell.exe",
            "DeviceId": "10cbf9182d4e95660362f65cfa67c7731f62fdb3"
        },
        {
            "Timestamp": "2020-02-05T01:10:26.5614772Z",
            "FileName": "csc.exe",
            "InitiatingProcessFileName": "powershell.exe",
            "DeviceId": "10cbf9182d4e95660362f65cfa67c7731f62fdb3"
        }
    ]
}

تلميح

هل تريد معرفة المزيد؟ Engage مع مجتمع أمان Microsoft في مجتمعنا التقني: Microsoft Defender لنقطة النهاية Tech Community.