搜尋使用者

您可以使用 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	字串	=, :	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 中含有「Manager」的使用者

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