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エイリアスを使用してください。
移行するクエリ
| ユースケース | v2 | v3 |
|---|---|---|
| 日付で検索 | updated_at:>=2018-01-15 | updated_at:[2018-01-15 TO *] |
| 日付で検索 | updated_at:>2018-01-15 | updated_at:{2018-01-15 TO *] |
| 日付で検索 | 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はユーザー検索エンジンを利用します。これらのSDKを使用している場合は、以下に一覧されているバージョン（またはそれ以降）を使用していること、およびユーザー検索操作を実行するときにsearch_engine=v3パラメーターを渡します。
| SDK | v3対応バージョン | 影響を受けるメソッド | 考慮事項 |
|---|---|---|---|
| Auth0 Java | 1.8.0 | com.auth0.client.mgmt.UsersEntity.list | UserFilterにwithSearchEngine("v3")を提供する |
| 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 | GetUsersRequestオブジェクトにSearchEngine = "v3"を提供する |
| 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'パラメーターを提供する |
影響を受ける拡張機能
次の拡張機能はユーザー検索エンジンを利用します。これらの拡張機能をインストールしている場合は、以下に一覧されているバージョン（またはそれ以降）を使用していることを確認してください。| 拡張機能 | v3対応バージョン | 考慮事項 |
|---|---|---|
| 認可拡張機能 | 2.5.0+ | 旧バージョンを使用している場合は、拡張機能ページから拡張機能を手動で更新する必要があります。 |
| 委任管理 | 3.1+ | 旧バージョンを使用している場合は、拡張機能ページから拡張機能を手動で更新する必要があります。ユーザー検索v3のみが利用できるため、SEARCH_ENGINE構成設定は3.1にはもう存在しません。 |
テナントログを利用してユーザー検索v2の使用状況を見つける
［Dashboard］のログを利用して、SDKにより実行された呼び出しを含む、ユーザー検索v2エンジンを使用する/api/v2/usersエンドポイントへの呼び出しを探すことができます。これらのログは、アプリケーション内でコードの変更が必要な場所を特定するのに役立ちます。
次のクエリを使用して、ユーザー検索v2に関連するすべてのログを取得できます：type:w AND description:*search_engine*。以下の場合は、ログの説明フィールドに追加情報が表示されます。
- v3では異なる結果が生成される可能性があるクエリ
- v3との互換性がない構文を使用したクエリ
- v3のページング要件を満たさないクエリ