搜尋使用者

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