Gerenciar contas de usuários

A API Directory fornece métodos programáticos para criar, atualizar e excluir usuários. Também é possível receber informações sobre usuários individuais ou listas de usuários que atendem a critérios especificados. Veja a seguir exemplos de algumas operações básicas do usuário.

Criar uma conta de usuário

Você pode adicionar uma conta de usuário a qualquer um dos domínios da sua conta do Google Workspace. Antes de adicionar uma conta de usuário, confirme a propriedade do domínio.

Se você tiver feito upgrade da sua conta pessoal do Gmail para uma conta de e-mail comercial com seu próprio nome de domínio, não será possível criar novas contas de usuário até desbloquear outras configurações do Google Workspace. Veja mais detalhes em As contas de e-mail comercial do G Suite foram atualizadas para o G Suite Basic.

Para criar uma conta de usuário com um dos seus domínios, use a seguinte solicitação POST e inclua a autorização descrita em Saiba mais sobre autenticação e autorização. Veja os escopos disponíveis para a API Directory na lista de escopos do OAuth 2.0. Para as propriedades da string de consulta da solicitação, consulte o método users.insert().

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

Todas as solicitações de criação exigem que você envie as informações necessárias para atender à solicitação. Se você estiver usando bibliotecas de cliente, elas vão converter os objetos de dados da linguagem escolhida em objetos formatados em dados JSON.

Solicitação JSON

O JSON a seguir mostra um exemplo de solicitação para criar um usuário. Para a lista completa de propriedades de solicitação e resposta, consulte a Referência da API.

{
"primaryEmail": "liz@example.com",
"name": {
 "givenName": "Elizabeth",
 "familyName": "Smith"
},
"suspended": false,
"password": "new user password",
"hashFunction": "SHA-1",
"changePasswordAtNextLogin": false,
"ipWhitelisted": false,
"ims": [
 {
  "type": "work",
  "protocol": "gtalk",
  "im": "liz_im@talk.example.com",
  "primary": true
 }
],
"emails": [
 {
  "address": "liz@example.com",
  "type": "home",
  "customType": "",
  "primary": true
 }
],
"addresses": [
 {
  "type": "work",
  "customType": "",
  "streetAddress": "1600 Amphitheatre Parkway",
  "locality": "Mountain View",
  "region": "CA",
  "postalCode": "94043"
 }
],
"externalIds": [
 {
  "value": "12345",
  "type": "custom",
  "customType": "employee"
 }
],
"organizations": [
 {
  "name": "Google Inc.",
  "title": "SWE",
  "primary": true,
  "type": "work",
  "description": "Software engineer"
 }
],
"phones": [
 {
  "value": "+1 nnn nnn nnnn",
  "type": "work"
 }
],
"orgUnitPath": "/corp/engineering",
"includeInGlobalAddressList": true
}

Se a taxa de consulta para solicitações de criação for muito alta, você poderá receber respostas HTTP 503 do servidor da API indicando que sua cota foi excedida. Se você receber essas respostas, use um algoritmo de espera exponencial para fazer novas solicitações.

