Admin Settings API 總覽

Google Workspace 網域的管理員可以透過 Admin Settings API,以 Google Data API 動態饋給的形式擷取及變更網域設定。

這些網域設定有許多 Google Workspace 管理控制台提供的功能。這個 API 的用途包括建立自訂控制台,或是將 Google Workspace 網域整合至現有舊環境中。

Admin Settings API 會導入 Google Data API 通訊協定。Google Data API 符合 Atom Publishing Protocol (AtomPub) 發布與編輯模型的要求。AtomPub HTTP 要求採用代表性集合傳輸 (符合 REST 樣式) 設計方法連線至網路服務。詳情請參閱 Google 資料開發人員指南

適用對象

本文件可協助開發人員編寫可修改及擷取 Google Workspace 網域相關資訊的用戶端應用程式。其中提供使用原始 XML 和 HTTP 進行 Admin Settings API 的基本互動範例。

本文假設您已瞭解 Google Data API 通訊協定的一般概念,而且您已熟悉 Google Workspace 管理控制台。如要進一步瞭解管理控制台,請參閱「使用管理控制台」。

入門課程

建立帳戶

已為 Google Workspace 帳戶啟用 Admin Settings API。註冊 Google Workspace 帳戶進行測試。「管理員設定」服務會使用 Google 帳戶,因此如果您的 Google Workspace 網域有帳戶,就大功告成了。

關於 Admin Settings API 動態饋給類型

Admin Settings API 可讓您管理以下類別的網域設定:

單一登入設定

SAML 式單一登入 (SSO) 服務可讓使用者使用相同的登入名稱和密碼,登入 Google Workspace 代管服務以及可能在貴機構內代管的其他服務。具體來說,使用單一登入 (SSO) 服務時,會將使用者重新導向至貴機構的識別資訊提供者 (例如 Google Workspace),在他們登入時驗證使用者。詳情請參閱「瞭解 Google Workspace 的 SAML 式單一登入 (SSO) 服務」。

設定單一登入 (SSO) 時,您需要輸入必要資訊,讓 Google Workspace 服務能與儲存使用者登入資訊的識別資訊提供者通訊,以及設定應將使用者的登入、登出及變更密碼時傳送至哪個連結。Admin Settings API 可讓您以程式輔助方式更新及擷取這些設定。Google 會使用您產生的公開金鑰,向識別資訊提供者驗證這項單一登入 (SSO) 要求,並確認在網路傳輸期間未修改私密金鑰 SAML 回應。

如要查看單一登入 (SSO) 設定的簡短 API 具體摘要,請向識別資訊提供者取得您的公開金鑰憑證、向 Google 註冊公開金鑰,以及調整 SAML 式單一登入 (SSO) 查詢設定。如需錯誤訊息,請參閱單一登入 (SSO) 疑難排解

  • 產生金鑰:請與您的識別資訊提供者合作,使用 DSA 或 RSA 演算法產生一組公開和私密金鑰。公開金鑰是採用 X.509 格式的憑證。如要進一步瞭解 SAML 式單一登入簽署金鑰,請參閱「為 Google Workspace 單一登入服務產生金鑰和憑證」一文。
  • 向 Google 註冊:使用 Admin Settings API 的單一登入設定,向 Google 註冊您的公用金鑰憑證。
  • 指定 SSO 設定:使用 Admin Settings API 的單一登入設定,指定用來與網域識別資訊提供者伺服器通訊的設定。

閘道和轉送設定

這項動態消息可讓網域管理員控管網域的電子郵件轉送方式。

電子郵件轉送作業可讓管理員指定網域層級的電子郵件轉送設定。這項功能與管理控制台 Gmail 設定的電子郵件轉送功能類似。詳情請參閱電子郵件轉送電子郵件轉送功能的雙重傳送設定

Admin Settings API XML 要求與回應範例

