此页面由 Cloud Translation API 翻译。

搜索用户

您可以使用 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