搜索用户

您可以使用 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	字符串	=, :	即时通讯网络 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 用户

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