Google Workspace Admin Settings API

透過集合功能整理內容 你可以依據偏好儲存及分類內容。

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

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

Admin Settings API 會導入 Google Data API 通訊協定。Google Data API 符合 Atom Publishing Protocol (AtomPub) 的發布和編輯模型。AtomPub HTTP 要求使用網路服務的表示法表示法 (RESTful) 設計方法。詳情請參閱 Google Data Developer&s 指南

觀眾

本文件旨在協助開發人員撰寫可修改及擷取 Google Workspace 網域資訊的用戶端應用程式。其中包含使用原始 XML 和 HTTP 的基本 Admin Settings API 互動範例。

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

開始使用

建立帳戶

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

關於「管理員設定」動態饋給類型

Admin Settings API 可讓您管理下列網域設定:

單一登入設定

透過 SAML 式單一登入 (SSO) 服務,使用者必須使用相同的登入資訊和密碼,才能供 Google Workspace 代管服務和貴機構內部代管的其他服務使用。具體來說,使用單一登入 (SSO) 等代管網頁應用程式時,系統會將使用者重新導向至貴機構的識別資訊提供者,藉此在登入時驗證使用者。詳情請參閱「瞭解 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 註冊 -- 使用 API 的單一登入設定,向 Google 註冊您的公開金鑰憑證。
  • 設定單一登入 (SSO) 設定 - 使用 API 的單一登入設定,調整用於與網域識別資訊提供者的伺服器通訊設定。

閘道和轉送設定

這個動態消息可讓網域管理員控管網域電子郵件的轉送作業。

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

Admin Settings API XML 要求和回應範例

本文件提供使用原始 XML 和基本 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 狀態碼和 AtomPub 資訊提供,內含網域的 SSO 設定。

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
識別資訊提供者 (#39;) 網址,這是 Google Workspace 傳送 SAML 使用者驗證要求的網址。
SAMLLogoutUri
使用者登出網頁應用程式時,要前往的地址。
變更密碼國家/地區
變更網頁應用程式單一登入 (SSO) 密碼時,使用者要前往的地址。
啟用單一登入 (SSO)
為這個網域啟用 SAML 式單一登入 (SSO) 服務。如果您先前已設定單一登入 (SSO) 設定,但後來將 enableSSO 設為 enableSSO=false,系統仍會儲存您先前輸入的設定。
關聯許可清單
sso 無障礙功能 是無類別跨網域路由 (CIDR) 格式的網路遮罩 IP 位址,sso 相關規定決定哪些使用者會使用單一登入 (SSO) 服務登入,以及哪些使用者是透過 Google Workspace 帳戶驗證頁面登入。如未指定遮罩,所有使用者都可以透過 SSO 登入。詳情請參閱網路遮罩的運作方式
使用 DomainSpecificIssuer
您可以在向識別資訊提供者發出的 SAML 要求中使用網域特定發行者。雖然在大多數單一登入 (SSO) 部署作業中都不需要使用這項功能,但這項功能在大型公司上會使用單一識別資訊提供者,透過多個子網域驗證整個機構。提供特定網域發行者會決定與要求建立關聯的子網域。詳情請參閱「SAML 要求中的 Issuer 元素如何運作」。

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

更新單一登入設定

如要更新網域的單一登入 (SSO) 設定,請先使用「擷取單一登入設定」作業擷取單一登入 (SSO) 設定,修改設定,然後將 PUT 要求傳送至單一登入 (SSO) 動態饋給網址。請確認更新項目中的 <id> 值與現有項目的 <id> 完全相符。按照「驗證管理員設定服務」一文所述,加入 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 狀態碼和 AtomPub 資訊提供以及單一登入 (SSO) 設定。

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 狀態碼

更新單一登入簽署金鑰

如要更新網域簽署金鑰,請先使用擷取單一登入簽署金鑰作業擷取簽署金鑰,然後修改該金鑰,然後將 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>

管理電子郵件閘道和轉送

「外寄電子郵件閘道」部分會顯示 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>

要求屬性如下:

智慧主機
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>

要求屬性如下:

目的地
這個目的地是轉送電子郵件的 SMTP-In 郵件伺服器的主機名稱或 IP 位址。您必須針對 Google 解析主機名稱或 IP 位址。如要進一步瞭解如何解析郵件主機名稱,請參閱測試電子郵件轉送功能的 Google Workspace
轉送 RewriteTo
如果值為 true,系統會將郵件的 SMTP 信封的 to: 欄位變更為目的地主機名稱 (user@destination's 主機名稱),接著將郵件傳送至目的地郵件伺服器上的使用者地址。如果設為 false,系統會將電子郵件傳送至目標郵件伺服器中的原始郵件 to: 電子郵件地址 (<使用者>@<原始主機名稱>)。操作方式與管理控制台和#39; 變更 SMTP 封包' 設定類似。詳情請參閱電子郵件轉送的網域設定
路徑已啟用
如果為 true,系統會啟用電子郵件轉送功能。如果設為 false,系統會停用這項功能。
bounceNotifications
如果為 true,系統會啟用 Google Workspace,在郵件傳送失敗時傳送退件通知給寄件者。
帳戶處理

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

  • allAccounts -- 將所有電子郵件傳送到這個目的地。
  • provisionedAccounts -- 如果使用者在 Google Workspace 中,將郵件傳送至這個目的地。
  • unknownAccounts -- 如果使用者不在 Google Workspace 中,可以將郵件傳送至這個目的地。 這與管理控制台的設定類似,例如:#39; settings。如要進一步瞭解必要條件和郵件轉送選項,請參閱電子郵件轉送網域設定。 ~ 如要發布這個要求,請將 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