مشاركة عبر

تصدير مخزون تقييم الأجهزة والبرامج الثابتة لكل جهاز

  • مقالة

ينطبق على:

هل تريد تجربة إدارة الثغرات الأمنية في Microsoft Defender؟ تعرف على المزيد حول كيفية التسجيل في إدارة الثغرات الأمنية في Microsoft Defender الإصدار التجريبي للمعاينة العامة.

هناك استدعاءات واجهة برمجة تطبيقات مختلفة للحصول على أنواع مختلفة من البيانات. بشكل عام، يحتوي كل استدعاء واجهة برمجة تطبيقات على البيانات المطلوبة للأجهزة في مؤسستك.

  • استجابة JSON تسحب واجهة برمجة التطبيقات جميع البيانات في مؤسستك كاستجابات JSON. هذا الأسلوب هو الأفضل للمؤسسات الصغيرة ذات الأجهزة الأقل من 100 كيلوبايت. يتم ترقيم الاستجابة، بحيث يمكنك استخدام حقل @odata.nextLink من الاستجابة لإحضار النتائج التالية.

  • عبر الملفات يتيح حل واجهة برمجة التطبيقات هذا سحب كميات أكبر من البيانات بشكل أسرع وأكثر موثوقية. لذلك، يوصى به للمؤسسات الكبيرة، مع أكثر من 100 كيلوبايت من الأجهزة. تسحب واجهة برمجة التطبيقات هذه جميع البيانات في مؤسستك كملفات تنزيل. تحتوي الاستجابة على عناوين URL لتنزيل جميع البيانات من Azure Storage. يمكنك تنزيل البيانات من Azure Storage كما يلي:

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

البيانات التي يتم جمعها باستخدام إما "استجابة JSON أو عبر الملفات" هي اللقطة الحالية للحالة الحالية. لا يحتوي على بيانات تاريخية. لجمع البيانات التاريخية، يجب على العملاء حفظ البيانات في مخازن البيانات الخاصة بهم.

ملاحظة

ما لم يشار إلى خلاف ذلك، فإن جميع طرق تقييم الأجهزة والبرامج الثابتة المصدرة المدرجة هي التصدير الكاملوالجهاز ( يشار إليها أيضا باسم لكل جهاز)

1. تصدير تقييم الأجهزة والبرامج الثابتة (استجابة JSON)

وصف أسلوب واجهة برمجة التطبيقات 1.1

إرجاع جميع تقييمات الأجهزة والبرامج الثابتة لجميع الأجهزة، على أساس كل جهاز. يقوم بإرجاع جدول مع إدخال منفصل لكل مجموعة فريدة من deviceId و componentType.

1.1.1 القيود

  • الحد الأقصى لحجم الصفحة هو 200,000.
  • قيود المعدل لواجهة برمجة التطبيقات هذه هي 30 استدعاء في الدقيقة و1000 استدعاء في الساعة.

1.2 الأذونات

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

نوع الإذن اذن اسم عرض الإذن
Application Software.Read.All "قراءة معلومات برنامج إدارة المخاطر والثغرات الأمنية"
مفوض (حساب العمل أو المؤسسة التعليمية) Software.Read "قراءة معلومات برنامج إدارة المخاطر والثغرات الأمنية"

عنوان URL 1.3

GET api/machines/HardwareFirmwareInventoryByMachine

1.4 معلمات

  • pageSize (افتراضي = 50,000): عدد النتائج استجابة.
  • $top: عدد النتائج التي يجب إرجاعها (لا ترجع @odata.nextLink وبالتالي لا تسحب جميع البيانات).

1.5 خصائص (استجابة JSON)

ملاحظة

كل سجل هو حوالي 1 كيلوبايت من البيانات. يجب أن تأخذ هذا في الاعتبار عند اختيار المعلمة pageSize الصحيحة.

قد يتم إرجاع بعض الأعمدة الإضافية في الاستجابة. هذه الأعمدة مؤقتة وقد تتم إزالتها. استخدم الأعمدة الموثقة فقط.

يتم سرد الخصائص المعرفة في الجدول التالي أبجديا حسب معرف الخاصية. عند تشغيل واجهة برمجة التطبيقات هذه، لن يتم بالضرورة إرجاع الإخراج الناتج بنفس الترتيب المدرج في هذا الجدول.

الخاصية (المعرف) نوع البيانات الوصف
معرف الجهاز سلسلة معرف فريد للجهاز في الخدمة.
معرف rbacGroup الباحث معرف مجموعة التحكم في الوصول استنادا إلى الدور (RBAC). إذا لم يتم تعيين الجهاز إلى أي مجموعة RBAC، ستكون القيمة "غير معينة". إذا لم تحتوي المؤسسة على أي مجموعات RBAC، ستكون القيمة "بلا".
rbacGroupName سلسلة مجموعة التحكم في الوصول استنادا إلى الدور (RBAC). إذا لم يتم تعيين الجهاز إلى أي مجموعة RBAC، ستكون القيمة "غير معينة". إذا لم تحتوي المؤسسة على أي مجموعات RBAC، ستكون القيمة "بلا".
اسم الجهاز سلسلة اسم المجال المؤهل بالكامل (FQDN) للجهاز.
نوع المكون سلسلة نوع مكونات الأجهزة أو البرامج الثابتة.
الشركه المصنعه سلسلة الشركة المصنعة لأجهزة أو مكونات برامج ثابتة معينة.
اسم المكون سلسلة اسم جهاز أو مكون برنامج ثابت معين.
إصدار المكون سلسلة إصدار جهاز معين أو مكون برنامج ثابت.
حقول إضافية سلسلة معلومات إضافية حول المكونات بتنسيق صفيف JSON.

مثال 1.6

1.6.1 مثال الطلب

