البدء السريع: تشغيل الاستعلام الأول Resource Graph باستخدام REST API

مقالة
03/05/2024

الخطوة الأولى لاستخدام Azure Resource Graph مع REST API هو التحقق من أن لديك أداة لاستدعاء واجهات برمجة التطبيقات REST المتوفرة. ثم يقوم هذا التشغيل السريع بالمرور خلال عملية تشغيل استعلام واسترداد النتائج عن طريق استدعاء نقطة النهاية Azure Resource Graph REST API.

في نهاية هذه العملية، سيكون لديك الأدوات اللازمة لاستدعاء نقاط نهاية REST API وتشغيل استعلام Graph الموارد الأول.

المتطلبات الأساسية

في حال لم يكن لديك اشتراك Azure، فأنشئ حساباً مجانيّاً قبل البدء.

Azure Cloud Shell

Azure يستضيف Azure Cloud Shell، بيئة تفاعلية يمكن استخدامها من خلال المستعرض. يمكنك استخدام Bash أو PowerShell مع Cloud Shell للعمل مع خدمات Azure. يمكنك استخدام أوامر Cloud Shell المثبتة مسبقًا لتشغيل التعليمات البرمجية في هذه المقالة دون الحاجة إلى تثبيت أي شيء على البيئة المحلية.

لبدء Azure Cloud Shell:

خيار	مثال/ رابط
انقر فوق ⁧⁩جربه⁧⁩ في الزاوية العلوية اليسرى من التعليمة البرمجية أو كتلة الأمر. تحديد ⁧⁩جربه⁧⁩ لا يقوم بنسخ التعليمة البرمجية أو الأمر تلقائيًا إلى Cloud Shell.
انتقل إلى ⁧⁩⁧ https://shell.azure.com⁩⁧⁩، أو حدد زر ⁩تشغيل Cloud Shell لفتح Cloud Shell في المتصفح لديك.
حدد زر Cloud Shell على شريط القوائم في أعلى اليمين في مدخل Microsoft Azure.

لاستخدام Azure Cloud Shell:

ابدأ تشغيل Cloud Shell.
حدد الزر نسخ على كتلة التعليمات البرمجية (أو كتلة الأوامر) لنسخ التعليمات البرمجية أو الأمر.
ألصق التعليمة البرمجية أو الأمر في جلسة Cloud Shell بتحديد Ctrl+Shift+Vعلى Windows وLunix، أو بتحديد Cmd+Shift+Vعلى macOS.
حدد Enter لتشغيل التعليمات البرمجية أو الأمر.

الشروع في العمل مع REST API

إذا لم تكن على دراية بواجهة برمجة تطبيقات REST، فابدأ بمراجعة مرجع واجهة برمجة تطبيقات Azure REST للحصول على فهم عام لواجهة برمجة تطبيقات REST، وطلب URI على وجه التحديد ونص الطلب. تستخدم هذه المقالة هذه المفاهيم لتوفير توجيهات للعمل مع Graph Azure Resource وتفترض معرفة عملية بها. قد تتعامل أدوات مثل ARMClient وغيرها مع التفويض تلقائيًّا ويوصى بها للمبتدئين.

للحصول على مواصفات Azure Resource Graph، راجع Azure Resource Graph REST API.

واجهة برمجة تطبيقات REST وPowerShell

إذا لم يكن لديك بالفعل أداة لإجراء مكالمات REST API، ففكر في استخدام PowerShell لهذه التعليمات. نموذج التعليمات البرمجية التالية يحصل على رأس للمصادقة لدى Azure. أنشئ رأس مصادقة، يُطلق عليه أحيانًا رمز الحامل المميز، وقدم REST API URI للاتصال بأي معلمات أو نص الطلب:

# Log in first with Connect-AzAccount if not using Cloud Shell

$azContext = Get-AzContext
$azProfile = [Microsoft.Azure.Commands.Common.Authentication.Abstractions.AzureRmProfileProvider]::Instance.Profile
$profileClient = New-Object -TypeName Microsoft.Azure.Commands.ResourceManager.Common.RMProfileClient -ArgumentList ($azProfile)
$token = $profileClient.AcquireAccessToken($azContext.Subscription.TenantId)
$authHeader = @{
    'Content-Type'='application/json'
    'Authorization'='Bearer ' + $token.AccessToken
}

