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

المدونة · Mirko Peters

الاتصال بـ SharePoint Online باستخدام PnP PowerShell: خيارات تسجيل الدخول

By · · Updated

الاتصال بـ SharePoint Online باستخدام PnP PowerShell: سجّل تطبيقك الخاص في Entra، ثم اختر تسجيل الدخول التفاعلي أو عبر الجهاز أو بالشهادة أو الهوية المُدارة لكل مهمة.

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

للاتصال بـ SharePoint Online باستخدام PnP PowerShell اليوم، تسجّل تطبيقك الخاص في Microsoft Entra ID مرة واحدة. ثم تستدعي Connect-PnPOnline مع عنوان URL لموقعك ومعرّف العميل (Client ID) لذلك التطبيق، مع طريقة تسجيل دخول واحدة: التفاعلية، أو تسجيل الدخول عبر الجهاز، أو الشهادة، أو الهوية المُدارة، أو بيانات الاعتماد القديمة. يستهدف هذا الدليل مسؤولي SharePoint الذين يشغّلون النصوص البرمجية يدويًا أو وفق جدول زمني. يشرح ما تفعله كل طريقة، ومتى تستخدمها، وما الأخطاء التي تُفسد الاتصال. كما يوضح كيف تختار طريقة واحدة لكل مهمة، حتى لا تحتاج النصوص البرمجية إلى صلاحيات أكثر مما تتطلبه.

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

  • منذ 9 سبتمبر 2024، يتطلب Connect-PnPOnline المعامل -ClientId، لذا يجب على كل مسؤول أولًا تسجيل تطبيق في Microsoft Entra ID يستطيع الوحدة النمطية تسجيل الدخول به.
  • تسجيل الدخول التفاعلي هو الخيار الصحيح لشخص يعمل على لوحة المفاتيح، لأنه يدعم المصادقة متعددة العوامل ولا يحتاج إلى سرّ مخزّن.
  • يجب أن تستخدم المهام غير المُشرف عليها تسجيل الدخول بالشهادة أو الهوية المُدارة، وليس كلمة مرور مكتوبة ولا سرًا للعميل مخزّنًا في نص برمجي.
  • تعمل طريقة السر القديم للعميل (Client Secret) مع أوامر SharePoint فقط، لذا سيفشل أي أمر يستدعي Microsoft Graph باستخدامها.
  • سجّل التطبيق بالأذونات المفوّضة التي تحتاجها فقط، لأن التسجيل الافتراضي يطلب صلاحيات واسعة مثل AllSites.FullControl.

البداية: لماذا يحتاج كل اتصال إلى تطبيقك الخاص

PnP PowerShell وحدة نمطية تُدار من المجتمع. ولا تملك صلاحيات خاصة بها. يمر كل تسجيل دخول عبر تسجيل تطبيق في Microsoft Entra، وذلك التطبيق هو الذي يحدد ما يحق للنص البرمجي تنفيذه.

يوضح مرجع Connect-PnPOnline أنه يجب توفير المعامل -ClientId بدءًا من 9 سبتمبر 2024. كما يوضح أنه يجب عليك تسجيل تطبيقك الخاص أولًا. ويمكنك ضبط متغير البيئة ENTRAID_APP_ID أو ENTRAID_CLIENT_ID بدلًا من كتابة المعرّف في كل مرة.

أثّر هذا التغيير في النصوص البرمجية القديمة. فإذا كان نص برمجي من عام 2023 يستدعي Connect-PnPOnline -Url ... -Interactive دون أي شيء آخر، فسيفشل الآن أو يطالب بمعرّف عميل مفقود. والحل لا يكمن في منطق النص البرمجي، بل تحتاج إلى تطبيق ومعرّف.

هناك قيمتان أخريان تظهران في كل مثال:

  • -Url هو عنوان الموقع الذي تريد العمل عليه، مثل https://contoso.sharepoint.com/sites/finance. وهو مطلوب في معظم الطرق.
  • -Tenant هو اسم المستأجر، مثل contoso.onmicrosoft.com. يذكر المرجع أنه مطلوب لطريقتي الشهادة والبصمة (Thumbprint). وهو اختياري لتسجيل الدخول التفاعلي وتسجيل الدخول عبر الجهاز.

إذا احتاج أمر إلى مركز إدارة SharePoint، يمكنك تمرير -TenantAdminUrl. وإذا تركته، تفترض الأوامر الصيغة https://[tenantname]-admin.sharepoint.com حيثما ينطبق ذلك.

الخطوة 1: أكمِل تسجيل التطبيق في Microsoft Entra

تفترض خطوة البدء هذه أن وحدة PnP.PowerShell مثبّتة بالفعل على جهازك. يوفّر PnP أداة مساعدة للإعداد الأول. تعرض صفحة الأمر الخاصة بـ Register-PnPEntraIDAppForInteractiveLogin أقصر صيغة:

