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çãoGET
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
commy_customer
ou o valor decustomerId
da conta. Como administrador da conta, use a stringmy_customer
para representar ocustomerId
da conta. Se você for um revendedor e acessar a conta de um cliente de revenda, use ocustomerId
dessa conta. Para o valorcustomerId
, 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 valorcustomerId
. - Usando os argumentos
domain
ecustomer
: a API Directory retorna todos os grupos paradomain
. - Não usar os argumentos
domain
ecustomer
: a API Directory retorna todos os grupos da conta associada aomy_customer
. Essa é a contacustomerId
do administrador que fez a solicitação. - Usando os argumentos
customer
euserKey
: 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 oid
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 propriedadenextPageToken
, 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 consultapageToken
. - Usando os argumentos
customer
euserKey
: 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çãoGET
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çãoDELETE
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.