Esta página foi traduzida pela API Cloud Translation.

Visão geral da API Admin Settings

A API Admin Settings permite que os administradores dos domínios do Google Workspace recuperem e alterem as configurações dos domínios na forma de feeds da API Google Data.

Essas configurações incluem vários dos recursos disponíveis no Admin Console do Google Workspace. Os exemplos de uso dessa API incluem a criação de um painel de controle personalizado ou a integração de domínios do Google Workspace em um ambiente legado.

A API Admin Settings implementa o protocolo da API Google Data. A API Google Data obedece ao modelo de publicação e edição do Atom Publishing Protocol (AtomPub). As solicitações HTTP do AtomPub usam a abordagem de design Representation Set Set Transfer (RESTful) para serviços da Web. Para mais informações, consulte o Guia do desenvolvedor de dados do Google.

Público-alvo

Este documento é destinado aos desenvolvedores que querem criar aplicativos cliente que modifiquem e recuperem informações sobre domínios do Google Workspace. Ele fornece exemplos das interações básicas da API Admin Settings usando XML e HTTP brutos.

Ele pressupõe que você entende as ideias gerais do protocolo da API Google Data e conhece o Admin Console do Google Workspace. Veja mais informações sobre o Admin Console em Usar o Admin Console.

Como começar

Como criar uma conta

A API Admin Settings está ativada para contas do Google Workspace. Inscreva-se em uma conta do Google Workspace para fins de teste. O serviço de Configurações do administrador usa as Contas do Google. Portanto, se você já tem uma conta em um domínio do Google Workspace, não precisa fazer mais nada.

Sobre os tipos de feed da API Admin Settings

A API Admin Settings permite gerenciar estas categorias de configurações do domínio:

Configurações de Logon único

O Logon único (SSO) baseado em SAML permite que os usuários usem o mesmo login e senha nos serviços hospedados do Google Workspace e em outros serviços da organização. Especificamente, ao usar o SSO, um app da Web hospedado, como o Google Workspace, redireciona os usuários para o provedor de identidade da sua organização. Veja informações detalhadas em Noções básicas sobre o SSO baseado em SAML no Google Workspace.

Para configurar o SSO, é preciso inserir as informações necessárias para que o serviço do Google Workspace se comunique com o provedor de identidade que armazena as informações de login dos seus usuários e para definir os links de login dos usuários, bem como para alterar as senhas deles. A API Admin Settings permite atualizar e recuperar essas configurações de maneira programática. O Google usa sua chave pública gerada para verificar a solicitação de SSO com seu provedor de identidade e se a resposta SAML de chave privada não foi modificada durante a transmissão de rede.

Para ver um breve resumo específico das APIs de uso das configurações de SSO, consiga o certificado de chave pública do seu provedor de identidade, registre a chave pública no Google e defina as configurações de consulta de SSO baseada em SAML. Para mensagens de erro, consulte Solução de problemas de SSO:

Gere suas chaves: com seu provedor de identidade, gere um conjunto de chaves públicas e privadas usando os algoritmos DSA ou RSA. A chave pública está em um certificado no formato X.509. Veja mais informações sobre as chaves de assinatura de Logon único baseadas em SAML em Como gerar chaves e certificados para o serviço de Logon único do Google Workspace.
Registrar-se no Google: use as configurações de Logon único da API Admin Settings para registrar seu certificado de chave pública no Google.
Defina suas configurações de SSO: use as configurações de Logon único da API Admin Settings para definir as configurações usadas para a comunicação com os servidores do provedor de identidade do domínio.

Configurações de gateway e roteamento

Esse feed permite que os administradores controlem o roteamento de e-mails nos seus domínios.

Com essas operações, os administradores podem especificar as configurações de roteamento de e-mail no nível do domínio. Isso é parecido com a funcionalidade de roteamento de e-mail das configurações do Gmail no Admin Console. Para mais informações, consulte Roteamento de e-mail e configuração de entrega dupla do recurso de roteamento de e-mail.

Exemplo de solicitação e resposta de XML da API Admin Settings

Este documento fornece exemplos de código de solicitações e respostas básicas da API Admin Settings usando XML e HTTP brutos. Este exemplo de idioma padrão mostra a sintaxe completa de XML e HTTP para o corpo de uma entrada de solicitação e resposta comum a cada operação:

Para mudar a configuração do gateway de e-mail de saída do domínio, envie um PUT HTTP para o URL do feed de gateway:

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

O idioma padrão do domínio PUT da solicitação 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>

Exceto pelas propriedades e valores específicos da operação, os elementos atom:property representam um único par de chave-valor que contém informações sobre uma propriedade que você quer recuperar ou atualizar. Elas são comuns a todos os corpos de solicitações da API Admin Settings.