Register-PnPEntraIDAppForInteractiveLogin -ApplicationName TestApp -Tenant yourtenant.onmicrosoft.com

تُفتح نافذة متصفح لتسجيل الدخول، ثم ينشئ الأمر التطبيق. كما يطبع معرّف التطبيق الذي ستستخدمه بوصفه -ClientId. أضِف -DeviceLogin إذا تعذّر فتح متصفح على الجهاز. تذكر الصفحة أن هذا يُفعّل تدفق تسجيل دخول الجهاز الذي يدعم المصادقة متعددة العوامل.

انتبهوا إلى الأذونات. في المثال البسيط، يطلب التطبيق للموافقة الأذونات المفوّضة التالية: AllSites.FullControl وGroup.ReadWrite.All وUser.ReadWrite.All وTermStore.ReadWrite.All. ويضيّق المثال الثاني في الصفحة نفسها هذا النطاق عبر -GraphDelegatePermissions "Group.Read.All" و-SharePointDelegatePermissions "AllSites.FullControl".

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

احتفظوا بسجلّ لكل تسجيل تطبيق: اسمه، ومعرّف العميل (client ID)، ومالكه، والأذونات التي يملكها. راجعوا تسجيل التطبيق مرة في السنة، واحذفوه عندما لا يعود أي نص برمجي يستخدمه.

هناك قيدان ينبغي معرفتهما. لا تحدد الصفحة المرجعية الدور المطلوب في Entra لتسجيل التطبيق، لذا اسألوا مسؤول الهوية قبل البدء. كما أن المعامل -SignInAudience يتحكم في أنواع الحسابات التي يدعمها التطبيق، فتأكدوا من توافقه مع المستأجر لديكم.

كيفية الاتصال بـ SharePoint Online باستخدام PnP PowerShell: الخيارات الخمسة

تستند الأمثلة الخمسة جميعها إلى مرجع Connect-PnPOnline. استبدلوا القيم الموجودة بين الأقواس الزاوية.

تسجيل الدخول التفاعلي

Connect-PnPOnline -Url "https://contoso.sharepoint.com" -Interactive -ClientId <appId>

هذا هو الخيار الافتراضي للمستخدم الفرد. تنص الصفحة المرجعية على أنه مصمم لدعم المصادقة متعددة العوامل. أضِف -ForceAuthentication لمسح المصادقة المخزّنة وتسجيل الدخول بحساب مختلف. استخدمه عندما تنتقل بين مستأجر الاختبار ومستأجر الإنتاج.

تسجيل دخول الجهاز

Connect-PnPOnline -Url "https://contoso.sharepoint.com" -DeviceLogin -ClientId <appId>

يُفتح متصفح ويُنسخ الرمز إلى الحافظة. اختاروا هذا الخيار عندما تعمل الصدفة في جلسة عن بُعد لا تعمل فيها النافذة التفاعلية بشكل جيد.

تسجيل الدخول بالشهادة (للتطبيق فقط)

Connect-PnPOnline -Url "https://contoso.sharepoint.com" -ClientId <appId> -Tenant 'contoso.onmicrosoft.com' -Thumbprint <thumbprint>

لا يسجّل أي شخص الدخول. يتصرف التطبيق بمفرده، بالأذونات الممنوحة له على مستوى التطبيق. يمكنكم تمرير -CertificatePath مع -CertificatePassword، أو قيمة -CertificateBase64Encoded، أو -Thumbprint. تتطلب طريقة البصمة وجود الشهادة في مخزن شهادات Windows. هذا هو الخيار المعتمد للنصوص البرمجية غير المراقبة على الخوادم.

الهوية المُدارة

Connect-PnPOnline -Url "https://contoso.sharepoint.com" -ManagedIdentity

تنص الصفحة المرجعية على أن هذا يعمل فقط في البيئات التي تدعم الهويات المُدارة، مثل Azure Functions وRunbooks في Automation وCloud Shell. لا تُخزَّن أي أسرار على الإطلاق. بالنسبة إلى الهوية المعيّنة من المستخدم، أضِفوا أحد المعاملات -UserAssignedManagedIdentityClientId أو -UserAssignedManagedIdentityObjectId أو -UserAssignedManagedIdentityAzureResourceId. معامل -Url اختياري مع هذه الطريقة.

بيانات الاعتماد وأسرار العملاء

لا تزال هناك طريقتان أقدم، وكلتاهما تأتيان مع تحذيرات.

  • -Credentials يقبل كائن PSCredential، مثل (Get-Credential)، أو اسم بيانات اعتماد عامة (Generic Credential) في Windows Credential Manager. تذكر الصفحة المرجعية دعم المصادقة متعددة العوامل لتسجيل الدخول التفاعلي وتسجيل دخول الجهاز، لكنها لا تقدّم هذا الادعاء هنا. اعتبروه خياراً للحسابات التي لا تعرض مطالبة، واختبروه قبل الاعتماد عليه.
  • -ClientSecret مع -ClientId هي الطريقة القديمة لـ ACS. تذكر الوثائق أنه مع هذه الطريقة، "لن تعمل إلا الأوامر التي تتصل بـ SharePoint Online." أما الأوامر التي تستخدم Microsoft Graph فستفشل.

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

