Pesquisar usuários

É possível pesquisar usuários que correspondem a determinados atributos com o método users.list() da API Directory. Esse método aceita o parâmetro query, que é uma consulta de pesquisa que combina uma ou mais cláusulas de pesquisa. Cada cláusula de pesquisa é composta por três partes:

Campo

Atributo do usuário pesquisado. Por exemplo, givenName.

Operador

Teste que é realizado nos dados para fornecer uma correspondência. Por exemplo, o operador : testa se um atributo de texto contém um valor.

Valor

O conteúdo do atributo testado. Por exemplo, Jane.

Para pesquisar vários campos em uma consulta, adicione cada cláusula de pesquisa separada por um espaço. A operação é uma AND implícita.

Observação: a maioria dos dados do usuário é atualizada em 1 hora. No entanto, pode levar até 36 horas para que os novos dados sejam refletidos em todos os resultados da pesquisa.

Campos

Campo	Tipo de valor	Operadores	Descrição
Nenhum especificado	string		Compare com o valor em givenName, familyName ou email.
name	string	=, :	O valor concatenado de givenName e familyName.
email	string	=, :, :{PREFIX}*	Os endereços de e-mail do usuário, incluindo aliases.
givenName	string	=, :, :{PREFIX}*	O nome de batismo ou de registro do usuário.
familyName	string	=, :, :{PREFIX}*	O sobrenome ou sobrenome de um usuário.
isAdmin	booleano	=	Se um usuário tem privilégios de superadministrador.
isDelegatedAdmin	booleano	=	Se um usuário tem privilégios de administrador delegados.
isSuspended	booleano	=	Indica se a conta de um usuário está suspensa.
isArchived	booleano	=	Indica se a conta de um usuário está arquivada.
im	string	=, :	ID da rede de mensagens instantâneas.
externalId	string	=, :	Valor do ID externo.
manager	string	=	O endereço de e-mail do gerente de um usuário, seja diretamente ou na cadeia de gerenciamento.
managerId	string	=	O ID do gerente de um usuário, diretamente ou na cadeia de gerenciamento.
directManager	string	=	O endereço de e-mail do gerente direto de um usuário.
directManagerId	string	=	O ID do administrador direto de um usuário.
address	string	:	Corresponde a todos os campos de endereço.
addressPoBox	string	=, :	Uma caixa postal.
addressExtended	string	=, :	Um endereço estendido, como um que inclui uma sub-região.
addressStreet	string	=, :	Um endereço.
addressLocality	string	=, :	Uma cidade do endereço.
addressRegion	string	=, :	Uma província ou estado abreviado.
addressPostalCode	string	=, :	Um código postal ou CEP.
addressCountry	string	=, :	Um país.
orgName	string	=, :	Um nome de organização.
orgTitle	string	=, :	O cargo de um usuário na organização.
orgDepartment	string	=, :	Um departamento dentro da organização.
orgDescription	string	=, :	Uma descrição da organização.
orgCostCenter	string	=, :	O centro de custo de uma organização.
phone	string	=	O número de telefone do usuário.
orgUnitPath	string	=	O caminho completo de uma unidade organizacional. Isso corresponde a todas as cadeias de unidades organizacionais do destino. Por exemplo, 'orgUnitPath=/' retorna todos os usuários na organização. Este campo só pode ser usado quando viewType=admin_view.
isEnrolledIn2Sv	booleano	=	Indica se o usuário está inscrito na verificação em duas etapas.
isEnforcedIn2Sv	booleano	=	Indica se a verificação em duas etapas é aplicada ao usuário.
schemaName.fieldName	?	?	Um atributo de usuário personalizado, referenciado pelo esquema e pelo nome do campo. O campo precisa ter a propriedade indexed definida como true.

Tipos de valor

Tipo de valor	Esquema equivalente fieldType	Observações
string	STRING, EMAIL, PHONE	Coloque entre aspas simples ' se a consulta tiver espaços em branco. Use \' para escapar de aspas simples em consultas, por exemplo, 'Valentine\'s Day'.
booleano	BOOL	Precisa ter um valor de true ou false. Somente compatível com o operador =.
number	INT64, DOUBLE	Use um ponto como separador decimal e nenhum separador de milhar, por exemplo, 150430.25.
data	DATE	Especificado no formato AAAA-MM-DD, por exemplo, 2001-02-15.

Operadores

