M365Con 2027 – مؤتمر مجاني عبر الإنترنت · 11–22 Jan 2027 · 120 sessions→ m365con.net

المدونة · Mirko Peters

Microsoft Graph PowerShell لمسؤولي SharePoint: الأوامر الأولى

By · · Updated

Microsoft Graph PowerShell لـ SharePoint: ثبّت الـ SDK، وسجّل الدخول بالنطاق الصحيح، واعرض المواقع باستخدام Get-MgSite، وعالج أخطاء 403 التي يصادفها المسؤولون أولاً.

Automatically translated with AI from the original post. Read the English original

يعني Microsoft Graph PowerShell لـ SharePoint استخدام SDK الخاص بـ Graph لقراءة المواقع وإدارتها من سطر الأوامر. تثبّت وحدة واحدة، وتسجّل الدخول باستخدام Connect-MgGraph ونطاق إذن، ثم تشغّل cmdlets مثل Get-MgSite. يستهدف هذا الدليل مسؤولي SharePoint الذين يعرفون مركز إدارة SharePoint بالفعل ويريدون مساراً آمناً للبدء في البرمجة النصية. ستثبّت الـ SDK، وتسجّل الدخول بأصغر نطاق يعمل، وتعرض المواقع، وتتعلم كيف تقرأ الأخطاء التي تظهر أولاً.

النقاط الرئيسية

  • Microsoft Graph PowerShell هو SDK يغلّف واجهات Graph البرمجية، لذا يتطلب كل أمر أولاً تسجيل دخول عبر Connect-MgGraph مع نطاقات الأذونات الصحيحة.
  • يعرض Get-MgSite مواقع SharePoint ويحتاج إلى الإذن Sites.Read.All كحد أدنى، وهو أقل خيار امتيازاً توثّقه Microsoft لهذا الأمر.
  • يعرض Get-MgContext النطاقات التي تملكها الجلسة الحالية، وهي أسرع طريقة لتفسير خطأ 403 Forbidden.
  • يُخبرك Find-MgGraphCommand وFind-MgGraphPermission بالإذن الذي يحتاجه الأمر، فلا تضطر إلى تخمين أسماء النطاقات.
  • يناسب تسجيل الدخول المفوَّض شخصاً أمام لوحة المفاتيح، بينما يناسب تسجيل الدخول للتطبيق فقط باستخدام شهادة أو هوية مُدارة المهامَ المجدولة التي تعمل دون تدخل بشري.

ما هو Microsoft Graph PowerShell، ولماذا يستخدمه المسؤولون

Microsoft Graph هي الواجهة البرمجية الموحدة لبيانات Microsoft 365: المستخدمون والمجموعات والملفات والبريد وTeams ومواقع SharePoint. وتغلّف حزمة Microsoft Graph PowerShell SDK واجهة Graph البرمجية في cmdlets. لا تحتاج إلى كتابة طلبات ويب لكل نقطة نهاية، بل تشغّل Get-MgSite فتحصل على كائنات المواقع مباشرة.

بالنسبة لمسؤول SharePoint، يقدّم هذا ثلاث فوائد عملية.

  • أداة واحدة لعدة خدمات. يعمل تسجيل الدخول نفسه مع المواقع والمستخدمين والمجموعات. يمكن للنص البرمجي أن يعرض المواقع، ثم يبحث عن مالكيها.
  • نموذج أذونات يمكن قراءته. يتطلب كل استدعاء أذونات محددة تُسمى النطاقات. يمكنك معرفة النطاقات التي تملكها الجلسة، وسبب رفض الاستدعاء.
  • مسار بعيد عن الوحدات القديمة. تصف ملاحظات الكيان الخاصة بـ Microsoft Graph PowerShell بأنها البديل لوحدتي Azure AD PowerShell وMSOnline المتقاعدتين.