Os itens a observar sobre uma nova conta são:

  • Se a conta do Google tiver adquirido licenças de e-mail, uma caixa de correio será automaticamente atribuída à nova conta de usuário. Esta atribuição pode levar alguns minutos para ser concluída e ativada.
  • A edição de um campo somente leitura em uma solicitação, como isAdmin, é ignorada silenciosamente pelo serviço da API.
  • O número máximo permitido de domínios em uma conta é 600 (1 domínio principal + 599 domínios adicionais)
  • Se um usuário não tiver sido atribuído a uma unidade organizacional específica quando a conta de usuário foi criada, ela estará na unidade organizacional de nível superior. A unidade organizacional de um usuário determina a quais serviços do Google Workspace ele tem acesso. Se o usuário for movido para uma nova organização, o acesso dele vai mudar. Para mais informações sobre estruturas organizacionais, consulte a Central de Ajuda para administração. Confira como mover um usuário para outra organização em Atualizar um usuário.
  • Uma password é necessária para novas contas de usuário. Se um hashFunction for especificado, a senha precisará ser uma chave de hash válida. Se não for especificado, a senha deve estar em texto não criptografado e ter entre 8 e 100 caracteres ASCII. Para mais informações, consulte a Referência da API.
  • Para os usuários com um plano flexível do Google Workspace, criar usuários usando essa API terá impacto monetário e vai resultar em cobranças na conta de faturamento do cliente. Para mais informações, consulte as informações de faturamento da API.
  • Uma conta do Google Workspace pode incluir qualquer um dos seus domínios. Em uma conta com vários domínios, os usuários de um domínio podem compartilhar serviços com usuários em outros domínios. Para mais informações sobre usuários em vários domínios, consulte Informações sobre vários domínios da API.
  • Pode haver contas conflitantes. Confira se alguém que você planeja adicionar já tem uma Conta do Google. Depois, siga as etapas para evitar conflitos com essas contas. Consulte Encontrar e resolver contas conflitantes.
  • Pode haver contas de visitante. Se os usuários convidarem pessoas de fora da sua organização que não têm uma Conta do Google para colaborar no Drive, elas vão receber contas de visitante no formato nome_de_usuário_do_visitante@seu_domínio.com. Se você adicionar um usuário com o mesmo nome de usuário de uma conta de visitante, ela será convertida em uma conta completa do Google Workspace. As permissões atuais dos arquivos do Drive vão ser mantidas. Consulte Compartilhar documentos com visitantes.

Se a resposta for bem-sucedida, o código de status HTTP 200 será retornado. Juntamente com o código de status, a resposta retorna as propriedades da nova conta de usuário.

Atualizar uma conta de usuário

Para atualizar uma conta de usuário, use a seguinte solicitação PUT e inclua a autorização descrita em Autorizar solicitações. O userKey pode ser o endereço de e-mail principal do usuário, o usuário único id ou um dos endereços de e-mail do alias do usuário.

PUT https://admin.googleapis.com/admin/directory/v1/users/userKey

O corpo da solicitação e da resposta contêm uma instância de User. No entanto, como a API Directory é compatível com a semântica de patch, você só precisa enviar os campos atualizados na sua solicitação.

Exemplo de solicitação

No exemplo abaixo, o givenName do usuário era "Elizabeth" quando a conta de usuário foi criada, e apenas um endereço de e-mail comercial foi fornecido.