Operador	Tipos de valor aceitos	Observações
=	string, booleano, número, data	O campo e o valor correspondem exatamente. Por exemplo, givenName=Jane corresponde a todos os usuários com o atributo givenName "Jane", mas não "Jane Ann". Oferece suporte à maioria dos campos de string (consulte acima).
:	string	O campo contém as palavras inteiras no valor, em ordem. Por exemplo, uma consulta com givenName:Jane corresponde a usuários com valores givenName de "Jane" e "Jane Ann", mas não "Janet". Uma consulta de várias palavras para 'givenName:Mary Ann' corresponderia aos valores de "Mary Ann Evans" e "Sarah Mary Ann", mas não a "Ann Mary". Oferece suporte à maioria dos campos de string (consulte acima).
:{PREFIX}*	string	O campo começa com o valor. Por exemplo, uma consulta com givenName:Jane* corresponde a usuários com valores de givenName de "Jane", "Jane Ann" e "Janet", mas não "Sarah Jane". Suporte limitado a um conjunto de campos de string (consulte acima). Não é compatível com atributos personalizados.
:[{MIN},{MAX}]	número, data	O campo está dentro de um intervalo. Para fazer a correspondência, o valor do campo precisa ser maior ou igual a {MIN} e menor que {MAX}. Os atributos de números personalizados precisam especificar um numericIndexingSpec para oferecer suporte a esse operador.
>	número, data	O campo é maior que o valor. Os atributos de números personalizados precisam especificar um numericIndexingSpec para oferecer suporte a esse operador.
>=	número, data	O campo é maior ou igual ao valor. Os atributos de números personalizados precisam especificar um numericIndexingSpec para oferecer suporte a esse operador.
<	número, data	O campo é menor que o valor. Os atributos de números personalizados precisam especificar um numericIndexingSpec para oferecer suporte a esse operador.
<=	número, data	O campo é menor ou igual ao valor. Os atributos de números personalizados precisam especificar um numericIndexingSpec para oferecer suporte a esse operador.

Observação: usar o operador de intervalo :[min,max] não é o mesmo que unir >=min E <max para campos com vários valores. Por exemplo, se houver um campo com vários valores com dois valores, 10 e 20, ele vai corresponder à consulta field>12 field<15, porque há pelo menos um valor correspondente a cada cláusula, mas não à consulta field:[12,15], porque não há um único valor nesse intervalo.

Exemplos

Todas as consultas usam o método users.list, que tem uma solicitação HTTP semelhante a esta (quebras de linha incluídas para facilitar a leitura):

GET https://admin.googleapis.com/admin/directory/v1/users?domain=DOMAIN_NAME&query=QUERY_PARAMETERS

Observação: os parâmetros query precisam ser codificados em URL. Por exemplo, a consulta query=givenName:Jane* é codificada como URL como query=givenName%3AJane*. Todos os exemplos nesta página mostram parâmetros query não codificados. As bibliotecas de cliente processam essa codificação de URL automaticamente.

Pesquisar um usuário pelo nome

O campo de consulta name testa o valor concatenado de givenName e familyName. Uma consulta de name='Jane' não retorna resultados para um usuário com givenName='Jane' e familyName='Smith'.

name='Jane Smith'

Pesquisar usuários com um givenName OU familyName que contenha um valor

name:'Jane'

Pesquisar usuários que correspondem a um prefixo de e-mail

email:admin*

Pesquisar todos os superadministradores

isAdmin=true

Pesquisar usuários com orgTitles contendo "Gerente"

orgTitle:Manager

Pesquisar usuários com um gerente comum na cadeia de hierarquia

manager='[e-mail]'

Pesquisar usuários com o mesmo gerente direto

directManager='[e-mail]'

Pesquisar usuários em um determinado país

addressCountry='Sweden'

Pesquisar usuários em uma organização específica

orgName='Human Resources'

Pesquisar gerentes em uma organização específica

orgName=Engineering orgTitle:Manager

Pesquisar atributos personalizados do usuário

Observação: os exemplos a seguir assumem um esquema de usuário chamado EmploymentData com os campos projects, location e jobLevel.

Pesquisar todos os funcionários que trabalham em um projeto específico

EmploymentData.projects:'GeneGnomes'

Pesquisar todos os funcionários em um local específico

EmploymentData.location='Atlanta'

Pesquisar todos os funcionários acima do nível de cargo 7

EmploymentData.jobLevel>=7

Pesquisar todos os funcionários com níveis de cargo maiores ou iguais a 5 e menores que 8

EmploymentData.jobLevel:[5,8]

Pesquisar todos os funcionários inscritos na verificação em duas etapas

isEnrolledIn2Sv=true

Pesquisar todos os funcionários que têm a verificação em duas etapas ativada

isEnforcedIn2Sv=true