Visão geral da API Admin Settings

Com a API Admin Settings, os administradores de domínios do Google Workspace podem recuperar e alterar as configurações dos domínios na forma de feeds da API Google Data.

Essas configurações do domínio incluem muitos dos recursos disponíveis no Admin Console do Google Workspace. Exemplos de usos dessa API incluem a criação de um painel de controle personalizado ou a integração de domínios do Google Workspace a um ambiente legado atual.

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

Público-alvo

Este documento é destinado aos desenvolvedores que querem criar aplicativos clientes que podem modificar e recuperar informações sobre os domínios do Google Workspace. Ele fornece exemplos das interações básicas da API de configurações de administrador usando XML e HTTP brutos.

Neste documento, presumimos que você conhece os princípios gerais por trás do protocolo da API Google Data e que conhece bem o Admin Console do Google Workspace. Para mais informações sobre o Admin Console, consulte Usar seu Admin Console.

Vamos começar

Como criar uma conta

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

Observação :defina as configurações do domínio usando a API Admin Settings e use a API Email Settings para definir as configurações de e-mail dos usuários.

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

Com o Logon único (SSO) baseado em SAML, os usuários podem usar o mesmo login e senha para os serviços hospedados no Google Workspace e nos outros serviços da sua organização. Mais especificamente, quando o SSO é usado, um aplicativo da Web hospedado, como o Google Workspace, redireciona os usuários ao provedor de identidade da sua organização para autenticá-los no momento do login. Veja informações detalhadas em Noções básicas sobre o SSO baseado em SAML para o Google Workspace.

Para configurar o SSO, você precisa 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 usuários, além de configurar os links que as pessoas devem acessar para fazer login, sair e alterar senhas. A API de configurações de administrador permite que você atualize e recupere essas configurações de forma programática. O Google usa a chave pública gerada para verificar essa solicitação de SSO com o provedor de identidade e se a resposta SAML da chave privada não foi modificada durante a transmissão da rede.

Para ver um breve resumo específico da API sobre como usar as configurações de SSO, solicite 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. Veja mensagens de erro em 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. Para mais informações sobre chaves de assinatura de Logon único baseadas em SAML, consulte 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 de configurações de administrador para registrar o seu certificado de chave pública no Google.
• Defina suas configurações de SSO – Use as configurações de Logon único da API de configurações do administrador para definir as configurações usadas para se comunicar com os servidores do provedor de identidade do domínio.

Observação :no caso de protocolos que não usam um fluxo de login baseado na Web, como alguns clientes de e-mail POP/IMAP, os usuários fazem login diretamente com o nome de usuário e a senha do Google Workspace.

Configurações de gateway e roteamento

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

As operações de roteamento de e-mail permitem que os administradores especifiquem as configurações de roteamento de e-mail no nível do domínio. Esse recurso é semelhante à 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 XML da API de configurações de administrador

Este documento fornece exemplos de código de solicitações e respostas básicas da API de configurações de administrador usando XML e HTTP brutos. Este exemplo de idioma padrão do domínio 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 alterar a configuração de gateway de e-mail de saída do domínio, envie um HTTP PUT para o URL de feed de gateway:

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

O idioma padrão do domínio PUT XML da solicitação AtomPub entry é:

<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 contendo informações sobre uma propriedade que você quer recuperar ou atualizar. Isso é comum para todos os corpos de solicitação da API de configurações de administrador.

O elemento entry da resposta de idioma padrão do domínio retorna as propriedades smartHost e smtpMode, além da 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 configurações de Logon único

Com o recurso de Logon único (SSO) do Google Workspace, os usuários precisam digitar um login e uma senha apenas uma vez para fazer login em vários serviços. Essa senha é armazenada pelo provedor de identidade do domínio, não pelo Google Workspace. Para mais informações, consulte a 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 configurações de logon único

Para recuperar as configurações de Logon único, envie um HTTP GET para o URL de feed geral de SSO e inclua um cabeçalho Authorization, conforme descrito em Como autenticar no serviço de configurações de administrador. Para ver 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 serão direcionados quando saírem do aplicativo da Web.

changePasswordUri

O endereço para onde os usuários serão enviados quando quiserem alterar a senha do SSO no aplicativo da Web.

ativarSSO

