Admin Settings API 總覽

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

這些網域設定包括 Google Workspace 管理控制台提供的許多功能。舉例來說，您可以使用這項 API 建立自訂控制面板，或將 Google Workspace 網域整合至現有的舊版環境。

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

觀眾

本文適用於想編寫用戶端應用程式的開發人員，這類應用程式可修改及擷取 Google Workspace 網域的相關資訊。本文提供基本管理設定 API 互動的範例，使用原始 XML 和 HTTP。

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

開始使用

如要開始使用 Admin Settings API，請先設定帳戶。

建立帳戶

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 註冊公開金鑰憑證。
設定單一登入設定：使用 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。詳情請參閱說明中心的單一登入頁面。以下各節將說明單一登入設定所用的 XML 格式。

擷取單一登入設定

如要擷取單一登入設定，請將 HTTP GET 傳送至單一登入一般動態消息網址，並按照「驗證管理設定服務」一文所述，加入 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 要求中使用網域特定發行者。雖然大部分的單一登入部署作業都不需要這項功能，但如果大型公司使用單一身分識別提供者，透過多個子網域驗證整個機構，這項功能就非常實用。指定網域發行者可決定要將哪個子網域與要求建立關聯。詳情請參閱「SAML 要求中的 Issuer 元素如何運作？」一文。

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

更新單一登入設定

如要更新網域的 SSO 設定，請先使用「Retrieve Single Sign-On settings」作業擷取 SSO 設定，修改設定，然後將 PUT 要求傳送至 SSO 饋給網址。請確認更新後的項目中的 <id> 值與現有項目中的 <id> 完全相符。如「驗證 Admin Settings API 服務」一文所述，加入 Authorization 標頭。如需錯誤訊息的相關說明，請參閱「排解 SSO 問題」。

更新單一登入設定時，請將 HTTP PUT 傳送至單一登入一般動態消息網址：

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 傳送至單一登入簽署金鑰動態饋給網址，並加入 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 狀態碼」。

更新單一登入簽署金鑰

如要更新網域的單一登入簽署金鑰，請先使用「Retrieve Single Sign-On signing key」作業擷取簽署金鑰，然後修改金鑰，再將 PUT 要求傳送至單一登入簽署金鑰動態饋給網址。請確認更新後的項目中，<id> 值與現有項目的 <id> 完全相符。如要進一步瞭解 SAML 型單一登入簽署金鑰，請參閱「產生 Google Workspace 單一登入服務的金鑰和憑證」。

更新單一登入簽署金鑰時，請將 HTTP PUT 傳送至單一登入簽署金鑰動態饋給網址：

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>

要求屬性如下：

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 -- Deliver mail to this destination if the user exists in Google Workspace.
unknownAccounts -- Deliver mail to this destination if the user doesn't exist in 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

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

觀眾

開始使用

建立帳戶

關於 Admin Settings API 饋給類型

Admin Settings API XML 要求和回應範例

管理單一登入設定

擷取單一登入設定

更新單一登入設定

擷取單一登入簽署金鑰

更新單一登入簽署金鑰

管理電子郵件閘道和轉送

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

更新外送電子郵件閘道設定

管理電子郵件轉送設定

Endpoints 將於 2018 年 10 月 31 日終止服務

Admin Settings API 總覽