API de configuración del administrador de Google Workspace

Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

La API de configuración de administrador de Google Workspace permite que los administradores de los dominios de Google Workspace recuperen y cambien la configuración de sus dominios en forma de feeds de la API de datos de Google.

Esta configuración incluye muchas de las funciones disponibles en la Consola del administrador de Google Workspace. Algunos ejemplos de usos de esta API incluyen la creación de un panel de control personalizado o la integración de dominios de Google Workspace en un entorno heredado existente.

La API de configuración de administrador implementa el protocolo de la API de datos de Google. La API de datos de Google cumple con el modelo de publicación y edición de protocolo Atom Publishing Protocol (AtomPub). Las solicitudes HTTP de AtomPub usan el enfoque de diseño de transferencia de conjuntos representativos (RESTful) para los servicios web. Para obtener más información, consulta la Guía para desarrolladores de datos de Google.

Público

Este documento está dirigido a desarrolladores que desean escribir aplicaciones cliente que pueden modificar y recuperar información sobre los dominios de Google Workspace. Proporciona ejemplos de las interacciones básicas de la API de configuración de administrador con XML y HTTP sin procesar.

En este documento, se asume que comprende las ideas generales detrás del protocolo de la API de datos de Google y que está familiarizado con la Consola del administrador de Google Workspace. Para obtener más información sobre la Consola del administrador, consulte Cómo usar la Consola del administrador.

Cómo comenzar

Cómo crear una cuenta

La API de Admin de Google Workspace está habilitada para las cuentas de Google Workspace. Regístrate para obtener una cuenta de Google Workspace con fines de prueba. El servicio de configuración de administrador usa Cuentas de Google, así que si ya tienes una cuenta en un dominio de Google Workspace, eso es todo.

Acerca de los tipos de feed de configuración de administrador

La API de Admin Settings te permite administrar las siguientes categorías de configuración de dominio:

Configuración de inicio de sesión único

El inicio de sesión único (SSO) basado en SAML permite que los usuarios usen el mismo acceso y la misma contraseña para los servicios alojados en Google Workspace y para otros servicios que usted aloje en su organización. Específicamente, cuando se usa el SSO, una aplicación web alojada, como Google Workspace, redirecciona a los usuarios al proveedor de identidad de tu organización para autenticar a los usuarios cuando acceden. Si deseas obtener información detallada, consulta Información sobre el SSO basado en SAML para Google Workspace.

Configurar el SSO implica ingresar la información necesaria para que el servicio de Google Workspace se comunique con el proveedor de identidad que almacena la información de acceso de los usuarios, además de configurar los vínculos a los que se debe enviar a los usuarios para acceder, salir y cambiar sus contraseñas. La API de Admin Settings te permite actualizar y recuperar esta configuración de manera programática. Google usa tu clave pública generada para verificar esta solicitud de SSO con tu proveedor de identidad y que la respuesta de SAML de clave privada no se haya modificado durante la transmisión de la red.

Para obtener un resumen breve de la API sobre cómo usar la configuración de SSO, obtén tu certificado de clave pública de tu proveedor de identidad, registra la clave pública con Google y configura la consulta de SSO basada en SAML. Para los mensajes de error, consulta Solución de problemas de SSO:

  • Genera tus claves: con tu proveedor de identidad, genera un conjunto de claves públicas y privadas con los algoritmos de DSA o RSA. La clave pública está en un certificado con formato X.509. Para obtener más información sobre las claves de firma de inicio de sesión único basadas en SAML, consulta Genera claves y certificados para el servicio de inicio de sesión único de Google Workspace.
  • Regístrate con Google: utiliza la configuración de inicio de sesión único de la API para registrar tu certificado de clave pública con Google.
  • Establece tu configuración de SSO: utiliza la configuración del inicio de sesión único de la API para establecer la configuración utilizada para la comunicación con los servidores del proveedor de identidad del dominio.

Configuración de puerta de enlace y enrutamiento

Este feed permite a los administradores de dominio controlar el enrutamiento de correo electrónico de sus dominios.