O elemento entry da resposta de idioma padrão do domínio retorna as propriedades smartHost e smtpMode com a sintaxe XML comum a todos os corpos de resposta da API Admin Settings:

<?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>

Como gerenciar as configurações de Logon único

O recurso de Logon único (SSO) do Google Workspace permite que os usuários façam login em vários serviços sem precisar digitar um login e uma senha. Essa senha é armazenada pelo provedor de identidade do domínio, não pelo Google Workspace. Veja mais informações na página de SSO da Central de Ajuda. As seções a seguir demonstram o formato XML usado para as configurações de Logon único.

Como recuperar as configurações de Logon único

Para recuperar as configurações de Logon único, envie um GET HTTP para o URL de feed geral de SSO e inclua um cabeçalho Authorization conforme descrito em Como autenticar no serviço Configurações do administrador. Para mensagens de erro, consulte Solução de problemas de SSO:

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

Esta operação não tem parâmetros no corpo da solicitação.

Uma resposta bem sucedida retornará um código de status HTTP 200 OK, junto com um feed AtomPub com as configurações de SSO do domínio.

O XML de resposta GET retorna as propriedades samlSignonUri, samlLogoutUri, changePasswordUri, enableSSO, ssoWhitelist e 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>

As propriedades incluem:

SAMLSignonUri: O URL do provedor de identidade para onde o Google Workspace envia a solicitação SAML para a autenticação do usuário.
samlLogoutUri: O endereço para onde os usuários vão ser direcionados ao sair do aplicativo da Web.
changePasswordUri: O endereço para onde os usuários vão ser direcionados quando quiserem mudar a senha de SSO do app da Web.
AtivarSSO: Ativa o SSO baseado em SAML neste domínio. Se você já tiver definido as configurações do SSO e depois tiver definido enableSSO como enableSSO=false, as definições anteriores vão ser salvas.
lista de permissões: Um ssoLIST é um endereço IP de máscara de rede no formato CIDR (Classless Inter-Domain Routing) O ssoLista de usuários determina quais usuários fazem login usando o SSO e quais usuários fazem login usando a página de autenticação de contas do Google Workspace. Se nenhuma máscara for especificada, todos os usuários farão login usando o SSO. Para mais informações, consulte Como as máscaras de rede funcionam.
useDomainSpecificIssuer: Um emissor específico do domínio pode ser usado na solicitação SAML ao provedor de identidade. Embora não seja necessário para a maioria das implantações de SSO, esse recurso é útil em grandes empresas que usam um único provedor de identidade para autenticar uma organização inteira com vários subdomínios. O emissor do domínio específico determina qual subdomínio associar à solicitação. Para mais informações, consulte Como funciona o elemento emissor na solicitação SAML?.

Se a sua solicitação falhar por algum motivo, um código de status diferente será retornado. Para mais informações sobre os códigos de status da API Google Data, consulte Códigos de status HTTP.

Como atualizar as configurações de Logon único

Para atualizar as configurações de SSO de um domínio, primeiro recupere as configurações de SSO usando a operação Recuperar configurações de Logon único, modifique-as e envie uma solicitação PUT para o URL do feed de SSO. Verifique se o valor <id> está na entrada atualizada que corresponde exatamente ao <id> da entrada atual. Inclua um cabeçalho Authorization conforme descrito em Como autenticar no serviço da API Admin Settings. Para mensagens de erro, consulte Solução de problemas de SSO.

Ao atualizar as configurações de Logon único, envie um PUT HTTP para o URL do feed geral de SSO:

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

O corpo XML da solicitação PUT é:

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

Uma resposta bem sucedida retornará um código de status HTTP 200 OK, junto com um feed AtomPub com as configurações de SSO.

O XML de resposta PUT é:

<?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>

Como recuperar a chave de assinatura de logon único

Para recuperar a chave de assinatura de Logon único, envie um GET HTTP para o URL do feed de chave de assinatura de SSO e inclua um cabeçalho Authorization, conforme descrito em Como autenticar no serviço Configurações do administrador. Para mensagens de erro, consulte Solução de problemas de SSO:

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

Esta operação não tem parâmetros no corpo da solicitação.

Uma resposta bem sucedida retornará um código de status HTTP 200 OK, junto com um feed AtomPub com a chave de assinatura.

O XML de resposta GET retorna a propriedade 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>

Como atualizar a chave de assinatura de Logon único

