Guía para programadores del API de administración de Google Apps: protocolo

Última actualización: 21 de abril de 2010 (ver últimos cambios)

Google Apps permite a los administradores de sitios web ofrecer a los usuarios versiones compartidas de distintas aplicaciones de Google personalizadas, como Gmail. En este documento se describe el API de administración de Google Apps, que permite a los programadores habilitar, mediante programas, el acceso a las aplicaciones que crean. Concretamente, el API ofrece funciones para crear, recuperar, modificar y eliminar cuentas de usuarios, seudónimos y grupos.

Nota: el API de administración solo está disponible para los clientes de las ediciones premier y educación de Google Apps. Para habilitarla, accede a la cuenta de administrador y haz clic en la pestaña Usuarios y grupos. A continuación, haz clic en la subpestaña Configuración, selecciona la casilla de verificación para habilitar el API de administración y guarda los cambios. Para poder acceder a tu cuenta de administrador, tienes que seguir los pasos de configuración de Google Apps.

Esta versión del API de administración sigue los principios de las API de datos de Google. Las API de datos de Google se basan en los formatos de sindicación de Atom 1.0 y de RSS 2.0, así como en el protocolo de publicación de contenido Atom Publishing Protocol (APP). Más información acerca de las API de datos de Google

(La versión 1.0 del API de administración ya no está disponible. Los clientes tienen que actualizarla a la versión 2.0.

Índice

Cómo empezar

Para configurar Google Apps, tienes que crear una cuenta de Google y utilizarla como cuenta de administrador de tu dominio. Puedes usar una cuenta de Google existente. Sin embargo, dado que el propietario de la cuenta podrá crear, modificar y eliminar cuentas de usuario de tu dominio, te recomendamos que crees una cuenta de Google nueva para tu dominio en lugar de utilizar la cuenta de Google personal de un usuario.

En estos pasos se describe cómo configurar Google Apps.

1. Ve a la página principal de Google Apps y sigue las instrucciones para registrarte en Google Apps edición premier (para tu empresa) o en Google Apps edición educación (para tu centro educativo).
2. Escribe el nombre de tu dominio o indica que quieres adquirir un dominio nuevo. Si compras un dominio nuevo, tienes que rellenar los formularios de registro del nuevo dominio para poder ir al paso siguiente.
3. Rellena el formulario para facilitar tus datos y los de tu organización a Google.
4. En la página siguiente, indica el número de cuentas de usuario que quieres adquirir y, después, acepta los términos y condiciones.
5. Realiza el proceso de registro con Google Checkout.
6. Rellena el formulario para configurar tu cuenta de administrador.
7. Sigue las instrucciones para verificar que eres el propietario del dominio.
8. Utiliza la dirección de correo electrónico y la contraseña de tu cuenta de administrador a fin de solicitar un token de autenticación para tu dominio. Este token se incluirá en cada solicitud de API que envíes a Google, y Google lo utilizará para autorizar la ejecución de estas solicitudes de API.

Autenticación en tu dominio

Todas las solicitudes que realices con el API deben enviarse a través de HTTPS. Cada solicitud de API que envíes debe incluir un token de autenticación, que Google utiliza para autorizar el acceso a la operación especificada en la solicitud del API. Los tokens de autenticación solo se ofrecen a los usuarios que tienen derechos de administrador en tu dominio y únicamente autorizan las operaciones dentro del dominio.

La interfaz de ClientLogin proporciona información adicional sobre cómo permitir mediante programas el acceso de los usuarios a sus cuentas.

Obtención de un token de autenticación

Para obtener un token de autenticación, envía una solicitud POST de HTTP a la siguiente URL:

https://www.google.com/accounts/ClientLogin

Las directrices siguientes corresponden a la solicitud:

• El cuerpo de POST debe incluir una cadena con el siguiente formato:
  • &Email=<email_address>&Passwd=<password>&accountType=HOSTED&service=apps
  • Debes realizar los siguientes cambios en esta cadena:

• Sustituye la cadena <email_address> por la dirección de correo electrónico de la cuenta de administrador.
• Sustituye la cadena <password> por la contraseña de dicha cuenta.

• Los valores de la dirección de correo electrónico y de la contraseña tienen que codificarse como URL. Por ejemplo, el formato codificado como URL de la dirección de correo electrónico apps.test.account@example.com es apps%2Etest%2Eaccount%40example%2Ecom.
• La solicitud POST debe especificar el valorapplication/x-www-form-urlencoded para la cabecera Content-Type.

Google devolverá una respuesta a la solicitud POST que incluirá el token de autenticación. El token de autenticación será el valor Auth de esa página, el cual deberás extraer. Cuando envías una solicitud al API, tienes que configurar las cabeceras Content-type y Authorization como se muestra en este ejemplo.

Content-type: application/atom+xml Authorization: GoogleLogin auth=your-authentication-token

Nota: los tokens de autenticación caducan al cabo de 24 horas. Por ello, tienes que enviar una solicitud a la URL anterior, como mínimo, una vez cada 24 horas. Te recomendamos que, en lugar de grabar el token en un archivo, lo guardes en la memoria. Si recibes un CAPTCHA mientras intentas obtener un token de autenticación, consulta en la base de datos de conocimientos cómo puedes resolverlo.

Código de ejemplo para obtener un token de autenticación

En la siguiente secuencia de comandos PERL se muestra cómo realizar una solicitud POST de HTTP para obtener un token de autenticación.

#! /usr/bin/perl -w use strict; use LWP::UserAgent; # Create an LWP object to make the HTTP POST request my $lwp_object = LWP::UserAgent->new; # Define the URL to submit the request to my $url = 'https://www.google.com/accounts/ClientLogin'; # Submit the request with values for the Email, Passwd, # accountType and service variables. my $response = $lwp_object->post( $url, [ 'accountType' => 'HOSTED', 'Email' => 'admin_email@example.com', 'Passwd' => 'admin_password', 'service' => 'apps' ] ); die "$url error: ", $response->status_line unless $response->is_success; # Extract the authentication token from the response my $auth_token; foreach my $line (split/\n/, $response->content) { if ($line =~ m/^Auth=(.+)$/) { $auth_token = $1; last; } } print "authentication token is $auth_token\n";

Ten en cuenta que para usar este código, tienes que sustituir los valores Email y Passwd por la dirección de correo electrónico y la contraseña de tu cuenta de administrador alojada.

Administración de cuentas de usuario

Todas las solicitudes de creación y de modificación (POST y PUT) también requieren que envíes un documento XML que contenga la información necesaria para llevar a cabo la solicitud. Esta información debe enviarse a través del tipo de contenido application/atom+xml. Los formatos de solicitud XML se describen en este documento.

Nota: si la velocidad de las solicitudes de administración es demasiado rápida, es posible que recibas respuestas 503 HTTP del servidor del API para indicarte que has superado tu cuota. En ese caso, utiliza un algoritmo de tiempo de descanso exponencial para volver a intentar realizar las solicitudes (con ejemplos de cómo llevar a cabo el tiempo de descanso exponencial). Para obtener unos resultados óptimos, realiza las operaciones en paralelo en distintos grupos, en lugar de añadir o eliminar a muchos miembros en un grupo de forma simultánea.

Creación de una cuenta de usuario

Para crear una cuenta de usuario, utiliza la siguiente solicitud POST:

POST https://apps-apis.google.com/a/feeds/domain/user/2.0

El siguiente código XML muestra una solicitud de ejemplo para crear un usuario. Este XML también puede utilizarse para modificar una cuenta de usuario. La posibilidad de configurar la cuota de espacio de disco del usuario mediante <apps:quota> no se ofrece a todos los usuarios. En tu acuerdo se indica si esta función está disponible para tu dominio. Todos los campos que tú configuras se muestran en negrita.

Nota: este formato XML contiene todos los datos que pueden guardarse en un objeto UserEntry de las bibliotecas cliente.

<?xml version="1.0" encoding="UTF-8"?> <atom:entry xmlns:atom="http://www.w3.org/2005/Atom" xmlns:apps="http://schemas.google.com/apps/2006"> <atom:category scheme="http://schemas.google.com/g/2005#kind" term="http://schemas.google.com/apps/2006#user"/> <apps:login userName="SusanJones-1321" password="123$$abc" suspended="false"/> <apps:quota limit="2048"/> <apps:name familyName="Jones" givenName="Susan"/> </atom:entry>

Aunque las solicitudes de creación y de modificación de cuentas de usuario utilizan el mismo formato XML, presentan ciertas diferencias.

• En una solicitud de creación de usuario, la etiqueta <apps:name> y sus atributos – familyName y givenName – son obligatorios. Sin embargo, una solicitud de modificación de usuario solo debe incluir esta etiqueta y sus atributos si la solicitud modifica el mote o el apellido del usuario.
• En una solicitud de creación de usuario, la etiqueta <apps:login>es obligatoria y la solicitud debe proporcionar valores para los atributos username ypassword. El valor de username debe ser exclusivo y no puede ser el seudónimo de otro usuario. Una solicitud de modificación de usuario no requiere la etiqueta <apps:login>. Además, solo debe proporcionar un valor para el atributo password de la etiqueta <apps:login> si se modifica la contraseña del usuario.
• Por lo general, el atributo suspended de la etiqueta <apps:login> solo se muestra en las solicitudes de modificación. De forma predeterminada, las cuentas nuevas están activas.

Recuperación de una cuenta de usuario

Para recuperar una cuenta de usuario concreta, utiliza la siguiente solicitud GET:

GET https://apps-apis.google.com/a/feeds/domain/user/2.0/(userName)

Para recuperar a todos los usuarios de un dominio, utiliza la siguiente solicitud GET:

GET https://apps-apis.google.com/a/feeds/domain/user/2.0

Modificación de una cuenta de usuario

Para modificar una cuenta de usuario, utiliza la siguiente solicitud PUT:

PUT https://apps-apis.google.com/a/feeds/domain/user/2.0/userName

Cambio del nombre de un usuario

Para cambiar el nombre de un usuario, utiliza la siguiente solicitud PUT:

PUT https://apps-apis.google.com/a/feeds/domain/user/2.0/userName

Ejemplo de solicitud UserEntry

<?xml version="1.0" encoding="UTF-8"?> <atom:entry xmlns:atom="http://www.w3.org/2005/Atom" xmlns:apps="http://schemas.google.com/apps/2006"> <atom:category scheme="http://schemas.google.com/g/2005#kind" term="http://schemas.google.com/apps/2006#user"/> <apps:login userName="NewUserName" password="testtest" suspended="false"/> </atom:entry>

Antes de cambiar el nombre de un usuario, te recomendamos que cierres todos los servicios y las sesiones de navegador a los que está conectado. Por ejemplo, puedes hablar con el usuario a través de la línea telefónica de asistencia técnica durante el proceso de cambio de nombre para asegurarte de que ha cerrado las sesiones. El proceso de cambio de nombre puede llegar a tardar 10 minutos en aplicarse en todos los servicios.

Nota: en Google Talk se pierden todas las invitaciones de chat registradas después del cambio de nombre, por lo que será necesario que el usuario vuelva a solicitar permiso para chatear con sus amigos. Asimismo, cuando se cambia el nombre a un usuario, el antiguo nombre se conserva como seudónimo para evitar interrupciones en la entrega del correo en caso de que la configuración de reenvío no esté disponible con el nuevo nombre de usuario. Para eliminar el seudónimo, debes enviar una solicitud DELETE HTTP al feed de seudónimos una vez cambiado el nombre.

Supresión de una cuenta de usuario

Para eliminar una cuenta de usuario, utiliza la siguiente solicitud DELETE:

DELETE https://apps-apis.google.com/a/feeds/domain/user/2.0/userName

Ejemplo de respuesta UserEntry

Tanto si creas como si recuperas o modificas una cuenta de usuario, el API de administración devuelve una respuesta XML de Atom en el mismo formato. En el código XML siguiente se muestra un ejemplo de respuesta de API a una solicitud de modificación de la información de una cuenta de usuario. Las bibliotecas cliente convierten este código XML en un objeto UserEntry.

<?xml version="1.0" encoding="UTF-8"?> <atom:entry xmlns:atom="http://www.w3.org/2005/Atom" xmlns:apps="http://schemas.google.com/apps/2006" xmlns:gd="http://schemas.google.com/g/2005"> <atom:id>https://apps-apis.google.com/a/feeds/example.com/user/2.0/SusanJones</atom:id> <atom:updated>1970-01-01T00:00:00.000Z</atom:updated> <atom:category scheme="http://schemas.google.com/g/2005#kind" term="http://schemas.google.com/apps/2006#user"/> <atom:title type="text">SusanJones</atom:title> <atom:link rel="self" type="application/atom+xml" href="https://apps-apis.google.com/a/feeds/example.com/user/2.0/SusanJones"/> <atom:link rel="edit" type="application/atom+xml" href="https://apps-apis.google.com/a/feeds/example.com/user/2.0/SusanJones"/> <apps:login userName="SusanJones" suspended="false" admin="false" changePasswordAtNextLogin="false" agreedToTerms="true"/> <apps:name familyName="Jones" givenName="Susan"/> <gd:feedLink rel="http://schemas.google.com/apps/2006#user.nicknames" href="https://apps-apis.google.com/a/feeds/example.com/nickname/2.0?username=Susy-1321"/> <gd:feedLink rel="http://schemas.google.com/apps/2006#user.groups" href="https://apps-apis.google.com/a/feeds//group/2.0/?recipient=us-sales@example.com"/> </atom:entry>

Ejemplo de respuesta Sample UserFeed

Cuando envías una solicitud para recuperar a todos los usuarios de un dominio, el API de administración devuelve un feed XML de Atom con una lista de usuarios, cada uno de los cuales se identifica en un bloque XML <atom:entry>. Las bibliotecas cliente traducen este feed en un objeto UserFeed, que contiene una serie de objetos UserEntry.

En el código XML siguiente se muestra un ejemplo de respuesta de API a una solicitud de recuperación de todos los usuarios de un dominio.

<?xml version="1.0" encoding="UTF-8"?> <atom:feed xmlns:atom="http://www.w3.org/2005/Atom" xmlns:apps="http://schemas.google.com/apps/2006" xmlns:openSearch="http://a9.com/-/spec/opensearchrss/1.0/" xmlns:gd="http://schemas.google.com/g/2005"> <atom:id> https://apps-apis.google.com/a/feeds/example.com/user/2.0 </atom:id> <atom:updated>1970-01-01T00:00:00.000Z</atom:updated> <atom:category scheme="http://schemas.google.com/g/2005#kind" term="http://schemas.google.com/apps/2006#user"/> <atom:title type="text">Users</atom:title> <atom:link rel="next" type="application/atom+xml" href="https://apps-apis.google.com/a/feeds/example.com/user/2.0?startUsername=john"/> <atom:link rel="http://schemas.google.com/g/2005#feed" type="application/atom+xml" href="https://apps-apis.google.com/a/feeds/example.com/user/2.0"/> <atom:link rel="http://schemas.google.com/g/2005#post" type="application/atom+xml" href="https://apps-apis.google.com/a/feeds/example.com/user/2.0"/> <atom:link rel="self" type="application/atom+xml" href="https://apps-apis.google.com/a/feeds/example.com/user/2.0"/> <openSearch:startIndex>1</openSearch:startIndex> <atom:entry> <atom:id> https://apps-apis.google.com/a/feeds/example.com/user/2.0/SusanJones </atom:id> <atom:category scheme="http://schemas.google.com/g/2005#kind" term="http://schemas.google.com/apps/2006#user"/> <atom:title type="text">SusanJones</atom:title> <atom:link rel="self" type="application/atom+xml" href="https://apps-apis.google.com/a/feeds/example.com/user/2.0/SusanJones"/> <atom:link rel="edit" type="application/atom+xml" href="https://apps-apis.google.com/a/feeds/example.com/user/2.0/SusanJones"/> <gd:who rel="http://schemas.google.com/apps/2006#user.recipient" email="SusanJones@example.com"/> <apps:login userName="SusanJones" suspended="false" admin="false" changePasswordAtNextLogin="false" agreedToTerms="true"/> <apps:quota limit="2048"/> <apps:name familyName="Jones" givenName="Susan"/> <gd:feedLink rel="http://schemas.google.com/apps/2006#user.nicknames" href="https://apps-apis.google.com/a/feeds/example.com/nickname/2.0?username=SusanJones"/> <gd:feedLink rel="http://schemas.google.com/apps/2006#user.emailLists" href="https://apps-apis.google.com/a/feeds/group/2.0/example.com/?recipient=SusanJones@example.com"/> </atom:entry> <atom:entry> <atom:id> https://apps-apis.google.com/a/feeds/example.com/user/2.0/JohnSmith </atom:id> <atom:category scheme="http://schemas.google.com/g/2005#kind" term="http://schemas.google.com/apps/2006#user"/> <atom:title type="text">JohnSmith</atom:title> <atom:link rel="self" type="application/atom+xml" href="https://apps-apis.google.com/a/feeds/example.com/user/2.0/JohnSmith"/> <atom:link rel="edit" type="application/atom+xml" href="https://apps-apis.google.com/a/feeds/example.com/user/2.0/JohnSmith"/> <gd:who rel="http://schemas.google.com/apps/2006#user.recipient" email="JohnSmith@example.com"/> <apps:login userName="JohnSmith" suspended="false" admin="false" changePasswordAtNextLogin="false" agreedToTerms="true"/> <apps:quota limit="2048"/> <apps:name familyName="Smith" givenName="John"/> <gd:feedLink rel="http://schemas.google.com/apps/2006#user.nicknames" href="https://apps-apis.google.com/a/feeds/example.com/nickname/2.0?username=JohnSmith"/> <gd:feedLink rel="http://schemas.google.com/apps/2006#user.group" href="https://apps-apis.google.com/a/feeds/group/example.com/2.0?recipient=JohnSmith@example.com"/> </atom:entry> </atom:feed>

Creación de un seudónimo

Para crear un seudónimo, utiliza la siguiente solicitud POST:

POST https://apps-apis.google.com/a/feeds/domain/nickname/2.0

Recuperación de un seudónimo

Para recuperar todos los seudónimos creados en el dominio, utiliza la siguiente solicitud GET:

GET https://apps-apis.google.com/a/feeds/domain/nickname/2.0

Para recuperar todos los seudónimos de un usuario concreto, utiliza la siguiente solicitud GET:

GET https://apps-apis.google.com/a/feeds/domain/nickname/2.0?username=userName

Para recuperar los datos de un seudónimo determinado, utiliza la siguiente solicitud GET:

GET https://apps-apis.google.com/a/feeds/domain/nickname/2.0/nickname

Supresión de un seudónimo

Para eliminar un seudónimo, utiliza la siguiente solicitud DELETE:

DELETE https://apps-apis.google.com/a/feeds/domain/nickname/2.0/nickname

Ejemplo de solicitud Sample NicknameEntry

En el código XML siguiente se muestra un ejemplo de solicitud para crear un seudónimo. El código XML utiliza la etiqueta <apps:nickname> para especificar el seudónimo y la etiqueta <apps:login> para identificar al usuario al cual se ha asignado. Los campos que configura el socio se muestran en negrita.

Nota: este formato XML contiene todos los datos que pueden guardarse en un objeto NicknameEntry de las bibliotecas cliente.

<?xml version="1.0" encoding="UTF-8"?> <atom:entry xmlns:atom="http://www.w3.org/2005/Atom" xmlns:apps="http://schemas.google.com/apps/2006"> <atom:category scheme="http://schemas.google.com/g/2005#kind" term="http://schemas.google.com/apps/2006#nickname"/> <apps:nickname name="Susy-1321"/> <apps:login userName="SusanJones-1321"/> </atom:entry>

Ejemplo de respuesta NicknameFeed

Cuando envías una solicitud para recuperar todos los seudónimos de un dominio o asignados a un usuario concreto, el API de administración devuelve un feed XML de Atom con una lista de los seudónimos, cada uno de los cuales se identifica en un bloque XML <atom:entry>. Las bibliotecas cliente traducen este feed en un objeto NicknameFeed, que contiene una serie de objetos NicknameEntry.

En el código XML siguiente se muestra un ejemplo de respuesta de API a una solicitud de recuperación de todos los seudónimos del nombre de usuarioSusanJones.

<?xml version="1.0" encoding="UTF-8"?> <atom:feed xmlns:atom="http://www.w3.org/2005/Atom" xmlns:openSearch="http://a9.com/-/spec/opensearchrss/1.0/" xmlns:apps="http://schemas.google.com/apps/2006"> <atom:id> https://apps-apis.google.com/a/feeds/example.com/nickname/2.0 </atom:id> <atom:updated>1970-01-01T00:00:00.000Z</atom:updated> <atom:category scheme="http://schemas.google.com/g/2005#kind" term="http://schemas.google.com/apps/2006#nickname"/> <atom:title type="text">Nicknames for user SusanJones</atom:title> <atom:link rel="http://schemas.google.com/g/2005#feed" type="application/atom+xml" href="https://apps-apis.google.com/a/feeds/example.com/nickname/2.0"/> <atom:link rel="http://schemas.google.com/g/2005#post" type="application/atom+xml" href="https://apps-apis.google.com/a/feeds/example.com/nickname/2.0"/> <atom:link rel="self" type="application/atom+xml" href="https://apps-apis.google.com/a/feeds/example.com/nickname/2.0?username=SusanJones"/> <openSearch:startIndex>1</openSearch:startIndex> <openSearch:itemsPerPage>2</openSearch:itemsPerPage> <atom:entry> <atom:id> https://apps-apis.google.com/a/feeds/example.com/nickname/2.0/susy </atom:id> <atom:category scheme="http://schemas.google.com/g/2005#kind" term="http://schemas.google.com/apps/2006#nickname"/> <atom:title type="text">susy</atom:title> <atom:link rel="self" type="application/atom+xml" href="https://apps-apis.google.com/a/feeds/example.com/nickname/2.0/susy"/> <atom:link rel="edit" type="application/atom+xml" href="https://apps-apis.google.com/a/feeds/example.com/nickname/2.0/susy"/> <apps:nickname name="susy"/> <apps:login userName="SusanJones"/> </atom:entry> <atom:entry> <atom:id> https://apps-apis.google.com/a/feeds/example.com/nickname/2.0/suse </atom:id> <atom:category scheme="http://schemas.google.com/g/2005#kind" term="http://schemas.google.com/apps/2006#nickname"/> <atom:title type="text">suse</atom:title> <atom:link rel="self" type="application/atom+xml" href="https://apps-apis.google.com/a/feeds/example.com/nickname/2.0/suse"/> <atom:link rel="edit" type="application/atom+xml" href="https://apps-apis.google.com/a/feeds/example.com/nickname/2.0/suse"/> <apps:nickname name="suse"/> <apps:login userName="SusanJones"/> </atom:entry> </atom:feed>

Creación de un grupo

Para crear un grupo, utiliza la siguiente solicitud POST:

POST https://apps-apis.google.com/a/feeds/group/2.0/domain

Modificación de un grupo

Para modificar un grupo, utiliza la siguiente solicitud PUT:

PUT https://apps-apis.google.com/a/feeds/group/2.0/domain/groupId

Recuperación de todos los grupos

Para recuperar todos los grupos de un miembro concreto, utiliza la siguiente solicitud GET:

GET https://apps-apis.google.com/a/feeds/group/2.0/domain/?member=memberId[&directOnly=true|false]

• directOnly: si su valor es "true", la solicitud identifica solo a los miembros directamente asociados al grupo.

Para recuperar todos los grupos de un dominio concreto, utiliza la siguiente solicitud GET:

GET https://apps-apis.google.com/a/feeds/group/2.0/domain[?[start=]]

Supresión de un grupo

Para eliminar un grupo, utiliza la siguiente solicitud DELETE:

DELETE https://apps-apis.google.com/a/feeds/group/2.0/domain/groupId

Nota: la supresión de un grupo no elimina las cuentas de usuario de sus miembros.

Los tipos de solicitud HTTP que se indican a continuación ya no se utilizan en esta versión:

Ejemplo de solicitud GroupEntry

En el código XML siguiente se muestra un ejemplo de solicitud para crear un grupo. El código XML utiliza la etiqueta "groupName" para especificar el nombre del grupo.

<atom:entry xmlns:atom="http://www.w3.org/2005/Atom" xmlns:apps="http://schemas.google.com/apps/2006" xmlns:gd="http://schemas.google.com/g/2005"> <apps:property name="groupId" value="us-sales"></apps:property> <apps:property name="groupName" value="US Sales"></apps:property> <apps:property name="description" value="United States Sales Team"></apps:property> <apps:property name="emailPermission" value="emailPermission"></apps:property> </atom:entry>

Los grupos recién creados no tienen suscriptores. El valor de emailPermission es uno de los siguientes:

• Owner: propietarios del grupo
• Member: miembros del grupo
• Domain: cualquier usuario que pertenezca al dominio del grupo
• Anyone: cualquier usuario

Ejemplo de respuesta Sample GroupEntry

Cuando envías una solicitud para crear, recuperar o modificar un grupo, el API de administración devuelve una respuesta XML que identifica al grupo. Las bibliotecas cliente traducen esta respuesta en un objeto Group. Una vez realizada la solicitud de creación de un grupo, este objeto solo sirve para confirmar que la solicitud se ha realizado correctamente.

En el código XML siguiente se muestra un ejemplo de respuesta de API a una solicitud de creación de grupo.

<atom:entry> <atom:id>https://www.google.com/a/feeds/group/2.0/example.com/us-sales</atom:id> <atom:link rel="self" type="application/atom+xml" href="https://www.google.com/a/feeds/group/2.0/example.com/us-sales"/> <atom:link rel="edit" type="application/atom+xml" href="https://www.google.com/a/feeds/group/2.0/example.com/us-sales"/> <apps:property name="groupId" value="us-sales"></apps:property> <apps:property name="groupName" value="us-sales"></apps:property> <apps:property name="description" value="UnitedStatesSalesTeam"></apps:property> <apps:property name="emailPermission" value="Domain"></apps:property> </atom:entry>

Ejemplo de respuesta Sample GroupFeed

Cuando envías una solicitud para recuperar todos los grupos de un dominio o todos los grupos a los que está suscrito un usuario concreto, el API de administración devuelve un feed XML de Atom con una lista de los grupos, cada uno de los cuales se identifica en un bloque XML <atom:entry>. Las bibliotecas cliente traducen este feed en una serie de objetos "Group".

En el código XML siguiente se muestra un ejemplo de respuesta de API a una solicitud de recuperación de todos los grupos de un dominio.

<?xml version="1.0" encoding="UTF-8"?> <atom:feed xmlns:atom="http://www.w3.org/2005/Atom" xmlns:apps="http://schemas.google.com/apps/2006" xmlns:openSearch="http://a9.com/-/spec/opensearchrss/1.0/"> <atom:id>https://www.google.com/a/feeds/group/2.0/example.com</atom:id> <atom:updated>2008-12-03T16:33:05.260Z</atom:updated> <atom:link href="https://apps-apis.google.com/a/feeds/group/2.0/example.com" type="application/atom+xml" rel="http://schemas.google.com/g/2005#feed"></atom:link> <atom:link href="https://apps-apis.google.com/a/feeds/group/2.0/example.com" type="application/atom+xml" rel="http://schemas.google.com/g/2005#post"></atom:link> <atom:link href="https://apps-apis.google.com/a/feeds/group/2.0/example.com" type="application/atom+xml" rel="self"></atom:link> <openSearch:startIndex>1</openSearch:startIndex> <atom:entry> <id>https://apps-apis.google.com/a/feeds/group/2.0/example.com/us-sales%40example.com</id> <atom:updated>2008-12-03T16:33:05.261Z</atom:updated> <atom:link href="https://apps-apis.google.com/a/feeds/group/2.0/example.com/us-sales%40example.com" type="application/atom+xml" rel="self"></atom:link> <atom:link href="https://apps-apis.google.com/a/feeds/group/2.0/example.com/us-sales%40example.com" type="application/atom+xml" rel="edit"></atom:link> <apps:property name="groupId" value="us-sales@example.com"></apps:property> <apps:property name="groupName" value="US Sales"></apps:property> <apps:property name="emailPermission" value="Anyone"></apps:property> <apps:property name="description" value="United States Sales Team"></apps:property> </atom:entry> <atom:entry> <atom:id>https://apps-apis.google.com/a/feeds/group/2.0/example.com/Staff-2435%40example.com</atom:id> <atom:updated>2008-12-03T16:33:05.260Z</atom:updated> <atom:link href="https://apps-apis.google.com/a/feeds/group/2.0/example.com/Staff-2435%40example.com" type="application/atom+xml" rel="self"></atom:link> <atom:link href="https://apps-apis.google.com/a/feeds/group/2.0/example.com/Staff-2435%40example.com" type="application/atom+xml" rel="edit"></atom:link> <apps:property name="groupId" value="Staff-2435@example.com"></apps:property> <apps:property name="groupName" value="Staff 2435"></apps:property> <apps:property name="emailPermission" value="Anyone"></apps:property> <apps:property name="description" value=""></apps:property> </atom:entry> <atom:entry> ... </atom:entry> </atom:feed>

Adición de un miembro a un grupo

Para añadir un miembro a un grupo, utiliza la siguiente solicitud POST:

POST https://apps-apis.google.com/a/feeds/group/2.0/domain/groupId/member

Nota: si añades un grupo como miembro de otro grupo, los miembros del grupo secundario pueden tardar hasta 10 minutos en aparecer como miembros del grupo principal.

Recuperación de los miembros de un grupo

Para recuperar a todos los miembros de un grupo, utiliza la siguiente solicitud GET:

GET https://apps-apis.google.com/a/feeds/group/2.0/domain/groupId/member[?[start=]]

Para recuperar a un miembro concreto de un grupo, utiliza la siguiente solicitud GET:

GET https://apps-apis.google.com/a/feeds/group/2.0/domain/groupId/member/memberId

Supresión de los miembros de un grupo

Para eliminar a un miembro de un grupo, utiliza la siguiente solicitud DELETE:

DELETE https://apps-apis.google.com/a/feeds/group/2.0/domain/groupId/member/memberId

Los tipos de solicitud HTTP que se indican a continuación ya no se utilizan en esta versión:

Ejemplo de solicitud MemberEntry

En el código XML siguiente se muestra un ejemplo de solicitud para añadir a un miembro a un grupo. El código XML utiliza la etiqueta "memberId" para especificar la dirección de correo electrónico del miembro.

<?xml version="1.0" encoding="UTF-8"?> <atom:entry xmlns:atom="http://www.w3.org/2005/Atom" xmlns:apps="http://schemas.google.com/apps/2006" xmlns:gd="http://schemas.google.com/g/2005"> <apps:property name="memberId" value="susanjones@example.com"/> </atom:entry>

Si añades a un miembro que es un grupo, utiliza la siguiente solicitud:

<?xml version="1.0" encoding="UTF-8"?> <atom:entry xmlns:atom="http://www.w3.org/2005/Atom" xmlns:apps="http://schemas.google.com/apps/2006" xmlns:gd='http://schemas.google.com/g/2005"> <apps:property name="memberId" value="us-sales@example.com"/> </atom:entry>

Ejemplo de respuesta MemberEntry

Cuando envías una solicitud para añadir una dirección de correo electrónico a un grupo, el API de administración devuelve una respuesta XML que especifica la nueva dirección. Una vez realizada la solicitud de adición de una dirección a un grupo, este objeto solo sirve para confirmar que la solicitud se ha realizado correctamente.

En el código XML siguiente se muestra un ejemplo de respuesta de API para recuperar a un miembro concreto de un grupo determinado.

<atom:entry> <atom:id>https://www.google.com/a/feeds/group/2.0/example.com/us-sales/member/suejones%40example.com</atom:id> <atom:link rel="self" type="application/atom+xml" href="https://www.google.com/a/feeds/group/2.0/example.com/us-sales/member/suejones%40example.com"/> <atom:link rel="edit" type="application/atom+xml" href="https://www.google.com/a/feeds/group/2.0/example.com/us-sales/member/suejones%40example.com"/> <apps:property name="memberId" value="suejones@example.com"/> <apps:property name="memberType" value="User"/> <apps:property name="directMember" value="true"/> </atom:entry>

Ejemplo de respuesta MemberFeed

Cuando envías una solicitud para recuperar a todos los suscriptores de un grupo, el API de administración devuelve un feed XML de Atom con una lista de los miembros, cada uno de los cuales se identifica en un bloque XML atom:entry. Las bibliotecas cliente traducen esta respuesta en un objeto MemberFeed, que contiene una lista de los objetos Member.

En el código XML siguiente se muestra un ejemplo de respuesta de API a una solicitud de recuperación de todos los miembros de un grupo.

<?xml version="1.0" encoding="UTF-8"?> <atom:feed xmlns:atom="http://www.w3.org/2005/Atom" xmlns:apps="http://schemas.google.com/apps/2006" xmlns:openSearch="http://a9.com/-/spec/opensearchrss/1.0/"> <atom:id>https://www.google.com/a/feeds/group/2.0/example.com/us-sales/member</atom:id> <atom:link rel="https://schemas.google.com/g/2005#feed" type="application/atom+xml" href="https://www.google.com/a/feeds/group/2.0/example.com/us-sales/member"/> <openSearch:startIndex>1</openSearch:startIndex> <atom:entry> <atom:id>https://www.google.com/a/feeds/group/2.0/example.com/us-sales/member/suejones%40example.com</atom:id> <atom:link rel="self" type="application/atom+xml" href="https://www.google.com/a/feeds/group/2.0/example.com/us-sales/member/suejones%40example.com"/> <atom:link rel="edit" type="application/atom+xml" href="https://www.google.com/a/feeds/group/2.0/example.com/us-sales/member/suejones%40example.com"/> <apps:property name="memberId" value="suejones@example.com"/> <apps:property name="memberType" value="User"/> <apps:property name="directMember" value="true"/> </atom:entry> <atom:entry> <atom:id>https://www.google.com/a/feeds/group/2.0/example.com/us-sales/member/ca-sales%40example.com</atom:id> <atom:link rel="self" type="application/atom+xml href="https://www.google.com/a/feeds/group/2.0/example.com/us-sales/member/ca-sales%40example.com"/> <atom:link rel="edit" type="application/atom+xml href="https://www.google.com/a/feeds/group/2.0/example.com/us-sales/member/ca-sales%40example.com"/> <apps:property name="memberId" value="ca-sales@example.com"/> <apps:property name="memberType" value="Group"/> <apps:property name="directMember" value="true"/> </atom:entry> <atom:entry> ...more entries... </atom:entry> </atom:feed>

Adición de un propietario a un grupo

Para añadir un propietario a un grupo, utiliza la siguiente solicitud POST:

POST https://apps-apis.google.com/a/feeds/group/2.0/domain/groupId/owner

Nota: la adición de un propietario a un grupo no añade a dicho usuario al feed de miembros.

Recuperación de un propietario de un grupo

Para recuperar al propietario de un grupo concreto, utiliza la siguiente solicitud GET:

GET https://apps-apis.google.com/a/feeds/group/2.0/domain/groupId/owner/ownerEmail

Recuperación de todos los propietarios de un grupo

Para recuperar a todos los propietarios de un grupo, utiliza la siguiente solicitud GET:

GET https://apps-apis.google.com/a/feeds/group/2.0/domain/groupId/owner

Supresión del propietario de un grupo

Para eliminar al propietario de un grupo, utiliza la siguiente solicitud DELETE:

DELETE https://apps-apis.google.com/a/feeds/group/2.0/domain/groupId/owner/ownerEmail

Ejemplo de solicitud OwnerEntry

En el código XML siguiente se muestra un ejemplo de solicitud para añadir a un propietario a un grupo. El código XML utiliza la propiedad "email" para especificar la dirección de correo electrónico del miembro que se va a añadir como propietario del grupo.

<?xml version="1.0" encoding="UTF-8"?> <atom:entry xmlns:atom="http://www.w3.org/2005/Atom" xmlns:apps="http://schemas.google.com/apps/2006" xmlns:gd='http://schemas.google.com/g/2005"> <apps:property name="email" value="joe@example.com"/> </atom:entry>

También puedes añadir a un propietario que sea un grupo. Para ello, tienes que especificar la dirección de correo electrónico del grupo:

<?xml version="1.0" encoding="UTF-8"?> <atom:entry xmlns:atom="http://www.w3.org/2005/Atom" xmlns:apps="http://schemas.google.com/apps/2006" xmlns:gd='http://schemas.google.com/g/2005"> <apps:property name="email" value="sales-leads@example.com"/> </atom:entry>