GET https://api.security.microsoft.com/api/machines/HardwareFirmwareInventoryByMachine

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

      {
        "@odata.context": "https://api-df.securitycenter.microsoft.com/api/$metadata#Collection(microsoft.windowsDefenderATP.api.AssetHardwareFirmware)",
        "value":[
        {
            "deviceId": "49126b9e4a5473b5229c73799e9e55c48668101b",
            "rbacGroupId": 39,
            "rbacGroupName": "testO6343398Gq31",
            "deviceName": "testmachine5",
            "componentType": "Hardware",
            "manufacturer": "razer",
            "componentName": "blade_15_advanced_model_(mid_2021)_-_rz09-0409",
            "componentVersion": "7.04",
            "additionalFields": "{\"SystemSKU\":\"RZ09-0409CE53\",\"BaseBoardManufacturer\":\"Razer\",\"BaseBoardProduct\":\"CH570\",\"BaseBoardVersion\":\"4\",\"DeviceFamily\":\"Workstation\"}"
          }  
        ]  
      },

2. تصدير تقييم الأجهزة والبرامج الثابتة (عبر الملفات)

وصف أسلوب واجهة برمجة التطبيقات 2.1

إرجاع جميع تقييمات الأجهزة والبرامج الثابتة لجميع الأجهزة، على أساس كل جهاز. يقوم بإرجاع جدول مع إدخال منفصل لكل مجموعة فريدة من DeviceId و ComponentType و ComponentName.

2.1.1 القيود

  • قيود المعدل لواجهة برمجة التطبيقات هذه هي 5 مكالمات في الدقيقة و20 استدعاء في الساعة.

2.2 الأذونات

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

نوع الإذن اذن اسم عرض الإذن
Application Software.Read.All "قراءة معلومات برنامج إدارة المخاطر والثغرات الأمنية"
مفوض (حساب العمل أو المؤسسة التعليمية) Software.Read "قراءة معلومات برنامج إدارة المخاطر والثغرات الأمنية"

عنوان URL 2.3

GET /api/machines/HardwareFirmwareInventoryExport

2.4 معلمات

  • sasValidHours: عدد الساعات التي ستكون عناوين URL للتنزيل صالحة لها (الحد الأقصى 24 ساعة).

2.5 خصائص (استجابة JSON)

ملاحظة

الملفات هي gzip مضغوطة & بتنسيق Json متعدد الأسطر.

عناوين URL للتنزيل صالحة لمدة 3 ساعات فقط؛ وإلا، يمكنك استخدام المعلمة .

لزيادة سرعات التنزيل إلى أقصى حد، تأكد من تنزيل البيانات من نفس منطقة Azure حيث توجد بياناتك.

كل سجل هو حوالي 1 كيلوبايت من البيانات. يجب أن تأخذ هذا في الاعتبار عند اختيار المعلمة pageSize التي تناسبك.

قد يتم إرجاع بعض الأعمدة الإضافية في الاستجابة. هذه الأعمدة مؤقتة وقد تتم إزالتها. استخدم الأعمدة الموثقة فقط.

الخاصية (المعرف) نوع البيانات الوصف
تصدير الملفات سلسلة[صفيف] قائمة بعناوين URL للتنزيل للملفات التي تحتفظ باللقطة الحالية للمؤسسة.
وقت التوليد Datetime الوقت الذي تم فيه إنشاء التصدير.

مثال 2.6

2.6.1 مثال الطلب

GET https://api.security.microsoft.com/api/machines/HardwareFirmwareInventoryExport

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

    {
        "@odata.context":"https://api-df.securitycenter.microsoft.com/api/$metadata#microsoft.windowsDefenderATP.api.ExportFilesResponse",
    "exportFiles": [
        "https://tvmexportstrprdcane.blob.core.windows.net/tvm-firmware-export/2022-07-11/1101/FirmwareHardwareExport/json/OrgId=3837d1f5-0d51-40cb-a99d-69ebedc9dcc8/_RbacGroupId=39/part-00999-71eea973-1bb1-4d0a-829d-80cb07aff5d8.c000.json.gz?sv=2020-08-04&st=2022-07-11T13%3A10%3A06Z&se=2022-07-11T16%3A10%3A06Z&sr=b&sp=r&sig=muN8Sq6rVN6bFMtR0u3S5Wzh3D9qNPgN5vpU7lWvULg%3D",
        "https://tvmexportstrprdcane.blob.core.windows.net/tvm-firmware-export/2022-07-11/1101/FirmwareHardwareExport/json/OrgId=3837d1f5-0d51-40cb-a99d-69ebedc9dcc8/_RbacGroupId=9/part-00968-71eea973-1bb1-4d0a-829d-80cb07aff5d8.c000.json.gz?sv=2020-08-04&st=2022-07-11T13%3A10%3A06Z&se=2022-07-11T16%3A10%3A06Z&sr=b&sp=r&sig=%2BA0%2B4qOOBCS5E4UenJPbMdLM%2FkbXHnz%2F1pvfSOCq%2F2s%3D",
        "https://tvmexportstrprdcane.blob.core.windows.net/tvm-firmware-export/2022-07-11/1101/FirmwareHardwareExport/json/OrgId=3837d1f5-0d51-40cb-a99d-69ebedc9dcc8/_RbacGroupId=9/part-00969-71eea973-1bb1-4d0a-829d-80cb07aff5d8.c000.json.gz?sv=2020-08-04&st=2022-07-11T13%3A10%3A06Z&se=2022-07-11T16%3A10%3A06Z&sr=b&sp=r&sig=sZUgYMwSr5zk6BZvS%2BoYIWlHJWk2oJ7YjiC8R26S1X4%3D"
    ],
    "generatedTime": "2022-07-11T11:01:00Z"

   }