Azure Resources Graph (ARG) GET/LIST API

تم تصميم واجهة برمجة تطبيقات ARG GET/LIST لتقليل تقييد القراءة بشكل كبير عن طريق إلغاء تحميل طلبات GET و LIST إلى نظام أساسي بديل ل ARG. يتم تحقيق هذا الإجراء من خلال توجيه مستوى التحكم الذكي، والذي يوجه الطلبات إلى النظام الأساسي البديل عند وجود معلمة معينة. إذا كانت المعلمة غير موجودة، يتم توجيه الطلبات بسلاسة مرة أخرى إلى موفر الموارد الأصلي، ما يضمن المرونة.

يوفر ARG GET/LIST حصة افتراضية تبلغ 4k في الدقيقة والمستخدم والاشتراك، على نافذة متحركة، ما يعني أن الحصة الافتراضية البالغة 4k في الدقيقة تسمح لك بتقديم ما يصل إلى 4000 طلب في الدقيقة باستخدام واجهات برمجة التطبيقات هذه. يتم فرض هذه الحصة لكل مستخدم لكل اشتراك. يعني ذلك:

• إذا كان المستخدم A يصل إلى Subscription X، فسيحصل على ما يصل إلى 4000 طلب في الدقيقة.
• إذا كان المستخدم A يصل إلى الاشتراك Y، هذه حصة نسبية منفصلة.
• إذا كان المستخدم B يصل إلى Subscription X، هذه أيضا حصة نسبية منفصلة.
• توفر واجهة برمجة التطبيقات عنوان استجابة "x-ms-user-quota-remaining" يشير إلى الحصة النسبية المتبقية و"x-ms-user-quota-resets-after" الذي يشير إلى الوقت لإعادة تعيين الحصة النسبية الكاملة بناء على ذلك يمكنك فهم استهلاك الحصة النسبية.

إشعار

ضع في اعتبارك أن الحصة النسبية ل Azure Resource Manager تنطبق على هذه الاستدعاءات. اقرأ عن حدود Azure Resource Manager، وهي الحدود الجديدة التي يتبعها Azure Resource Manager للسحابة العامة ل Azure. 

استخدام ARG GET/LIST API

لاستخدام ARG GET/LIST API، حدد أولا ما إذا كان السيناريو الخاص بك يطابق الشروط المذكورة في إرشادات الطلبات المقيدة أم لا. يمكنك بعد ذلك إلحاق العلامة &useResourceGraph=true باستدعاءات GET/LIST API القابلة للتطبيق، والتي توجه الطلب إلى خلفية ARG هذه للاستجابة.

يطلب منك الاتصال بمجموعة منتجات ARG عن طريق إرسال بريد إلكتروني إلى فريق Azure Resource Graph يشارك نظرة عامة موجزة على السيناريو الخاص بك وسيقوم فريق ARG بالتواصل معك بالخطوات التالية.

تم اختيار نموذج الاشتراك هذا عمدا للسماح لفريق Azure Resource Graph بفهم أنماط استخدام العملاء بشكل أفضل وإدخال تحسينات حسب الحاجة.

راجع بعض القيود المعروفة هناوالأسئلة المتداولة.

ARG GET/LIST API Contract

الحصول على نقطة المورد

يستخدم هذا الطلب للبحث عن مورد واحد من خلال توفير المورد D.

طلب الحصول على نقطة تقليدية:

GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}/providers/{providerNamespace}/{resourceType}/{resourceName}?api-version={apiVersion} 

طلب الحصول على نقطة ARG:

GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}/providers/{providerNamespace}/{resourceType}/{resourceName}?api-version={apiVersion}&useResourceGraph=true 

الحصول على مجموعة الاشتراكات

يستخدم هذا الطلب لإدراج كافة الموارد ضمن نوع مورد واحد في اشتراك.

طلب الحصول على مجموعة الاشتراكات التقليدية:

GET https://management.azure.com/subscriptions/{subscriptionId}/providers/{providerNamespace}/{resourceType}?api-version={apiVersion} 

طلب الحصول على مجموعة اشتراك ARG:

GET https://management.azure.com/subscriptions/{subscriptionId}/providers/{providerNamespace}/{resourceType}?api-version={apiVersion}&useResourceGraph=true 

الحصول على مجموعة الموارد

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

طلب الحصول على نقطة تقليدية:

GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}/providers/{providerNamespace}/{resourceType}?api-version={apiVersion} 

ARG GET/LIST Point Get Request:

GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}/providers/{providerNamespace}/{resourceType}?api-version={apiVersion}&useResourceGraph=true 

إشعار

