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