Para atualizar a chave de assinatura de SSO do domínio, primeiro recupere a chave de assinatura usando a operação Recuperar chave de assinatura de Logon único, modifique-a e envie uma solicitação PUT ao URL do feed da chave de assinatura de SSO. Verifique se o valor <id> está na entrada atualizada que corresponde exatamente ao <id> da entrada atual. Veja mais informações sobre as chaves de assinatura de Logon único baseadas em SAML em Como gerar chaves e certificados para o serviço de Logon único do Google Workspace.

Ao atualizar a chave de assinatura de Logon único, envie um HTTP PUT para o URL do feed da chave de assinatura de SSO:

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

O XML da solicitação PUT é:

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

Como gerenciar o gateway e o roteamento de e-mails

A seção "Gateway de e-mail de saída" mostra como a API Admin Settings oferece suporte ao roteamento de e-mails enviados dos usuários no seu domínio. A seção de roteamento de e-mail mostra como rotear mensagens para outro servidor de e-mail.

Como recuperar configurações de gateway de e-mail de saída

Para recuperar as configurações do gateway de e-mail de saída, envie um GET HTTP para o URL do feed de gateway e inclua um cabeçalho Authorization conforme descrito em Como autenticar no serviço Configurações do administrador:

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

Esta operação não tem parâmetros no corpo da solicitação.

Uma resposta bem sucedida retornará um código de status HTTP 200 OK, junto com um feed AtomPub com as informações de status do gateway de e-mail.

A resposta GET retorna as propriedades smartHost e smtpMode. Para mais informações sobre essas propriedades, consulte Como atualizar as configurações do gateway de e-mail de saída.

Veja um exemplo de possível resposta:

<?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>

Atualizando configurações do gateway de e-mail de saída

Para atualizar a configuração do gateway de e-mail de saída de um domínio, envie uma solicitação PUT HTTP para o URL do feed de gateway:

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

O XML da solicitação PUT é:

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

As propriedades da solicitação são:

host inteligente: O endereço IP ou o nome do host do servidor SMTP. O Google Workspace encaminha mensagens de saída para este servidor.
Modo smtp: O valor padrão é SMTP. Outro valor, SMTP_TLS, protege uma conexão com o TLS ao entregar a mensagem.

Uma resposta bem sucedida retornará um código de status HTTP 200 OK, junto com o feed AtomPub com o status de configurações do gateway de e-mail.

Como gerenciar as configurações de roteamento de e-mail

Primeiro, crie uma solicitação 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>

As propriedades da solicitação são:

routeDestination

Esse é o nome do host ou endereço IP do servidor de e-mail SMTP-In para onde o e-mail está sendo roteado. O nome do host ou endereço IP precisa ser resolvido para o Google. Veja mais detalhes sobre como resolver nomes de host de e-mail em Pilotar o Google Workspace com roteamento de e-mail.

routeRewriteTo

Se verdadeiro, o campo to: do envelope SMTP da mensagem será alterado para o nome do host de destino (nome do host do usuário@destino) e a mensagem será entregue a esse endereço de usuário no servidor de e-mail de destino. Se false, o e-mail é entregue no endereço de e-mail to: da mensagem original (usuário@nome do host original) no servidor de e-mail de destino. Isso é parecido com a configuração "Alterar o envelope SMTP" do Admin Console. Veja mais informações em Configurações do domínio para roteamento de e-mail.

routeEnabled

Se true, a funcionalidade de roteamento de e-mail está ativada. Se for false, a funcionalidade será desativada.

Notificações de devolução

Se true, o Google Workspace vai poder enviar notificações de devolução ao remetente quando uma entrega falhar.

Gerenciamento de contas

Esta configuração determina como diferentes tipos de usuário no domínio são afetados pelo roteamento de e-mail:

allAccounts: entregue todos os e-mails para este destino.
provisionedAccounts: entregue e-mails para esse destino se o usuário existir no Google Workspace.
unknownAccounts: entregue e-mails para esse destino se o usuário não existir no Google Workspace. Isso é semelhante à configuração "E-mail de entrega para" do Admin Console. Veja mais informações sobre os pré-requisitos e como usar o roteamento de e-mail em Configurações do domínio para o roteamento de e-mail. ~ Para publicar essa solicitação, envie um POST HTTP para o URL do feed de roteamento de e-mail e inclua um cabeçalho Authorization conforme descrito em Como autenticar no serviço Configurações do administrador:

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

Uma resposta bem sucedida retornará um código de status HTTP 200 OK, junto com um feed AtomPub com as informações de arquivo.

Desativação do Endpoints em 31 de outubro de 2018

Descontinuamos os endpoints a seguir como parte deste comunicado. Ela foi desativada em 31 de outubro de 2018 e não está mais disponível.

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