搜索用户

您可以使用 Directory API 的 users.list() 方法搜索与某些属性匹配的用户。此方法接受 query 参数，该参数是组合了一个或多个搜索子句的搜索查询。每个搜索子句由 3 个部分组成：

字段

搜索的用户特性。例如 givenName。

运营商

针对数据执行以提供匹配的测试。例如，: 运算符测试文本属性是否包含值。

值

被测试属性的内容。例如 Jane。

如需在查询中搜索多个字段，请添加各个搜索子句，并用空格分隔。该操作是隐式 AND。

注意 ：大多数用户数据会在 1 小时内更新，但新数据最长可能需要 36 小时才能反映在所有搜索结果中。

字段

字段	值类型	运算符	说明
未指定任何值	string		与 givenName、familyName 或 email 中的值进行比较。
name	string	=, :	givenName 和 familyName 的串联值。
email	string	=、:、:{PREFIX}*	用户的电子邮件地址，包括别名。
givenName	string	=、:、:{PREFIX}*	用户的名字或名字。
familyName	string	=、:、:{PREFIX}*	用户的姓氏或名字。
isAdmin	boolean	=	用户是否拥有超级用户权限。
isDelegatedAdmin	boolean	=	用户是否拥有委派管理员权限。
isSuspended	boolean	=	用户的账号是否已暂停。
isArchived	boolean	=	用户的账号是否已归档。
im	string	=, :	即时通讯网络 ID。
externalId	string	=, :	外部 ID 值。
manager	string	=	用户经理的直接电子邮件地址或管理链上游的电子邮件地址。
managerId	string	=	用户的经理的 ID，可以是直接的，也可以是管理链上层的。
directManager	string	=	用户的直接关联的经理的电子邮件地址。
directManagerId	string	=	用户的直接关联的经理的 ID。
address	string	:	匹配所有地址字段。
addressPoBox	string	=, :	一个邮政信箱。
addressExtended	string	=, :	扩展地址，例如包含子区域的地址。
addressStreet	string	=, :	街道地址。
addressLocality	string	=, :	地址所在的城镇或城市。
addressRegion	string	=, :	省/自治区/直辖市的缩写。
addressPostalCode	string	=, :	邮政编码。
addressCountry	string	=, :	国家/地区。
orgName	string	=, :	组织名称。
orgTitle	string	=, :	用户在组织中的职位。
orgDepartment	string	=, :	组织内的一个部门。
orgDescription	string	=, :	组织说明。
orgCostCenter	string	=, :	组织的成本中心。
phone	string	=	用户的电话号码。
orgUnitPath	string	=	组织部门的完整路径。这匹配目标下的所有组织部门链。例如，'orgUnitPath=/' 会返回组织中的所有用户。此字段只能在 viewType=admin_view 时使用。
isEnrolledIn2Sv	boolean	=	用户是否注册了两步验证。
isEnforcedIn2Sv	boolean	=	是否为用户强制执行两步验证。
schemaName.fieldName	?	?	通过架构和字段名称引用的自定义用户属性。该字段必须将其 indexed 属性设置为 true。

值类型

值类型	等效架构 fieldType	备注
string	STRING、EMAIL、PHONE	如果查询包含空格，请用单引号 ' 括住。使用 \' 转义查询中的单引号，例如 'Valentine\'s Day'。
boolean	BOOL	值必须为 true 或 false。仅支持 = 运算符。
number	INT64、DOUBLE	必须将英文句点用作小数分隔符，并且不能使用千位分隔符，例如 150430.25。
date	DATE	以 YYYY-MM-DD 格式指定，例如 2001-02-15。

运算符

运营商	支持的值类型	备注
=	string, boolean, number, date	字段与值完全匹配。例如，givenName=Jane 匹配所有具有 givenName 属性 "Jane" 的用户，但不匹配 "Jane Ann"。大多数字符串字段都支持（见上文）。
:	string	字段内包含值中的全部字词（按顺序）。例如，包含 givenName:Jane 的查询匹配 givenName 值为 "Jane" 和 "Jane Ann" 的用户，但不匹配 "Janet" 的用户。针对 'givenName:Mary Ann' 的多字词查询将匹配 "Mary Ann Evans" 和 "Sarah Mary Ann" 的值，但不匹配 "Ann Mary"。大多数字符串字段都支持（见上文）。
:{PREFIX}*	string	该字段以值开头。例如，包含 givenName:Jane* 的查询会匹配 givenName 值为 "Jane"、"Jane Ann" 和 "Janet" 的用户，但不会匹配 "Sarah Jane"。仅适用于一组有限的字符串字段（参见上文）。自定义属性不支持。
:[{MIN},{MAX}]	编号、日期	字段在一定范围内。若要进行匹配，此字段的值必须大于或等于 {MIN} 且小于 {MAX}。自定义数字属性必须指定 numericIndexingSpec 才能支持此运算符。
>	编号、日期	字段大于值。自定义数字属性必须指定 numericIndexingSpec 才能支持此运算符。
>=	编号、日期	字段大于或等于值。自定义数字属性必须指定 numericIndexingSpec 才能支持此运算符。
<	编号、日期	字段值小于该值。自定义数字属性必须指定 numericIndexingSpec 才能支持此运算符。
<=	编号、日期	字段小于或等于值。自定义数字属性必须指定 numericIndexingSpec 才能支持此运算符。

注意 ：使用范围运算符 :[min,max] 与联接多值字段的 >=min 和 <max 不同。例如，如果存在包含两个值 10 和 20 的多值字段，则该多值字段与查询 field>12 field<15 匹配，因为至少有一个值与每个子句匹配，但与查询 field:[12,15] 不匹配，因为此范围内没有单个值。

示例

所有查询都使用 users.list 方法，该方法具有类似于以下内容的 HTTP 请求（加入了换行符，以提高可读性）：

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

注意： query 参数必须采用网址编码。例如，查询 query=givenName:Jane* 的网址编码为 query=givenName%3AJane*。本页中的所有示例显示的是未编码的 query 参数。客户端库会自动处理此网址编码。

按名称搜索用户

name 查询字段测试 givenName 和 familyName 的串联值。如果用户使用了 givenName='Jane' 和 familyName='Smith'，则对 name='Jane' 的查询不会返回任何结果。

name='Jane Smith'

搜索 givenName 或 familyName 包含值的用户

name:'Jane'

搜索与电子邮件前缀匹配的用户

email:admin*

搜索所有超级用户

isAdmin=true

搜索 orgTitles 包含“经理”的用户

orgTitle:Manager

搜索其汇报链中有共同经理帐号的用户

manager='[e-mail]'

搜索具有相同直接关联的经理账号的用户

directManager='[e-mail]'

搜索位于特定国家/地区的用户

addressCountry='Sweden'

搜索特定组织中的用户

orgName='Human Resources'

搜索特定组织中的管理员

orgName=Engineering orgTitle:Manager

搜索自定义用户属性

注意 ：以下示例假定了一个名为 EmploymentData 的用户架构，其中包含字段 projects、location 和 jobLevel。

搜索参与特定项目的所有员工

EmploymentData.projects:'GeneGnomes'

搜索特定地点的所有员工

EmploymentData.location='Atlanta'

搜索职位级别高于 7 的所有员工

EmploymentData.jobLevel>=7

搜索职位级别不低于 5 且小于 8 的所有员工

EmploymentData.jobLevel:[5,8]

搜索已注册两步验证的所有员工

isEnrolledIn2Sv=true

搜索所有已强制执行两步验证的员工

isEnforcedIn2Sv=true