وحدة PnP PowerShell المجتمعية هي الخيار الشائع الآخر للبرمجة النصية في SharePoint، وتشير وثائقها إلى أن بعض أوامرها تتواصل مع Graph أيضاً. لا يحل Graph PowerShell محل كل أدوات إدارة SharePoint، فهو يغطي ما تكشفه واجهة Graph البرمجية. وما زالت بعض إعدادات المستأجر موجودة في مركز إدارة SharePoint أو في وحدات أخرى. تعامل مع Graph باعتباره أداة واحدة ضمن مجموعتك، لا الأداة الوحيدة.

الخطوة 1: تثبيت الـ SDK وتسجيل الدخول

يوصي دليل التثبيت باستخدام PowerShell 7 أو أحدث على جميع المنصات. يتطلب Windows PowerShell الإصدار 5.1 أو أحدث، و.NET Framework 4.7.2 أو أحدث، وسياسة تنفيذ RemoteSigned أو أقل تقييداً.

اتبع هذه الخطوات:

  1. ثبّت الوحدة لحسابك الشخصي: Install-Module Microsoft.Graph -Scope CurrentUser -Repository PSGallery -Force. استخدم -Scope AllUsers فقط إذا كانت لديك صلاحيات المسؤول وتحتاج إلى تثبيت مشترك.
  2. تحقّق من النتيجة باستخدام Get-InstalledModule Microsoft.Graph.
  3. اعلم أن الوحدة الرئيسية تثبّت أكثر من 47 وحدة فرعية. تشير الصفحة إلى أنه يمكنك تثبيت الوحدات التي تحتاجها فقط، وأن Microsoft.Graph.Authentication يأتي معها.
  4. حدّث الوحدة لاحقًا باستخدام Update-Module Microsoft.Graph. الوحدة القديمة سبب مذكور لتعارضات الإصدارات.

التثبيت في إصدار من PowerShell لا يثبّتها في الإصدار الآخر، لذا نفّذ الأمر في الإصدار الذي ستستخدمه.

الآن سجّل الدخول. تشرح صفحة أوامر المصادقة أن SDK يدعم نوعين من الوصول: مفوَّض وبدون مستخدم (app-only). الوصول المفوَّض يعمل نيابةً عن مستخدم مسجّل الدخول، وأذوناته هي النطاقات (scopes). أما الوصول بدون مستخدم فيعمل دون مستخدم، باستخدام شهادة أو سر عميل أو هوية مُدارة.

في أوامرك الأولى، استخدم الوصول المفوَّض واطلب نطاقًا واحدًا للقراءة فقط:

Connect-MgGraph -Scopes "Sites.Read.All"

يُفتح نافذة متصفح لتسجيل الدخول. للتحقق مما حصلت عليه، نفّذ Get-MgContext | Select -ExpandProperty Scopes. توثّق Microsoft الأمر Get-MgContext بأنه الأمر الذي يُرجع تفاصيل جلستك الحالية، مثل معرّف العميل ومعرّف المستأجر والنطاقات ونوع المصادقة. عند الانتهاء، نفّذ Disconnect-MgGraph. تذكر الصفحة أنك تبقى متصلًا حتى تفعل ذلك، لأن الرموز تُخزَّن مؤقتًا ضمن النطاق الافتراضي CurrentUser. أضف -ContextScope Process إلى Connect-MgGraph إذا أردت أن يستمر تسجيل الدخول للجلسة الحالية فقط.

أولى الأوامر لمواقع SharePoint

يسرد المرجع الخاص بـ Get-MgSite المعاملات الرئيسية: -Filter و-Search و-Property (الاسم المستعار -Select) و-Top و-Sort و-All. أمثلة الصفحة نفسها قصيرة:

  • Get-MgSite يسرد المواقع.
  • Get-MgSite -Property "siteCollection,webUrl" -Filter "siteCollection/root ne null" يُرجع مجموعات المواقع الجذرية فقط، مع خاصيتين.