المعلمة API-version إلزامية لجميع استدعاءات Azure Resource Graph GET/LIST API. ومع ذلك، يتم تجاهل قيمة هذه المعلمة بواسطة الخدمة. بغض النظر عن إصدار واجهة برمجة التطبيقات المحدد، تقوم ARG دائما بإرجاع النتائج استنادا إلى أحدث إصدار غير معاينة متوفر بشكل عام (GA) من واجهة برمجة التطبيقات.

بعض الأمثلة المستخدمة بشكل متكرر

السيناريو: الحصول على الجهاز الظاهري (VM) باستخدام InstanceView

لهذا المثال المحدد، استخدم الطلبات التالية للحصول على جهاز ظاهري باستخدام InstanceView.

طلب ARG GET/LIST

HTTP GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}/providers/microsoft.compute/virtualmachines/{vm}?api-version=2024-07-01&$expand=instanceView&useResourceGraph=true 

قائمة الأجهزة الظاهرية ضمن ResourceGroup

لهذا المثال المحدد، استخدم الطلبات التالية لاسترداد قائمة الأجهزة الظاهرية ضمن مجموعة الموارد.

طلب ARG GET/LIST

HTTP GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}/providers/microsoft.compute/virtualmachines?api-version=2024-07-01&$expand=instanceView&useResourceGraph=true 

سرد VMSS VM (موحد) مع InstanceView

لهذا المثال المحدد، استخدم الطلب التالي لاسترداد قائمة VMSS VM مع InstanceView. هذا السيناريو مخصص ل VMSS VM في وضع التنسيق المرن.

طلب ARG GET/LIST

HTTP GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}/providers/microsoft.compute/virtualmachinescalesets/{vmss}/virtualmachines?api-version=2024-07-01&$expand=instanceView&useResourceGraph=true 

قائمة VMSS VM (Flex) مع InstanceView

لهذا المثال المحدد، استخدم الطلبات التالية لاسترداد قائمة VMSS VM مع InstanceView.

طلب ARG GET/LIST

https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}/providers/microsoft.compute/virtualmachines?api-version=2024-07-01&$filter='virtualMachineScaleSet/id' eq '/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}/providers/microsoft.compute/virtualmachinescalesets/{vmss}'&$expand=instanceView&useResourceGraph=true

سرد حسابات التخزين في الاشتراك

لهذا المثال المحدد، استخدم الطلبات التالية لاسترداد قائمة حسابات التخزين في الاشتراك.

طلب ARG GET/LIST

HTTP GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}/providers/microsoft.storage/storageAccounts?api-version=2024-01-01&useResourceGraph=true 

القيود المعروفة

• الحالة الصحية ل VMSS VM غير مدعومة حاليا. إذا كنت بحاجة إلى هذه البيانات، يمكنك مشاركة السيناريو الخاص بك واقتراح إضافة الميزة في منتديات ملاحظاتنا.
• ملحقات VM وVMSS VM - الحالات قيد التشغيل لملحقات VM وVMSS VM غير مدعومة. إذا كنت بحاجة إلى هذه البيانات، يمكنك مشاركة السيناريو الخاص بك واقتراح إضافة الميزة في منتديات ملاحظاتنا.
• الموارد المدعومة - تدعم ARG GET/LIST API جميع أنواع الموارد كجزء من resources الجدول و computeresources . إذا كنت تحتاج إلى نوع مورد ليس جزءا من هذه الجداول، يمكنك مشاركة السيناريو الخاص بك واقتراح إضافة الميزة في منتديات ملاحظاتنا.
• دعم إصدار API واحد - يدعم ARG GET/LIST اليوم إصدار API واحد فقط لكل نوع مورد، وهو بشكل عام أحدث إصدار غير معاينة من النوع الموجود في مواصفات Azure REST API. ترجع apiVersion وظيفة ARG GET/LIST الحقل في حمولة المورد للاستجابة التي تشير إلى إصدار نوع المورد الذي تم استخدامه عند استرداد تفاصيل المورد. يمكن للمتصلين تطبيق هذا الحقل لفهم إصدار واجهة برمجة التطبيقات لاستخدامه، إذا كان مناسبا للسيناريو الخاص بهم.
• دعم العميل
  • Azure REST API: مدعوم
  • Azure SDK: نموذج مدعوم من التعليمات البرمجية .NET
  • PowerShell: غير مدعوم حاليا
  • Azure CLI: غير مدعوم حاليا
  • مدخل Microsoft Azure: غير مدعوم حاليا
• مخاوف إلغاء تسلسل العميل
  • إذا كان العميل يستخدم واجهة برمجة تطبيقات REST لإصدار استدعاءات GET، يجب ألا تكون هناك أي مخاوف بشكل عام بشأن إلغاء التسلسل بسبب اختلافات إصدار واجهة برمجة التطبيقات.
  • إذا كان العميل يستخدم Azure SDK لإصدار استدعاءات GET، بسبب إعداد إلغاء التسلسل المريح عبر جميع اللغات، فلا ينبغي أن تكون مشكلة إلغاء التسلسل مصدر قلق، ما لم تكن هناك تغييرات كسر العقد بين إصدارات مختلفة لنوع المورد الهدف.
