Gerenciar grupos

Esta página explica como gerenciar os Grupos do Google com a API Directory:

  • Criar um grupo
  • Atualizar um grupo
  • Adicionar um alias de grupo
  • Recuperar um grupo
  • Extrair todos os grupos de um domínio ou da conta
  • Extrair todos os grupos de um participante
  • Extrair todos os pseudônimos de grupo
  • Excluir um alias de grupo
  • Excluir um grupo

Criar um grupo

Para criar um grupo, use a seguinte solicitação POST e inclua a autorização descrita em Autorizar solicitações. É possível criar um grupo para qualquer domínio associado à conta. Para as strings de consulta, as propriedades de solicitação e de resposta, consulte o método groups.insert. 

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

A solicitação JSON a seguir mostra um exemplo de corpo de solicitação que cria um grupo. O endereço de e-mail do grupo é sales_group@example.com: 

{
   "email": "sales_group@example.com",
   "name": "Sales Group",
   "description": "This is the Sales group."
}

Uma resposta bem-sucedida retorna um código de status HTTP 201 e as propriedades do novo grupo.

Atualizar um grupo

Para atualizar as configurações de um grupo, use a seguinte solicitação PUT e inclua a autorização descrita em Autorizar solicitações. O groupKey é o endereço de e-mail do grupo, qualquer um dos endereços de e-mail do alias do grupo ou o id exclusivo do grupo. Para as strings de consulta, as propriedades de solicitação e de resposta, consulte o método groups.update. 

PUT https://admin.googleapis.com/admin/directory/v1/groups/groupKey

Em geral, o Google recomenda não usar o endereço de e-mail do grupo como uma chave para dados persistentes, porque ele está sujeito a mudanças.

No exemplo abaixo, o groupKey exclusivo é nnn e o nome do grupo é "APAC Sales Group": 

PUT https://admin.googleapis.com/admin/directory/v1/groups/nnn

{
    "email": "sales_group@example.com",
    "name": "APAC Sales Group"
}

Para uma solicitação de atualização, você só precisa enviar as informações atualizadas. Não é necessário inserir todas as propriedades do grupo na solicitação.

Uma resposta bem-sucedida retorna um código de status HTTP 201 e as propriedades do novo 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"
     }
    ]
}

Adicionar um alias de grupo

Para adicionar um alias de grupo, use a solicitação POST abaixo e inclua a autorização descrita em Autorizar solicitações. O groupKey é o endereço de e-mail do grupo, qualquer um dos endereços de e-mail do alias do grupo ou o id exclusivo do grupo. Para as strings de consulta, as propriedades de solicitação e de resposta, consulte o recurso groups. 

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

Em geral, o Google recomenda não usar o endereço de e-mail do grupo como uma chave para dados persistentes, porque ele está sujeito a mudanças.

A solicitação JSON a seguir mostra um exemplo de solicitação para criar o alias de um grupo. O groupKey é o id exclusivo do grupo representado por NNNN.

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

{
    "alias": "best_sales_group@example.com"
}

Uma resposta bem-sucedida retorna um código de status HTTP 201 e as propriedades do novo alias de grupo.

Recuperar um grupo

Para recuperar um grupo, use a seguinte solicitação GET e inclua a autorização descrita em Autorizar solicitações. O groupKey é o endereço de e-mail do grupo, qualquer um dos endereços de e-mail do alias do grupo ou o id exclusivo do grupo. Para as strings de consulta, as propriedades de solicitação e de resposta, consulte o método groups.get. 
GET https://admin.googleapis.com/admin/directory/v1/groups/groupKey

Em geral, o Google recomenda não usar o endereço de e-mail do grupo como uma chave para dados persistentes, porque ele está sujeito a mudanças.

No exemplo a seguir, o ID exclusivo de groupKey é nnnn: 

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

Uma resposta bem-sucedida retorna um código de status HTTP 200 e as configurações do 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"
     }
    ]
}

Extrair todos os grupos de um domínio ou da conta

Para recuperar todos os grupos de um domínio ou da conta, use a seguinte solicitação GET e inclua a autorização descrita em Autorizar solicitações. Para as strings de consulta, as propriedades de solicitação e de resposta, consulte o método groups.list. Para facilitar a leitura, este exemplo usa retornos de linha: 

GET https://admin.googleapis.com/admin/directory/v1/groups?domain=domain name
&customer=my_customer or customerId&pageToken=pagination token
&maxResults=max results

