דף זה תורגם על ידי Cloud Translation API.

סקירה כללית על Admin Settings API

ה-Admin Settings API מאפשר לאדמינים בדומיינים של Google Workspace לאחזר ולשנות את ההגדרות של הדומיינים שלהם בצורה של פידים של Google Data API.

הגדרות הדומיין האלה כוללות הרבה מהתכונות הזמינות במסוף Google Workspace Admin. השימושים בממשק ה-API הזה כוללים יצירת לוח בקרה בהתאמה אישית או שילוב דומיינים של Google Workspace בסביבה קיימת מדור קודם.

ה-Admin Settings API מטמיע את הפרוטוקול Google Data API. Google Data API תואם למודל הפרסום והעריכה של פרוטוקול Atom Publishing Protocol (AtomPub). בקשות ה-HTTP של AtomPub משתמשות בגישת העיצוב לייצוג קבוצה (RESTful) עבור שירותי אינטרנט. למידע נוסף, אפשר לעיין במדריך למפתחים של Google Data.

Audience

המסמך מיועד למפתחים שרוצים לכתוב אפליקציות לקוח שיכולות לשנות ולאחזר מידע על דומיינים של Google Workspace. הוא מספק דוגמאות לאינטראקציות בסיסיות של Admin Settings API באמצעות XML ו-HTTP גולמי.

המסמך הזה מבוסס על ההנחה שאתם מבינים את הרעיונות הכלליים שעומדים אחרי פרוטוקול Google Data API ומכירים את מסוף Google Workspace Admin. מידע נוסף על מסוף Admin זמין במאמר שימוש במסוף Admin.

תחילת העבודה

יצירת חשבון

Admin Settings API מופעל בחשבונות Google Workspace. לשם כך, צריך להירשם לחשבון Google Workspace. השירות 'הגדרות אדמין' משתמש בחשבונות Google, אז אם כבר יש לך חשבון בדומיין Google Workspace, הכול מוכן.

מידע על סוגי העדכונים של Admin Settings API

ממשק ה-API של הגדרות מנהל המערכת מאפשר לך לנהל את הקטגוריות הבאות של הגדרות הדומיין:

הגדרות כניסה יחידה

כניסה יחידה (SSO) מבוססת SAML מאפשרת למשתמשים להיכנס עם שם המשתמש והסיסמה האלה גם בשירותים שמתארחים ב-Google Workspace וגם בשירותים אחרים בארגון. באופן ספציפי, כשמשתמשים ב-SSO, אפליקציית אינטרנט מתארחת, כמו Google Workspace, מפנה משתמשים לספק הזהויות של הארגון כדי לאמת את המשתמשים כשהם מתחברים. מידע מפורט זמין במאמר הסבר על SSO על בסיס SAML ל-Google Workspace.

כדי להגדיר SSO, צריך להזין את המידע הדרוש לשירות Google Workspace כדי לתקשר עם ספק הזהויות שבו שמורים פרטי ההתחברות של המשתמשים. אפשר גם להגדיר את הקישורים שאליהם המשתמשים אמורים להתחבר כדי להתחבר, לצאת מהמערכת ולשנות את הסיסמאות שלהם. ב-Admin Settings API אפשר לעדכן ולאחזר את ההגדרות האלה באופן פרוגרמטי. Google משתמשת במפתח הציבורי שנוצר כדי לאמת את בקשת ה-SSO עם ספק הזהויות שלך, ושתגובת ה-SAML של המפתח הפרטי לא שונתה במהלך שידור הרשת.

לסיכום קצר של השימוש ב-API בהגדרות ה-SSO, יש לקבל את אישור המפתח הציבורי מספק הזהויות שלך, לרשום את המפתח הציבורי ב-Google ולקבוע את הגדרות שאילתות ה-SSO המבוססות על SAML. כדי לאתר הודעות שגיאה, ראו פתרון בעיות בנושא כניסה יחידה:

יוצרים את המפתחות – בעזרת ספק הזהויות, יוצרים סדרה של מפתחות ציבוריים ופרטיים, באמצעות האלגוריתמים DSA או RSA. המפתח הציבורי נמצא באישור בפורמט X.509. למידע נוסף על מפתחות לחתימה יחידה המבוססים על SAML, אפשר לעיין במאמר יצירת מפתחות ואישורים לשירות כניסה יחידה ב-Google Workspace.
הרשמה באמצעות Google – יש להשתמש בהגדרות כניסה יחידה של Admin Settings API כדי לרשום את אישור המפתח הציבורי שלך ב-Google.
קביעת הגדרות SSO – יש להשתמש בהגדרות הכניסה היחידה של Admin Settings API כדי לקבוע את ההגדרות שישמשו בתקשורת עם שרתי ספק הזהויות של הדומיין.