ابنِ على ذلك:

  1. القائمة مع التصفح بين الصفحات. نفّذ Get-MgSite -All لتتبّع كل صفحات النتائج. بدون -All قد ترى الصفحة الأولى فقط.
  2. اختر الأعمدة. أضف -Property "id,displayName,webUrl" لتبقى المخرجات مختصرة وسهلة القراءة.
  3. البحث بالكلمة المفتاحية. نفّذ Get-MgSite -Search "finance". تطابق واجهة البحث في Graph النص الحر عبر عدة خصائص للموقع.
  4. احصل على موقع واحد. نفّذ Get-MgSite -SiteId <id>، حيث المعرّف هو قيمة id من نتيجة سابقة. وله شكل اسم مضيف يليه معرّفان عامان (GUID)، مفصولان بفاصلة.

كل واحد من هذه الأوامر يقابل استدعاء REST. يقرأ Get-MgSite -All مجموعة المواقع من https://graph.microsoft.com/v1.0/sites، وهو العنوان الذي تعرضه وثائق REST لسرد المواقع، وتصبح -Filter و-Search و-Property خيارات استعلام على هذا العنوان. يحصل SDK على رموزه عبر مكتبة المصادقة من Microsoft (MSAL). إذا لم يتوفر أمر لاستدعاء تحتاجه، يمكن لـ Invoke-MgGraphRequest استدعاء URI مباشرةً. وتستخدمه صفحة استكشاف الأخطاء لفحص الـ URI الكامن وراء خطأ Bad request.

هناك حدّان مهمّان. أولًا، تُرجع نقطة نهاية القائمة في Graph المواقع ضمن المنطقة الجغرافية الافتراضية للمؤسسة. ولجميع المناطق الجغرافية، توجّه Microsoft إلى واجهة getAllSites، التي يقابلها الأمر Get-MgAllSite. ثانيًا، لا يمكن لواجهة البحث الفرز إلا حسب createdDateTime.

ما الأذونات التي تحتاجها؟ Microsoft Graph PowerShell ونطاقات SharePoint

تُعدّ أذونات Microsoft Graph الجزءَ الذي يفاجئ المستخدمين الجدد. بالنسبة إلى قراءة المواقع، تُدرج صفحة الأوامر Sites.Read.All بوصفه الخيارَ الأقل امتيازاً، وSites.ReadWrite.All بوصفه الخيارَ الأعلى امتيازاً. اختروا الأول ما لم يكن السكربت مطالباً بتغيير شيء ما.

لا حاجة إلى حفظ أسماء النطاقات (scopes). هناك أمرا مساعدة يتوليان البحث عنها:

  • يعرض Find-MgGraphCommand الأذونات التي يتطلبها أمرٌ أو واجهة برمجية. تستخدم صفحة استكشاف الأخطاء وإصلاحها الأمر Find-MgGraphCommand -command New-MgServicePrincipal | Select -First 1 -ExpandProperty Permissions مثالاً لها.
  • يعثر Find-MgGraphPermission على الأذونات حسب المجال أو الاسم، مثل Find-MgGraphPermission application. يعرض الناتج نوع الإذن (مفوَّض أو تطبيق)، وما إذا كانت الموافقة تتم من قبل مسؤول، إضافةً إلى وصف.

لاحظوا نقطة تعارض واحدة في الوثائق. تُظهر صفحة REST الخاصة بسرد المواقع أذونات التطبيقات فقط لهذا الاستدعاء، وتُشير إلى أن الوصول المفوَّض غير مدعوم. أما صفحة الأمر Get-MgSite فتُدرج النوعين. اختبروا الاستدعاء الخاص بكم في مستأجر غير إنتاجي، واقرؤوا نص الخطأ إذا فشل. لا تفترضوا أن صفحة الأمر صحيحة لكل استدعاء.

بالنسبة إلى المهام غير المراقَبة، تحتاجون إلى وصول خاص بالتطبيق فقط. وهذا يعني تسجيل تطبيق في Microsoft Entra، وأذونات التطبيقات (وتُسمّى أيضاً أذونات واجهة برمجة التطبيقات)، وموافقة المسؤول. تنص صفحة استكشاف الأخطاء وإصلاحها على أن أذونات التطبيقات تتطلب موافقة المسؤول. استخدموا شهادة أو هوية مُدارة، لا كلمة مرور مكتوبة.

