您可以使用 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 |
字串 | =, : |
即時訊息網路 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 | 附註 |
|---|---|---|
| 字串 | 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 的串連值。name='Jane' 查詢不會傳回擁有 givenName='Jane' 和 familyName='Smith' 的使用者結果。
name='Jane Smith'
搜尋具備「givenName」或「familyName」含有特定值的使用者
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