• طلب موارد غير قابل للمعالجة
  • هناك سيناريوهات نادرة حيث لا يتمكن ARG GET/LIST من فهرسة مورد بشكل صحيح، بخلاف وجود المورد. لعدم التضحية بجودة البيانات، يرفض ARG GET/LIST خدمة استدعاءات GET لهذه الموارد وإرجاع رمز خطأ HTTP 422.
  • يجب على عملاء ARG GET/LIST التعامل مع HTTP 422 كخطأ دائم. يجب على العملاء إعادة المحاولة بالرجوع إلى موفر الموارد (عن طريق إزالة العلامة useResourceGraph=true ). نظرا لأن الخطأ قابل للتطبيق خصيصا على ARG GET/LIST، يجب أن يؤدي الرجوع إلى موفري الموارد إلى نجاح E2E.
• مستوى التناسق المدعوم
  • عند استخدام ARG GET أو LIST، تعكس البيانات التي تتلقاها التغييرات الأخيرة بتأخير طفيف - عادة بضع ثوان فقط - بدلا من التحديثات في الوقت الفعلي. يعرف هذا باسم "bounded staleness" ويضمن استعلامات سريعة وقابلة للتطوير مع توفير طريقة عرض متناسقة up-to-date لموارد Azure. على عكس المكالمات المباشرة إلى موفري الموارد، والتي تضمن دقة في الوقت الحقيقي (تناسق قوي)، تم تحسين ARG للأداء مع بيانات يمكن التنبؤ بها وشبه في الوقت الفعلي.
  • في استجابات الحصول على نقطة المورد، يوفر ARG GET/LIST عنوان استجابة x-ms-arg-snapshot-timestamp يشير إلى الطابع الزمني عند فهرسة لقطة المورد التي تم إرجاعها. قيمة العنوان هي وقت التوقيت العالمي المتفق عليه بتنسيق ISO8601. (مثال، "x-ms-arg-snapshot-timestamp" : "2023-01-20T18:55:59.5610084Z").

نموذج التعليمات البرمجية ل SDK

المثال التالي هو نموذج .NET Code لاستدعاء ARG GET/LIST API عن طريق إنشاء ARMClient مع نهج يضيف العلامة useResourceGraph=true إلى كل استدعاء:

أولا، نقوم بإنشاء ArmClientOption مخصص مع نهج يضيف العلامة useResourceGraph=True لكل استدعاء:

var armClientOptions = new ArmClientOptions(); armClientOptions.AddPolicy(new ArgGetListHttpPipelinePolicy(), HttpPipelinePosition.PerCall); 

ثم نقوم بإنشاء ArmClient باستخدام ArmClientOptions المخصصة:

ArmClient resourceGraphClient = new ArmClient(new DefaultAzureCredential(), null, armClientOptions); 

ماذا لو أردنا إنشاء ARMClient باستخدام اشتراك افتراضي؟ سنضبط قيمة عميل ArmClient على:

ArmClient resourceGraphClient = new ArmClient(new DefaultAzureCredential(), defaultSubId, armClientOptions);

اختياريا، لإنشاء عميل افتراضي لا يضيف العلامة useResourceGraph ، تختار التعليمات البرمجية للعميل العميل الذي يجب استخدامه استنادا إلى السيناريو والاحتياجات المحددة. للقيام بذلك، استخدم كتلة التعليمات البرمجية التالية:

ArmClient defaultClient = new ArmClient(new DefaultAzureCredential(), null, new ArmClientOptions()); 

ثم استخدم هذا النهج لإضافة معلمات الاستعلام لكل طلب من خلال العميل:

internal class ArgGetListHttpPipelinePolicy : HttpPipelineSynchronousPolicy 

{ 
    private static const string UseResourceGraph = "useResourceGraph"; 
    public override void OnSendingRequest(HttpMessage message) 

    { 
        // Adds the required query parameter to explicitly query ARG GET/LIST if the flag is not already present 
        if (!message.Request.Uri.ContainsQuery(UseResourceGraph)) 
        { 
          message.Request.Uri.AppendQuery(UseResourceGraph, bool.TrueString); 
        } 
    } 
} 

الأسئلة الشائعة

• كيف تضمن إرجاع الاستجابة بواسطة ARG GET/LIST API؟

  هناك بعض الطرق التي يمكنك من خلالها تحديد وقت طلب ARG GET/LIST:

  • في نص الاستجابة، apiVersion سيتم ملء حقل الموارد، إذا كان يخدمه ARG GET/LIST. 
  • تقوم ARG GET/LIST/ARG بإرجاع المزيد من رؤوس الاستجابة، بعضها:
    • x-ms-arg-snapshot
    • x-ms-user-quota-remaining
    • x-ms-user-quota-resets-after
    • x-ms-resource-graph-request-duration

