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 Publishing Protocol (AtomPub) 的發布與編輯模型。AtomPub HTTP 要求採用 Representational Set Transfer (RESTful) 設計方法，適用於網路服務。詳情請參閱 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 元素會傳回 smartHost 和 smtpMode 屬性，以及所有 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 會傳回 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
ssoAllowed 是採用無類別跨網域路由 (CIDR) 格式的網路遮罩 IP 位址，ssoAllowed 會決定使用單一登入 (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 狀態碼。

目標客戶啟用多方核准執行敏感動作時，不允許變更「單一登入」設定。要求會在出現 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" 時失敗。

管理電子郵件閘道和轉送

「外寄電子郵件閘道」部分會顯示 Admin Settings 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 位址。必須為 Google 解析主機名稱或 IP 位址。
如要進一步瞭解如何解決郵件主機名稱，請參閱使用 Google Workspace 的電子郵件轉送功能前測。
routeRewriteTo
如果設為 true，郵件的 SMTP 信封的 to: 欄位會變更為目的地主機名稱 (<使用者>@目的地的主機名稱)，且郵件會傳送至目標郵件伺服器上的這個使用者地址。如果是 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