検索v2からv3への移行

ユーザー検索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_metadatafi-rudo/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では、フィールドは提供された値全体と照合され、v2のようにトークン化されることはありません（.rawサフィックスなし）。

• connectionフィールドはv3でサポートされていません。代わりに、そのidentities.connectionエイリアスを使用してください。

次のSDKはユーザー検索エンジンを利用します。これらのSDKを使用している場合は、以下に一覧されているバージョン（またはそれ以降）を使用していること、およびユーザー検索操作を実行するときにsearch_engine=v3パラメーターを渡します。

次の拡張機能はユーザー検索エンジンを利用します。これらの拡張機能をインストールしている場合は、以下に一覧されているバージョン（またはそれ以降）を使用していることを確認してください。

［Dashboard］のログを利用して、SDKにより実行された呼び出しを含む、ユーザー検索v2エンジンを使用する/api/v2/usersエンドポイントへの呼び出しを探すことができます。これらのログは、アプリケーション内でコードの変更が必要な場所を特定するのに役立ちます。

次のクエリを使用して、ユーザー検索v2に関連するすべてのログを取得できます：type:w AND description:*search_engine*。以下の場合は、ログの説明フィールドに追加情報が表示されます。

• v3では異なる結果が生成される可能性があるクエリ

• v3との互換性がない構文を使用したクエリ

• v3のページング要件を満たさないクエリ

ログエントリーに追加の詳細が指定されていない場合は、おそらくクエリにv3との互換性があります。ただし、変更を運用環境にデプロイする前にクエリをテストすることをお勧めします。

同じ種類のログは60分間に1つしか生成されないことに注意してください。これは、ユーザー検索エンドポイントに対して複数の呼び出しを行ったとしても、1時間あたり各タイプのログが1つしか表示されないことを意味します。