• كيف يمكنك معرفة إصدار واجهة برمجة التطبيقات الذي تم استخدامه من قبل ARG GET/LIST؟

  يتم إرجاع هذه القيمة في apiVersion الحقل في استجابة الموارد اليوم. 

• ماذا يحدث إذا اتصل المتصل ب ARG GET/LIST API مع useResourceGraph=true علامة لمورد غير مدعوم من قبل ARG GET/LIST؟  

  ينتج عن useResourceGraph=true أي طلبات غير مدعومة/غير قابلة للاسترداد تجاهلها، ويتم توجيه الاستدعاء تلقائيا إلى موفر الموارد. لا يتعين على المستخدم اتخاذ أي إجراء.  

• ما هي الأذونات المطلوبة للاستعلام عن ARG GET/LIST APIs؟

  لا توجد أذونات خاصة مطلوبة ل ARG GET/LIST APIs؛ ARG GET/LIST APIs مكافئة لواجهات برمجة تطبيقات GET المستندة إلى موفر الموارد الأصلي، وبالتالي، ينطبق التحكم في الوصول استنادا إلى الدور القياسي. يحتاج المتصلون إلى الحصول على أذونات READ على الأقل للموارد/النطاقات التي يحاولون الوصول إليها. 

• ما هي استراتيجية التراجع، إذا وجدنا مشكلات أثناء استخدام ARG GET/LIST APIs؟  

  إذا تم إلحاقه من خلال العلامة useResourceGraph=true، فقد يختار المتصل إزالة العلامة (أو) تعيين القيمة إلى useResourceGraph=false، ويتم توجيه المكالمة تلقائيا إلى موفر الموارد. 

• ماذا لو كنت تحصل على 404 Not Found عند محاولة الحصول على مورد من ARG GET/LIST الذي تم إنشاؤه مؤخرا؟

  هذا سيناريو شائع مع العديد من الخدمات حيث يقوم العملاء بإنشاء الموارد وإصدار GET على الفور في جزء من 1-2 ثانية من سير عمل WRITE آخر. على سبيل المثال، ينشئ العملاء موردا جديدا وبعد محاولة إنشاء تنبيه قياسي يراقبه مباشرة. ربما لم تتم فهرسة المورد بواسطة ARG GET/LIST حتى الآن. هناك طريقتان للتغلب على هذا الموقف:

  • أعد المحاولة على ARG GET/LIST عدة مرات حتى يقوم بإرجاع رمز الحالة 200. 
  • أعد المحاولة بدون علامة ARG GET/LIST للعودة إلى موفر الموارد. لا يصل رمز الحالة الحقيقي 404 إلى موفر الموارد نظرا لأن Azure Resource Manager يرجع الخطأ مباشرة، بينما يجب تقديم خطأ 404 من قبل موفري الموارد للحصول على البيانات الفعلية.

• ما معلمات URI التي تدعمها ARG GET/LIST API؟

  تدعم ARG GET/LIST API مجموعة من معلمات URI للمساعدة في تخصيص نتائج الاستعلام وفصل الصفحات. وتشمل هذه: معلمات ترقيم صفحات OData القياسية:

  • $top: يحدد عدد السجلات التي يجب إرجاعها.
  • $skip: يتخطى عدد السجلات المحدد.
  • $skipToken: يستخدم لاسترداد الصفحة التالية من النتائج في استعلامات مرقمة الصفحات.

  معلمات الاستعلام للأجهزة الظاهرية والأجهزة الظاهرية VMSS -

  • statusOnly: statusOnly=true تمكن إحضار حالة وقت التشغيل لجميع الأجهزة الظاهرية في الاشتراك.
  • $expand=instanceView: تعبير التوسيع الذي يجب تطبيقه على العملية. يتيح 'instanceView' إحضار حالة وقت التشغيل لجميع الأجهزة الظاهرية، ولا يمكن تحديد هذا إلا إذا تم تحديد خيار $filter صالح
  • $filter: خيار استعلام النظام لتصفية الأجهزة الظاهرية التي تم إرجاعها في الاستجابة. القيمة المسموح بها هي virtualMachineScaleSet/id eq /subscriptions/{subId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Compute/virtualMachineScaleSets/{vmssName}

• ماذا أفعل إذا واجهت مشكلات أثناء استخدام المعلمة useResourceGraph عند استدعاء Azure Resource Graph؟

  إذا واجهت أي مشكلات أثناء استخدام المعلمة useResourceGraph مع ARG، قم بإنشاء تذكرة دعم ضمن خدمة Azure Resource Graph في مدخل Microsoft Azure ضمن Help + Support.