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 Data 開發人員指南。

目標對象

本文件旨在協助開發人員撰寫可修改及擷取 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 的 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 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 元素會傳回 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 狀態碼，以及 AtomPub 資訊提供以及網域的 SSO 設定。

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
使用者登出網路應用程式時，系統傳送到這個位址。
變更密碼 Uri
使用者想變更網路應用程式的單一登入 (SSO) 密碼時，要將他們傳送到哪個電子郵件地址。
啟用 SSO
為這個網域啟用 SAML 式單一登入 (SSO) 服務。如果您先前已設定單一登入 (SSO) 設定，之後選擇將 enableSSO 設為 enableSSO=false，系統仍會儲存您先前輸入的設定。
關聯許可清單
ssolist 是採用無類別跨網域路由 (CIDR) 格式的網路遮罩 IP 位址。sso 項封鎖功能可決定哪些使用者可以使用 SSO 登入，以及哪些使用者是透過 Google Workspace 帳戶驗證頁面登入。如未指定遮罩，所有使用者都會透過 SSO 登入。詳情請參閱網路遮罩的運作方式。
使用網域特定發行者
您可以在向識別資訊提供者傳送的 SAML 要求中使用特定網域發行者。雖然大多數單一登入 (SSO) 部署作業並非必要，但對於使用單一識別資訊提供者來驗證擁有多個子網域整個機構的大型公司而言，這項功能非常實用。提供特定網域發行者可決定要將哪個子網域與要求建立關聯。詳情請參閱「SAML 要求中的 Issuer 元素如何運作」。

如果因為某些原因導致要求失敗，系統會傳回不同的狀態碼。如要進一步瞭解 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 狀態碼和 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 狀態碼。

更新單一登入簽署金鑰

如要更新網域的單一登入 (SSO) 簽署金鑰，請先使用 [擷取單一登入 (Signing-On) 簽署金鑰] 操作來擷取簽署金鑰，接著修改該金鑰，然後將 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 回應會傳回 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>

要求屬性如下：

目的地目的地
這個目的地是轉送電子郵件的 SMTP-In 郵件伺服器的主機名稱或 IP 位址。Google 必須解析主機名稱或 IP 位址。如要進一步瞭解如何解析郵件主機名稱，請參閱運用電子郵件轉送功能測試 Google Workspace。
routeRewriteTo 路徑
如果值為 true，郵件的 SMTP 封包的 to: 欄位會變更為目的地主機名稱 (user@destination 的主機名稱)，而郵件會傳送到目標郵件伺服器上的這個使用者地址。如果設為 false，系統會將電子郵件傳送至目標郵件伺服器上的原始郵件的 to: 電子郵件地址 (<使用者>@<原始主機名稱>)。操作方式與管理控制台的「變更 SMTP 封包」設定類似。詳情請參閱電子郵件轉送的網域設定。
路徑已啟用
如果為 true，系統會啟用電子郵件轉送功能。如果設為 false，系統會停用這項功能。
退回通知
true
帳戶處理

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

  • 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