בדף הזה מוסבר איך להגדיר אפליקציה של צד שלישי לפני שיוצרים את מאגר הנתונים של Microsoft 365.
הגדרת אימות והרשאות
המחבר של Microsoft 365 נכנס כמשתמש הקצה באמצעות תהליך קוד ההרשאה של OAuth 2.0 מול פלטפורמת הזהויות של מיקרוסופט. כל ההרשאות של Microsoft Graph מועברות, כך שהמחבר יכול לגשת רק לנתונים שהמשתמש המחובר כבר יכול לגשת אליהם. אפשר להגדיר אימות באחת משתי דרכים:
- OAuth בניהולGoogle (OAuth 2.0 (Google Managed), ברירת המחדל): המחבר משתמש באפליקציית Microsoft Entra עם ריבוי דיירים (multitenancy) ש-Google רושמת ומנהלת. לא צריך לרשום אפליקציה או להזין מזהה דייר (Tenant), מזהה לקוח או סוד לקוח. שימוש ב-OAuth בניהול Google.
- אפליקציה משלכם (OAuth 2.0 (אפליקציה משלכם)): אתם רושמים אפליקציה משלכם ב-Microsoft Entra, נותנים לה את ההרשאות של Microsoft Graph לפעולות שאתם רוצים להפעיל, ומזינים את מזהה הדייר, מזהה הלקוח וסוד הלקוח שלה ב-Gemini Enterprise. בחרו באפשרות הזו אם הארגון שלכם צריך לשלוט באפליקציה ובהרשאות שלה באופן ישיר, אם אתם צריכים תעבורת נתונים יוצאת (egress) של כתובת IP סטטית או אם הדייר (tenant) שלכם נמצא בענן של ממשלת ארה"ב. איך רושמים אפליקציה ב-Microsoft Entra
שימוש ב-OAuth בניהול של Google
אם משתמשים ב-OAuth 2.0 (Google Managed), לא צריך ליצור שום דבר ב-Microsoft Entra לפני שיוצרים את מאגר הנתונים. כשהמשתמש מאשר את המחבר, מיקרוסופט מבקשת ממנו להסכים להרשאות של Microsoft Graph שנדרשות לפעולות שהופעלו. הרשימה המלאה מופיעה במאמר הגדרת הרשאות ל-API של מיקרוסופט.
כדי להעניק חלק מההרשאות האלה, וכדי להסכים לחלק מכללי המדיניות של הדייר, נדרשת הסכמה של אדמין ב-Microsoft Entra בשם הארגון. אם למשתמשים מופיעה ההודעה נדרש אישור אדמין כשהם מאשרים את המחבר, אדמין צריך לתת הסכמה ברמת הדייר לאפליקציה שמנוהלת על ידי Google. מידע נוסף זמין במאמר Grant tenant-wide admin consent to an application במסמכי התיעוד של Microsoft.
כשמשתמשים ב-OAuth בניהול Google, חשוב לזכור את הדברים הבאים:
- האפליקציה שמנוהלת על ידי Googleרשומה בענן המסחרי של מיקרוסופט, לכן צריך להשאיר את Microsoft 365 Environment Type מוגדר כ-Standard. בדיירים ב-GCC High או ב-DoD, צריך להשתמש ב-OAuth 2.0 (Bring Your Own App).
- אי אפשר להשתמש בתעבורת נתונים יוצאת עם כתובת IP סטטית, כי האפליקציה המשותפת לא יכולה להכיל רשימת היתרים של כתובות IP לכל לקוח.
שאר החלק הזה רלוונטי רק ל-OAuth 2.0 (אפליקציה משלך).
רישום אפליקציית Microsoft Entra למחבר של Microsoft 365
כדי לרשום את Gemini Enterprise כאפליקציית OAuth 2.0 ב-Microsoft Entra:
עוברים אל מרכז הניהול של Microsoft Entra.
בתפריט הניווט, מרחיבים את Entra ID ובוחרים באפשרות App registrations.
בדף App registrations, לוחצים על New registration.
בדף Register an application, מבצעים את הפעולות הבאות:
- בשדה שם, מזינים שם לאפליקציה.
- בקטע סוגי חשבונות נתמכים, בוחרים באפשרות חשבונות בספריית הארגון בלבד.
- בקטע Redirect URI:
- ברשימת הפלטפורמות, בוחרים באפשרות אינטרנט.
- בשדה ה-URI להפניה אוטומטית, מזינים את הערך
https://vertexaisearch.cloud.google.com/oauth-redirect.
- לוחצים על הרשמה. Microsoft Entra יוצרת את האפליקציה ומציגה את דף הסקירה הכללית שלה.
קבלת מזהה הלקוח וסוד הלקוח
כדי לקבל את מזהה הלקוח:
- בתפריט הניווט של האפליקציה, לוחצים על סקירה כללית.
- מעתיקים את מה שכתוב בשדה Application (client) ID.
כדי לקבל את סוד הלקוח של האפליקציה:
- בתפריט הניווט של האפליקציה, בוחרים באפשרות Certificates & secrets.
- לוחצים על סוד לקוח חדש.
- בחלונית של סוד הלקוח:
- בשדה Description, מזינים תיאור של הסוד.
- ברשימה תוקף, בוחרים את משך הזמן עד שהתוקף יפוג.
- לוחצים על הוספה.
- מעתיקים את סוד הלקוח מהעמודה Value.
איך מקבלים את מזהה הדייר (tenant)
מזהה הדייר מופיע בתיבה Tenant ID בדף הסקירה הכללית במרכז הניהול של Microsoft Entra.
הגדרת הרשאות ל-API של מיקרוסופט
אם אתם משתמשים ב-OAuth 2.0 (אפליקציה משלכם), תנו לאפליקציה את ההרשאות המוענקות של Microsoft Graph לפעולות שאתם רוצים להפעיל. אם אתם משתמשים ב-OAuth 2.0 (בניהול Google), אתם לא צריכים להוסיף את ההרשאות האלה בעצמכם. המשתמשים מתבקשים להביע הסכמה להרשאות האלה כשהם מאשרים את המחבר.
ההרשאות שנדרשות לכל פעולה מפורטות בעמודה Required permissions בטבלאות של הפעולות הנתמכות. כל חיבור צריך גם User.Read ו-offline_access.
כדי להגדיר את הרשאות ה-API הנדרשות באפליקציה שלכם, מבצעים את הפעולות הבאות:
בדף האפליקציה, בוחרים באפשרות API permissions (הרשאות API).
לוחצים על הוספת הרשאה.
בדף Request API permissions, בוחרים באפשרות Microsoft Graph ואז באפשרות Delegated permissions.
מחפשים ובוחרים את
User.Read,offline_accessואת ההרשאות שמופיעות לכל פעולה שרוצים להפעיל.לוחצים על הוספת הרשאות.
עננים ממשלתיים וריבוניים
אם הדייר לא נמצא בענן הרגיל של Microsoft, צריך להגדיר את שני הפרטים הבאים כשיוצרים את מאגר הנתונים. כדי להיכנס דרך US Government, צריך להשתמש ב-OAuth 2.0 (Bring Your Own App) עם אפליקציה שרשומה בענן הזה.
סוג הסביבה של Microsoft 365, בקטע הגדרות אימות, בוחרים את נקודת הקצה לכניסה: רגיל משתמש ב-
login.microsoftonline.comוממשלת ארה"ב משתמש ב-login.microsoftonline.us.סביבת הענן של Microsoft 365, בקטע אפשרויות מתקדמות, בוחרת את נקודת הקצה של Microsoft Graph: Standard / GCC משתמשת ב-
https://graph.microsoft.com, GCC High משתמשת ב-https://graph.microsoft.usו-DoD משתמשת ב-https://dod-graph.microsoft.us.
פתרון בעיות
בקטע הזה מתוארות שגיאות שיכולות להופיע אחרי שמגדירים את האפליקציה של Microsoft Entra, ואיך לפתור אותן.
הפעולות נכשלות עם שגיאת HTTP 403
בדרך כלל, פעולה שמחזירה את השגיאה HTTP 403 היא פעולה שחסרה בה הרשאה. צריך לוודא שהתקבלה הסכמה להרשאה שהפעולה דורשת, שהתקבלה הסכמת אדמין במקרים שבהם היא נדרשת, ושהחיבור קיבל הרשאה מחדש אחרי שהפעולה הופעלה. אם אתם משתמשים ב-OAuth 2.0 (Bring Your Own App), ודאו שרישום האפליקציה ב-Microsoft Entra מעניק את ההרשאה. טוקן רענון קיים כולל רק את ההיקפים שהמשתמש הסכים להם כשהטוקן הונפק.
החיפוש באימייל מחזיר MailboxNotEnabledForRESTAPI
השגיאה הזו מציינת שאי אפשר להגיע לתיבת הדואר דרך Microsoft Graph. היא מתרחשת כשתיבת הדואר מתארחת באופן מקומי בפריסת Exchange היברידית, כשתיבת הדואר לא פעילה או נמחקה עם יכולת שחזור, או כשיש חוסר התאמה בין הדייר לספרייה. כדי לפתור את הבעיה, צריך לוודא שתיבת הדואר מאוחסנת ב-Exchange Online. למידע נוסף, קראו את המאמר How to fix MailboxNotEnabledForRESTAPI (איך לפתור את הבעיה MailboxNotEnabledForRESTAPI) בתיעוד של מיקרוסופט.