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

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

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

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

קהל

המסמך הזה מיועד למפתחים שרוצים לכתוב אפליקציות לקוח שיכולות לשנות ולאחזר מידע על דומיינים של 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

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

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

כניסה יחידה (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. להודעות שגיאה, ראו פתרון בעיות ב-SSO:

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

הגדרות שער וניתוב

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

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

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

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

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

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

שפת ברירת המחדל של הדומיין PUT בקשת 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 מייצגים צמד מפתח/ערך אחד שמכיל מידע על הנכס שאתם רוצים לאחזר או לעדכן. הפעולות האלה משותפות לכל גופי הבקשות של 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. למידע נוסף, עיין בדף SSO במרכז העזרה. הקטעים הבאים מדגימים את פורמט ה-XML שמשמש להגדרות של כניסה יחידה (SSO).

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

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

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

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

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

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

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.

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

כדי לאחזר את מפתח החתימה לכניסה יחידה, צריך לשלוח GET HTTP לכתובת ה-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>

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

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

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

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

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>

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

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

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

כדי לאחזר את ההגדרות של שער האימייל היוצא, צריך לשלוח GET HTTP לכתובת ה-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.

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

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

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

קודם כול, יוצרים בקשת 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>

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

routeDestination
היעד הזה הוא שם המארח או כתובת ה-IP של שרת האימייל ב-SMTP שבו מתבצע ניתוב של האימייל. שם המארח או כתובת ה-IP חייבים להתאים ל-Google. למידע נוסף על פתרון בעיות בשמות של מארחי אימייל, ראו תוכנית פיילוט של Google Workspace עם ניתוב אימיילים.
routeRewriteTo
אם הערך הוא True, השדה to: של מעטפת ה-SMTP של ההודעה ישתנה לשם המארח של היעד (שם המארח של user@destination), וההודעה תימסר לכתובת המשתמש הזו בשרת הדואר של היעד. אם הערך שלו הוא false, האימייל יישלח לכתובת האימייל to: של ההודעה המקורית (שם המארח של המשתמש@המקורי) בשרת האימייל של היעד. הפעולה הזו דומה להגדרה 'שינוי מעטפת SMTP' במסוף Admin. למידע נוסף, ראו הגדרות דומיין לניתוב אימייל.
routeEnabled
אם הערך שלו הוא true, הפונקציונליות של ניתוב האימיילים תופעל. אם הערך שלו הוא false, הפונקציונליות מושבתת.
bounceNotifications
במקרה של true, מערכת Google Workspace מופעלת לשליחת התראות חוזרות לשולח כשמסירה נכשלה.
accountHandling

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

  • 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 עם פרטי הארכיון.

אם הבקשה נכשלת מסיבה כלשהי, מוחזר קוד סטטוס אחר. מידע נוסף על קודי הסטטוס של 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