Ao recuperar todos os grupos de um domínio ou da conta, considere o seguinte:

  • Todos os grupos de um subdomínio: use o argumento domain com o nome do domínio.
  • Todos os grupos da conta: use o argumento customer com my_customer ou o valor customerId da conta. Como administrador da conta, use a string my_customer para representar o customerId da sua conta. Se você for um revendedor acessando a conta de um cliente revendido, use o customerId da conta revendida. Para o valor customerId, use o nome de domínio principal da conta na solicitação da operação Recuperar todos os usuários em um domínio. A resposta resultante tem o valor customerId.
  • Usando os argumentos domain e customer: a API Directory retorna todos os grupos para o domain.
  • Não usar os argumentos domain e customer: a API Directory retorna todos os grupos da conta associada a my_customer. Esta é a conta customerId do administrador que fez a solicitação.
  • Usando os argumentos customer e userKey: a API Directory retorna um erro. É necessário fazer duas solicitações separadas com esses argumentos.

No exemplo a seguir, um administrador da conta usa my_customer para solicitar uma lista de todos os grupos de uma conta:

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

No exemplo abaixo, a solicitação de um administrador de revendedor retorna todos os grupos da conta revendida com o customerId C03az79cb. O número máximo de resultados retornados por página de resposta é 2. Há um nextPageToken para a lista de usuários a seguir nesta resposta: 

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

Uma resposta bem-sucedida retorna um código de status HTTP 200 e os grupos na ordem alfabética do e-mail do 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"
  }

Extrair todos os grupos de um participante

Para recuperar todos os grupos em que um membro tem uma assinatura, use a seguinte solicitação GET e inclua a autorização descrita em Autorizar solicitações. Para facilitar a leitura, este exemplo usa retornos de linha: 

GET https://admin.googleapis.com/admin/directory/v1/groups?userKey=user key
?pageToken=pagination token
&maxResults=maximum results per response page
  • Um membro pode ser um usuário ou um grupo.
  • O userKey pode ser o endereço de e-mail principal do usuário, o endereço de e-mail de alias do usuário, o endereço de e-mail principal de um grupo, o alias de e-mail de um grupo ou o id exclusivo do usuário, que pode ser encontrado usando a operação Recuperar um usuário.
  • O usuário ou grupo especificado no userKey precisa pertencer ao seu domínio.
  • Use a string de consulta pageToken para respostas com um grande número de grupos. No caso da paginação, a resposta retorna a propriedade nextPageToken, que fornece um token para a próxima página de resultados. A próxima solicitação usa esse token como o valor da string de consulta pageToken.
  • Usando os argumentos customer e userKey: a API Directory retorna um erro. É necessário fazer duas solicitações separadas com esses argumentos.

Para as propriedades de solicitação e resposta, consulte o método groups.list.

Uma resposta bem-sucedida retorna um código de status HTTP 200 e a lista de informações do membro:

  • Todos os grupos em que um membro tem uma assinatura, incluindo grupos fora do domínio do usuário, são retornados.
  • Os grupos são retornados na ordem alfabética do endereço de e-mail de cada grupo.
  • No corpo da resposta, o id é o ID exclusivo do grupo.
  • Na resposta, a listagem de um grupo de fora do domínio do usuário não inclui os pseudônimos do 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"
}

Extrair todos os aliases de grupo

Para recuperar todos os aliases de um grupo, use a solicitação GET abaixo e inclua a autorização descrita em Autorizar solicitações. O groupKey pode ser o endereço de e-mail principal do grupo, o id exclusivo do grupo ou qualquer um dos e-mails de alias do grupo. Para as propriedades de solicitação e resposta, consulte o recurso groups. 

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

Uma resposta bem-sucedida retorna um código de status HTTP 201 e uma lista de aliases do grupo.

Excluir um alias de grupo

Para excluir o alias de um grupo, use a seguinte solicitação DELETE e inclua a autorização descrita em Autorizar solicitações. O groupKey pode ser o endereço de e-mail principal do grupo, o id exclusivo do grupo ou qualquer um dos e-mails de alias do grupo. O aliasId é o alias que está sendo excluído. Para as propriedades de solicitação e resposta, consulte o recurso groups: 

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

Uma resposta bem-sucedida retorna um código de status HTTP 201.

Excluir um grupo

Para excluir um grupo, use a seguinte solicitação DELETE e inclua a autorização descrita em Autorizar solicitações. O groupKey é o id exclusivo do grupo: 

DELETE https://admin.googleapis.com/admin/directory/v1/groups/groupKey
 Por exemplo, esta solicitação DELETE exclui o grupo que tem o grupo nnnn id: 
DELETE https://admin.googleapis.com/admin/directory/v1/group/nnnn

Uma resposta bem-sucedida retorna um código de status HTTP 200.

Quando um grupo é excluído, o seguinte acontece:

  • Todos os membros do grupo são excluídos. As contas de usuário do participante não são excluídas.
  • O grupo arquivado é excluído.
  • As mensagens enviadas para o endereço do grupo excluído não são entregues. Em vez disso, o remetente recebe uma mensagem de erro na entrega.