Las operaciones de enrutamiento de correo electrónico permiten que los administradores especifiquen la configuración de enrutamiento de correo electrónico a nivel del dominio. Esto es similar a la función de enrutamiento de correo electrónico de la configuración de Gmail en la Consola del administrador. Para obtener más información, consulta Enrutamiento de correo electrónico y Configuración de la entrega dual de la función de enrutamiento de correo electrónico.

Ejemplo de una solicitud y respuesta XML de la API de Admin Settings

En este documento, se proporcionan ejemplos de código de solicitudes y respuestas básicas de la API de configuración de administrador mediante XML y HTTP sin procesar. Este ejemplo de idioma predeterminado del dominio muestra la sintaxis XML y HTTP completa del cuerpo de una solicitud y una entrada de respuesta, que es común a cada operación:

Para cambiar la configuración de la puerta de enlace de correo electrónico saliente del dominio, envía un HTTP PUT a la URL del feed de la puerta de enlace:

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

El XML PUT de la solicitud PUT del idioma predeterminado del dominio es el siguiente:

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

Excepto por las propiedades y los valores específicos de la operación, los elementos atom:property representan un solo par clave-valor que contiene información sobre una propiedad que deseas recuperar o actualizar. Estos son comunes a todos los cuerpos de solicitudes de la API de Admin Settings.

El elemento entry de respuesta de idioma predeterminado del dominio muestra las propiedades smartHost y smtpMode junto con la sintaxis XML común a todos los cuerpos de respuesta de la API de 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>

Administra la configuración del inicio de sesión único

La función de inicio de sesión único (SSO) de Google Workspace permite a los usuarios acceder a varios servicios y solo tiene que ingresar una vez su nombre de usuario y contraseña. Esta contraseña se almacena en el proveedor de identidad del dominio, no en Google Workspace. Para obtener más información, consulta la página de SSO del Centro de ayuda. En las siguientes secciones, se muestra el formato XML que se usa para la configuración del inicio de sesión único.

Recuperando configuración de inicio de sesión único

Para recuperar la configuración de inicio de sesión único, envía un HTTP GET a la URL del feed general de SSO y, además, incluye un encabezado Authorization como se describe en Cómo autenticar el servicio de configuración de administrador. Para mensajes de error, consulte Solución de problemas de SSO:

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

Esta operación no tiene parámetros en el cuerpo de la solicitud.

Una respuesta correcta muestra un código de estado 200 OK HTTP, junto con un feed AtomPub con la configuración de SSO del dominio.

El XML de respuesta GET muestra las propiedades samlSignonUri, samlLogoutUri, changePasswordUri, enableSSO, ssoWhitelist y 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>

Las propiedades incluyen lo siguiente:

samlSignonUri
La URL del proveedor de identidad a la que Google Workspace envía la solicitud de autenticación de usuarios de SAML.
samlLogoutUri
La dirección a la que se enviará a los usuarios cuando salgan de la aplicación web
CambiarContraseñaUri
La dirección a la que se enviará a los usuarios cuando quieran cambiar su contraseña de SSO para la aplicación web
habilitar SSO
Habilita el SSO basado en SAML para este dominio. Si anteriormente configuraste la configuración de SSO y, luego, estableciste enableSSO en enableSSO=false, se seguirá guardando la configuración que ingresaste anteriormente.
lista blanca de soso
Una ssoWhitelist es una dirección IP de máscara de red en formato de enrutamiento entre dominios sin clases (CIDR). ssoWhitelist determina qué usuarios acceden con el SSO y qué usuarios acceden con la página de autenticación de la cuenta de Google Workspace. Si no se especifican máscaras, todos los usuarios accederán usando el SSO. Para obtener más información, consulta Cómo funcionan las máscaras de red.
useDomainSpecificIssuer
Se puede usar una entidad emisora específica del dominio en la solicitud de SAML al proveedor de identidad. Aunque no es necesaria para la mayoría de las implementaciones de SSO, esta función es útil en empresas grandes que utilizan un único proveedor de identidad para autenticar una organización completa con varios subdominios. Otorgar al emisor del dominio específico determina qué subdominio se asociará con la solicitud. Para obtener más información, consulta ¿Cómo funciona el elemento emisor en la solicitud de SAML?

