Admin Settings API 概览

借助 Admin Settings API，Google Workspace 网域的管理员可以通过 Google Data API Feed 的形式检索和更改网域的设置。

这些域名设置包括 Google Workspace 管理控制台中提供的许多功能。该 API 的示例用途包括创建自定义控制台，或将 Google Workspace 网域集成到现有的旧环境中。

Admin Settings API 实现了 Google Data API 协议。Google 数据 API 符合 Atom 发布协议 (AtomPub) 发布和编辑模式。AtomPub HTTP 请求使用表示集传输 (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 配置您的网域设置，并使用 Email Settings API 来配置用户的电子邮件设置。

关于管理设置 API Feed 类型

通过 Admin Settings API，您可以管理以下类别的网域设置：

单点登录设置

通过基于 SAML 的单点登录 (SSO)，用户可以使用相同的登录信息和密码访问 Google Workspace 托管的服务以及您组织中可能托管的其他服务。尤其是在使用 SSO 时，Google Workspace 等托管的 Web 应用会将用户重定向到贵组织的身份提供方，以便在用户登录时对其进行身份验证。有关详情，请参阅了解 Google Workspace 基于 SAML 的单点登录。

配置单点登录时，需要为 Google Workspace 服务输入必要信息，以便与存储用户登录信息的身份提供方通信，以及设置用户在登录、退出和更改密码时应访问的链接。通过 Admin Settings API，您可以通过编程方式更新和检索这些设置。Google 会使用您生成的公钥向身份提供方验证此单点登录请求，并确保私钥 SAML 响应在网络传输过程中未发生修改。

如需简要了解单点登录设置用法，请从身份提供方处获取公钥证书，向 Google 注册公钥，然后设定基于 SAML 的单点登录查询设置。如需了解错误消息，请参阅 SSO 问题排查：

• 生成密钥 -- 通过身份提供方使用 DSA 或 RSA 算法生成一组公钥和私钥。公钥是 X.509 格式的证书。要详细了解基于 SAML 的单点登录签名密钥，请参阅为 Google Workspace 单点登录服务生成密钥和证书。
• 向 Google 注册 - 使用 Admin Settings API 的单一登录设置向 Google 注册您的公钥证书。
• 设定 SSO 设置 -- 使用 Admin Settings API 的单一登录设置可以配置用来与域身份提供者的服务器进行通信的设置。

注意 ：对于不采用基于网络的登录流程的协议（例如某些 POP/IMAP 电子邮件客户端），用户可使用自己的 Google Workspace 用户名和密码直接登录。

网关和转送设置

此 Feed 可让网域管理员控制其网域的电子邮件转送。

通过电子邮件转送操作，管理员可以指定网域级别的电子邮件转送设置。这类似于管理控制台 Gmail 设置的电子邮件转送功能。有关详情，请参阅电子邮件转送和电子邮件转送功能的双重递送配置。

管理设置 API XML 请求和响应示例

本文档提供了使用原始 XML 和 HTTP 的基本管理设置 API 请求和响应的代码示例。以下网域默认语言示例展示了每个操作通用的请求和响应条目正文的完整 XML 和 HTTP 语法：

要更改网域的出站电子邮件网关设置，请向网关 Feed 网址发送 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 元素表示单个键值对，其中包含您要检索或更新的属性的相关信息。这些是所有管理设置 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)，用户只需输入一次登录名和密码，即可登录多项服务。此密码由域名的身份提供方（而非 Google Workspace）存储。有关详情，请参阅帮助中心的单点登录页面。以下各部分介绍了用于单点登录设置的 XML 格式。

检索单点登录设置

要检索单点登录设置，请将 HTTP GET 发送到 SSO 常规 Feed 网址并包含 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

用户退出 Web 应用时将被转到的地址。

更改密码 URI

用户要更改 Web 应用的单点登录密码时将会转到的地址。

启用单点登录

为此网域启用基于 SAML 的单点登录。如果您之前配置了单点登录设置，并且随后将 enableSSO 设为了 enableSSO=false，那么系统仍会保存您之前输入的设置。

sso 白名单

sso 白名单是采用无类别域间路由 (CIDR) 格式的网络掩码 IP 地址。sso 白名单决定了哪些用户使用 SSO 登录，哪些用户使用 Google Workspace 帐号身份验证页面登录。如果未指定掩码，则所有用户都使用 SSO 登录。如需了解详情，请参阅网络掩码的工作原理。

useDomainSpecificIssuer

