Esta página foi traduzida pela API Cloud Translation.

Visão geral da API Admin Settings

A API Admin Settings permite que administradores de domínios do Google Workspace recuperem e mudem as configurações dos domínios no formato de feeds da API Google Data.

Essas configurações incluem muitos dos recursos disponíveis no Admin Console do Google Workspace. 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 a um ambiente legado.

A API Admin Settings implementa o protocolo da API Google Data. A API Google Data está em conformidade com o modelo de publicação e edição do protocolo Atom Publishing (AtomPub). As solicitações HTTP do AtomPub usam a abordagem de design de transferência de estado representacional (RESTful) para serviços da Web. Para mais informações, consulte o Guia para desenvolvedores de dados do Google.

Público-alvo

Este documento é destinado a desenvolvedores que querem criar aplicativos cliente capazes de modificar e recuperar 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.

Este documento pressupõe que você entenda as ideias gerais por trás do protocolo da API Google Data e que tenha familiaridade com o console do administrador do Google Workspace. Para mais informações sobre o Admin Console, consulte Usar o Admin Console.

Primeiros passos

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 Configurações do administrador usa Contas do Google. Portanto, se você já tiver uma conta em um domínio do Google Workspace, não precisa fazer mais nada.

Sobre os tipos de feeds da API Admin Settings

Com a API Admin Settings, é possível gerenciar estas categorias de configurações de 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 do Google Workspace e outros serviços hospedados na sua organização. Especificamente ao usar o SSO, um aplicativo da Web hospedado, como o Google Workspace, redireciona os usuários ao provedor de identidade da sua organização para autenticar o login. Para mais informações, consulte Entender o SSO baseado em SAML para o Google Workspace.

A configuração do SSO envolve 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 para onde os usuários devem ser enviados para fazer login, sair e mudar as senhas. Com a API Admin Settings, é possível atualizar e recuperar essas configurações de forma programática. O Google usa a chave pública gerada para verificar essa solicitação de SSO com seu provedor de identidade e que a resposta SAML da chave privada não foi modificada durante a transmissão pela rede.

Para um breve resumo específico da API sobre o uso das configurações de SSO, receba o certificado de chave pública do seu provedor de identidade, registre a chave pública no Google e configure as definições de consulta de SSO baseadas em SAML. Para mensagens de erro, consulte Solução de problemas do 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 formatado X.509. Para mais informações sobre chaves de assinatura de Logon único baseado em SAML, consulte Gerar chaves e certificados para o serviço de Logon único do Google Workspace.
Registre-se no Google: use as configurações de logon único da API Admin Settings para registrar seu certificado de chave pública no Google.
Configure as definições de SSO: use as configurações de logon único da API Admin Settings para configurar as definições usadas na comunicação com os servidores do provedor de identidade do domínio.

Configurações de gateway e roteamento

Com esse feed, os administradores de domínio controlam o roteamento de e-mails dos domínios deles.

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. Isso é semelhante à funcionalidade de roteamento de e-mails das configurações do Gmail no Admin Console. Para mais informações, consulte Roteamento de e-mails e configuração de entrega dupla do recurso de roteamento de e-mails.

Exemplo de uma solicitação e resposta 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 do domínio mostra a sintaxe XML e HTTP completa para o corpo de uma entrada de solicitação e resposta, que é comum a cada operação:

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

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

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

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

O elemento entry da resposta do 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>

Gerenciar as configurações de Logon único

Com o recurso de Logon único (SSO) do Google Workspace, os usuários podem fazer login em vários serviços inserindo um login e uma senha apenas uma vez. 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.

Recuperando as configurações de logon único

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

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

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

Uma resposta bem-sucedida retorna um código de status HTTP 200 OK, além de 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 em que o Google Workspace envia a solicitação SAML para autenticação do usuário.
samlLogoutUri: O endereço para onde os usuários serão enviados quando fizerem logout do aplicativo da Web.
changePasswordUri: O endereço para onde os usuários serão enviados quando quiserem mudar a senha do SSO para o aplicativo da Web.
enableSSO: Ativa o SSO baseado em SAML para este domínio. Se você já tiver configurado as configurações de SSO e definido enableSSO como enableSSO=false, as configurações inseridas anteriormente ainda serão salvas.
ssoWhitelist: Uma ssoWhitelist é um endereço IP de máscara de rede no formato de roteamento entre domínios sem classe (CIDR). A ssoWhitelist determina quais usuários fazem login usando o SSO e quais fazem login usando a página de autenticação da conta 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 de 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. Informar o emissor de domínio específico determina qual subdomínio associar à solicitação. Para mais informações, consulte Como o elemento "Issuer" na solicitação SAML funciona?

