搜尋使用者

您可以使用 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 AND <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 的串連值。使用者查詢「name='Jane'」時，系統不會傳回任何結果，因為使用者同時具有 givenName='Jane' 和 familyName='Smith'。

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