ユーザーの検索

特定の属性と一致するユーザーを検索するには、Directory API の users.list() メソッドを使用します。このメソッドには、1 つ以上の検索句を組み合わせた検索クエリを 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	ブール値	=	ユーザーが 2 段階認証プロセスに登録されているかどうか。
isEnforcedIn2Sv	ブール値	=	ユーザーに 2 段階認証プロセスが適用されているかどうか。
schemaName.fieldName	?	?	スキーマとフィールド名で参照されるカスタム ユーザー属性。このフィールドの indexed プロパティは true に設定されている必要があります。

値の型

値の型	同等のスキーマ fieldType	メモ
文字列	STRING、EMAIL、PHONE	クエリに空白文字が含まれている場合は、単一引用符 ' で囲みます。クエリ内の単一引用符は \' を使ってエスケープします（例: 'Valentine\'s Day'）。
ブール値	BOOL	値は true または false です。= 演算子のみがサポートされています。
数値	INT64、DOUBLE	小数点にはピリオドを使用し、3 桁ごとの区切り記号は使用しません（例: 150430.25）。
date	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* というクエリは、"Jane"、"Jane Ann"、"Janet" の givenName 値を持つユーザーに一致しますが、"Sarah Jane" を持つユーザーには一致しません。一部の文字列フィールドでのみサポートされています（上記を参照）。カスタム属性ではサポートされません。
:[{MIN},{MAX}]	数値、日付	フィールドが範囲内にあります。一致するのは、フィールドの値が {MIN} 以上かつ {MAX} 未満の場合です。カスタム数値属性でこの演算子をサポートするには、numericIndexingSpec を指定する必要があります。
>	数値、日付	フィールドがこの値よりも大きくなっています。カスタム数値属性でこの演算子をサポートするには、numericIndexingSpec を指定する必要があります。
>=	数値、日付	フィールドがこの値以上になっています。カスタム数値属性でこの演算子をサポートするには、numericIndexingSpec を指定する必要があります。
<	数値、日付	フィールドがこの値よりも小さくなっています。カスタム数値属性でこの演算子をサポートするには、numericIndexingSpec を指定する必要があります。
<=	数値、日付	フィールドがこの値以下になっています。カスタム数値属性でこの演算子をサポートするには、numericIndexingSpec を指定する必要があります。

注: 複数の値を持つフィールドに対しては、範囲演算子 :[min,max] と、>=min AND <max とでは意味が異なります。たとえば、10 と 20 という 2 つの値を持つ複数値フィールドがあるとします。この場合、クエリ field>12 field<15 は、各句に一致する値が 1 つ以上あるため、一致します。一方、field:[12,15] は、この範囲にある値がないため、一致しません。

例

すべてのクエリは users.list メソッドを使用します。このメソッドには、次のような HTTP リクエストがあります（読みやすくするために改行を入れています）。

GET https://admin.googleapis.com/admin/directory/v1/users?domain=DOMAIN_NAME&query=QUERY_PARAMETERS

注: query パラメータは URL エンコードする必要があります。たとえば、query=givenName:Jane* というクエリを URL エンコードすると query=givenName%3AJane* になります。このページのすべての例では、query パラメータをエンコードせずに表記しています。クライアント ライブラリは、この URL エンコードを自動的に行います。

名前でユーザーを検索する

name クエリ フィールドは、givenName と familyName を連結した値に対してテストします。name='Jane' というクエリは、givenName='Jane' と familyName='Smith' を持つユーザーに対して結果を返しません。

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

カスタム ユーザー属性を検索する

注: 以下の例では、projects、location、jobLevel のフィールドを持つ EmploymentData という名前のユーザー スキーマを想定しています。

特定のプロジェクトに従事するすべての従業員を検索する

EmploymentData.projects:'GeneGnomes'

特定の場所にいるすべての従業員を検索する

EmploymentData.location='Atlanta'

職位が 7 以上のすべての従業員を検索する

EmploymentData.jobLevel>=7

職位が 5 以上 8 未満のすべての従業員を検索する

EmploymentData.jobLevel:[5,8]

2 段階認証プロセスに登録されているすべての従業員を検索する

isEnrolledIn2Sv=true

2 段階認証プロセスが適用されているすべての従業員を検索する

isEnforcedIn2Sv=true