En esta página, se explica cómo administrar Grupos de Google con la API de Directory:
- Crear un grupo
- Cómo actualizar un grupo
- Agregar un alias de grupo
- Cómo recuperar un grupo
- Recuperar todos los grupos de un dominio o de la cuenta
- Recuperar todos los grupos de un miembro
- Cómo recuperar todos los alias de grupos
- Cómo borrar el alias de un grupo
- Cómo borrar un grupo
Crear un grupo
Para crear un grupo, usa la siguiente solicitud POST
y, además, incluye la autorización que se describe en Autoriza solicitudes.
Puedes crear un grupo para cualquier dominio asociado con la cuenta. Para conocer las cadenas de consulta, la solicitud y las propiedades de respuesta, consulta el método groups.insert
.
POST https://admin.googleapis.com/admin/directory/v1/groups
La siguiente solicitud JSON muestra un cuerpo de solicitud de ejemplo que crea un grupo. La dirección de correo electrónico del grupo es sales_group@example.com:
{ "email": "sales_group@example.com", "name": "Sales Group", "description": "This is the Sales group." }
Una respuesta correcta muestra un código de estado HTTP 201
y las propiedades para el grupo nuevo.
Cómo actualizar un grupo
Para actualizar la configuración de un grupo, usa la siguiente solicitud PUT
y, además, incluye la autorización que se describe en Autoriza solicitudes.
groupKey
es la dirección de correo electrónico del grupo, cualquiera de las direcciones de correo electrónico del alias del grupo o el id
único del grupo. Para conocer las cadenas de consulta, la solicitud y las propiedades de respuesta, consulta el método groups.update
.
PUT https://admin.googleapis.com/admin/directory/v1/groups/groupKey
En general, Google recomienda no usar la dirección de correo electrónico del grupo como clave para los datos persistentes, ya que está sujeta a cambios.
En el siguiente ejemplo, el groupKey
único es nnn
y el nombre del grupo es APAC Sales Group:
PUT https://admin.googleapis.com/admin/directory/v1/groups/nnn
{ "email": "sales_group@example.com", "name": "APAC Sales Group" }
Para enviar una solicitud de actualización, solo debes enviar la información actualizada en tu solicitud. No es necesario ingresar todas las propiedades del grupo en la solicitud.
Una respuesta correcta muestra un código de estado HTTP 201
y las propiedades del grupo nuevo:
{ "kind": "directory#groups", "id": "group's unique ID", "etag": "group's unique ETag", "email": "sales_group@example.com", "name": "APAC Sales Group", "directMembersCount": "5", "description": "This is the APAC sales group.", "adminCreated": true, "aliases": [ { "alias": "best_sales_group@example.com" } ], "nonEditableAliases: [ { "alias": "liz@test.com" } ] }
Agregar un alias de grupo
Para agregar un alias de grupo, usa la siguiente solicitud POST
y, luego, incluye la autorización que se describe en Autoriza solicitudes.
groupKey
es la dirección de correo electrónico del grupo, cualquiera de las direcciones de correo electrónico del alias del grupo o el id
único del grupo. Para conocer las cadenas de consulta, la solicitud y las propiedades de respuesta, consulta el recurso groups
.
POST https://admin.googleapis.com/admin/directory/v1/groups/groupKey/aliases
En general, Google recomienda no usar la dirección de correo electrónico del grupo como clave para los datos persistentes, ya que está sujeta a cambios.
La siguiente solicitud JSON muestra una solicitud de ejemplo para crear el alias de un grupo. El groupKey
es el id
único del grupo representado por NNNN
.
POST https://admin.googleapis.com/admin/directory/v1/groups/NNNN/aliases
{ "alias": "best_sales_group@example.com" }
Una respuesta correcta muestra un código de estado HTTP 201
y las propiedades para el alias de grupo nuevo.
Cómo recuperar un grupo
Para recuperar un grupo, usa la siguiente solicitudGET
y, además, incluye la autorización que se describe en Autoriza solicitudes.
groupKey
es la dirección de correo electrónico del grupo, cualquiera de las direcciones de correo electrónico del alias del grupo o el id
único del grupo. Para conocer las cadenas de consulta, la solicitud y las propiedades de respuesta, consulta el método groups.get
.
GET https://admin.googleapis.com/admin/directory/v1/groups/groupKey
En general, Google recomienda no usar la dirección de correo electrónico del grupo como clave para los datos persistentes, ya que está sujeta a cambios.
En el siguiente ejemplo, el ID de groupKey
único es nnnn
:
GET https://admin.googleapis.com/admin/directory/v1/groups/nnnn
Una respuesta correcta muestra un código de estado HTTP 200
y la configuración del grupo:
{ "kind": "directory#groups", "id": "group's unique ID", "etag": "group's unique ETag", "email": "sales_group@example.com", "name": "APAC Sales Group", "directMembersCount": "5", "description": "This is the APAC sales group.", "adminCreated": true, "aliases": [ { "alias": "best_sales_group@example.com" } ], "nonEditableAliases: [ { "alias": "liz@test.com" } ] }
Recuperar todos los grupos de un dominio o de la cuenta
Para recuperar todos los grupos de un dominio específico o de la cuenta, usa la siguiente solicitud GET
y, además, incluye la autorización que se describe en Autoriza solicitudes. Para conocer las cadenas de consulta, la solicitud y las propiedades de respuesta, consulta el método groups.list
.
Para facilitar la lectura, en este ejemplo, se usa una línea que muestra lo siguiente:
GET https://admin.googleapis.com/admin/directory/v1/groups?domain=domain name &customer=my_customer or customerId&pageToken=pagination token &maxResults=max results
Cuando recuperes todos los grupos de un dominio o cuenta, ten en cuenta lo siguiente:
- Todos los grupos de un subdominio: Usa el argumento
domain
con el nombre del dominio. - Todos los grupos de la cuenta: Usa el argumento
customer
conmy_customer
o el valorcustomerId
de la cuenta. Como administrador de la cuenta, usa la cadenamy_customer
para representar elcustomerId
de tu cuenta. Si eres revendedor y accedes a la cuenta de un cliente de reventa, usa elcustomerId
de la cuenta de reventa. Para el valorcustomerId
, usa el nombre de dominio principal de la cuenta en la solicitud de la operación Recuperar todos los usuarios de un dominio. La respuesta resultante tiene el valorcustomerId
. - Con los argumentos
domain
ycustomer
, la API de Directory muestra todos los grupos dedomain
. - Si no se usan los argumentos
domain
ycustomer
, la API de Directory muestra todos los grupos de la cuenta asociada conmy_customer
. Esta es la cuentacustomerId
del administrador que realiza la solicitud. - Si usas los argumentos
customer
yuserKey
, la API de Directory muestra un error. Debes realizar dos solicitudes separadas con estos argumentos.
En el siguiente ejemplo, un administrador de cuenta usa my_customer
para solicitar una lista de todos los grupos de una cuenta:
GET https://admin.googleapis.com/admin/directory/v1/groups?domain=sales.com&customer=my_customer&maxResults=2
En el siguiente ejemplo, la solicitud de un administrador de revendedor muestra todos los grupos de la cuenta de reventa
con el customerId C03az79cb
. La cantidad máxima de resultados que se muestran por página de respuesta es 2.
Hay un nextPageToken
para la lista de seguimiento de usuarios en esta respuesta:
GET https://admin.googleapis.com/admin/directory/v1/groups?domain=sales.com&customer=C03az79cb&maxResults=2
Una respuesta correcta muestra un código de estado HTTP 200
y los grupos en orden alfabético del correo electrónico de grupo:
{ "kind": "directory#groups", "groups": [ { "kind": "directory#groups", "id": "group's unique ID", "etag": "group's unique ETag", "email": "support@sales.com", "name": "Sales support", "directMembersCount": "6", "description": "The sales support group", "adminCreated": true }, { "kind": "directory#groups", "id": "group's unique ID", "etag": "group's unique ETag", "email": "travel@sales.com", "name": "Sales travel", "directMembersCount": "2", "description": "The travel group supporting sales", "adminCreated": false, "aliases": [ { "alias": "best_sales_group@example.com" } ], "nonEditableAliases: [ { "alias": "liz@test.com" } ] }, "nextPageToken": "NNNN" }
Recuperar todos los grupos de un miembro
Si deseas recuperar todos los grupos para los que un miembro tiene una suscripción, usa la siguiente solicitud GET
y, luego, incluye la autorización que se describe en Solicitudes de autorización. Para facilitar la lectura, en este ejemplo, se usa una línea que muestra lo siguiente:
GET https://admin.googleapis.com/admin/directory/v1/groups?userKey=user key ?pageToken=pagination token &maxResults=maximum results per response page
- Un miembro puede ser un usuario o un grupo.
userKey
puede ser la dirección de correo electrónico principal del usuario, la dirección de correo electrónico del alias, la dirección de correo electrónico principal de un grupo, el alias de correo electrónico de un grupo o elid
único del usuario, que se puede encontrar con Cómo recuperar una operación de usuario.- El usuario o grupo especificado en el
userKey
debe pertenecer a tu dominio. - Usa la cadena de consulta
pageToken
para respuestas con un gran número de grupos. En el caso de la paginación, la respuesta muestra la propiedadnextPageToken
, que proporciona un token para la siguiente página de resultados de respuesta. En tu próxima solicitud, se usa este token como el valor de cadena de consultapageToken
. - Si usas los argumentos
customer
yuserKey
, la API de Directory muestra un error. Debes realizar dos solicitudes separadas con estos argumentos.
Para conocer las propiedades de solicitud y respuesta, consulta el método groups.list
.
Una respuesta correcta muestra un código de estado HTTP 200 y la lista de información de los miembros:
- Se muestran todos los grupos en los que un miembro tiene una suscripción, incluidos los grupos ajenos al dominio del usuario.
- Los grupos se muestran en orden alfabético de la dirección de correo electrónico de cada grupo.
- En el cuerpo de la respuesta,
id
es el ID único del grupo. - En la respuesta, la lista de un grupo desde fuera del dominio del usuario no incluye los alias del grupo externo.
{ "kind": "directory#groups", "groups": [ { "kind": "directory#group", "id": "group's unique ID", "etag": "group's unique ETag", "email": "sales_group@example.com", "name": "sale group", "directMembersCount": "5", "description": "Sales group" }, { "kind": "directory#group", "id": "group's unique ID", "etag": "group's unique ETag", "email": "support_group.com", "name": "support group", "directMembersCount": "5", "description": "Support group" } ], "nextPakeToken": "NNNNN" }
Cómo recuperar todos los alias de grupos
Para recuperar todos los alias de un grupo, usa la siguiente solicitudGET
e incluye la autorización que se describe en Autoriza solicitudes. El groupKey
puede ser la dirección de correo electrónico principal del grupo, la id
única del grupo o cualquiera de los correos electrónicos de los alias del grupo. Para conocer las propiedades de solicitud y respuesta, consulta el recurso groups
.
GET https://admin.googleapis.com/admin/directory/v1/groups/groupKey/aliases
Una respuesta correcta muestra un código de estado HTTP 201
y una lista de los alias del grupo.
Cómo borrar el alias de un grupo
Para borrar el alias de un grupo, usa la siguiente solicitudDELETE
y, luego, incluye la autorización que se describe en Autoriza solicitudes.
El groupKey
puede ser la dirección de correo electrónico principal del grupo, la id
única del grupo o cualquiera de los correos electrónicos de los alias del grupo. aliasId
es el alias que se borrará. Para obtener las propiedades de solicitud y respuesta, consulta el recurso groups
:
DELETE https://admin.googleapis.com/admin/directory/v1/groups/groupKey/aliases/aliasId
Una respuesta correcta muestra un código de estado HTTP 201
.
Cómo borrar un grupo
Para borrar un grupo, usa la siguiente solicitud DELETE
y, además, incluye la autorización que se describe en Autoriza solicitudes.
groupKey
es el id
único del grupo:
DELETE https://admin.googleapis.com/admin/directory/v1/groups/groupKey
Por ejemplo, esta solicitud DELETE
borra el grupo que tiene el grupo nnnn
id
:
DELETE https://admin.googleapis.com/admin/directory/v1/group/nnnn
Una respuesta correcta muestra un código de estado HTTP 200
.
Cuando se borra un grupo, ocurre lo siguiente:
- Se borrarán todos los miembros del grupo. No se borrarán las cuentas de usuario de los miembros.
- Se borró el archivo del grupo.
- Los mensajes que se envíen a la dirección del grupo borrado no se entregarán. En cambio, el remitente recibe un mensaje de rebote.