Administrar grupos

En esta página, se explica cómo administrar Grupos de Google con la API de Directory:

  • Crear un grupo
  • Actualiza un grupo
  • Cómo agregar un alias de grupo
  • Cómo recuperar un grupo
  • Cómo recuperar todos los grupos de un dominio o la cuenta
  • Cómo recuperar todos los grupos de un miembro
  • Cómo recuperar todos los alias de grupo
  • Cómo borrar un alias de grupo
  • Cómo borrar un grupo

Crear un grupo

Para crear un grupo, usa la siguiente solicitud POST y, luego, incluye la autorización que se describe en Cómo autorizar solicitudes. Puedes crear un grupo para cualquier dominio asociado con la cuenta. Para conocer las cadenas de consulta, las solicitudes y las propiedades de respuesta, consulta el método groups.insert. 

POST https://admin.googleapis.com/admin/directory/v1/groups

En la siguiente solicitud JSON, se muestra un cuerpo de solicitud de muestra que crea un grupo. La dirección de correo electrónico del grupo es ventas_grupo@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 del grupo nuevo.

Actualiza un grupo

Para actualizar la configuración de un grupo, usa la siguiente solicitud PUT y, luego, incluye la autorización que se describe en Cómo autorizar 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, las solicitudes 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 esta dirección 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 una solicitud de actualización, solo debes enviar la información actualizada en la solicitud. No es necesario que ingreses 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"
     }
    ]
}

Cómo 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 Autorizar solicitudes. groupKey es la dirección de correo electrónico del grupo, cualquiera de las direcciones de correo electrónico de los alias del grupo o el id único del grupo. Para conocer las cadenas de consulta, las solicitudes 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 esta dirección está sujeta a cambios.

En la siguiente solicitud JSON, se 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 del nuevo alias de grupo.

Cómo recuperar un grupo

Para recuperar un grupo, usa la siguiente solicitud GET y, luego, incluye la autorización que se describe en Autorizar solicitudes. groupKey es la dirección de correo electrónico del grupo, cualquiera de las direcciones de correo electrónico de los alias del grupo o el id único del grupo. Para conocer las cadenas de consulta, las solicitudes 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 esta dirección está sujeta a cambios.

En el siguiente ejemplo, el ID único de groupKey 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"
     }
    ]
}

Cómo recuperar todos los grupos de un dominio o la cuenta

Para recuperar todos los grupos de un dominio o la cuenta específicos, usa la siguiente solicitud GET y, luego, incluye la autorización que se describe en Autorizar solicitudes. Para conocer las cadenas de consulta, las solicitudes y las propiedades de respuesta, consulta el método groups.list. Para facilitar la lectura, este ejemplo usa saltos de línea: 

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 de la 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 con my_customer o el valor customerId de la cuenta. Como administrador de la cuenta, usa la cadena my_customer para representar el customerId de tu cuenta. Si eres un revendedor que accede a la cuenta de un cliente que revendió, usa el customerId de la cuenta de reventa. Para el valor customerId, usa el nombre de dominio principal de la cuenta en la solicitud de la operación Retrieve all users in a domain. La respuesta resultante tiene el valor customerId.
  • Con los argumentos domain y customer: La API de Directory muestra todos los grupos de domain.
  • No se usan los argumentos domain y customer: La API de Directory muestra todos los grupos de la cuenta asociada con my_customer. Esta es la cuenta customerId del administrador que realiza la solicitud.
  • Si usas los argumentos customer y userKey, la API de Directory muestra un error. Debes realizar dos solicitudes separadas con estos argumentos.

En el siguiente ejemplo, un administrador de cuentas 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 revendida con 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 usuarios de seguimiento en esta respuesta: 

GET https://admin.googleapis.com/admin/directory/v1/groups?domain=sales.com&customer=C03az79cb&maxResults=2

Una respuesta correcta devuelve un código de estado HTTP 200 y los grupos en el orden alfabético del correo electrónico del 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"
  }

Cómo recuperar todos los grupos de un miembro

Para recuperar todos los grupos para los que un miembro tiene una suscripción, usa la siguiente solicitud GET e incluye la autorización que se describe en Autorizar solicitudes. Para facilitar la lectura, en este ejemplo, se usan saltos de línea: 

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 de alias del usuario, la dirección de correo electrónico principal de un grupo, el alias de correo electrónico de un grupo o el id único del usuario, que se puede encontrar con la operación Recuperar un usuario.
  • El usuario o grupo especificado en userKey debe pertenecer a tu dominio.
  • Usa la cadena de consulta pageToken para las respuestas con una gran cantidad de grupos. En el caso de la paginación, la respuesta muestra la propiedad nextPageToken, que proporciona un token para la siguiente página de resultados de la respuesta. Tu próxima solicitud usará este token como el valor de la cadena de consulta pageToken.
  • Si usas los argumentos customer y userKey, 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 del miembro:

  • Se muestran todos los grupos para los que un miembro tiene una suscripción, incluidos los grupos fuera del dominio del usuario.
  • Los grupos se muestran en orden alfabético según la dirección de correo electrónico de cada uno.
  • En el cuerpo de la respuesta, id es el ID único del grupo.
  • En la respuesta, la ficha de un grupo 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 grupo

Para recuperar todos los alias de un grupo, usa la siguiente solicitud GET y, luego, incluye la autorización que se describe en Autorizar solicitudes. El groupKey puede ser la dirección de correo electrónico principal del grupo, el id único 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 un alias de grupo

Para borrar el alias de un grupo, usa la siguiente solicitud DELETE y, luego, incluye la autorización que se describe en Autorizar solicitudes. El groupKey puede ser la dirección de correo electrónico principal del grupo, el id único del grupo o cualquiera de los correos electrónicos de los alias del grupo. aliasId es el alias que se borrará. Para conocer 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, luego, incluye la autorización que se describe en Autorizar 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, sucede lo siguiente:

  • Se borrarán todos los miembros del grupo. No se borran las cuentas de usuario del miembro.
  • Se borrará el archivo del grupo.
  • Los mensajes que se envíen a la dirección del grupo borrado no se entregarán. En su lugar, el remitente recibe un mensaje de rebote.