搜索用户

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

字段

要搜索的用户属性。例如 givenName。

运算符

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

值

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

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

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

字段

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

值类型

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

运算符

运算符	支持的值类型	备注
=	字符串、布尔值、数字、日期	字段和值完全匹配。例如，givenName=Jane 会与 givenName 属性为 "Jane" 的所有用户匹配，但不会与 "Jane Ann" 匹配。大多数字符串字段都支持该类型（见上文）。
:	字符串	该字段包含值中的完整字词，按顺序排列。例如，使用 givenName:Jane 的查询会与 givenName 值为 "Jane" 和 "Jane Ann" 的用户匹配，但与 "Janet" 不匹配。针对 'givenName:Mary Ann' 的多字词查询将与 "Mary Ann Evans" 和 "Sarah Mary Ann" 的值匹配，但与 "Ann Mary" 的值不匹配。大多数字符串字段都支持该类型（见上文）。
:{PREFIX}*	字符串	字段以该值开头。例如，使用 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 包含“Manager”的用户

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