روابط سريعة
تعد Microsoft GraphAPI أداة قوية يجب عليك امتلاكها. لا يمكننا استخدامها لإنشاء أدوات لأتمتة أعباء العمل لدينا فحسب، بل يمكننا أيضًا الوصول إلى وظائف جديدة في وقت مبكر.
في هذه المقالة، سنتعلم كيفية استكشاف واستخدام Microsoft GraphAPI لـ Azure AD.
المتطلبات الأساسية
يجب عليك تلبية بعض المتطلبات الأساسية قبل أن نبدأ. قبل أن تبدأ بالخطوات الموضحة في هذه المقالة، تأكد من استيفاء ما يلي أو حصولك عليه:
- ان تسجيل التطبيق في AzureAD بأذونات GraphAPI التالية:
- الدليل.اقرأ.الكل
- Directory.ReadWrite.All
- معرف التطبيق (معرف العميل) وسر العميل لتسجيل التطبيق أعلاه
- اسم المستأجر الخاص بك
- جهاز كمبيوتر يعمل بنظام PowerShell الإصدار 5.1 أو أعلى
بعد الانتهاء من ذلك — دعنا نتعلم كيفية استكشاف GraphAPI.
اقرأ الوثائق
إن Microsoft GraphAPI موثق جيدًا، وأفضل مكان للبدء عند اكتشاف كيفية استخدام وظيفة جديدة هو البدء في الوثائق المرجعية من واجهة برمجة تطبيقات Microsoft Graph.
يحدد هذا كيفية استخدام وظيفة معينة والأذونات التي تحتاجها لاستخدامها. يوجد حاليًا إصداران من GraphAPI: v1.0 وbeta API. قد تبدو متطابقة في البداية، لكن واجهة برمجة التطبيقات التجريبية تحتوي على الكثير من الوظائف الجديدة التي لم يتم إصدارها بعد. انتبه أيضًا إلى أن الوظائف الموجودة في واجهة برمجة التطبيقات التجريبية تخضع للتغيير في أي وقت.
الأذونات
تعد الأذونات جزءًا مهمًا من استكشاف أذونات Graph API واستخدامها — ولحسن الحظ، يتم تحديد جميع الأذونات التي تحتاجها لتنفيذ إجراء معين في الوثائق المرجعية من تلك الوظيفة.
توضح لقطة الشاشة التالية الإذن المطلوب لاستخدام
getDirectoryObject وظيفة. ولأنك ستتمكن من الوصول إليه كتطبيق، فأنت بحاجة إلى إذن Directory.ReadAll.
الآن بعد أن أصبحت لديك الأساسيات، فلنبدأ بطلب رمز وصول — سر مؤقت سنستخدمه للوصول إلى Microsoft Graph API.
طلب رمز الوصول
رمز الوصول هو سر يمكنك طلبه باستخدام معرف العميل وسر العميل. هذا هو الرمز المميز الذي يجب عليك تقديمه في الطلبات الموجهة إلى GraphAPI.
لطلب رمز وصول، يتعين عليك تفويض نفسك مقابل نقطة نهاية oauth2 الخاصة بالمستأجر عن طريق نشر معرف التطبيق وسر التطبيق.
قم بتحرير البرنامج النصي التالي، واستبدال AppId وAppSecret واسم Tenant، وتشغيله في PowerShell لطلب رمز وصول:
Add-Type -AssemblyName System.Web$AppId = 'CHANGEME'
$AppSecret = 'CHANGEME'
$Scope = "https://graph.microsoft.com/.default"
$TenantName = "CHANGEME.onmicrosoft.com"
$Url = "https://login.microsoftonline.com/$TenantName/oauth2/v2.0/token"
$Body = @{
client_id = $AppId
client_secret = $AppSecret
scope = $Scope
grant_type = 'client_credentials'
}
$PostSplat = @{
ContentType = 'application/x-www-form-urlencoded'
Method = 'POST'
Body = $Body
Uri = $Url
}
$Request = Invoke-RestMethod @PostSplat
الآن إذا ألقيت نظرة على $Request المتغير، يمكنك أن ترى أنه يحتوي على رمز الوصول الخاص بنا، بالإضافة إلى النوع ووقت انتهاء الصلاحية.
PS51> $Requesttoken_type expires_in ext_expires_in access_token
Bearer 3599 3599 eyJ...............
تنتهي الصلاحية بالثواني، مما يعني أنه يتعين عليك طلب رمز مميز جديد خلال ساعة وإلا سيتوقف عن العمل.
دعونا نحفظ رمز الوصول في متغير لاستخدامه في المستقبل ثم نبدأ في تقديم الطلبات نحو GraphApi:
PS51> $AccessToken = $Request.access_token
طلبك الأول لـ GraphAPI
لقد حان الوقت لطلب الرسم البياني الأول الخاص بك! أبسط الطلبات للبدء بها هي الطلبات التي تستخدم HTTP GET. أوامر GET مخصصة فقط لجلب المعلومات، لذلك لا داعي للقلق بشأن إفساد أي شيء.
سنبدأ بطلب بسيط يدرج النطاقات المرتبطة بالمستأجر لدينا. وتذكر — اقرأ الوثائق. جميع المعلومات حول كيفية استخدام وظائف GraphAPI موجودة في الوثائق.
ربما لاحظت في وثائق أمر List Domains أنه يمكنك الاتصال به باستخدام HTTP GET — الطريقة الافتراضية عند استخدام Invoke-RestMethod:
باستخدام هذه المعلومات، يمكنك البدء في إنشاء الطلب. لذلك، نحتاج إلى إنشاء رأس تفويض يحتوي على “Bearer ” واستخدمه لتقديم طلب GET نحو عنوان URL الموجود في الصورة أعلاه:
$Headers = @{
Authorization = "Bearer $AccessToken"
}$Uri = "https://graph.microsoft.com/v1.0/domains"
$Result = Invoke-RestMethod -Headers $Headers -Uri $Uri
لديك الآن قائمة بالمجالات الموجودة في $Result متغير، ولكن تحاول إخراج قيمة $Result المتغير سيؤدي إلى هذا:
PS51> $Result@odata.context value
$metadata
عادة ما تكون نتيجة الاستعلام في خاصية القيمة للنتيجة. يمكنك الحصول على النتيجة بأكملها بمجرد إخراج تلك الخاصية بدلاً من ذلك:
PS51> $Result.valueauthenticationType : Managed
availabilityStatus :
id : contoso.com
isAdminManaged : True
isDefault : True
isInitial : False
isRoot : True
isVerified : True
supportedServices : {Email, Intune}
state :
passwordValidityPeriodInDays : 2147483647
passwordNotificationWindowInDays : 14
authenticationType : Managed
availabilityStatus :
id : contoso.onmicrosoft.com
isAdminManaged : True
isDefault : False
isInitial : True
isRoot : True
isVerified : True
supportedServices : {Email, OfficeCommunicationsOnline}
state :
passwordValidityPeriodInDays : 2147483647
passwordNotificationWindowInDays : 14
الآن بعد أن تعلمت أساسيات الحصول على المعلومات باستخدام GraphAPI، فقد حان الوقت لمعرفة كيفية استخدام المرشحات.
استخدام المرشحات
إنه لأمر رائع أن تكون قادرًا على جلب جميع البيانات المتوفرة. وعلى الرغم من أنه قد ينجح، إلا أنه غير فعال على الإطلاق. من الممارسات الجيدة أن تطلب فقط البيانات التي تحتاجها. لتحقيق ذلك في GraphAPI، يمكننا استخدام المرشحات.
المرشح الجيد لتجربة المرشحات هو عن طريق الجلب المستخدمين. لديهم الكثير من أسماء السمات الشائعة لـ Active Directory المحلي، وعادةً ما يكون لديك عدد قليل منها على الأقل.
عنوان URI لجلب جميع المستخدمين هو *https://graph.microsoft.com/v1.0/users*، ولكننا نريد تصفية هذا الطلب. يمكنك القيام بذلك عن طريق إضافة $filter= المعلمة إلى URI.
يتكون المرشح (عادةً) من عامل تشغيل الخاصية وقيمة مثل هذه:
property operator 'value'
إذا كنت تريد الآن جلب كافة المستخدمين بالاسم المحدد “John”، فيجب استخدام عنوان URI التالي:
https://graph.microsoft.com/v1.0/users?$filter=givenName eq 'John'
لذا، إذا كنت تريد استخدام PowerShell لإجراء هذا الطلب، فيجب أن يبدو الرمز كما يلي:
$Uri = "https://graph.microsoft.com/v1.0/users?`$filter=givenName eq 'John'"
$Result = Invoke-RestMethod -Headers $Headers -Uri $Uri لاحظ علامة الرجوع من قبل $filter— هذا للهروب من علامة الدولار — وإلا لكان PowerShell قد فسرها على أنها متغير.
ألقِ نظرة على خاصية القيمة، وسترى جميع المستخدمين الذين لديهم اسم محدد “John” في Azure Active Directory:
PS51> $Result.valuebusinessPhones : {5554012}
displayName : John Doe
givenName : John
jobTitle :
mail : jdoe@contoso.com
mobilePhone :
officeLocation :
preferredLanguage : en
surname : Doe
userPrincipalName : jdoe@contoso.com
id : 7fd22087-ec0a-47a1-91fb-0a7d8e6f0c
“EQ” ليس العامل الوحيد، فليس لديك (ne)، أو تطابق، أو يحتوي، أو أقل/أكبر من (lt/gt)، وغير ذلك الكثير. على الرغم من أنها خارج نطاق هذه المقالة، إلا أن المزيد من المعلومات حول المشغلين متوفرة في الوثائق. تتوفر أيضًا وثائق أكثر شمولاً حول خصائص التصفية المختلفة في الخاصية الوثائق حول كل نوع كائن.
إنشاء مستخدم
الآن بعد أن حصلت على الأساسيات، فلنقم بإجراء عملية كتابة وإنشاء مستخدم. لذلك، عليك أن تعرف كيفية إنشاء البيانات ومكان نشرها. يمكنك الاطلاع على مثال حول كيفية تنفيذ ذلك من خلال الانتقال إلى وثائق Microsoft Graph API والنظر فيها “إنشاء مستخدم”:
يمكنك أن ترى أنك بحاجة إلى إرسال البيانات كطلب POST، وأن نوع المحتوى يجب أن يكون application/json. يمكنك أيضًا رؤية تمثيل JSON للبيانات — الهدف هنا هو إنشاء كائن PowerShell الذي ينشئ JSON عندما ConvertTo-Json يستخدم عليه.
دعونا نلقي نظرة على ذلك:
$Body = (PSCustomObject)@{
accountEnabled = $True
displayName = "Jane Doe"
mailNickname = "janedoe"
userPrincipalName = "jane.doe@automativity.com"
passwordProfile = @{
forceChangePasswordNextSignIn = $True
password = "Hunter221!"
}
}
جري $Body | ConvertTo-Json سيؤدي إلى JSON مماثل لتلك المعروضة في الوثائق. ما تبقى الآن هو تحويله إلى JSON ونشره إلى GraphAPI URI بنوع المحتوى الصحيح:
$Body = (PSCustomObject)@{
accountEnabled = $True
displayName = "Jane Doe"
mailNickname = "janedoe"
userPrincipalName = "jane.doe@contoso.com"
passwordProfile = @{
forceChangePasswordNextSignIn = $True
password = "Hunter221!"
}
}$BodyJson = $Body | ConvertTo-Json
$Uri = "https://graph.microsoft.com/v1.0/users"
Invoke-RestMethod -Uri $Uri -Headers $Headers -Method POST -ContentType application/json -Body $BodyJson
إذا انتقلت الآن إلى وحدة تحكم Azure Active Directory وألقيت نظرة، فستجد المستخدم الذي تم إنشاؤه حديثًا:
لقد قمت الآن بإنشاء المستخدم الأول الخاص بك باستخدام GraphAPI!
خاتمة
تعد Microsoft GraphAPI أداة قوية وستمكنك من أتمتة بيئتك بشكل أكبر. وليس فقط عندما يتعلق الأمر بـ Azure Active Directory — ولكن أيضًا بالنسبة لغالبية خدمات SaaS التي تقدمها Microsoft.
مع الأخذ في الاعتبار أيضًا الحركة “بدون خادم” باستخدام Azure Functions أو AWS Lambda في حدث ما، فمن الممكن إنشاء وظائف بسيطة تعتمد على الحدث لأتمتة أكبر قدر ممكن في بيئتك. كل ذلك دون الحاجة إلى تضمين مكتبات كبيرة في وظائفك.
(العلامات للترجمة)سحابة(ر)مايكروسوفت