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 de três partes:

Campo

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

Operador

Teste 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 é um AND implícito.

Observação: a maioria das atualizações de dados do usuário leva até uma hora, mas pode levar até 36 horas para que os novos dados apareçam 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 um usuário.
familyName	string	=, :, :{PREFIX}*	O 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 delegado.
isSuspended	booleano	=	Se a conta de um usuário está suspensa.
isArchived	booleano	=	Se a conta de um usuário está arquivada.
im	string	=, :	ID da rede de MI.
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 gestão.
managerId	string	=	O ID do gerente de um usuário, seja diretamente ou na cadeia de gestão.
directManager	string	=	O endereço de e-mail do gerente direto de um usuário.
directManagerId	string	=	O ID do gerente 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 completo, 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 um estado abreviado.
addressPostalCode	string	=, :	Um CEP ou código postal.
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	=, :	A descrição de uma 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 no destino. Por exemplo, 'orgUnitPath=/' retorna todos os usuários da organização. Esse campo só pode ser usado quando viewType=admin_view.
isEnrolledIn2Sv	booleano	=	Indica se um usuário está inscrito na verificação em duas etapas.
isEnforcedIn2Sv	booleano	=	Indica se a verificação em duas etapas é obrigatória para o usuário.
schemaName.fieldName	?	?	Um atributo de usuário personalizado, referenciado pelo esquema e nome do campo. A propriedade indexed do campo precisa ser definida como true.

Tipos de valor

Tipo de valor	fieldType do esquema equivalente	Observações
string	STRING, EMAIL, PHONE	Coloque entre aspas simples ' se a consulta contiver espaços em branco. Use o escape \' em aspas simples nas consultas, por exemplo, 'Valentine\'s Day'.
booleano	BOOL	Precisa ter um valor de true ou false. Aceita apenas o operador =.
número	INT64, DOUBLE	Use um ponto como separador decimal e não use 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 compatíveis	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". Compatível com a maioria dos campos de string (consulte acima).
:	string	O campo contém as palavras inteiras dentro do 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 com várias palavras para 'givenName:Mary Ann' corresponderia aos valores "Mary Ann Evans" e "Sarah Mary Ann", mas não a "Ann Mary". Compatível com a 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 givenName de "Jane", "Jane Ann" e "Janet", mas não "Sarah Jane". Só é compatível com um conjunto limitado de campos de string (consulte acima). Não é compatível com atributos personalizados.
:[{MIN},{MAX}]	number, date	O campo está dentro de um intervalo. Para corresponder, o valor do campo precisa ser maior ou igual a {MIN} e menor que {MAX}. Os atributos numéricos personalizados precisam especificar um numericIndexingSpec para oferecer suporte a esse operador.
>	number, date	O campo é maior que o valor. Os atributos numéricos personalizados precisam especificar um numericIndexingSpec para oferecer suporte a esse operador.
>=	number, date	O campo é maior ou igual ao valor. Os atributos numéricos personalizados precisam especificar um numericIndexingSpec para oferecer suporte a esse operador.
<	number, date	O campo é menor que o valor. Os atributos numéricos personalizados precisam especificar um numericIndexingSpec para oferecer suporte a esse operador.
<=	number, date	O campo é menor ou igual ao valor. Os atributos numéricos 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 combinar >=min E <max para campos de vários valores. Por exemplo, se houver um campo de vários valores com 10 e 20, ele vai corresponder à consulta field>12 field<15, já que há pelo menos um valor correspondente a cada cláusula, mas não à consulta field:[12,15], já que 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 à seguinte (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 por nome

O campo de consulta name testa o valor concatenado de givenName e familyName. Uma consulta por 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 que contenham "Gerente"

orgTitle:Manager

Pesquisar usuários com um gerente em comum na cadeia hierárquica

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 pressupõem 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 7

EmploymentData.jobLevel>=7

Pesquisar todos os funcionários com níveis de trabalho >= 5 e < 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