本文件提供基本 Admin Settings API 要求和使用原始 XML 和 HTTP 的回應程式碼範例。這個網域預設語言示例會顯示要求和回應項目內文的完整 XML 和 HTTP 語法,而這些語法在每項作業中都很常見:

如要變更網域的外送電子郵件閘道設定,請將 HTTP PUT 傳送至閘道動態饋給網址:

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 元素會傳回 smartHostsmtpMode 屬性,以及所有 Admin Settings API 回應主體通用的 XML 語法:

<?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>

管理單一登入設定

Google Workspace 單一登入功能 (SSO) 可讓使用者登入多項服務,而且只需輸入登入密碼和密碼一次。這個密碼是由網域的識別資訊提供者儲存,而非 Google Workspace。詳情請參閱說明中心的 SSO 頁面。下列各節說明單一登入設定使用的 XML 格式。

擷取單一登入設定

如要擷取單一登入設定,請將 HTTP GET 傳送至單一登入 (SSO) 一般動態饋給網址,並根據「驗證管理員設定服務」一文的說明加入 Authorization 標頭。如需查看錯誤訊息,請參閱單一登入 (SSO) 疑難排解

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

這項作業的要求主體中沒有參數。

成功的回應會傳回 HTTP 200 OK 狀態碼,以及含網域的單一登入 (SSO) 設定的 AtomPub 動態饋給。

GET 回應 XML 會傳回 samlSignonUrisamlLogoutUrichangePasswordUrienableSSOssoWhitelistuseDomainSpecificIssuer 屬性:

<?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
識別資訊提供者的網址,Google Workspace 會將 SAML 要求用於使用者驗證。
samlLogoutUri
使用者登出網頁應用程式後,系統會將他們導向的電子郵件地址。
changePasswordUri
當使用者想變更網頁應用程式的單一登入 (SSO) 密碼時,系統會導向哪個網址。
enableSSO
為這個網域啟用 SAML 式 SSO 服務。如果您先前已指定單一登入 (SSO) 設定,而後來將 enableSSO 設為 enableSSO=false,系統會保留您先前輸入的設定。
ssoWhitelist
ssoWhitelist 是採用無類別跨網域轉送 (CIDR) 格式的網路遮罩 IP 位址。ssoWhitelist 能判斷哪些使用者能夠使用單一登入 (SSO) 服務登入,以及哪些使用者是透過 Google Workspace 帳戶驗證頁面登入。如果沒有指定遮罩,所有使用者將透過單一登入 (SSO) 服務登入。詳情請參閱「網路遮罩如何運作」。
useDomainSpecificIssuer
在向識別資訊提供者的 SAML 要求中,使用網域特定發行者。對於大多數單一登入 (SSO) 部署作業來說,這項功能並非必要,但如果公司是透過單一識別資訊提供者,為具有多個子網域的整個機構進行驗證,就很適合使用這項功能。授予特定網域發行者可決定要將哪個子網域與要求建立關聯。詳情請參閱 SAML 要求中的發行者元素如何運作?

如果因為某些原因導致要求失敗,系統會傳回其他狀態碼。如要進一步瞭解 Google Data API 狀態碼,請參閱 HTTP 狀態碼

更新單一登入設定

如要更新網域的單一登入 (SSO) 設定,請先透過「擷取單一登入設定」作業擷取單一登入 (SSO) 設定並進行修改,然後傳送 PUT 要求至單一登入 (SSO) 動態饋給網址。請確認更新項目中的 <id> 值與現有項目的 <id> 完全相符。按照「驗證 Admin Settings API 服務」的說明加入 Authorization 標頭。如需查看錯誤訊息,請參閱單一登入 (SSO) 疑難排解

更新單一登入設定時,請將 HTTP PUT 傳送至 SSO 一般動態饋給網址:

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

PUT 要求的 XML 主體如下:

<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 狀態碼,以及含有單一登入 (SSO) 設定的 AtomPub 動態饋給。

PUT 回應 XML 如下:

