Admin Settings API 總覽

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

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

Admin Settings API 會實作 Google Data API 通訊協定。Google Data API 符合 Atom 發布協定 (AtomPub) 的發布和編輯模型。AtomPub HTTP 要求會使用 Representational Set Transfer (RESTful) 設計方法，以便提供網路服務。詳情請參閱 Google 資料開發人員指南。

目標對象

本文件適用對象為希望編寫可修改及擷取 Google Workspace 網域相關資訊的用戶端應用程式的開發人員。這份文件提供使用原始 XML 和 HTTP 進行基本管理員設定 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 服務的必要資訊，以便與儲存使用者登入資訊的 ID 提供者進行通訊，並設定使用者登入、登出和變更密碼時應前往的連結。您可以透過 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 的單一登入設定，設定用於與網域的 ID 提供者伺服器通訊的設定。

閘道和轉送設定

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

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

Admin Settings API XML 要求和回應範例

本文件提供使用原始 XML 和 HTTP 的基礎管理員設定 API 要求和回應的程式碼範例。這個網域預設語言範例顯示了要求和回應項目主體的完整 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 元素會傳回 smartHost 和 smtpMode 屬性，以及所有「管理設定」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) 功能可讓使用者登入多項服務，只需輸入一次登入資訊和密碼。這個密碼由網域的 ID 提供者儲存，而非 Google Workspace。詳情請參閱說明中心的單一登入服務頁面。以下各節將說明單一登入設定的 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 會傳回 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
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 要求中的 Issuer 元素如何運作？」。

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

更新單一登入設定

如要更新網域的單一登入設定，請先使用「擷取單一登入設定」作業擷取單一登入設定，然後修改設定，再將 PUT 要求傳送至單一登入動態饋給網址。請確認更新項目中的 <id> 值與現有項目的 <id> 完全相符。如「驗證 Admin Settings API 服務」一文所述，請加入 Authorization 標頭。如要瞭解錯誤訊息，請參閱「單一登入功能疑難排解」一文。

更新單一登入設定時，請將 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 狀態碼」。

如果目標客戶已啟用敏感操作的多方核准，就無法變更單一登入設定。要求會失敗，並傳回 errorCode="1811" 和 reason="LegacyInboundSsoChangeNotAllowedWithMultiPartyApproval"。

擷取單一登入簽署金鑰

如要擷取單一登入簽署金鑰，請將 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>

如果目標客戶已啟用敏感操作的多方核准，就無法變更單一登入設定。要求會失敗，並傳回 errorCode="1811" 和 reason="LegacyInboundSsoChangeNotAllowedWithMultiPartyApproval"。

管理電子郵件閘道和轉送

「外寄電子郵件閘道」部分會說明「管理設定」API 如何支援從您網域使用者傳送的郵件外寄路由。「電子郵件轉送」部分會說明如何將郵件轉送至其他郵件伺服器。

擷取外送電子郵件閘道設定

如要擷取外寄電子郵件閘道設定，請將 HTTP GET 傳送至閘道動態饋給網址，並加入 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 要求傳送至閘道動態饋給網址：

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 位址，用於將電子郵件轉送至該伺服器。主機名稱或 IP 位址必須能解析 Google。如要進一步瞭解如何解析郵件主機名稱，請參閱「透過電子郵件路由功能試用 Google Workspace」。
routeRewriteTo
如果為 true，郵件的 SMTP 信封的 to: 欄位會變更為目的地主機名稱 (user@destination 的主機名稱)，郵件也會傳送至目的地郵件伺服器上的這個使用者地址。如果是 false，電子郵件會傳送至目的地郵件伺服器上原始郵件的 to: 電子郵件地址 (user@original hostname)。這類似於管理控制台的「變更 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 狀態碼」。

Endpoints 將於 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