您可以使用 Directory API 的 users.list() 方法搜索与特定属性匹配的用户。此方法接受 query 参数，该参数是一个搜索查询，用于组合一个或多个搜索子句。每个搜索子句由 3 部分组成：
- 字段
- 要搜索的用户属性。例如
givenName。 - 运算符
- 对数据执行的测试，以提供匹配项。例如，
:运算符用于测试文本属性是否包含某个值。 - 值
- 要测试的属性的内容。例如
Jane。
如需在查询中搜索多个字段，请添加每个搜索子句，并用空格分隔。该操作是隐式 AND。
字段
| 字段 | 值类型 | 运算符 | 说明 |
|---|---|---|---|
| 未指定任何值 | 字符串 | 与 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，才能支持此运算符。 |
示例
所有查询均使用 users.list 方法，该方法的 HTTP 请求类似于以下内容（添加了换行符以提高可读性）：
GET https://admin.googleapis.com/admin/directory/v1/users?domain=DOMAIN_NAME&query=QUERY_PARAMETERS
按姓名搜索用户
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='janesmith@example.com'
搜索具有相同直接经理的用户
directManager='bobjones@example.com'
搜索特定国家/地区的用户
addressCountry='Sweden'
搜索特定组织中的用户
orgName='Human Resources'
搜索特定组织中的经理
orgName=Engineering orgTitle:Manager
搜索自定义用户属性
搜索参与特定项目的所有员工
EmploymentData.projects:'GeneGnomes'
搜索特定地理位置的所有员工
EmploymentData.location='Atlanta'
搜索职级高于 7 级的所有员工
EmploymentData.jobLevel>=7
搜索职级介于 5 和 8 之间的所有员工
EmploymentData.jobLevel:[5,8]
搜索已注册两步验证的所有员工
isEnrolledIn2Sv=true
搜索已强制执行两步验证的所有员工
isEnforcedIn2Sv=true