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 פירושו שימוש ב-Graph SDK לקריאה וניהול של אתרים משורת הפקודה. מתקינים מודול אחד, מתחברים עם Connect-MgGraph והיקף הרשאות, ומריצים cmdlets כגון Get-MgSite. המדריך מיועד לאדמיני SharePoint שכבר מכירים את מרכז הניהול של SharePoint ורוצים דרך בטוחה להתחיל עם סקריפטים. תתקינו את ה-SDK, תתחברו עם ההיקף הקטן ביותר שעובד, תציגו אתרים, ותלמדו לקרוא את השגיאות הראשונות שמופיעות.

עיקרי הדברים

  • Microsoft Graph PowerShell הוא SDK העוטף את ממשקי Graph API, ולכן כל פקודה דורשת קודם התחברות עם Connect-MgGraph והיקפי הרשאות נכונים.
  • Get-MgSite מציג אתרי SharePoint ודורש לפחות את ההרשאה Sites.Read.All, שהיא האפשרות עם מינימום ההרשאות שמיקרוסופט מתעדת עבורה.
  • Get-MgContext מציג אילו היקפים מוחזקים בהפעלה הנוכחית שלכם, וזו הדרך המהירה ביותר להסביר שגיאת 403 Forbidden.
  • Find-MgGraphCommand ו-Find-MgGraphPermission מראים איזו הרשאה נדרשת לפקודה, כך שלא תצטרכו לנחש שמות היקפים.
  • התחברות מואצלת מתאימה לאדם שיושב מול המקלדת, ואילו התחברות לאפליקציה בלבד עם אישור או זהות מנוהלת מתאימה למשימות לא מלוות.

מהו Microsoft Graph PowerShell, ומדוע אדמינים משתמשים בו

Microsoft Graph הוא ה-API היחיד לנתוני Microsoft 365: משתמשים, קבוצות, קבצים, דואר, Teams ואתרי SharePoint. ערכת ה-PowerShell SDK של Microsoft Graph עוטפת את ה-Graph API בפקודות cmdlet. אינכם צריכים לכתוב קריאות רשת לכל נקודת קצה. מריצים Get-MgSite ומקבלים בחזרה אובייקטים של אתרים.

לאדמין של SharePoint יש שלושה יתרונות מעשיים.

  • כלי אחד לכל השירותים. אותה התחברות עובדת לאתרים, למשתמשים ולקבוצות. סקריפט יכול להציג אתרים ואז לחפש את הבעלים שלהם.
  • מודל הרשאות שניתן לקרוא. כל קריאה דורשת הרשאות בשם, שנקראות היקפים. אתם יכולים לראות אילו היקפים מוחזקים בהפעלה ומדוע קריאה נדחתה.
  • מעבר ממודולים ישנים. הרשומה על Microsoft Graph PowerShell מתארת אותו כמחליף למודולים שהופסקו, Azure AD PowerShell ו-MSOnline.

מודול PnP PowerShell הקהילתי הוא הבחירה הנפוצה האחרת לסקריפטים של SharePoint, והתיעוד שלו מציין שחלק מה-cmdlets מתקשרים גם עם Graph. Graph PowerShell אינו מחליף כל כלי של אדמין SharePoint. הוא מכסה את מה שה-Graph API חושף. חלק מההגדרות של הדייר עדיין נמצאות במרכז הניהול של SharePoint או במודולים אחרים. התייחסו ל-Graph ככלי אחד בערכת הכלים שלכם, לא ככלי היחיד.

שלב 1: התקנת ה-SDK והתחברות

מדריך ההתקנה ממליץ על PowerShell 7 ומעלה בכל הפלטפורמות. Windows PowerShell דורש גרסה 5.1 ומעלה, .NET Framework 4.7.2 ומעלה, ומדיניות הרצה (execution policy) של 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 תומך בשני סוגי גישה: מואצלת (delegated) ו-app-only. גישה מואצלת פועלת בשם משתמש מחובר, וההרשאות שלה הן scopes. גישה app-only פועלת ללא משתמש, באמצעות אישור, סוד לקוח או managed identity.

לפקודות הראשונות שלכם, השתמשו בגישה מואצלת ובקשו scope אחד לקריאה בלבד:

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

יפתח חלון דפדפן להתחברות. כדי לבדוק מה קיבלתם, הריצו Get-MgContext | Select -ExpandProperty Scopes. Microsoft מתעדת את Get-MgContext כפקודה שמחזירה את פרטי הסשן הנוכחי, כגון client ID, tenant ID, scopes וסוג האימות. בסיום הריצו Disconnect-MgGraph. לפי הדף, נשארים מחוברים עד שמנתקים, מאחר שהטוקנים נשמרים במטמון תחת הscope ברירת המחדל 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 הוא ערך ה-id מתוצאה קודמת. הוא בנוי משם מארח, ואחריו שני GUIDs, מופרדים בפסיקים.

כל אחת מהפקודות האלה מתאימה לקריאת REST. Get-MgSite -All קורא את אוסף האתרים בכתובת https://graph.microsoft.com/v1.0/sites, הכתובת שתיעוד ה-REST מציג לרשימת אתרים, ו--Filter, -Search ו--Property הופכים לאפשרויות שאילתה בכתובת הזו. ה-SDK מקבל את הטוקנים דרך Microsoft Authentication Library (MSAL). אם חסרה פקודה לקריאה שאתם צריכים, Invoke-MgGraphRequest יכולה לקרוא ל-URI ישירות. עמוד פתרון הבעיות משתמש בה כדי לבדוק את ה-URI שמאחורי שגיאת Bad request.

