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

​
移行時の注意事項

移行を開始する前に、いくつか知っておくべき点があります。
  • v2 が利用できなくなる前に、クエリで 検索エンジン 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 のようにトークン化はされません。
  • v3 では connection フィールドはサポートされていません。代わりに、その別名である identities.connection を使用してください。

​
移行が必要なクエリ

​
影響を受けるSDK

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

​
影響を受けるExtensions

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

​
テナントログを活用して User Search v2 の使用箇所を特定する

Auth0 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 件のログしか表示されません。