搜尋使用者

您可以使用 Directory API 的 users.list() 方法，搜尋符合特定屬性的使用者。這個方法接受 query 參數，這是結合一或多個搜尋子句的搜尋查詢。每個搜尋子句都由 3 個部分組成：

欄位

搜尋的使用者屬性。例如 givenName。

業者

對資料執行測試以提供匹配。舉例來說，: 運算子會測試文字屬性「包含」值。

值

受測試的屬性內容。例如 Jane。

如要在查詢中搜尋多個欄位，請新增每個搜尋子句，並以空格分隔。這項作業為隱式 AND，

注意： 大部分使用者資料更新會在 1 小時內更新，但新資料最多可能需要 36 小時才會反映在所有搜尋結果中。

欄位

欄位	值類型	運算子	說明
未指定	字串		比較 givenName、familyName 或 email 中的值。
name	字串	=, :	givenName 和 familyName 的串連值。
email	字串	=、:、:{PREFIX}*	使用者的電子郵件地址，包括別名。
givenName	字串	=、:、:{PREFIX}*	使用者的名字或名字。
familyName	字串	=、:、:{PREFIX}*	使用者的姓氏或名字。
isAdmin	boolean	=	使用者是否擁有超級管理員權限。
isDelegatedAdmin	boolean	=	使用者是否擁有委派管理員權限。
isSuspended	boolean	=	使用者帳戶是否遭停權。
isArchived	boolean	=	使用者帳戶是否已封存。
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	boolean	=	使用者是否已註冊兩步驟驗證。
isEnforcedIn2Sv	boolean	=	是否要為使用者強制執行兩步驟驗證。
schemaName.fieldName	?	?	一個自訂使用者屬性，由其結構定義和欄位名稱參照。這個欄位的 indexed 屬性必須設為 true。

值類型

值類型	對等結構定義 fieldType	附註
字串	STRING、EMAIL、PHONE	如果查詢含有空白字元，請用單引號括住 '。在查詢中使用 \' 逸出單引號，例如 'Valentine\'s Day'。
boolean	BOOL	值必須為 true 或 false。僅支援 = 運算子。
號碼	INT64、DOUBLE	必須以半形句號做為小數分隔符，且不可使用千位分隔符，例如 150430.25。
日期	DATE	以 YYYY-MM-DD 格式指定，例如 2001-02-15。

運算子

業者	支援的值類型	附註
=	string, boolean, number, date	欄位與值完全相符。舉例來說，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