{
  "name": {
    "givenName": "Elizabeth",
    "familyName": "Smith"
   },
  "emails": [
    {
      "address": "liz@example.com",
      "type": "work",
      "primary": true
    }
}

A solicitação abaixo atualiza givenName de "Elizabeth" para "Liz" e também adiciona um endereço de e-mail residencial. Ambos os endereços de e-mail são fornecidos porque o campo é uma matriz.

PUT https://admin.googleapis.com/admin/directory/v1/users/liz@example.com

{
  "name": {
    "givenName": "Liz",
   },
  "emails": [
    {
      "address": "liz@example.com",
      "type": "work",
      "primary": true
    },
    {
      "address": "liz@home.com",
      "type": "home"
    }
  ]
}

Uma resposta bem-sucedida retorna um código de status HTTP 200 e um recurso User com os campos atualizados.

Esteja ciente do seguinte ao atualizar o nome da conta de um usuário:

  • Renomear uma conta de usuário muda o endereço de e-mail principal e o domínio usado ao recuperar as informações. Antes de renomear um usuário, recomendamos que você desconecte o usuário de todas as sessões do navegador e serviços.
  • O processo de renomeação de uma conta de usuário pode levar até 10 minutos para ser propagado em todos os serviços.
  • Quando você renomeia um usuário, o nome de usuário antigo é mantido como um alias para garantir a entrega contínua de e-mails no caso de configurações de encaminhamento de e-mail e não está disponível como um novo nome de usuário.
  • Em geral, também recomendamos não usar o endereço de e-mail do usuário como uma chave para dados persistentes, porque ele está sujeito a alterações.
  • Para uma lista completa dos efeitos da renomeação de um usuário nos apps do Google Workspace, consulte a Central de Ajuda para admins.

Transformar um usuário em administrador

Para transformar o usuário em um superadministrador, use a seguinte solicitação POST e inclua a autorização descrita em Autorizar solicitações. O userKey pode ser o endereço de e-mail principal, o usuário único id ou um dos aliases de e-mail do usuário. Para as propriedades de solicitação e resposta, consulte a Referência da API. Para acessar mais informações sobre um superadministrador, consulte a Central de Ajuda para administração.

POST https://admin.googleapis.com/admin/directory/v1/users/userKey/makeAdmin

Solicitação JSON

Neste exemplo, o usuário com userKey é liz@example.com se tornou um superadministrador:

POST https://admin.googleapis.com/admin/directory/v1/users/liz@example.com/makeAdmin
{
 "status": true
}

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

Gerenciar relacionamentos com usuários

A API Directory usa o campo relations para definir diferentes tipos de relações entre usuários. Em um ambiente de negócios, as pessoas geralmente usam esse campo para relacionamentos de gerente-funcionário e assistente, mas o campo também oferece suporte a muitos outros tipos. O relacionamento é mostrado no card "Pessoas relacionadas" do usuário em qualquer aplicativo do Google Workspace compatível com o cartão. Para exemplos de onde o card é visível, consulte Adicionar informações ao perfil de um usuário no diretório.

Criar uma relação entre os usuários

Você pode definir um relacionamento em apenas uma direção, começando pelo usuário "proprietário", cujo registro inclui o campo relations. O type descreve a relação da outra pessoa com o usuário proprietário. Por exemplo, em uma relação gerente-funcionário, o funcionário é o usuário proprietário, e você adiciona um campo relations à conta com o tipo manager. Para os tipos permitidos, consulte a referência do objeto User.

Para configurar o relacionamento, crie ou atualize o usuário proprietário com um corpo de solicitação JSON que inclua o campo relations. Você pode criar vários relacionamentos em uma solicitação.

{
  "relations": [
    {
      "value": "EMAIL_ADDRESS_RELATION_1",
      "type": "manager"
    },
    {
      "value": "EMAIL_ADDRESS_RELATION_2",
      "type": "dotted_line_manager"
    }
  ]
}

Atualizar ou excluir um relacionamento

Só é possível atualizar o campo relations. Ele só pode ser atualizado como um todo. Não é possível abordar as pessoas listadas para mudar o tipo de relação ou remover. No exemplo acima, para remover o relacionamento de gerente existente e tornar o administrador de linha pontilhada o gerente do usuário proprietário, atualize a conta do usuário proprietário com todos os valores do campo que você quer agora.

{
  "relations": [
    {
      "value": "EMAIL_ADDRESS_RELATION_2",
      "type": "manager"
    }
  ]
}

Para remover todas as relações dos usuários proprietários, defina relations como vazio:

{
  "relations": []
}

Recuperar um usuário

Para recuperar um usuário, use a seguinte solicitação GET e inclua a autorização descrita em Autorizar solicitações. O userKey pode ser o endereço de e-mail principal, o usuário único id ou um dos aliases de e-mail do usuário. Para as propriedades de solicitação e resposta, consulte a Referência da API.

GET https://admin.googleapis.com/admin/directory/v1/users/userKey

Este exemplo retorna as propriedades da conta do usuário cujo endereço de e-mail principal ou alias é liz@example.com:

GET https://admin.googleapis.com/admin/directory/v1/users/liz@example.com

Resposta JSON

Se a resposta for bem-sucedida, o código de status HTTP 200 será retornado. Juntamente com o código de status, a resposta retorna as propriedades da conta de usuário.

{
 "kind": "directory#user",
 "id": "the unique user id",
 "primaryEmail": "liz@example.com",
 "name": {
  "givenName": "Liz",
  "familyName": "Smith",
  "fullName": "Liz Smith"
 },
 "isAdmin": true,
 "isDelegatedAdmin": false,
 "lastLoginTime": "2013-02-05T10:30:03.325Z",
 "creationTime": "2010-04-05T17:30:04.325Z",
 "agreedToTerms": true,
 "hashFunction": "SHA-1",
 "suspended": false,
 "changePasswordAtNextLogin": false,
 "ipWhitelisted": false,
 "ims": [
  {
   "type": "work",
   "protocol": "gtalk",
   "im": "lizim@talk.example.com",
   "primary": true
  }
 ],
 "emails": [
  {
   "address": "liz@example.com",
   "type": "home",
   "customType": "",
   "primary": true
  }
 ],
 "addresses": [
  {
   "type": "work",
   "customType": "",
   "streetAddress": "1600 Amphitheatre Parkway",
   "locality": "Mountain View",
   "region": "CA",
   "postalCode": "94043"
  }
 ],
 "externalIds": [
  {
   "value": "employee number",
   "type": "custom",
   "customType": "office"
  }
 ],
 "organizations": [
  {
   "name": "Google Inc.",
   "title": "SWE",
   "primary": true,
   "customType": "",
   "description": "Software engineer"
  }
 ],
 "phones": [
  {
   "value": "+1 nnn nnn nnnn",
   "type": "work"
  }
 ],
 "aliases": [
  "lizsmith@example.com",
  "lsmith@example.com"
 ],
 "nonEditableAliases": [
  "liz@test.com"
 ],
 "customerId": "C03az79cb",
 "orgUnitPath": "corp/engineering",
 "isMailboxSetup": true,
 "includeInGlobalAddressList": true
}

Recuperar todos os usuários em um domínio

Para recuperar todos os usuários no mesmo domínio, 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/users
?domain=primary domain name&pageToken=token for next results page
&maxResults=max number of results per page
&orderBy=email, givenName, or familyName
&sortOrder=ascending or descending
&query=email, givenName, or familyName:the query's value*

Para as propriedades de solicitação e resposta, consulte a Referência da API.

Resposta JSON

Nesse exemplo, todos os usuários do domínio example.com são retornados com no máximo dois domínios de usuário por página de resposta. Há um nextPageToken para a lista de acompanhamento de usuários nessa resposta. Por padrão, o sistema retorna uma lista de cem usuários na ordem alfabética do endereço de e-mail do usuário:

GET https://admin.googleapis.com/admin/directory/v1/users?domain=example.com&maxResults=2

Se a resposta for bem-sucedida, o código de status HTTP 200 será retornado. Juntamente com o código de status, a resposta retorna duas contas de usuário no domínio example.com (maxResults=2):

{
 "kind": "directory#users",
 "users": [
  {
   "kind": "directory#user",
   "id": "the unique user id",
   "primaryEmail": "liz@example.com",
   "name": {
    "givenName": "Liz",
    "familyName": "Smith",
    "fullName": "Liz Smith"
   },
   "isAdmin": true,
   "isDelegatedAdmin": false,
   "lastLoginTime": "2013-02-05T10:30:03.325Z",
   "creationTime": "2010-04-05T17:30:04.325Z",
   "agreedToTerms": true,
   "hashFunction": "SHA-1",
   "suspended": false,
   "changePasswordAtNextLogin": false,
   "ipWhitelisted": false,
   "ims": [
    {
     "type": "work",
     "protocol": "gtalk",
     "im": "lizim@talk.example.com",
     "primary": true
    }
   ],
   "emails": [
    {
     "address": "liz@example.com",
     "type": "work",
     "customType": "",
     "primary": true
    }
   ],
   "addresses": [
    {
     "type": "work",
     "customType": "",
     "streetAddress": "1600 Amphitheatre Parkway",
     "locality": "Mountain View",
     "region": "CA",
     "postalCode": "94043"
    }
   ],
   "externalIds": [
    {
     "value": "employee number",
     "type": "custom",
     "customType": "office"
    }
   ],
   "organizations": [
    {
     "name": "Google Inc.",
     "title": "SWE",
     "primary": true,
     "customType": "",
     "description": "Software engineer"
    }
   ],
   "phones": [
    {
     "value": "+1 nnn nnn nnnn",
     "type": "work"
    }
   ],
   "aliases": [
    "lizsmith@example.com",
    "lsmith@example.com"
   ],
   "nonEditableAliases": [
    "liz@test.com"
   ],
   "customerId": "C03az79cb",
   "orgUnitPath": "corp/engineering",
   "isMailboxSetup": true,
   "includeInGlobalAddressList": true
  },
  {
   "kind": "directory#user",
   "id": "user unique ID",
   "primaryEmail": "admin2@example.com",
   "name": {
    "givenName": "admin",
    "familyName": "two",
    "fullName": "admin two"
   },
   "isAdmin": true,
   "isDelegatedAdmin": true,
   "lastLoginTime": "2013-02-05T10:30:03.325Z",
   "creationTime": "2010-04-05T17:30:04.325Z",
   "agreedToTerms": true,
   "hashFunction": "SHA-1",
   "suspended": true,
   "suspensionReason": "ADMIN",
   "changePasswordAtNextLogin": false,
   "ipWhitelisted": false,
   "emails": [
    {
     "address": "admin2@example.com",
     "type": "work",
     "customType": "",
     "primary": true
    }
   ],
   "externalIds": [
    {
     "value": "contractor license number",
     "type": "custom",
     "customType": "work"
    }
   ],
   "aliases": [
    "second_admin@example.com"
   ],
   "nonEditableAliases": [
    "admin@test.com"
   ],
   "customerId": "C03az79cb",
   "orgUnitPath": "corp/engineering",
   "isMailboxSetup": true,
   "includeInGlobalAddressList": true
  }
 ],
 "nextPageToken": "next page token"
}

Recuperar todos os usuários da conta

Para recuperar todos os usuários em uma conta que pode consistir em vários domínios, 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/users
?customer=my_customer or customerId&pageToken=token for next results page
&maxResults=max number of results per page
&orderBy=email, givenName, or familyName
&sortOrder=ascending or descending
&query=user attributes
  • A string de consulta customer é o valor my_customer ou customerId.
  • Use a string my_customer para representar o customerId da sua conta.
  • Como administrador do revendedor, use o customerId do cliente de revenda. Para o 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.
  • A string de consulta orderBy opcional determina se a lista é classificada pelo endereço de e-mail principal, sobrenome ou nome do usuário. Ao usar orderBy, também é possível usar a string de consulta sortOrder para listar os resultados em ordem crescente ou decrescente.
  • A string de consulta query opcional permite pesquisar muitos campos em um perfil de usuário, incluindo campos principais e personalizados. Consulte exemplos em Pesquisar usuários.

Para as propriedades de solicitação e resposta, consulte a Referência da API.

Neste exemplo, um administrador de conta está solicitando que todos os usuários da conta sejam retornados com uma entrada de usuário em cada página de resposta. O nextPageToken vai para a página de resultados seguinte:

GET https://admin.googleapis.com/admin/directory/v1/users?customer=my_customer&maxResults=1

Neste exemplo, um administrador de revendedor está solicitando todos os usuários em uma conta de revenda com o valor C03az79cb de customerId.

GET https://admin.googleapis.com/admin/directory/v1/users?customer=C03az79cb&maxResults=1

Resposta JSON

Se a resposta for bem-sucedida, o código de status HTTP 200 será retornado. Junto com o código de status, a resposta retorna todos os usuários desta conta:

{
 "kind": "directory#users",
 "users": [
  {
   "kind": "directory#user",
   "id": "the unique user id",
   "username": "admin2@example.com",
   "name": {
    "givenName": "admin",
    "familyName": "two",
    "fullName": "admin two"
   },
   "isAdmin": true,
   "isDelegatedAdmin": true,
   "lastLoginTime": "2013-02-05T10:30:03.325Z",
   "creationTime": "2010-04-05T17:30:04.325Z",
   "agreedToTerms": true,
   "hashFunction": "SHA-1",
   "suspended": false,
   "changePasswordAtNextLogin": false,
   "ipWhitelisted": false,
   "emails": [
    {
     "address": "admin2@example.com",
     "type": "work",
     "customType": "",
     "primary": true
    }
   ],
   "externalIds": [
    {
     "value": "employee number",
     "type": "custom",
     "customType": "office"
    }
   ],
   "aliases": [
     "second_admin@example.com"
   ],
   "nonEditableAliases": [
     "another_admin@test.com"
   ],
   "customerId": "C03az79cb",
   "orgUnitPath": "/",
   "isMailboxSetup": true,
   "includeInGlobalAddressList": true
  },
  {
   "kind": "directory#user",
   "id": "the unique user id",
   "username": "liz@example.com",
   "name": {
    "givenName": "Elizabeth",
    "familyName": "Smith",
    "fullName": "Elizabeth Smith"
   },
   "isAdmin": false,
   "isDelegatedAdmin": false,
   "lastLoginTime": "1336509883546",
   "creationTime": "1404802800000",
   "agreedToTerms": false,
   "hashFunction": "SHA-1",
   "suspended": false,
   "changePasswordAtNextLogin": false,
   "ipWhitelisted": false,
   "emails": [
    {
     "address": "liz@example.com",
     "type": "home",
     "customType": "",
     "primary": true
    }
   ],
   "externalIds": [
    {
     "value": "employee number",
     "type": "custom",
     "customType": "bank"
    }
   ],
   "relations": [
    {
     "value": "liz",
     "type": "friend",
     "customType": ""
    }
   ],
   "aliases": [
    "lizsmith@example.com",
    "lsmith@example.com"
   ],
   "nonEditableAliases": [
    "liz@test.com"
   ],
   "customerId": "C03az79cb",
   "orgUnitPath": "/",
   "isMailboxSetup": true,
   "includeInGlobalAddressList": true
  },
  {
   "kind": "directory#user",
   "id": "the unique user id",
   "username": "test3@example.com",
   "name": {
    "givenName": "Tester",
    "familyName": "Three",
    "fullName": "Tester Three"
   },
   "isAdmin": false,
   "isDelegatedAdmin": false,
   "lastLoginTime": "1336509883546",
   "creationTime": "1404802800000",
   "agreedToTerms": true,
   "hashFunction": "SHA-1",
   "suspended": false,
   "changePasswordAtNextLogin": false,
   "ipWhitelisted": false,
   "emails": [
    {
     "address": "test@example.com",
     "type": "work",
     "customType": "",
     "primary": true
    }
   ],
   "externalIds": [
    {
     "value": "employee number",
     "type": "custom",
     "customType": "office"
    }
   ],
   "aliases": [
    "tester3@example.com"
   ],
   "nonEditableAliases": [
    "third@test.com"
   ],
   "customerId": "C03az79cb",
   "orgUnitPath": "/",
   "isMailboxSetup": true,
   "includeInGlobalAddressList": true
  },
  {
   "kind": "directory#user",
   "id": "the unique user id",
   "username": "work_admin@example.com",
   "name": {
    "givenName": "Admin",
    "familyName": "Work",
    "fullName": "Admin Work"
   },
   "isAdmin": true,
   "isDelegatedAdmin": true,
   "lastLoginTime": "1336509883546",
   "creationTime": "1404802800000",
   "agreedToTerms": true,
   "hashFunction": "SHA-1",
   "suspended": false,
   "changePasswordAtNextLogin": false,
   "ipWhitelisted": false,
   "emails": [
    {
     "address": "work_admin@example.com",
     "type": "work",
     "customType": "",
     "primary": true
    }
   ],
   "externalIds": [
    {
     "value": "employee number",
     "type": "custom",
     "customType": "office"
    }
   ],
   "aliases": [
    "my_alias@example.com"
   ],
   "nonEditableAliases": [
    "other_alias@test.com"
   ],
   "customerId": "C03az79cb",
   "orgUnitPath": "/",
   "isMailboxSetup": true,
   "includeInGlobalAddressList": true
  }
 ],
 "nextPageToken": "NNNNN"
}

Recuperar usuários excluídos recentemente

Para recuperar todos os usuários excluídos nos últimos 20 dias de uma conta ou de um dos domínios dela, use as seguintes solicitações GET e inclua a autorização descrita em Autorizar solicitações. Veja como cancelar a exclusão de um usuário em Cancelar a exclusão de um usuário.

Para recuperar usuários excluídos nos últimos 20 dias do domínio principal ou de um subdomínio da conta, use a seguinte solicitação GET. A string de consulta domain é o nome de domínio principal do domínio. Para obter as propriedades de solicitação e resposta do usuário, consulte a Referência da API. Para facilitar a leitura, este exemplo usa retornos de linha:

GET https://admin.googleapis.com/admin/directory/v1/users
?domain=primary domain name&pageToken=token for next results page
&maxResults=max number of results per page
&showDeleted=true
Se uma conta tem vários domínios, você pode recuperar os usuários excluídos nos últimos 20 dias de toda a conta. Para isso, use a seguinte solicitação GET. Para facilitar a leitura, este exemplo usa retornos de linha:
GET https://admin.googleapis.com/admin/directory/v1/users
?customer=my_customer or customerId&pageToken=token for next results page
&maxResults=max number of results per page&showDeleted=true
  • A string de consulta customer é o valor my_customer ou customerId.
  • Como administrador da conta, use a string my_customer para representar o customerId da conta.
  • Como administrador do revendedor, use o customerId do cliente de revenda. Para o 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.

Para as propriedades de solicitação e resposta, consulte a Referência da API.

Neste exemplo, um administrador de conta solicita todos os usuários excluídos da conta:

GET https://admin.googleapis.com/admin/directory/v1/users?customer=my_customer&showDeleted=true

Resposta JSON

Se a resposta for bem-sucedida, o código de status HTTP 200 será retornado. Junto com o código de status, a resposta retorna todos os usuários da conta excluídos nos últimos 20 dias:

{
 "kind": "directory#users",
 "users": [
  {
   "kind": "directory#user",
   "id": "the unique user id",
   "primaryEmail": "user1@example.com"
  },
  {
   "kind": "directory#user",
   "id": "the unique user id",
   "primaryEmail": "user3@example.com"
  }
 ],
 "nextPageToken": "token for next page of deleted users"
}

Recuperar a foto de um usuário

A API recupera uma miniatura de foto, a foto mais recente do perfil do Google. Para recuperar a foto mais recente do usuário, use a seguinte solicitação GET e inclua a autorização descrita em Autorizar solicitações. O userKey pode ser o endereço de e-mail principal, o id ou qualquer um dos aliases de e-mail do usuário. Para as propriedades de solicitação e resposta, consulte a Referência da API.

GET https://admin.googleapis.com/admin/directory/v1/users/userKey/photos/thumbnail

Neste exemplo, a foto mais recente de liz@example.com é retornada:

GET https://admin.googleapis.com/admin/directory/v1/users/liz@example.com/photos/thumbnail

Resposta JSON

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

{
 "kind": "directory#user#photo",
 "id": "the unique user id",
 "primaryEmail": "liz@example.com",
 "mimeType": "the photo mime type",
 "height": "the photo height in pixels",
 "width": "the photo width in pixels",
 "photoData": "web safe base64 encoded photo data"
}

A codificação base64 segura da API para a Web das suas fotos é semelhante ao RFC 4648 "base64url". Isso significa que:

  • O caractere de barra (/) é substituído pelo caractere sublinhado (_).
  • O caractere do sinal de adição (+) é substituído pelo hífen (-).
  • O caractere do sinal de igual (=) é substituído pelo asterisco (*).
  • Para preenchimento, o caractere de ponto (.) é usado em vez da definição de URL de base RFC-4648, que usa o sinal de igual (=) para preenchimento. Isso é feito para simplificar a análise de URL.
  • Seja qual for o tamanho da foto enviada, a API a reduz proporcionalmente para 96 x 96 pixels.

Se você precisar criar links compatíveis a partir de JavaScript, a Google closure Library (links em inglês) inclui funções de codificação e decodificação Base64 que são lançadas sob a licença Apache.

Recuperar um usuário como não administrador

Embora as contas de usuário só possam ser modificadas pelos administradores, qualquer usuário no domínio pode ler os perfis de usuário. Um usuário que não é administrador pode fazer uma solicitação users.get ou users.list com o parâmetro viewType igual a domain_public para recuperar o perfil público de um usuário. O escopo https://www.googleapis.com/auth/admin.directory.user.readonly é ideal para esse caso de uso.

A visualização domain_public permite que um usuário não administrador acesse um conjunto padrão de campos principais. No caso de um campo personalizado, escolha se ele será público ou privado ao definir o esquema.

Atualizar a foto de um usuário

Para atualizar a foto de um usuário, use a seguinte solicitação PUT e inclua a autorização descrita em Autorizar solicitações. O userKey pode ser o endereço de e-mail principal, o id ou qualquer um dos aliases de usuário. Para as propriedades de solicitação e resposta, consulte a Referência da API.

PUT https://admin.googleapis.com/admin/directory/v1/users/userKey/photos/thumbnail

Neste exemplo, a foto liz@example.com foi atualizada:

PUT https://admin.googleapis.com/admin/directory/v1/users/liz@example.com/photos/thumbnail
{
"photoData": "web safe base64 encoded photo data"
}

Ao atualizar uma foto, height e width são ignorados pela API.

Resposta JSON

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

{
 "kind": "directory#user#photo",
 "id": "the unique user id",
 "primaryEmail": "liz@example.com",
 "mimeType": "the photo mime type",
 "height": "the photo height in pixels",
 "width": "the photo width in pixels",
 "photoData": "web safe base64 encoded photo data"
}

Excluir a foto de um usuário

Para excluir a foto de um usuário, use a seguinte solicitação DELETE e inclua a autorização descrita em Autorizar solicitações. O userKey pode ser o endereço de e-mail principal, o id ou qualquer um dos aliases de usuário. Para as propriedades de solicitação e resposta, consulte a Referência da API.

DELETE https://admin.googleapis.com/admin/directory/v1/users/userKey/photos/thumbnail

Depois de excluída, a foto do usuário não aparece. Sempre que a foto de um usuário for necessária, uma silhueta será exibida.

Excluir uma conta de usuário

Para excluir uma conta de usuário, use a seguinte solicitação DELETE e inclua a autorização descrita em Autorizar solicitações. O userKey pode ser o endereço de e-mail principal, o usuário único id ou um dos aliases de e-mail do usuário. Para as propriedades de solicitação e resposta, consulte a Referência da API.

DELETE https://admin.googleapis.com/admin/directory/v1/users/userKey

Neste exemplo, a conta de usuário liz@example.com é excluída:

DELETE https://admin.googleapis.com/admin/directory/v1/users/liz@example.com

Se a resposta for bem-sucedida, ela retornará apenas um código de status HTTP 200.

Considerações importantes antes de excluir um usuário:

  • O usuário excluído não poderá mais fazer login.
  • Para mais informações sobre a exclusão de contas de usuários, consulte a Central de Ajuda para admins.

Cancelar a exclusão de uma conta de usuário

Um usuário excluído nos últimos 20 dias precisa atender a determinadas condições antes que a conta do usuário possa ser restaurada.

Para cancelar a exclusão de uma conta de usuário, use a seguinte solicitação POST e inclua a autorização descrita em Autorizar solicitações. O userKey é o usuário único id encontrado na resposta da operação Recuperar usuários excluídos nos últimos 20 dias. O endereço de e-mail principal do usuário ou um dos endereços de e-mail do alias não pode ser usado no userKey para esta operação. Para as propriedades de solicitação e resposta, consulte a Referência da API.

POST https://admin.googleapis.com/admin/directory/v1/users/userKey/undelete

Nesse exemplo, a exclusão do usuário liz@example.com é cancelada. Todas as propriedades anteriores da conta desse usuário serão restauradas:

POST https://admin.googleapis.com/admin/directory/v1/users/12309329403209438205/undelete

Se a resposta for bem-sucedida, ela retornará apenas um código de status HTTP 204. Para ver a conta do usuário que teve a exclusão cancelada, use a operação Recuperar um usuário.