Search v2 から v3 への移行

Auth0 Search v2 から v3 へ移行する方法について説明します。

ユーザー検索 v2 は、2019 年 6 月 30 日をもって提供終了となりました。ユーザー検索機能は、できるだけ早く search engine v3 (search_engine=v3) に移行することを強くお勧めします。

​

移行に関する考慮事項

移行を開始する前に、把握しておくべき点がいくつかあります。

• v2 が利用できなくなる前に、クエリで search engine v3 を使用していることを確実にするには、GET /api/v2/users エンドポイントへのすべての呼び出しを更新し、search_engine=v3 パラメーターを含める必要があります。これにより、更新が必要なクエリがあるかどうかを確認できるため、v2 が利用できなくなった際のダウンタイムを回避できます。
• 影響を受ける SDK のいずれかを介してユーザー検索を実行している場合も、上記のとおり search_engine=v3 パラメーターを渡す必要があります。
• 正規化されたユーザーフィールド (email、name、given_name、family_name、nickname) の検索値では、大文字と小文字は区別されません。その他のすべてのフィールド (すべての app_metadata/user_metadata フィールドを含む) では、大文字と小文字が区別されます。
• v3 では、取得できるユーザー数は 1000 件に制限されます。この制限に達している場合は、より詳細な結果が得られるように検索クエリを見直すことをお勧めします。ある時点で 1000 件を超えるユーザーの一覧が必要な場合は、代わりに Export Job API エンドポイントまたは User Import / Export Extension の使用をお勧めします。
• app_metadata/user_metadata フィールドでは、範囲検索とワイルドカード検索は使用できません。
• ユーザーフィールドは v2 のようにトークン化されないため、user_id:auth0 は値が auth0|12345 の user_id には一致しません。代わりに user_id:auth0* を使用してください。
• ワイルドカードはプレフィックス一致に使用できます。たとえば name:j* です。ワイルドカードのその他の使用方法 (例: サフィックス一致) では、リテラルは 3 文字以上である必要があります。たとえば、name:*usa は使用できますが、name:*sa は使用できません。
• .raw フィールド拡張子はサポートされなくなったため、削除する必要があります。v3 では、フィールドは指定された値全体に一致し、.raw サフィックスのない v2 のようにトークン化されません。
• connection フィールドは v3 ではサポートされていません。代わりに、そのエイリアスである identities.connection を使用してください。

​

移行が必要なクエリ

ユースケース	v2	v3
日付で検索	updated_at:>=2018-01-15	updated_at:[2018-01-15 TO *]
日付で検索	updated_at:>2018-01-15	<br/>updated_at:\{2018-01-15 TO *]<br/>
日付で検索	updated_at:<=2018-01-15	updated_at:[* TO 2018-01-15]
日付で検索	updated_at:<2018-01-15	updated_at:[* TO 2018-01-15}
日付で検索	last_login:<=2017-12	last_login:[* TO 2017-12]
文字列の完全一致	name.raw:"john richard doe"	name:"john richard doe"
語を含むフレーズ	name:"richard", name:richard	name:*richard*
語を含むフレーズ (3 文字未満)	name:*ri,name:*a, name:*ab*	(サポートされていません)

​

影響を受けるSDK

以下のSDKは User Search エンジンを使用しています。これらを使用している場合は、以下に示すバージョン (またはそれ以降のバージョン) を使用し、ユーザー検索を実行する際に search_engine=v3 パラメーターを指定してください。

SDK	v3 をサポートするバージョン	影響を受けるメソッド	注意事項
Auth0 Java	1.8.0	com.auth0.client.mgmt.UsersEntity.list	withSearchEngine("v3") を指定した UserFilter を渡します
Auth0 Python	3.0.0	management.Users.list	search_engine='v3' パラメーターを指定します
Auth0 Node	2.0.0	UsersManager.getAll, ManagementClient.getUsers	search_engine:'v3' パラメーターを指定します
Auth0 .NET	3.0.0 または 4.0.0	Auth0.ManagementApi.IUsersClient.GetAllAsync	SearchEngine = "v3" を指定した GetUsersRequest オブジェクトを渡します
Auth0 PHP	5.2.0	Auth0.SDK.API.Management.Users.getAll	'search_engine' => 'v3' パラメーターを指定します
Auth0 Ruby	4.5.0	Auth0.Api.V2.Users.users	search_engine: 'v3' パラメーターを指定します

​

影響を受ける拡張機能

次の拡張機能では User Search エンジンを使用しています。これらをインストールしている場合は、以下に示すバージョン (またはそれ以降のバージョン) を使用していることを確認してください。

Extension	v3 対応バージョン	注意事項
Authorization Extension	2.5.0+	それ以前のバージョンを使用している場合は、Extensions ページから拡張機能を手動で更新する必要があります。
Delegated Administration	3.1+	それ以前のバージョンを使用している場合は、Extensions ページから拡張機能を手動で更新する必要があります。3.1 では SEARCH_ENGINE 設定項目は廃止されており、利用可能なのは User Search v3 のみです。

​

テナントログを活用して User Search v2 の使用状況を確認する

Dashboard の ログ を活用すると、SDK による呼び出しを含め、User Search v2 エンジンを使用している /api/v2/users エンドポイントへの呼び出しを特定できます。これらのログは、アプリケーション内のどこでコードの変更が必要になる可能性があるかを把握するのに役立ちます。

User Search v2 に関連するログをすべて取得するには、次のクエリを使用します: type:w AND description:*search_engine*。ログでは、次のような場合に description フィールドに追加情報が表示されます。

• v3 で異なる結果になる可能性があるクエリ
• v3 と互換性のない構文を含むクエリ
• v3 のページング要件を満たしていないクエリ

ログエントリに追加の詳細が表示されていない場合は、クエリが v3 と互換性がある可能性が高いと考えられます。ただし、変更を本番環境にデプロイする前に、クエリをテストすることを引き続き推奨します。

同じ種類のログは、60 分以内に 1 件だけ生成される点に注意してください。つまり、User Search エンドポイントに対して複数回呼び出しを行っていても、1 時間あたり各種類のログは 1 件しか表示されません。