搜索用户

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

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

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

字段

字段 值类型 运算符 说明
未指定任何值 string givenNamefamilyNameemail 中的值进行比较。
name string =, : givenNamefamilyName 的串联值。
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 STRINGEMAILPHONE 如果查询包含空格,请用单引号 ' 括住。使用 \' 转义查询中的单引号,例如 'Valentine\'s Day'
boolean BOOL 值必须为 truefalse。仅支持 = 运算符。
number INT64DOUBLE 必须将英文句点用作小数分隔符,并且不能使用千位分隔符,例如 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 才能支持此运算符。

示例

所有查询都使用 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]

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

isEnrolledIn2Sv=true

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

isEnforcedIn2Sv=true