# Invoke the REST API
$restUri = "https://management.azure.com/subscriptions/$($azContext.Subscription.Id)?api-version=2020-01-01"
$response = Invoke-RestMethod -Uri $restUri -Method Get -Headers $authHeader

$response يحتوي المتغير على نتيجة Invoke-RestMethod cmdlet، والتي يمكن تحليلها مع cmdlets مثل ConvertFrom-Json. إذا كانت نقطة نهاية خدمة واجهة برمجة تطبيقات REST تتوقع نص طلب، فقم بتوفير متغير بتنسيق JSON للمعلمة-Body الخاصة بـInvoke-RestMethod.

تشغيل أول استعلام لك في Resource Graph

مع إضافة أدوات REST API إلى البيئة التي اخترتها، فقد حان الوقت لتجربة استعلام Resource Graph البسيط القائم على الاشتراك. الاستعلام بإرجاع موارد Azure الخمس الأولى مع الاسم ونوع المورد لكل مورد. للاستعلام حسب مجموعة الإدارة، استخدم managementgroups بدلا من subscriptions. للاستعلام عن المستأجر بأكمله، احذف كلا managementgroups من خصائص و subscriptions من نص الطلب.

في نص الطلب لكل استدعاء REST API، هناك متغير يستخدم تحتاج إلى استبداله بقيمتك الخاصة:

{subscriptionID} - استبدل معرف الاشتراك الخاص بك

قم بتشغيل استعلام Azure Resource Graph الأول باستخدام واجهة برمجة تطبيقات REST ونقطة resources النهاية:
- REST API URI
```
POST https://management.azure.com/providers/Microsoft.ResourceGraph/resources?api-version=2021-03-01
```
- نص الطلب
```
{
    "subscriptions": [
        "{subscriptionID}"
    ],
    "query": "Resources | project name, type | limit 5"
}
```
إشعار

ونظرًا لأن مثال الاستعلام هذا لا يوفر معدلاً للفرز مثل order by، فمن المحتمل أن يؤدي تشغيل هذا الاستعلام عدة مرات إلى إنتاج مجموعة مختلفة من الموارد لكل طلب.
تحديث الاستدعاء إلى resouces نقطة النهاية وتغيير الاستعلام إلى order by الخاصية Name :
- REST API URI
```
POST https://management.azure.com/providers/Microsoft.ResourceGraph/resources?api-version=2021-03-01
```
- نص الطلب
```
{
    "subscriptions": [
        "{subscriptionID}"
    ],
    "query": "Resources | project name, type | limit 5 | order by name asc"
}
```
إشعار

كما هو الحال مع الاستعلام الأول، من المحتمل أن يؤدي تشغيل هذا الاستعلام عدة مرات إلى إنتاج مجموعة مختلفة من الموارد لكل طلب. إن ترتيب أوامر الاستعلام مهم. في هذا المثال، يأتي order by بعد limit. يحدد ترتيب الأوامر هذا أولاً نتائج الاستعلام ثم يأمر بها.

تحديث الاستدعاء إلى resources نقطة النهاية وتغيير الاستعلام إلى خاصية الاسم أولا order byثم limit إلى أفضل خمس نتائج:

REST API URI

POST https://management.azure.com/providers/Microsoft.ResourceGraph/resources?api-version=2021-03-01

نص الطلب

{
    "subscriptions": [
        "{subscriptionID}"
    ],
    "query": "Resources | project name, type | order by name asc | limit 5"
}

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

لمزيد من الأمثلة على استدعاءات واجهة برمجة تطبيقات REST ل Azure Resource Graph، راجع أمثلة REST ل Azure Resource Graph.

تنظيف الموارد

REST API لا يوجد لديه مكتبات أو وحدات نمطية لإلغاء التثبيت. إذا قمت بتثبيت أداة مثل ARMClient لإجراء المكالمات ولم تعد بحاجة إليها، يمكنك إلغاء تثبيت الأداة الآن.

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

في هذا البدء السريع، قمت باستدعاء نقطة نهاية Resource Graph REST وتشغيل الاستعلام الأول. لمعرفة المزيد حول لغة Resource Graph، تابع إلى صفحة تفاصيل لغة الاستعلام.

الحصول على مزيد من المعلومات حول لغة الاستعلام

Share via