Admin Settings API 概览

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

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

Admin Settings API 实现了 Google Data API 协议。 Google Data API 符合 Atom 发布协议 (AtomPub) 发布和编辑模型。AtomPub HTTP 请求使用 Web 服务的表述性状态转移 (RESTful) 设计方法。如需了解详情，请参阅Google Data API 开发者指南。

受众群体

本文档面向希望编写客户端应用以修改和检索 Google Workspace 网域相关信息的开发者。它提供了使用原始 XML 和 HTTP 的基本 Admin Settings API 交互示例。

本文档假定您了解 the Google Data API 协议背后的总体思路，并且熟悉 Google Workspace 管理控制台。如需详细了解管理控制台，请参阅使用您的管理控制台。

开始使用

如需开始使用 Admin Settings API，请先设置您的账号。

创建账号

Admin Settings API 适用于 Google Workspace 账号。注册一个 Google Workspace 账号以进行测试。 Admin Settings 服务使用 Google 账号，因此如果您已拥有 Google Workspace 网域的账号，则无需进行任何操作。

Admin Settings API Feed 类型简介

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

单点登录设置: 借助基于 SAML 的单点登录 (SSO)，用户可以使用相同的登录名和密码来访问 Google Workspace 托管服务以及您可能在组织内托管的其他服务。具体来说，在使用 SSO 时，托管式 Web 应用（例如 Google Workspace）会在用户登录时将用户重定向到您组织的身份提供方，以对用户进行身份验证。如需了解详情，请参阅了解 Google Workspace 的基于 SAML 的 SSO。

配置 SSO 涉及输入必要的信息，以便 Google Workspace 服务与存储用户登录信息的身份提供方进行通信，并设置用户应收到的用于登录、退出和更改密码的链接。借助 Admin Settings API，您可以以编程方式更新和检索这些设置。Google 会使用您生成的公钥向身份提供方验证此单点登录请求，并验证私钥 SAML 响应在网络传输期间是否被修改。

如需简要了解如何使用 SSO 设置的 API 特定摘要，请从身份提供方获取公钥证书，向 Google 注册公钥，并设置基于 SAML 的 SSO 查询设置。如需了解错误消息，请参阅排查 SSO 问题：

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

网关和路由设置

借助此 Feed，网域管理员可以控制其网域的电子邮件路由。

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

Admin Settings API XML 请求和响应示例

本文档提供了使用原始 XML 和 HTTP 的基本 Admin Settings 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 元素还表示包含您要检索或更新的属性相关信息的单个键值对。这些元素对于所有 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 格式。

检索单点登录设置

如需检索单点登录设置，请向 SSO 常规 Feed 网址发送 HTTP GET，并添加 Authorization 标头，如在向 Admin Settings 服务进行身份验证中所述。如需了解错误消息，请参阅排查 SSO问题：

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

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

成功响应会返回 HTTP 200 OK 状态代码，以及包含网域 SSO 设置的 AtomPub Feed。

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 应用时将被发送到的地址。
changePasswordUri: 用户想要更改 Web 应用的 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 状态代码。

更新单点登录设置

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

更新单点登录设置时，请向 SSO 常规 Feed 网址发送 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 Feed。

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"。

检索单点登录签名密钥

如需检索单点登录签名密钥，请向 SSO 签名密钥 Feed 网址发送 HTTP GET，并添加 Authorization 标头，如向 Admin Settings service进行身份验证中所述。如需了解错误消息，请参阅排查 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 签名密钥，请先使用检索单点登录签名密钥操作检索签名密钥，对其进行修改，然后向 SSO 签名密钥 Feed 网址发送 PUT 请求。请确保更新后的条目中的 <id> 值与现有条目的 <id> 完全一致。如需详细了解基于 SAML 的单点登录签名密钥，请参阅为 Google Workspace 单点登录服务生成密钥和证书。

更新单点登录签名密钥时，请向 SSO 签名密钥 Feed 网址发送 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 如何支持从您网域中的用户路由出站邮件。电子邮件路由部分介绍了如何将邮件路由到其他邮件服务器。

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

如需检索出站电子邮件网关设置，请向网关 Feed 网址发送 HTTP GET，并添加 Authorization 标头，如在向 Admin Settings 服务进行身份验证中所述：

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

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

成功响应会返回 HTTP 200 OK 状态代码，以及包含电子邮件网关状态信息的 AtomPub Feed。

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

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 Feed。

如果您的请求因某种原因而失败，系统会返回不同的状态代码。如需详细了解 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 中，则将邮件传送到此目标。这类似于管理控制台的“传送电子邮件给”设置。如需详细了解前提条件以及如何使用邮件路由，请参阅电子邮件路由的网域设置。

如需发布此请求，请向电子邮件路由 Feed 网址发送 HTTP POST，并添加 Authorization 标头，如在向 Admin Settings 服务进行身份验证中所述：

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

成功响应会返回 HTTP 200 OK 状态代码，以及包含归档信息的 AtomPub Feed。

如果您的请求因某种原因而失败，系统会返回不同的状态代码。如需详细了解 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

Admin Settings API 概览 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

受众群体

开始使用

创建账号

Admin Settings API Feed 类型简介

Admin Settings API XML 请求和响应示例

管理单点登录设置

检索单点登录设置

更新单点登录设置

检索单点登录签名密钥

更新单点登录签名密钥

管理电子邮件网关和路由

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

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

管理电子邮件路由设置

端点已于 2018 年 10 月 31 日停用

Admin Settings API 概览