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

ה-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 משתמשות בגישת העיצוב Representational Set Transfer‏ (RESTful) לשירותי אינטרנט. למידע נוסף, אפשר לעיין במדריך למפתחים של Google Data APIs.

קהל

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

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

שנתחיל?

כדי להתחיל להשתמש ב-Admin Settings API, קודם צריך להגדיר את החשבון.

יצירת חשבון

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

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

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

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

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

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

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

הגדרות שער

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

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

דוגמה לבקשת XML ותגובה מ-Admin Settings API

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

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

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

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

<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 מייצגים צמד יחיד של מפתח/ערך שמכיל מידע על מאפיין שרוצים לאחזר או לעדכן. המאפיינים האלה משותפים לכל גופי בקשות ה-API של Admin Settings API.

רכיב התשובה entry של שפת ברירת המחדל של הדומיין מחזיר את המאפיינים smartHost ו-smtpMode יחד עם תחביר ה-XML שמשותף לכל גופי התשובות של Admin Settings 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)

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

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

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

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

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

תגובה מוצלחת מחזירה קוד סטטוס HTTP 200 OK, יחד עם פיד 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
הכתובת שאליה המשתמשים יועברו כשהם יתנתקו מאפליקציית האינטרנט.
changePasswordUri
הכתובת שאליה המשתמשים יועברו כשהם ירצו לשנות את הסיסמה שלהם לכניסה יחידה באפליקציית האינטרנט.
enableSSO
הפעלת כניסה יחידה (SSO) מבוססת-SAML לדומיין הזה. אם הגדרתם בעבר הגדרות של כניסה יחידה (SSO), ואחר כך הגדרתם את enableSSO ל-enableSSO=false, ההגדרות שהזנתם בעבר עדיין יישמרו.
ssoWhitelist
רשימת היתרים של SSO היא כתובת IP של מסכת רשת בפורמט Classless Inter-Domain Routing‏ (CIDR). הפרמטר ssoWhitelist קובע אילו משתמשים נכנסים באמצעות SSO ואילו משתמשים נכנסים באמצעות דף האימות של חשבון Google Workspace. אם לא מוגדרות מסכות, כל המשתמשים ייכנסו באמצעות SSO. מידע נוסף זמין במאמר איך מסכות רשת פועלות.
useDomainSpecificIssuer
אפשר להשתמש במנפיק ספציפי לדומיין בבקשת SAML לספק הזהויות. התכונה הזו לא נדרשת ברוב ההטמעות של SSO, אבל היא שימושית בחברות גדולות שמשתמשות בספק זהויות יחיד כדי לאמת ארגון שלם עם כמה תת-דומיינים. הגדרת מנפיק ספציפי לדומיין קובעת לאיזה תת-דומיין לשייך את הבקשה. מידע נוסף זמין במאמר איך פועל רכיב ה-Issuer בבקשת SAML?

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

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

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

כשמעדכנים את הגדרות הכניסה היחידה, שולחים HTTP 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>

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

כשלקוח היעד הפעיל אישור על ידי גורמים מרובים לפעולות רגישות, אי אפשר לבצע שינויים בהגדרות של כניסה יחידה (SSO). הבקשות ייכשלו עם השגיאות errorCode="1811" ו-reason="LegacyInboundSsoChangeNotAllowedWithMultiPartyApproval".

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

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

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

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

תגובה מוצלחת מחזירה קוד סטטוס HTTP 200 OK, יחד עם פיד 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>

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

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

כדי לעדכן את מפתח החתימה של SSO בדומיין, קודם צריך לאחזר את מפתח החתימה באמצעות הפעולה Retrieve Single Sign-On signing key, לשנות אותו ואז לשלוח בקשת PUT לכתובת ה-URL של פיד מפתח החתימה של SSO. חשוב לוודא שהערך <id> ברשומה המעודכנת זהה לערך <id> ברשומה הקיימת. מידע נוסף על מפתחות חתימה של כניסה יחידה (SSO) שמבוססת על SAML זמין במאמר יצירת מפתחות ואישורים לשירות הכניסה היחידה (SSO) של 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>

כשלקוח היעד הפעיל אישור על ידי גורמים מרובים לפעולות רגישות, אי אפשר לבצע שינויים בהגדרות של כניסה יחידה (SSO). הבקשות ייכשלו עם השגיאות errorCode="1811" ו-reason="LegacyInboundSsoChangeNotAllowedWithMultiPartyApproval".

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

בקטע 'שער לדואר יוצא' מוסבר איך Admin Settings 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>

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

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

כדי לעדכן את ההגדרה של שער דואר יוצא בדומיין, שולחים בקשת 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>

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

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

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

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

הוצאה משימוש של נקודות קצה ב-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