Si, por algún motivo, tu solicitud falla, se mostrará un código de estado diferente. Para obtener más información sobre los códigos de estado de la API de datos de Google, consulte Códigos de estado de HTTP.

Actualizando la configuración del inicio de sesión único

Para actualizar la configuración de SSO de un dominio, primero debes recuperar la configuración de SSO con la operación Recuperación de configuración de inicio de sesión único, modificarla y, luego, enviar una solicitud PUT a la URL del feed de SSO. Asegúrate de que el valor <id> esté en la entrada actualizada y coincida exactamente con el <id> de la entrada existente. Incluye un encabezado Authorization como se describe en Autentica el servicio de configuración de administrador. Para mensajes de error, consulte Solución de problemas de SSO.

Cuando actualice la configuración de inicio de sesión único, envíe un PUT en HTTP a la URL del feed general de SSO:

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

El cuerpo XML de la solicitud PUT es el siguiente:

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

Una respuesta correcta muestra un código de estado HTTP 200 OK, junto con un feed AtomPub con la configuración de SSO.

El XML de respuesta PUT es el siguiente:

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

Si, por algún motivo, tu solicitud falla, se mostrará un código de estado diferente. Para obtener más información sobre los códigos de estado de la API de datos de Google, consulte Códigos de estado de HTTP.

Recupera la clave de acceso único

Para recuperar la clave de firma del inicio de sesión único, envía un GET HTTP a la URL del feed de la clave de firma de SSO y, además, incluye un encabezado Authorization como se describe en Cómo autenticar el servicio de configuración de administrador. Para mensajes de error, consulte Solución de problemas de SSO:

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

Esta operación no tiene parámetros en el cuerpo de la solicitud.

Una respuesta correcta muestra un código de estado HTTP 200 OK, junto con un feed AtomPub y la clave de firma.

El XML de respuesta GET muestra la propiedad 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>

Si, por algún motivo, tu solicitud falla, se mostrará un código de estado diferente. Para obtener más información sobre los códigos de estado de la API de datos de Google, consulte Códigos de estado de HTTP.

Actualiza la clave de acceso único

Para actualizar la clave de firma de SSO de un dominio, primero debes recuperar la clave con la operación de recuperación de la clave de acceso único, modificarla y, luego, enviar una solicitud PUT a la URL del feed de la clave de firma de SSO. Asegúrate de que el valor <id> esté en la entrada actualizada y coincida exactamente con el <id> de la entrada existente. Para obtener más información sobre las claves de firma de inicio de sesión único basadas en SAML, consulta Genera claves y certificados para el servicio de inicio de sesión único de Google Workspace.

Cuando actualices la clave de firma del inicio de sesión único, envía un PUT HTTP a la URL del feed de la clave de firma de SSO:

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

El archivo XML de solicitud PUT es el siguiente:

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

Administra la puerta de enlace y el enrutamiento del correo electrónico

La sección de la puerta de enlace de correo electrónico saliente muestra cómo la API admite el enrutamiento de correo saliente de los usuarios de su dominio. La sección de enrutamiento de correo electrónico muestra cómo enrutar mensajes a otro servidor de correo electrónico.

Recuperando la configuración de la puerta de enlace de correo electrónico saliente

Para recuperar la configuración de la puerta de enlace de correo electrónico saliente, envía un GET HTTP a la URL del feed de la puerta de enlace y, luego, incluye un encabezado Authorization como se describe en Cómo autenticar el servicio de configuración de administrador:

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

Esta operación no tiene parámetros en el cuerpo de la solicitud.

Una respuesta correcta muestra un código de estado HTTP 200 OK, junto con un feed AtomPub y la información de estado de la puerta de enlace de correo electrónico.

La respuesta GET muestra las propiedades smartHost y smtpMode. Para obtener más información sobre estas propiedades, consulta Actualiza la configuración de la puerta de enlace de correo electrónico saliente.