مثال: جرد للمواقع المهجورة في خمسة أوامر

الأرقام الواردة في هذا المثال مُختلَقة.

يريد أحد المسؤولين قائمة أولية بالمواقع التي لم يُجرِ أحد عليها أي تعديل منذ عام.

  1. Connect-MgGraph -Scopes "Sites.Read.All"
  2. $sites = Get-MgSite -All -Property "id,displayName,webUrl,lastModifiedDateTime"
  3. يُرجع $sites.Count القيمة 480 في هذا المثال.
  4. $old = $sites | Where-Object { $_.LastModifiedDateTime -lt (Get-Date).AddYears(-1) }
  5. $old | Select DisplayName, WebUrl, LastModifiedDateTime | Export-Csv stale-sites.csv -NoTypeInformation

لنفترض أن الملف يحتوي على 60 صفاً. هذا يعني 60 من أصل 480، أي 12.5 بالمئة، وهي قائمة قصيرة يسهل مراجعتها مع مالكي المواقع. لم يملك المسؤول سوى صلاحية القراءة، ولم يُجرِ أي تغيير. لكن تاريخ آخر تعديل على الموقع لا يثبت أن أحداً لا يستخدمه، لذا فالقائمة نقطة انطلاق لطرح الأسئلة، وليست قائمة للحذف.

الأخطاء الشائعة

  • الاتصال دون نطاق مناسب. يؤدي تسجيل الدخول دون النطاق الصحيح إلى أخطاء 403. شغّلوا Get-MgContext وقارنوا النطاقات بما يحتاجه الأمر.
  • طلب نطاقات الكتابة لمهمة قراءة. Sites.ReadWrite.All يتجاوز ما يحتاجه أي تقرير. ابدأوا بـ Sites.Read.All.
  • نسيان -All. بدونه قد تبدو القائمة كاملة بينما هي الصفحة الأولى فقط.
  • الخلط بين إصدارات الوحدات. توصي Microsoft بوحدة الإصدار v1.0 للسكربتات. أما وحدة beta فهي في مرحلة المعاينة، وقد تتغير دون إشعار.
  • تخطي التحديث. تُعدّ نسخة Microsoft.Graph القديمة سبباً معروفاً لتعارضات الإصدارات. شغّلوا Update-Module Microsoft.Graph قبل البحث عن أسباب أخرى.
  • البقاء مسجلاً للدخول على جهاز مشترك. تُخزَّن الرموز المميزة مؤقتاً. شغّلوا Disconnect-MgGraph عند الانتهاء.

كيف يمكن للبرمجيات أن تساعد

تُلبّى معظم الاحتياجات الأولى بأدوات تملكونها بالفعل. يتولى Microsoft Graph PowerShell SDK القراءة والتصدير. يعرض مركز إدارة SharePoint قوائم المواقع وإعداداتها دون الحاجة إلى كود. ويحوّل Excel أو Power BI ملف CSV إلى تقرير يستطيع مالكو المواقع قراءته. وفي حال التشغيل المجدول، يمكن لـ Azure Automation تشغيل سكربت باستخدام هوية مُدارة.

ابحثوا عن الثغرات بعد الشهر الأول فقط. إذا كنتم تعيدون بناء الجرد نفسه يدوياً باستمرار، فعادةً ما يكفي سكربت محفوظ بمجلد مخرجات ثابت وتذكير شهري.

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

ثبّتوا الـ SDK، وشغّلوا Connect-MgGraph -Scopes "Sites.Read.All"، وصدّروا ناتج Get-MgSite -All إلى ملف CSV اليوم. ثم استخدموا Find-MgGraphCommand مع أمرك التالي لمعرفة إذنه قبل تشغيل مهام SharePoint عبر Microsoft Graph PowerShell في بيئة الإنتاج.

تابع البودكاستApple PodcastsSpotify

Entities in this article

Microsoft Graph PowerShell Microsoft Graph SharePoint Microsoft Graph permissions

Related articles

RSS