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

קהל

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

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

תחילת העבודה

יצירת חשבון

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

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

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

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

כניסה יחידה (SSO) מבוססת-SAML מאפשרת למשתמשים להשתמש באותם פרטי התחברות וסיסמה גם לשירותים שמתארחים ב-Google Workspace וגם לשירותים אחרים שאתם מארחים בארגון. כשמשתמשים בכניסה יחידה, אפליקציית אינטרנט מתארחת כמו 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, אפשר לעיין במאמר יצירת מפתחות ואישורים לשירות כניסה יחידה (SSO) של Google Workspace.
  • הרשמה באמצעות Google – השתמשו בהגדרות הכניסה היחידה בממשק ה-Admin Settings API כדי לרשום את האישור של המפתח הציבורי ב-Google.
  • קבע את הגדרות ה-SSO -- השתמש בהגדרות כניסה יחידה (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 לבקשת 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 המשותף לכל גופי התגובה של 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) ב-Google Workspace מאפשרת למשתמשים להתחבר לכמה שירותים, בלי להזין פרטי התחברות וסיסמה פעם אחת בלבד. הסיסמה הזו שמורה לספק הזהויות של הדומיין, לא ל-Google Workspace. מידע נוסף זמין בדף בנושא כניסה יחידה במרכז העזרה. הקטעים הבאים מדגימים את פורמט ה-XML המשמש להגדרות של 'כניסה יחידה'.

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

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

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

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

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

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

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

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

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

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

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

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

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

תגובה מוצלחת מחזירה קוד סטטוס HTTP 200 OK, ביחד עם פיד 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-In שאליו האימייל מנותב. שם המארח או כתובת ה-IP חייבים לפענח עבור Google. לפרטים נוספים על פתרון שמות מארחי אימיילים, ניתן לעיין במאמר פיילוט של Google Workspace עם ניתוב אימייל.
routeRewriteTo
אם הערך הוא true, השדה to: של מעטפת ה-SMTP של ההודעה ישתנה לשם המארח של היעד (שם המארח של user@destination), וההודעה מועברת לכתובת המשתמש הזו בשרת הדואר של היעד. אם בוחרים באפשרות false, האימייל מועבר לכתובת to: של ההודעה המקורית (שם המארח מסוג user@Original) בשרת הדואר של היעד. היא דומה להגדרה 'שינוי מעטפת SMTP' במסוף הניהול. למידע נוסף, ראה הגדרות דומיין לניתוב אימייל.
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

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

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

נקודות הקצה (endpoints) יוצאו ב-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