<?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 傳送至單一登入 (SSO) 簽署金鑰動態饋給網址,並根據「驗證管理員設定服務」一文的說明加入 Authorization 標頭。如需查看錯誤訊息,請參閱單一登入 (SSO) 疑難排解

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

這項作業的要求主體中沒有參數。

成功的回應會傳回 HTTP 200 OK 狀態碼,以及包含簽署金鑰的 AtomPub 動態饋給。

GET 回應 XML 會傳回 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 要求傳送至單一登入 (SSO) 簽署金鑰動態饋給網址。請確認更新項目中的 <id> 值與現有項目的 <id> 完全相符。如要進一步瞭解 SAML 式單一登入簽署金鑰,請參閱「為 Google Workspace 單一登入服務產生金鑰和憑證」一文。

更新單一登入簽署金鑰時,請將 HTTP PUT 傳送至單一登入 (SSO) 簽署金鑰動態饋給網址:

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

PUT 要求 XML 為:

<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 傳送至閘道動態饋給網址,並根據驗證管理員設定服務的說明加入 Authorization 標頭:

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

這項作業的要求主體中沒有參數。

成功的回應會傳回 HTTP 200 OK 狀態碼,以及內含電子郵件閘道狀態資訊的 AtomPub 動態饋給。

GET 回應會傳回 smartHostsmtpMode 屬性。如要進一步瞭解這些屬性,請參閱更新外寄電子郵件閘道設定

可能的回應範例如下:

<?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 要求至閘道動態饋給網址:

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

PUT 要求 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>

要求屬性如下:

smartHost
SMTP 伺服器的 IP 位址或主機名稱。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
這個目的地是電子郵件轉送目的地的 SMTP-In 郵件伺服器主機名稱或 IP 位址。必須為 Google 解析主機名稱或 IP 位址。如要進一步瞭解如何解析郵件主機名稱,請參閱電子郵件轉送功能測試 Google Workspace
routeRewriteTo
如果為 true,郵件的 SMTP 信封的 to: 欄位會變更為目的地主機名稱 (user@destination 的主機名稱),且郵件會傳送至目標郵件伺服器上的這個使用者地址。如為 false,電子郵件會傳送至原始郵件的 to: 電子郵件地址 (<使用者>@<原始主機名稱) 在目的地郵件伺服器。這類似於管理控制台的「變更 SMTP 信封」設定。詳情請參閱電子郵件轉送網域設定
routeEnabled
如果為 true,電子郵件轉送功能將會啟用。如果為 false,這項功能就會停用。
bounceNotifications
如果啟用 true,Google Workspace 會在傳送失敗時,向寄件者傳送退信通知。
accountHandling

這項設定會決定網域中不同類型的使用者如何受到電子郵件轉送影響:

  • allAccounts -- 將所有電子郵件傳送至這個目的地。
  • provisionedAccounts:如果使用者是 Google Workspace 使用者,請將郵件傳送至這個目的地。
  • unknownAccounts -- 如果使用者不在 Google Workspace 中,將郵件傳送至這個目的地。 這與管理控制台的「傳送電子郵件寄件者」設定類似。如要進一步瞭解必要條件和郵件轉送功能的使用方式,請參閱電子郵件轉送的網域設定。 ~ 如要發布這項要求,請將 HTTP POST 傳送至電子郵件轉送動態饋給網址,並根據「驗證管理員設定服務」一節的說明加入 Authorization 標頭:

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

成功的回應會傳回 HTTP 200 OK 狀態碼,以及含有封存資訊的 AtomPub 動態饋給。

如果因為某些原因導致要求失敗,系統會傳回其他狀態碼。如要進一步瞭解 Google Data API 狀態碼,請參閱 HTTP 狀態碼

端點將於 2018 年 10 月 31 日停用

在此公告中,我們淘汰了下列端點。 這些資訊已於 2018 年 10 月 31 日停用,不再提供。

  • 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