搜索用户

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

字段
搜索的用户属性。例如 givenName
运营商
对数据执行的测试以提供匹配。例如,: 运算符测试文本特性是否包含值。
被测试的属性的内容。例如 Jane

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

字段

字段 值类型 运算符 说明
未指定任何值 字符串 givenNamefamilyNameemail 中的值进行比较。
name 字符串 =, : givenNamefamilyName 的串联值。
email 字符串 =::{PREFIX}* 用户的电子邮件地址,包括别名。
givenName 字符串 =::{PREFIX}* 用户的姓氏或名字。
familyName 字符串 =::{PREFIX}* 用户的姓氏。
isAdmin 布尔值 = 用户是否有超级用户权限。
isDelegatedAdmin 布尔值 = 用户是否拥有委派的管理员权限。
isSuspended 布尔值 = 用户的帐号是否被暂停。
isArchived 布尔值 = 用户的帐号是否已被归档。
im 字符串 =, : IM 网络 ID。
externalId 字符串 =, : 外部 ID 值。
manager 字符串 = 用户管理员直接或管理链的电子邮件地址。
managerId 字符串 = 用户管理器直接 ID 或在管理链中的 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 备注
字符串 STRINGEMAILPHONE 如果查询包含空格,请用英文单引号 ' 括起来。使用 \' 对查询中的单引号进行转义,例如 'Valentine\'s Day'
布尔值 BOOL 值必须为 truefalse。仅支持 = 运算符。
number INT64DOUBLE 必须使用句点作为小数分隔符,而不是千位分隔符,例如 150430.25
date 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 查询字段测试 givenNamefamilyName 的串联值。对于具有 givenName='Jane'familyName='Smith' 的用户,对 name='Jane' 的查询不会返回任何结果。

name='Jane Smith'

搜索 givenNamefamilyName 中包含值的用户

name:'Jane'

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

email:admin*

搜索所有超级用户

isAdmin=true

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

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]

搜索所有已加入两步验证 vVerification 的员工

isEnrolledIn2Sv=true

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

isEnforcedIn2Sv=true