שער וניתוב

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

פעולות ניתוב האימייל מאפשרות לאדמינים לקבוע את ההגדרות של ניתוב האימייל ברמת הדומיין. היא דומה לפונקציונליות ניתוב האימייל בהגדרות Gmail של מסוף הניהול. מידע נוסף מפורט במאמר ניתוב אימייל ובתצורה של העברת אימייל כפולה.

דוגמה לבקשה ולתגובה ב-XML של ממשק ה-API להגדרות מנהל המערכת

מסמך זה מספק דוגמאות קוד של בקשות ותגובות בסיסיות של ממשק API לניהול, באמצעות XML ו-HTTP גולמי. דוגמה זו לשפת ברירת המחדל של הדומיין מציגה את התחביר המלא של XML ו-HTTP עבור גוף הבקשה ורשומת התגובה, המשותפת לכל פעולה:

כדי לשנות את הגדרת שער האימייל היוצא של הדומיין, יש לשלוח HTTP PUT לכתובת ה-URL של פיד השער:

https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/email/gateway

שפת ברירת המחדל PUT לבקשת AtomPub entry XML היא:

<atom:entry xmlns:atom='http://www.w3.org/2005/Atom'
  xmlns:apps='http://schemas.google.com/apps/2006'>
  <apps:property name='smartHost' value='smtp.out.domain.com' />
  <apps:property name='smtpMode' value='SMTP' />
</atom:entry>

למעט המאפיינים והערכים הספציפיים לפעולה, רכיבי atom:property מייצגים צמד מפתח/ערך אחד שמכיל מידע לגבי נכס שרוצים לאחזר או לעדכן. הם נפוצים בכל גופי הבקשות של Admin Settings API.

הרכיב 'תגובת ברירת מחדל לשפה' entry מחזיר את המאפיינים smartHost ו-smtpMode עם תחביר XML המשותף לכל גופי התגובה של ממשק ה-API להגדרות הניהול:

<?xml version='1.0' encoding='UTF-8'?>
<entry xmlns='http://www.w3.org/2005/Atom' xmlns:apps='http://schemas.google.com/apps/2006'>
<id>https://apps-apis.google.com/a/feeds/domain/2.0/domainName/email/gateway</id>
<updated>2008-12-17T23:59:23.887Z</updated>
<link rel='self' type='application/atom+xml' href='https://apps-apis.google.com/a/feeds/domain/
  2.0/domainName/email/gateway'/>
<link rel='edit' type='application/atom+xml' href='https://apps-apis.google.com/a/feeds/domain/
  2.0/domainName/email/gateway'/>
<apps:property name='smartHost' value='smtp.out.domain.com' />
<apps:property name='smtpMode' value='SMTP' />
</entry>

ניהול ההגדרות של כניסה יחידה (SSO)

הפיצ'ר 'כניסה יחידה' ב-Google Workspace מאפשר למשתמשים להתחבר לכמה שירותים, כל עוד הם צריכים להזין את פרטי הכניסה והסיסמה פעם אחת בלבד. הסיסמה הזו שמורה על ידי ספק הזהויות של הדומיין, ולא על ידי Google Workspace. מידע נוסף זמין בדף ה-SSO במרכז העזרה. הקטעים הבאים מדגימים את פורמט ה-XML המשמש להגדרות כניסה יחידה.

מתבצע אחזור הגדרות של כניסה יחידה

כדי לאחזר הגדרות של כניסה יחידה, יש לשלוח HTTP GET לכתובת ה-URL של הפיד הכללי לSSO. יש לכלול כותרת Authorization כפי שמתואר באימות לשירות ההגדרות של האדמין. בהודעות שגיאה, כדאי לקרוא את המאמר פתרון בעיות בנושא SSO:

https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/sso/general

פעולה זו לא מכילה פרמטרים בגוף הבקשה.

תגובה מוצלחת מחזירה קוד סטטוס 200 OK של HTTP, בנוסף לפיד AtomPub עם הגדרות ה-SSO בדומיין.

XML של תגובת GET מחזיר את המאפיינים samlSignonUri, samlLogoutUri, changePasswordUri, enableSSO, ssoWhitelist ו-useDomainSpecificIssuer:

<?xml version='1.0' encoding='UTF-8'?>
<entry xmlns='http://www.w3.org/2005/Atom' xmlns:apps='http://schemas.google.com/apps/2006'>
<apps:property name='samlSignonUri' value='http://www.example.com/sso/signon'/>
...
<apps:property name='samlLogoutUri' value='http://www.example.com/sso/logout'/>
<apps:property name='changePasswordUri' value='http://www.example.com/sso/changepassword'/>
<apps:property name='enableSSO' value='true'/>
<apps:property name='ssoWhitelist' value='CIDR formatted IP address'/>
<apps:property name='useDomainSpecificIssuer' value='false'/>
</entry>

המאפיינים כוללים:

SamlSignonUri: כתובת ה-URL של ספק הזהויות שאליו Google Workspace שולח את בקשת ה-SAML לאימות משתמש.
samlLogoutUri: הכתובת שאליה המשתמשים יועברו אחרי שהם מתנתקים מאפליקציית האינטרנט.
שינוי הסיסמה: הכתובת שאליה המשתמשים יועברו כשהם ירצו לשנות את סיסמת ה-SSO שלהם לאפליקציית האינטרנט.
EnableSSO: הפעלה של SSO המבוסס על SAML עבור הדומיין הזה. אם קבעת בעבר הגדרות SSO, ושינית את ההגדרה של enableSSO ל-enableSSO=false, ההגדרות שהזנת עדיין נשמרות.
רשימת ההיתרים: ssoWhitelist הוא כתובת IP של מסכת רשת בפורמט CIDR (Classless Inter-Domain Routing). רשימת ההיתרים קובעת אילו משתמשים מתחברים באמצעות כניסה יחידה ומשתמשים שמתחברים באמצעות דף האימות של חשבון Google Workspace. אם לא מוגדרות מסכות, כל המשתמשים יתחברו באמצעות SSO. מידע נוסף זמין במאמר איך פועלות מסכות רשת.
useDomainספציפי למנפיק: אפשר להשתמש ב-SAML כדי לספק מנפיק לספק הזהויות בדומיין. למרות שהיא אינה נחוצה למרבית פריסות ה-SSO, התכונה הזו שימושית בחברות גדולות המשתמשות בספק זהויות אחד כדי לאמת ארגון שלם עם תת-דומיינים מרובים. מנפיק הדומיין הספציפי קובע איזה תת-דומיין ישויך לבקשה. מידע נוסף זמין במאמר איך פועל הרכיב המנפיק בבקשת SAML?

אם הבקשה תיכשל מסיבה כלשהי, יוחזר קוד סטטוס שונה. מידע נוסף על קודי הסטטוס של Google Data API זמין במאמר קודי מצב של HTTP.

עדכון הגדרות כניסה יחידה

כדי לעדכן את הגדרות ה-SSO של הדומיין, קודם צריך לאחזר את הגדרות ה-SSO באמצעות הפעולה אחזור הגדרות כניסה יחידה, לשנות אותה ולאחר מכן לשלוח בקשת PUT לכתובת ה-URL של פיד ה-SSO. עליך לוודא שהערך <id> נמצא ברשומה המעודכנת שתואמת בדיוק ל-<id> של הרשומה הקיימת. יש לכלול כותרת Authorization כפי שמתואר באימות לשירות API של הגדרות האדמין. כאן תוכלו לקרוא הסבר על הודעות שגיאה.

בעת עדכון הגדרות כניסה יחידה, יש לשלוח קוד PUT לכתובת ה-URL של הפיד הכללי לכניסה יחידה:

https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/sso/general

גוף ה-XML של הבקשה PUT הוא:

<atom:entry xmlns:atom='http://www.w3.org/2005/Atom' xmlns:apps='http://schemas.google.com/apps/2006'>
<apps:property name='enableSSO' value='false' />
<apps:property name='samlSignonUri' value='http://www.example.com/sso/signon' />
<apps:property name='samlLogoutUri' value='http://www.example.com/sso/logout' />
<apps:property name='changePasswordUri' value='http://www.example.com/sso/changepassword' />
<apps:property name='ssoWhitelist' value='127.0.0.1/32' />
<apps:property name='useDomainSpecificIssuer' value='false'/>
</atom:entry>

תגובה מוצלחת מחזירה קוד סטטוס 200 OK של HTTP, יחד עם פיד AtomPub עם הגדרות ה-SSO.

XML של תגובת PUT:

<?xml version='1.0' encoding='UTF-8'?>
<entry xmlns='http://www.w3.org/2005/Atom' xmlns:apps='http://schemas.google.com/apps/2006'>
...
<apps:property name='samlSignonUri' value='http://www.example.com/sso/signon'/>
<apps:property name='samlLogoutUri' value='http://www.example.com/sso/logout'/>
<apps:property name='changePasswordUri' value='http://www.example.com/sso/changepassword'/>
<apps:property name='enableSSO' value='false'/>
<apps:property name='ssoWhitelist' value='127.0.0.1/32'/>
<apps:property name='useDomainSpecificIssuer' value='false'/>
</entry>

אחזור של חתימת הכניסה היחידה

כדי לאחזר את חתימת הכניסה היחידה, יש לשלוח HTTP GET לכתובת ה-URL של פיד החתימה של SSO, ולכלול כותרת Authorization כפי שמתואר באימות לשירות ההגדרות של האדמין. בהודעות שגיאה, כדאי לקרוא את המאמר פתרון בעיות בנושא SSO:

https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/sso/signingkey

פעולה זו לא מכילה פרמטרים בגוף הבקשה.

תגובה מוצלחת מחזירה את קוד הסטטוס 200 OK HTTP, יחד עם פיד AtomPub עם מפתח החתימה.

XML התגובה של GET מחזיר את המאפיין signingKey:

<?xml version='1.0' encoding='UTF-8'?>
<entry xmlns='http://www.w3.org/2005/Atom' xmlns:apps='http://schemas.google.com/apps/2006'>
...
<apps:property name='signingKey' value='yourBase64EncodedPublicKey'/>
</entry>

עדכון חתימת הכניסה היחידה

כדי לעדכן חתימת SSO של דומיין, קודם צריך לאחזר את חתימת החתימה באמצעות הפעולה של אחזור חתימת כניסה יחידה, לשנות אותה ולאחר מכן לשלוח בקשת PUT לכתובת ה-URL של פיד חתימת ה-SSO. עליך לוודא שהערך <id> נמצא ברשומה המעודכנת שתואמת בדיוק ל-<id> של הרשומה הקיימת. למידע נוסף על מפתחות לחתימה יחידה המבוססים על SAML, אפשר לעיין במאמר יצירת מפתחות ואישורים לשירות כניסה יחידה ב-Google Workspace.

כשמעדכנים את חתימת הכניסה היחידה, יש לשלוח HTTP PUT לכתובת ה-URL של פיד חתימת המפתח:

https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/sso/signingkey

XML של הבקשה PUT הוא:

<atom:entry xmlns:atom='http://www.w3.org/2005/Atom' xmlns:apps="http://schemas.google.com/apps/2006">
<apps:property name='signingKey' value='yourBase64EncodedPublicKey'/>
</atom:entry>

ניהול שער וניתוב אימייל

הקטע 'שער דוא"ל יוצא' מראה את האופן שבו ממשק ה-API של הגדרות הניהול תומך בניתוב דואר יוצא ממשתמשים בדומיין שלך. הקטע 'ניתוב אימייל' מראה כיצד לנתב הודעות לשרת דואר אחר.

מתבצע אחזור הגדרות של שער אימייל יוצא

כדי לאחזר הגדרות של שער אימייל יוצא, יש לשלוח HTTP GET לכתובת ה-URL של פיד השער, ולכלול כותרת Authorization כפי שמתואר באימות לשירות הגדרות האדמין:

https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/email/gateway

פעולה זו לא מכילה פרמטרים בגוף הבקשה.

תגובה מוצלחת מחזירה קוד סטטוס של HTTP 200 OK, יחד עם עדכון AtomPub עם פרטי הסטטוס של שער האימייל.

התגובה GET מחזירה את המאפיינים smartHost ו-smtpMode. מידע נוסף על הנכסים האלה זמין במאמר עדכון ההגדרות של שער האימייל היוצא.

דוגמה לתגובה אפשרית:

<?xml version='1.0' encoding='UTF-8'?>
<entry xmlns='http://www.w3.org/2005/Atom' xmlns:apps='http://schemas.google.com/apps/2006'>
...
<apps:property name='smartHost' value='smtpout.domain.com'/>
<apps:property name='smtpMode' value='SMTP'/>
</entry>

המערכת מעדכנת הגדרות של שער אימייל יוצא

כדי לעדכן את ההגדרה של שער אימייל יוצא בדומיין, יש לשלוח בקשת HTTP PUT לכתובת ה-URL של פיד השער:

https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/email/gateway

XML של הבקשה PUT הוא:

<atom:entry xmlns:atom='http://www.w3.org/2005/Atom' xmlns:apps="http://schemas.google.com/apps/2006">
<apps:property name='smartHost' value='smtp.out.domain.com' />
<apps:property name='smtpMode' value='SMTP' />
</atom:entry>

מאפייני הבקשה הם:

מארח חכם: כתובת ה-IP או שם המארח של שרת ה-SMTP. Google Workspace מנתב דואר יוצא לשרת הזה.
מצב smtpMode: ערך ברירת המחדל הוא SMTP. ערך אחר, SMTP_TLS, מאבטח חיבור באמצעות TLS בעת מסירת ההודעה.

תגובה מוצלחת מחזירה את קוד הסטטוס 200 OK של HTTP, יחד עם פיד ה-AtomPub עם סטטוס ההגדרות של שער האימייל.

ניהול הגדרות ניתוב אימייל

ראשית, יוצרים בקשת XML:

<atom:entry xmlns:atom='http://www.w3.org/2005/Atom' xmlns:apps="http://schemas.google.com/apps/2006">
<apps:property name='routeDestination' value='route-smtp.domain.com'/>
<apps:property name='routeRewriteTo' value='true'/>
<apps:property name='routeEnabled' value='true'/>
<apps:property name='bounceNotifications' value='true'/>
<apps:property name='accountHandling' value='can be either allAccounts | provisionedAccounts | unknownAccounts'/>
</atom:entry>

מאפייני הבקשה הם:

נתיב יעד

היעד הזה הוא שם המארח או כתובת ה-IP של שרת הדואר SMTP-In, שאליו מנותב האימייל. שם המארח או כתובת ה-IP חייבים להתאים עבור Google. מידע נוסף על תיקון שמות של מארחים של אימייל זמין במאמר איך מציפים את Google Workspace עם ניתוב אימייל?

נתיבReWriteTo

אם הערך הוא True, שדה to: של מעטפת SMTP של ההודעה ישתנה לשם המארח (שם המארח של המשתמש@destination), וההודעה תועבר לכתובת המשתמש הזו בשרת דואר היעד. אם false, האימייל מועבר לכתובת האימייל to: של ההודעה המקורית (שם משתמש@ @username) בשרת דואר היעד. היא דומה להגדרה 'שינוי מעטפת SMTP' של מסוף הניהול. מידע נוסף זמין במאמר הגדרות דומיין לניתוב אימייל.

נתיב מופעל

אם true, הפונקציונליות של ניתוב האימייל מופעלת. אם האפשרות false מושבתת, הפונקציונליות מושבתת.

הודעות חוזרות

אם true מופעלת, Google Workspace מופעל לשליחת התראות חוזרות לשולח כשהמסירה נכשלת.

ניהול חשבון

הגדרה זו קובעת כיצד סוגים שונים של משתמשים בדומיין יושפעו מניתוב האימייל:

allAccounts – עליך לשלוח את כל האימיילים ליעד הזה.
provisionedAccounts -- שליחת אימייל ליעד הזה אם המשתמש קיים ב-Google Workspace.
unknownAccounts -- שליחת אימייל ליעד הזה אם המשתמש לא קיים ב-Google Workspace. היא דומה להגדרה 'כתובת אימייל לשליחת אימייל' במסוף Admin. למידע נוסף על הדרישות המוקדמות ועל אופן השימוש בניתוב דואר, ראה הגדרות דומיין לניתוב אימייל. ~ כדי לפרסם את הבקשה הזו, יש לשלוח HTTP POST לכתובת ה-URL של פיד ניתוב האימייל ולכלול כותרת Authorization כפי שמתואר באימות לשירות הגדרות האדמין:

https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/emailrouting

תגובה מוצלחת מחזירה קוד סטטוס 200 OK של HTTP יחד עם פיד AtomPub עם פרטי הארכיון.

נקודת קצה בשקיעה ב-31 באוקטובר 2018

נקודות הקצה הבאות הוצאו משימוש כחלק מההודעה הזו. הם הוצאו משימוש ב-31 באוקטובר 2018, והם לא זמינים יותר.

https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/general/defaultLanguage
https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/general/organizationName
https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/general/currentNumberOfUsers
https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/general/maximumNumberOfUsers
https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/accountInformation/supportPIN
https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/accountInformation/customerPIN
https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/accountInformation/adminSecondaryEmail
https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/accountInformation/edition
https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/accountInformation/creationTime
https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/accountInformation/countryCode
https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/appearance/customLogo
https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/verification/mx