API de Directory: Grupos

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

Crear un grupo

Para crear un grupo, usa la siguiente solicitud POST e incluye la autorización descrita en Autorizar solicitudes. Se puede crear un grupo para cualquier dominio asociado a la cuenta. Para conocer las strings de consulta, las solicitudes y las propiedades de respuesta, revisa la Referencia de la API:

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

Solicitud JSON

La siguiente solicitud JSON muestra un cuerpo de solicitud de muestra que crea un grupo. La dirección de correo electrónico del grupo es ventas_grupo@ejemplo.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. Junto con el código de estado, la respuesta muestra las propiedades para el grupo nuevo.

Actualizar un grupo

Para actualizar la configuración de un grupo, usa la siguiente solicitud PUT e incluye la autorización descrita en Autorizar solicitudes. El groupKey es la dirección de correo electrónico del grupo, cualquiera de los alias del grupo o la dirección única del grupo del id. Para conocer las strings de consulta, las solicitudes y las propiedades de respuesta, revisa la Referencia de la API:

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 la dirección de correo electrónico está sujeta a cambios.

Solicitud JSON

En el siguiente ejemplo, el groupKey único es &n33; y el nombre del grupo se cambió a 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 tu solicitud. No es necesario que ingreses todas las propiedades del grupo en la solicitud.

Respuesta JSON

Una respuesta correcta muestra un código de estado HTTP 201. Junto con el código de estado, la respuesta muestra las propiedades para el 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 e incluye la autorización descrita en Autorizar solicitudes. La groupKey es la dirección de correo electrónico del grupo, cualquiera de los alias del grupo o cualquier otra dirección id exclusiva del grupo. Para conocer las strings de consulta, las solicitudes y las propiedades de respuesta, revisa la Referencia de la API:

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 la dirección de correo electrónico está sujeta a cambios.

Solicitud JSON

La siguiente solicitud JSON muestra una solicitud de ejemplo para crear el alias de un grupo. groupKey es el único id del grupo representado por NNNN
POST https://admin.googleapis.com/admin/directory/v1/groups/NNNN/aliases
{
    "alias": "best_sales_group@example.com"
}

Respuesta JSON

Una respuesta correcta muestra un código de estado HTTP 201. Junto con el código de estado, la respuesta muestra las propiedades del nuevo alias de grupo.

Recuperar un grupo

Para recuperar un grupo, usa la siguiente solicitud GET e incluye la autorización descrita en Autorizar solicitudes. La groupKey es la dirección de correo electrónico del grupo, cualquiera de los alias del grupo o cualquier otra dirección id exclusiva del grupo. Para conocer las strings de consulta, las solicitudes y las propiedades de respuesta, revisa la Referencia de la API:
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 la dirección de correo electrónico está sujeta a cambios.

En el siguiente ejemplo, el ID de groupKey único & 'nnnn':

GET https://admin.googleapis.com/admin/directory/v1/groups/nnnn

Respuesta JSON

Una respuesta correcta muestra un código de estado HTTP 200. Junto con el código de estado, la respuesta muestra 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 o de una cuenta específicos, usa la siguiente solicitud GET e incluye la autorización que se describe en Autoriza solicitudes. Para conocer las strings de consulta, las solicitudes y las propiedades de respuesta, consulta la Referencia de la API. Para mayor legibilidad, en este ejemplo, se usan 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 realizas la recuperación:

  • Todos los grupos para un subdominio: usa el argumento domain con el nombre del dominio.
  • Todos los grupos para la cuenta: Usa el argumento customer con my_customer o el valor customerId de la cuenta. Como administrador de la cuenta, usa la string my_customer para representar la customerId de tu cuenta. Si eres un distribuidor que accede a la cuenta de un cliente de reventa, usa la cuenta de reventa customerId. Para el valor customerId utiliza el nombre de dominio principal de la cuenta en la solicitud de operación Recuperar todos los usuarios de un dominio. La respuesta resultante tiene el valor customerId.
  • Con los argumentos domain y customer: la API muestra todos los grupos para domain.
  • No se usan los argumentos domain y customer: la API muestra todos los grupos de la cuenta asociada con my_customer. Esta es la cuenta customerId del administrador que realiza la solicitud a la API.

En este ejemplo, un administrador de cuenta utiliza 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 este ejemplo, la solicitud de un administrador distribuidor muestra todos los grupos de la cuenta de reventa con la customerId C03az79cb. La cantidad máxima de resultados que se muestran por página de respuesta es 2. Hay una 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

Respuesta JSON

Una respuesta correcta muestra un código de estado HTTP 200. Junto con el código de estado, la respuesta muestra los grupos en orden alfabético del correo electrónico del grupo y no distingue entre mayúsculas y minúsculas:

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

Para recuperar todos los grupos a los que un miembro tiene una suscripción, usa la siguiente solicitud GET e incluye la autorización que se describe en Autoriza solicitudes. Para mayor legibilidad, 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.
  • El userKey puede ser la dirección de correo electrónico principal del usuario, la dirección de correo electrónico del alias del usuario, la dirección de correo electrónico principal de un grupo, el alias de correo electrónico del grupo o el id único del usuario, que se puede encontrar mediante la operación de recuperación de un usuario.
  • El usuario o grupo especificado en userKey debe pertenecer a tu dominio.
  • Usa la string 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 los resultados de la respuesta. Tu próxima solicitud usa este token como el valor de string de consulta pageToken.

Para conocer las propiedades de solicitud y respuesta, consulta la Referencia de API.

Respuesta JSON

Si la respuesta es correcta, se 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 que no pertenecen al dominio del usuario.
  • Los grupos se muestran en orden alfabético según 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 ajeno al 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"
}

Recuperar todos los alias de grupo

Para recuperar todos los alias de un grupo, usa la siguiente solicitud GET e incluye la autorización descrita en Autorizar solicitudes. El groupKey puede ser la dirección de correo electrónico principal del grupo, la id única del grupo o cualquiera de los alias del grupo. Para conocer las propiedades de solicitud y respuesta, consulta la Referencia de API:

GET https://admin.googleapis.com/admin/directory/v1/groups/groupKey/aliases

Una respuesta correcta muestra un código de estado HTTP 201. Junto con el código de estado, la respuesta muestra una lista de los alias del grupo.

Borrar un alias de grupo

Para borrar el alias de un grupo, usa la siguiente solicitud DELETE e incluye la autorización descrita en Autorizar solicitudes. El groupKey puede ser la dirección de correo electrónico principal del grupo, la id única del grupo o cualquiera de los alias del grupo. aliasId es el alias que se borra. Para conocer las propiedades de solicitud y respuesta, consulta la Referencia de API:

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 e incluye la autorización descrita en Autorizar solicitudes. El 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:

  • Se borran todos los miembros del grupo. No se borran las cuentas de usuario del miembro.
  • Se borró el archivo del grupo.
  • No se entregarán los mensajes enviados a la dirección del grupo borrado. En cambio, el remitente recibe un mensaje de rebote.