Este es un ejemplo de una posible respuesta:

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

Si, por algún motivo, tu solicitud falla, se mostrará un código de estado diferente. Para obtener más información sobre los códigos de estado de la API de datos de Google, consulte Códigos de estado de HTTP.

Actualizando configuración de puerta de enlace de correo electrónico saliente

Para actualizar la configuración de la puerta de enlace de correo electrónico saliente de un dominio, envía una solicitud PUT HTTP a la URL del feed de la puerta de enlace:

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

El archivo XML de solicitud PUT es el siguiente:

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

Las propiedades de la solicitud son las siguientes:

host inteligente
La dirección IP o el nombre de host del servidor SMTP. Google Workspace enruta el correo electrónico saliente a este servidor.
modosmtp
El valor predeterminado es SMTP. Otro valor, SMTP_TLS, asegura una conexión con TLS cuando se entrega el mensaje.

Una respuesta correcta muestra un código de estado HTTP 200 OK, junto con el feed AtomPub y el estado de la configuración de la puerta de enlace de correo electrónico.

Si, por algún motivo, tu solicitud falla, se mostrará un código de estado diferente. Para obtener más información sobre los códigos de estado de la API de datos de Google, consulte Códigos de estado de HTTP.

Cómo administrar la configuración de enrutamiento de correo electrónico

Primero, crea una solicitud 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>

Las propiedades de la solicitud son las siguientes:

Destino de ruta
Este destino es el nombre de host o la dirección IP del servidor de correo electrónico SMTP en el que se enruta el correo electrónico. El nombre de host o la dirección IP deben resolverse para Google. Para obtener más detalles sobre cómo resolver los nombres de host de correo electrónico, consulta Pilote Google Workspace con enrutamiento de correo electrónico.
rutaRewriteTo
Si el valor es verdadero, el campo to: del sobre del SMTP del mensaje se cambia al nombre de host de destino (nombredeusuario@destino) y el mensaje se entrega a esta dirección de usuario en el servidor de correo electrónico de destino. Si es false, el correo electrónico se envía a la dirección de correo electrónico del mensaje original to: (usuario@nombre de host original) en el servidor de correo electrónico de destino. Esto es similar a la configuración de "Cambiar el sobre SMTP" de la Consola del administrador. Para obtener más información, consulte Configuración de dominio para el enrutamiento de correo electrónico.
Ruta habilitada
Si el valor es true, la funcionalidad de enrutamiento de correo electrónico está habilitada. Si es false, la funcionalidad está inhabilitada.
Notificaciones de rebote
Si el valor es true, Google Workspace está habilitado para enviar notificaciones de rebote al remitente cuando falla una entrega.
manejo de la cuenta

Esta configuración determina cómo el enrutamiento de correo electrónico afecta a los diferentes tipos de usuarios del dominio:

  • allAccounts: envía todos los correos electrónicos a este destino.
  • provisionedAccounts: Envía correos electrónicos a este destino si el usuario existe en Google Workspace.
  • unknownAccounts: Envía correos electrónicos a este destino si el usuario no existe en Google Workspace. Esto es similar a la configuración de "Correo electrónico de entrega de la Consola del administrador". Para obtener más información sobre los requisitos previos y la forma de usar el enrutamiento de correo electrónico, consulte Configuración de dominio para el enrutamiento de correo electrónico. Para publicar esta solicitud, envía un POST HTTP a la URL del feed de enrutamiento de correo electrónico y, luego, incluye un encabezado Authorization como se describe en Autentica el servicio de configuración de administrador:

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

Una respuesta correcta muestra un código de estado HTTP 200 OK, junto con un feed AtomPub y la información del archivo.

Si, por algún motivo, tu solicitud falla, se mostrará un código de estado diferente. Para obtener más información sobre los códigos de estado de la API de datos de Google, consulte Códigos de estado de HTTP.

Endpoints se dará de baja el 31 de octubre de 2018

Como parte de este anuncio, se dieron de baja los siguientes extremos. Estaban retirados el 31 de octubre de 2018 y ya no están disponibles.

  • 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