مثال: اختيار خيار تسجيل الدخول لأربع مهام

الأرقام والأسماء أدناه من نسج الخيال، وهي للتوضيح فقط.

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

  1. فحوصات مخصصة يجريها مسؤول من جهاز محمول. استخدم -Interactive مع تطبيق يملك أذونات مفوّضة محدودة. يسجّل المسؤول الدخول باستخدام المصادقة متعددة العوامل. ولا يُخزَّن أي شيء.
  2. تنفيذ تنظيف لمرة واحدة على خادم قفز بعيد. استخدم -DeviceLogin. يُكمل المسؤول تسجيل الدخول من هاتف أو جهاز محمول، ثم تبدأ المهمة.
  3. جرد ليلي على خادم Windows. استخدم شهادة مع -Thumbprint. يملك التطبيق أذونات تطبيق للقراءة فقط. الشهادة صالحة لمدة 12 شهرًا، ويضيف الفريق تاريخ التجديد إلى تقويم مشترك.
  4. مهمة أسبوعية في runbook لـ Automation. استخدم -ManagedIdentity. لا توجد شهادة أو سر يحتاج إلى تدوير.

النتيجة: المهمتان 1 و2 فقط تعتمدان على شخص. المهمتان 3 و4 تعملان دون حضور أي شخص، ولا تخزّن أيٌّ منهما كلمة مرور. وإذا سُرق خادم المهمة 3، يُلغي الفريق شهادة واحدة فقط، ولا يضطر إلى إعادة تعيين كلمة مرور أحد المسؤولين.

أيًّا كان الخيار الذي تختاره، احتفظ بعنوان URL الخاص بالموقع في متغير مثل $siteUrl، حتى يتمكن برنامج PowerShell نصي واحد من المرور على كل موقع في قائمة المواقع، واسترجاع ما يلزمه من كل موقع SharePoint، ورفع تقرير. اختبر تشغيل البرنامج النصي على مجموعة موقع واحدة قبل تشغيله عبر المستأجر Microsoft 365 بأكمله.

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

  • نسيان -ClientId. يفشل الاتصال أو يطلب المعرّف. احفظ المعرّف في متغير البيئة ENTRAID_APP_ID على الأجهزة التي تشغّل عليها البرامج النصية بشكل متكرر.
  • استخدام تطبيق واحد بصلاحيات كاملة لكل شيء. يطلب التسجيل الافتراضي الصلاحية AllSites.FullControl وصلاحية الكتابة على المستخدمين والمجموعات. سجّل تطبيقًا ثانيًا للقراءة فقط من أجل التقارير.
  • استخدام سر تطبيق مع الأوامر المعتمدة على Graph. تعمل الطريقة القديمة مع أوامر SharePoint فقط. إذا استدعى أمر Graph، فسيفشل، وقد تكون رسالة الخطأ مربكة.
  • وضع كلمة مرور أو سر داخل ملف البرنامج النصي. كل من يملك صلاحية القراءة للملف يحصل على بيانات الاعتماد. استخدم مخزن الشهادات أو هوية مُدارة.
  • عدم اختبار تسجيل الدخول في البيئة النهائية. قد يعمل البرنامج النصي على جهازك المحمول باستخدام -Interactive ثم يفشل على خادم لا يوجد عليه متصفح. اختبر باستخدام الطريقة التي ستستخدمها المهمة فعليًا.
  • البقاء مسجّلًا للدخول إلى المستأجر الخطأ. استخدم -ForceAuthentication عند تبديل الحسابات، واطبع تفاصيل الاتصال في بداية كل برنامج نصي.

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

ابدأ بما لديك بالفعل. تغطي وحدة PnP وحزمة Microsoft Graph PowerShell SDK معظم البرمجة النصية للمسؤولين. تشغّل Azure Automation البرامج النصية وفق جدول زمني باستخدام هوية مُدارة، ويعرض مركز إدارة SharePoint المواقع والإعدادات دون الحاجة إلى كتابة أي شيفرة. أما الأسرار، فمخزن الشهادات أو Key Vault أكثر أمانًا من ملف البرنامج النصي.

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

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

سجّل تطبيقًا واحدًا اليوم، بأصغر مجموعة من الأذونات المفوّضة التي تحتاجها برامجك النصية. ثم تحقّق من قدرتك على الاتصال بـ SharePoint Online باستخدام PnP PowerShell مع -Interactive، ودوّن خيار تسجيل الدخول الذي سيستخدمه كل مهمة مجدولة لديك.

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

Entities in this article

PnP PowerShell Microsoft Entra PowerShell SharePoint

Related articles

RSS