Se a 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.

Atualizando 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> na entrada atualizada corresponde exatamente ao <id> da entrada atual. Inclua um cabeçalho Authorization, conforme descrito em Autenticação no serviço da API Admin Settings. Para mensagens de erro, consulte Solução de problemas do SSO.

Ao atualizar as configurações de Logon único, envie um HTTP PUT para o URL do feed geral do 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 retorna um código de status HTTP 200 OK, além de 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>

Se a 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.

Não é possível fazer mudanças nas configurações de logon único quando o cliente de destino ativou a aprovação de outra parte para ações sensíveis. As solicitações vão falhar com errorCode="1811" e reason="LegacyInboundSsoChangeNotAllowedWithMultiPartyApproval".

Como recuperar a chave de assinatura do Single Sign-On

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

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

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

Uma resposta bem-sucedida retorna um código de status HTTP 200 OK, além de 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 será retornado. Para mais informações sobre os códigos de status da API Google Data, consulte Códigos de status HTTP.

Atualizar a chave de assinatura do Single Sign-On

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

Ao atualizar a chave de assinatura do Logon único, envie um HTTP PUT para o URL do feed da chave de assinatura do 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>

Gerenciar gateway e roteamento de e-mail

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

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

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

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

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

Uma resposta bem-sucedida retorna um código de status HTTP 200 OK, além de 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.

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 será retornado. Para mais informações sobre os códigos de status da API Google Data, consulte Códigos de status HTTP.

Atualizar as 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 HTTP PUT para o URL do feed do 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:

smartHost: O endereço IP ou o nome do host do seu servidor SMTP. O Google Workspace roteia os e-mails enviados para esse servidor.
smtpMode: O valor padrão é SMTP. Outro valor, SMTP_TLS, protege uma conexão com TLS ao entregar a mensagem.

Uma resposta bem-sucedida retorna um código de status HTTP 200 OK, além do feed AtomPub com o status das configurações do gateway de e-mail.

Se a 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.

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 destino é o nome do host ou o endereço IP do servidor de e-mail SMTP-In para onde o e-mail está sendo encaminhado. O nome do host ou endereço IP precisa ser resolvido para o Google. Para mais detalhes sobre como resolver nomes de host de e-mail, consulte Fazer um piloto do Google Workspace com roteamento de e-mail.

routeRewriteTo

Se for "true", o campo to: do envelope SMTP da mensagem será alterado para o nome do host de destino (user@hostname de destino), e a mensagem será entregue ao endereço do usuário no servidor de e-mail de destino. Se false, o e-mail será entregue no endereço to: da mensagem original (user@hostname original) no servidor de e-mail de destino. Isso é semelhante à configuração "Mudar envelope SMTP" do Admin Console. Para mais informações, consulte Configurações de domínio para roteamento de e-mail.

routeEnabled

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

bounceNotifications

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

accountHandling

Essa configuração determina como diferentes tipos de usuários no domínio são afetados pelo encaminhamento de e-mail:

allAccounts: entregue todos os e-mails neste destino.
provisionedAccounts -- Entregue o e-mail neste destino se o usuário existir no Google Workspace.
unknownAccounts -- Entregue o e-mail neste 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 pré-requisitos e como usar o roteamento de e-mail, consulte Configurações de 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 Autenticação no serviço de configurações do administrador:

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

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

Se a 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.

Desativação dos endpoints em 31 de outubro de 2018

Descontinuamos os seguintes endpoints como parte deste anúncio. Elas foram desativadas 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

Visão geral da API Admin Settings Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Público-alvo

Primeiros passos

Como criar uma conta

Sobre os tipos de feeds da API Admin Settings

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

Gerenciar as configurações de Logon único

Recuperando as configurações de logon único

Atualizando as configurações de logon único

Como recuperar a chave de assinatura do Single Sign-On

Atualizar a chave de assinatura do Single Sign-On

Gerenciar gateway e roteamento de e-mail

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

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

Gerenciar as configurações de roteamento de e-mail

Desativação dos endpoints em 31 de outubro de 2018

Visão geral da API Admin Settings