Ativa o SSO baseado em SAML para este domínio. Se você já tiver definido as configurações de SSO e definir enableSSO como enableSSO=false, as configurações inseridas vão ser salvas.

ssochecklist

Um ssochecklist é um endereço IP de máscara de rede no formato de roteamento entre domínios sem classe (CIDR). O ssochecklist determina quais usuários fazem login usando o SSO e na página de autenticação da conta do Google Workspace. Se nenhuma máscara for especificada, todos os usuários farão login com o SSO. Para mais informações, consulte Como funcionam as máscaras de rede.

useDomainSpecificIssuer

Um emissor específico do domínio pode ser usado na solicitação SAML para o 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. Fornecer ao emissor do domínio específico determina qual subdomínio será associado à solicitação. Para mais informações, consulte Como funciona o elemento emissor na solicitação SAML?.

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

Atualizando configurações de logon único

Para atualizar as configurações de SSO de um domínio, primeiro recupere essas configurações usando a operação Como 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 corresponde exatamente ao <id> da entrada existente. 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 HTTP PUT para o URL de 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 da 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>

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

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 de feed da chave de assinatura de SSO e inclua um cabeçalho Authorization, conforme descrito em Como autenticar no serviço de configurações de administrador. Para ver 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>

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

Como atualizar a chave de assinatura de logon único

Para atualizar a chave de assinatura de SSO de um domínio, primeiro recupere a chave de assinatura usando a operação Como recuperar a chave de assinatura de logon único, modifique-a e envie uma solicitação PUT para o URL de feed da chave de assinatura de SSO. Verifique se o valor <id> está na entrada atualizada corresponde exatamente ao <id> da entrada existente. Para mais informações sobre chaves de assinatura de Logon único baseadas em SAML, consulte 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>

Observação :a propriedade signingKey é obrigatória para essa solicitação.

Como gerenciar o gateway de e-mail e o roteamento

A seção de gateway de e-mail de saída mostra como a API de configurações do administrador oferece suporte para o roteamento de e-mails enviados de 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 de gateway de e-mail de saída, envie um GET HTTP para o URL de feed de gateway e inclua um cabeçalho Authorization, conforme descrito em Como autenticar no serviço de configurações de 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.

Observação :você precisa ter uma edição qualificada do Google Workspace para usar o recurso de gateway de saída do Google Workspace.

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 configurações de gateway de e-mail de saída.

Um exemplo de resposta possível é:

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

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

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

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

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

Observação :você precisa ter uma edição qualificada do Google Workspace para usar o recurso de gateway de saída do Google Workspace.

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 os e-mails de saída para esse servidor.

Modo smtp

O valor padrão é SMTP. Outro valor, SMTP_TLS, protege uma conexão com TLS ao entregar a mensagem.

Observação: siga as instruções do seu agente de transferência para configurar e-mails redirecionados enviados do Google Workspace.

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

Observação :envie um e-mail do Google Workspace a um usuário fora do seu domínio para verificar se os e-mails enviados pelo gateway estão funcionando depois das mudanças.

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

Gerenciar 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

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

routeRewriteTo

Se for verdadeiro, o campo to: do envelope SMTP da mensagem será alterado para o nome do host de destino (usuário@nome do host de destino), e a mensagem será entregue para esse endereço de usuário no servidor de e-mail de destino. Se false, o e-mail será entregue para o endereço de e-mail to: da mensagem original (usuário@nome do host original) no servidor de e-mail de destino. É semelhante à configuração "Alterar 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 será ativada. Se for false, a funcionalidade será desativada.

rejeição de notificações

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

Processamento de conta

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

• allAccounts: entregar todos os e-mails para esse destino.
• provisionedAccounts: entregue os 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. Para mais informações sobre os pré-requisitos e como usar o roteamento de e-mail, consulte Configurações do domínio para roteamento de e-mail. ~ Para publicar essa solicitação, envie um HTTP POST para o URL do feed de roteamento de e-mail e inclua um cabeçalho Authorization, conforme descrito em Como autenticar no serviço de configurações de 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.

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

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

Como parte deste aviso, suspendemos o uso dos endpoints abaixo. Eles foram desativados em 31 de outubro de 2018 e não estão mais disponíveis.

• 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