مشاركة عبر

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

  • ينطبق على: Microsoft Defender for Endpoint

تحذير

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

ملاحظة

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

تلميح

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

  • 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
  • ina.api.security.microsoft.com
  • aea.api.security.microsoft.com

القيود

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

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

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

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

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

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

  • لا يمكن أن يتجاوز الحد الأقصى لحجم نتيجة الاستعلام لطلب واحد 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.security.microsoft.com/api/advancedqueries/run

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

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

نص الطلب

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

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

استجابه

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

المثال

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

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

POST https://api.security.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"
        }
    ]
}

تلميح

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

  • Last updated on