Gerenciar grupos

Nesta página, descrevemos como gerenciar o Google Grupos 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 é vendas_grupo@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, o endereço de e-mail de qualquer um dos aliases 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, não recomendamos usar o endereço de e-mail do grupo como uma chave para dados persistentes, porque ele está sujeito a mudanças.

Em geral, não recomendamos 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 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, basta enviar as informações atualizadas na solicitação. 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, o endereço de e-mail de qualquer um dos aliases 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 um alias de 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, o endereço de e-mail de qualquer um dos aliases 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 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"
     }
    ]
}

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

Para recuperar todos os grupos de um domínio ou conta específica, 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 do domain.
  • Sem 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 está fazendo a solicitação.
  • Usando os argumentos customer e userKey: a API Directory retorna um erro. Você precisa 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 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 subsequente 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 em 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 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 participante 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 Recuperação de uma operação do 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 da resposta. Sua 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. Você precisa 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 são retornados, incluindo grupos de fora do domínio do usuário.
  • Os grupos são retornados em ordem alfabética de acordo com o endereço de e-mail de cada um.
  • 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"
     }
  ],
   "nextPageToken": "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 retorna um código de status HTTP 201 e uma lista dos aliases do grupo.

Excluir um alias de grupo

Para excluir um alias de 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

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 id do grupo nnnn:

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, acontece o seguinte:

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