Gerenciar grupos

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

  • Criar um grupo
  • Atualizar um grupo
  • Adicionar um alias de grupo
  • Recuperar um grupo
  • Recuperar todos os grupos de um domínio ou da conta
  • Recuperar todos os grupos de um participante
  • Recuperar todos os aliases 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 o endereço de e-mail está sujeito a alterações.

No exemplo a seguir, o groupKey exclusivo é nnn e o nome do grupo é "Grupo de vendas da APAC": 

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

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

Para um pedido 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 seguinte solicitação POST 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, a solicitação e as propriedades 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 o endereço de e-mail está sujeito a alterações.

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, a solicitação e as propriedades 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 o endereço de e-mail está sujeito a alterações.

No exemplo a seguir, o ID groupKey exclusivo é 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"
     }
    ]
}

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

Para recuperar todos os grupos de uma conta ou um domínio específico, use a seguinte solicitação GET e inclua a autorização descrita em Autorizar solicitações. Para as strings de consulta, a solicitação e as propriedades 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 a 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 de customerId da conta. Como administrador da conta, use a string my_customer para representar o customerId da conta. Se você for um revendedor e acessar a conta de um cliente de revenda, use o customerId dessa conta. Para o valor customerId, use o nome de domínio principal da conta na solicitaçã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 domain.
  • Não usar os argumentos domain e customer: a API Directory retorna todos os grupos da conta associada ao my_customer. Essa é a conta customerId do administrador que fez a solicitação.
  • Usando os argumentos customer e userKey: a API Directory retorna um erro. É preciso fazer duas solicitações separadas com esses argumentos.

No exemplo a seguir, um administrador de 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 a seguir, a solicitação de um administrador de revendedor retorna todos os grupos da conta de revenda com o customerId C03az79cb. O máximo de resultados retornados por página de resposta é 2. Há um nextPageToken para a lista de acompanhamento de usuários 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"
  }

Recuperar todos os grupos de um participante

Para recuperar todos os grupos de 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 do 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 em 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 de resposta. Sua próxima solicitação usa esse token como o valor de string de consulta pageToken.
  • Usando os argumentos customer e userKey: a API Directory retorna um erro. É preciso 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 de 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, 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 aliases 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"
}

Recuperar todos os aliases de grupo

Para recuperar todos os aliases de um grupo, use a seguinte solicitação GET 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 dos aliases 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 retornará um código de status HTTP 201 e uma lista dos 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 dos aliases 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

Se a resposta for bem-sucedida, será retornado 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

Se a resposta for bem-sucedida, será retornado um código de status HTTP 200.

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

  • Todos os participantes do grupo serão excluídos. As contas de usuário do membro não são excluídas.
  • O arquivo do grupo foi 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.