网域特定的颁发者可以在发送到身份提供方的 SAML 请求中使用。虽然对大多数 SSO 部署而言并非必须，但对于使用单一身份提供方对具有多个子网域的整个组织进行身份验证的大型公司，此功能非常有用。由特定网域颁发者确定要与请求关联的子网域。有关详情，请参阅 SAML 请求中的颁发者元素的工作原理

如果您的请求因某种原因而失败，则会返回不同的状态代码。如需详细了解 Google Data API 状态代码，请参阅 HTTP 状态代码。

更新单点登录设置

要更新网域的 SSO 设置，请先使用检索单点登录设置操作检索 SSO 设置，对其进行修改，然后将 PUT 请求发送到 SSO Feed 网址。请确保更新后的条目中的 <id> 值与现有条目的 <id> 完全匹配。添加 Authorization 标头（如向 Admin Settings API 服务进行身份验证中所述）。有关错误消息，请参阅 SSO 问题排查。

在更新单点登录设置时，将 HTTP PUT 发送到 SSO 常规 Feed 网址：

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 状态代码。

检索单点登录签名密钥

要检索单点登录签名密钥，请将 HTTP GET 发送到 SSO 签名密钥 Feed 网址并包含 Authorization 标头，如在管理设置服务中进行身份验证中所述。并且，有关错误消息，请参阅 SSO 问题排查：

https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/sso/signingkey

此操作在请求正文中没有任何参数。

成功的响应将返回一个 HTTP 200 OK 状态代码以及具有签名密钥的 AtomPub Feed。

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 签名密钥 Feed 网址。请确保更新后的条目中的 <id> 值与现有条目的 <id> 完全匹配。要详细了解基于 SAML 的单点登录签名密钥，请参阅为 Google Workspace 单点登录服务生成密钥和证书。

更新单点登录签名密钥时，将 HTTP PUT 发送到 SSO 签名密钥 Feed 网址：

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>

注意： 此请求需要 signingKey 属性。

管理电子邮件网关和路由

出站电子邮件网关部分展示了 Admin Settings API 如何支持从您网域中用户接收邮件的出站路由。电子邮件转送部分介绍了如何将邮件转送到其他邮件服务器。

检索出站电子邮件网关设置

要检索出站电子邮件网关设置，请将 HTTP GET 发送到网关 Feed 网址并包含 Authorization 标头，如向管理设置服务进行身份验证中所述：

https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/email/gateway

此操作在请求正文中没有任何参数。

注意 ：您必须订阅符合条件的 Google Workspace 版本，才能使用 Google Workspace 出站网关功能。

成功的响应将返回一个 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 状态代码。

正在更新出站电子邮件网关设置

要更新网域的出站电子邮件网关设置，请向网关 Feed 网址发送 HTTP PUT 请求：

https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/email/gateway

注意： 您必须拥有符合条件的 Google Workspace 版本，才能使用 Google Workspace 出站网关功能。

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 的连接。

注意 ：请按照邮件转移代理的说明配置从 Google Workspace 发送的中继电子邮件。

成功的响应将返回一个 HTTP 200 OK 状态代码以及具有电子邮件网关设置状态的 AtomPub 供稿。

注意 ：您可以从 Google Workspace 向网域外的用户发送电子邮件，以验证通过网关发送的出站邮件在更改后是否可以正常接收。

如果您的请求因某种原因而失败，则会返回不同的状态代码。如需详细了解 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: 字段会更改为目标主机名（user@destination 的主机名），并且邮件会递送到目标邮件服务器上的该用户地址。如果为 false，则电子邮件将递送到目标邮件服务器上原始邮件的 to: 电子邮件地址（user@original 主机名）。这类似于管理控制台的“更改 SMTP 信包”设置。有关详情，请参阅电子邮件转送的网域设置。

routeEnabled

如果为 true，则表示电子邮件转送功能已启用。如果为 false，则此功能将停用。

退信通知

如果设为 true，则 Google Workspace 可以在递送失败时向发件人发送退信通知。

帐号处理

此设置决定了电子邮件转送对网域中不同类型的用户的影响：

• allAccounts -- 将所有电子邮件递送到此目标位置。
• provisionedAccounts - 如果 Google Workspace 中存在用户，则将邮件递送至此目标位置。
• unknownAccounts - 如果 Google Workspace 中不存在此用户，则将邮件递送到此目标位置。 这类似于管理控制台的“电子邮件递送对象”设置。要详细了解相关前提条件以及如何使用邮件转送，请参阅电子邮件转送的网域设置。 ~ 若要发布此请求，请将 HTTP POST 发送到电子邮件路由 Feed 网址并包含 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