יש שתי מגבלות שחשוב להכיר. ראשית, נקודת הקצה של הרשימה ב-Graph מחזירה אתרים בגיאוגרפיה ברירת המחדל של הארגון. לכל הגיאוגרפיות, Microsoft מפנה ל-API בשם getAllSites, שמתאים לפקודה Get-MgAllSite. שנית, ממשק החיפוש יכול למיין רק לפי createdDateTime.

אילו הרשאות אתם צריכים? Microsoft Graph PowerShell וה-scopes של SharePoint

הרשאות Microsoft Graph הן החלק שמפתיע משתמשים חדשים. לקריאת אתרים, דף ה-cmdlet מציין ש-Sites.Read.All היא הבחירה בעלת ההרשאות המינימליות, ו-Sites.ReadWrite.All היא הבחירה בעלת הרשאות רחבות יותר. בחרו בראשונה, אלא אם סקריפט חייב לשנות משהו.

אין צורך לזכור שמות היקפים. יש שתי פקודות עזר שמבצעות את החיפוש:

  • Find-MgGraphCommand מציג אילו הרשאות נדרשות ל-cmdlet או ל-API. דף פתרון הבעיות משתמש ב-Find-MgGraphCommand -command New-MgServicePrincipal | Select -First 1 -ExpandProperty Permissions כדוגמה.
  • Find-MgGraphPermission מאתר הרשאות לפי תחום או שם, למשל Find-MgGraphPermission application. הפלט מציג את הסוג (מואצלות או של אפליקציה), האם נדרשת הסכמה של מנהל, ותיאור.

שימו לב לנקודת אי-התאמה אחת בתיעוד. דף ה-REST לקבלת רשימת אתרים מציג רק הרשאות של אפליקציה לקריאה הזו, ומסמן גישה מואצלת כלא נתמכת. דף ה-cmdlet של Get-MgSite מציין את שתיהן. בדקו את הקריאה שלכם בדייר שאינו ייצור, וקראו את טקסט השגיאה אם היא נכשלת. אל תניחו שדף ה-cmdlet מדויק לכל קריאה.

לעבודות ללא השגחה נדרשת גישה של אפליקציה בלבד. זה אומר רישום אפליקציה ב-Microsoft Entra, הרשאות של אפליקציה (הנקראות גם הרשאות API) והסכמת מנהל. דף פתרון הבעיות קובע שהרשאות של אפליקציה דורשות הסכמת מנהל. השתמשו באישור (certificate) או בזהות מנוהלת (managed identity), ולא בסיסמה שנכתבת ידנית.

דוגמה: מלאי אתרים לא פעילים בחמש פקודות

המספרים בדוגמה זו בדויים.

מנהל רוצה רשימה ראשונית של אתרים שאיש לא שינה אותם במשך שנה.

  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 והשוו את ההיקפים למה שה-cmdlet דורש.
  • בקשת היקפי כתיבה לעבודת קריאה. Sites.ReadWrite.All חורגת ממה שדוח צריך. התחילו עם Sites.Read.All.
  • שכחת -All. בלעדיו, רשימה יכולה להיראות מלאה כשהיא מכילה רק את העמוד הראשון.
  • בלבול בין גרסאות המודול. Microsoft ממליצה להשתמש במודול v1.0 לסקריפטים. מודול ה-beta נמצא בתצוגה מקדימה ועשוי להשתנות ללא הודעה מוקדמת.
  • דילוג על העדכון. גרסה ישנה של Microsoft.Graph היא סיבה מתועדת להתנגשויות גרסאות. הריצו Update-Module Microsoft.Graph לפני שתחפשו סיבות אחרות.
  • נשארים מחוברים על מכונה משותפת. האסימונים נשמרים במטמון. הריצו Disconnect-MgGraph כשאתם מסיימים.

איך תוכנה יכולה לעזור

רוב הצרכים הראשונים מכוסים בכלים שכבר יש לכם. ערכת ה-SDK של Microsoft Graph PowerShell מטפלת בקריאות ובייצוא. מרכז הניהול של SharePoint מציג רשימות אתרים והגדרות ללא קוד. Excel או Power BI הופכים קובץ CSV לדוח שבעלי האתרים יכולים לקרוא. להרצות מתוזמנות, Azure Automation יכולה להריץ סקריפט עם זהות מנוהלת.

חפשו פערים רק אחרי החודש הראשון. אם אתם ממשיכים לבנות מחדש את אותו מלאי ביד, סקריפט שמור עם תיקיית פלט קבועה ותזכורת חודשית בדרך כלל מספיקים.

הצעד הבא

התקינו את ה-SDK, הריצו Connect-MgGraph -Scopes "Sites.Read.All" וייצאו את הפלט של Get-MgSite -All לקובץ CSV עוד היום. לאחר מכן השתמשו ב-Find-MgGraphCommand עבור ה-cmdlet הבא שלכם כדי ללמוד מהי ההרשאה הנדרשת, לפני שתריצו משימות SharePoint עם Microsoft Graph PowerShell בסביבת ייצור.

עקבו אחרי הפודקאסטSpotify

Entities in this article

Microsoft Graph PowerShell Microsoft Graph SharePoint Microsoft Graph permissions

Related articles

RSS