> ## Documentation Index
> Fetch the complete documentation index at: https://auth0.generaltranslation.app/llms.txt
> Use this file to discover all available pages before exploring further.

# 検索v2からv3への移行

> Auth0検索v2からv3へ移行する方法を学びます。

ユーザー検索v2は、**2019年6月30日** をもってサポート終了となりました。なるべく早めに、ユーザー検索機能を[検索エンジンv3](/docs/ja-JP/ja-jp/manage-users/user-search)（`search_engine=v3`）に移行することを強くお勧めします。

<div id="migration-considerations">
  ## 移行に関する検討事項
</div>

移行を開始する前に、知っておくべきことがいくつかあります。

* v2が使用できなくなる前にクエリで検索エンジンv3が使用されるようにするには、すべての`GET /api/v2/users`エンドポイントの呼び出しを更新して、`search_engine=v3`パラメーターを含める必要があります。これにより、更新する必要があるクエリがあるかどうかを確認できるため、v2が使用できなくなったときにダウンタイムが発生することはありません。
* [影響を受けるSDK](#impacted-sdks)を通じてユーザー検索操作を行っている場合も、上記のように`search_engine=v3`パラメーターを渡す必要があります。
* 正規化されたユーザーフィールド（`email`、`name`、`given_name`、`family_name`、および`nickname`）の検索値は、大文字と小文字を区別しません。その他すべてのフィールド（すべての`app_metadata/user_metadatafi-rudo`/`user_metadata`フィールドを含む）は、大文字と小文字を区別します。
* v3では、取得できるユーザーの数が1000に制限されています。この制限に達しそうになった場合は、より詳細な結果を得るために検索クエリを再定義することをお勧めします。同時に1000人を超えるユーザーのリストが必要な場合は、代わりに[Export Job（ジョブのエクスポート）](/docs/ja-JP/ja-jp/api/management/v2#!/Jobs/post_users_exports)APIエンドポイントまたは、[［User Import / Export Extension（ユーザーのインポート/エクスポート拡張機能）］](/docs/ja-JP/ja-jp/manage-users/user-migration/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`エイリアスを使用してください。

<div id="queries-to-migrate">
  ## 移行するクエリ
</div>

<table class="table">
  <thead>
    <tr>
      <th>ユースケース</th>
      <th>v2</th>
      <th>v3</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>日付で検索</td>
      <td>`updated_at:&gt;=2018-01-15`</td>
      <td>`updated_at:[2018-01-15 TO *]`</td>
    </tr>

    <tr>
      <td>日付で検索</td>
      <td>`updated_at:&gt;2018-01-15`</td>
      <td>`updated_at:{2018-01-15 TO *]`</td>
    </tr>

    <tr>
      <td>日付で検索</td>
      <td>`updated_at:&lt;=2018-01-15`</td>
      <td>`updated_at:[* TO 2018-01-15]`</td>
    </tr>

    <tr>
      <td>日付で検索</td>
      <td>`updated_at:&lt;2018-01-15`</td>
      <td>`updated_at:[* TO 2018-01-15}`</td>
    </tr>

    <tr>
      <td>日付で検索</td>
      <td>`last_login:&lt;=2017-12`</td>
      <td>`last_login:[* TO 2017-12]`</td>
    </tr>

    <tr>
      <td>文字列の完全一致</td>
      <td>`name.raw:"john richard doe"`</td>
      <td>`name:"john richard doe"`</td>
    </tr>

    <tr>
      <td>単語を含む語句</td>
      <td>`name:"richard"`, `name:richard`</td>
      <td>`name:*richard*`</td>
    </tr>

    <tr>
      <td>単語を含む語句（3文字未満）</td>
      <td>`name:*ri`,`name:*a`, `name:*ab*`</td>
      <td><em>（非対応）</em></td>
    </tr>
  </tbody>
</table>

<div id="impacted-sdks">
  ## 影響を受けるSDK
</div>

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

<table class="table">
  <thead>
    <tr>
      <th>SDK</th>
      <th>v3対応バージョン</th>
      <th>影響を受けるメソッド</th>
      <th>考慮事項</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><a href="https://github.com/auth0/auth0-java">Auth0 Java</a></td>
      <td>1.8.0</td>
      <td>com.auth0.client.mgmt.UsersEntity.list</td>
      <td>`UserFilter`に`withSearchEngine("v3")`を提供する</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0/auth0-python">Auth0 Python</a></td>
      <td>3.0.0</td>
      <td>management.Users.list</td>
      <td>`search_engine='v3'`パラメーターを提供する</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0/node-auth0">Auth0 Node</a></td>
      <td>2.0.0</td>
      <td>UsersManager.getAll, ManagementClient.getUsers</td>
      <td>`search_engine:'v3'`パラメーターを提供する</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0/auth0.net">Auth0 .NET</a></td>
      <td>3.0.0または4.0.0</td>
      <td>Auth0.ManagementApi.IUsersClient.GetAllAsync</td>
      <td>`GetUsersRequest`オブジェクトに`SearchEngine` = `"v3"`を提供する</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0/auth0-php">Auth0 PHP</a></td>
      <td>5.2.0</td>
      <td>Auth0.SDK.API.Management.Users.getAll</td>
      <td>`'search_engine' =&gt; 'v3'`パラメーターを提供する</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0/ruby-auth0">Auth0 Ruby</a></td>
      <td>4.5.0</td>
      <td>Auth0.Api.V2.Users.users</td>
      <td>`search_engine: 'v3'`パラメーターを提供する</td>
    </tr>
  </tbody>
</table>

<div id="impacted-extensions">
  ## 影響を受ける拡張機能
</div>

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

<table class="table">
  <thead>
    <tr>
      <th>拡張機能</th>
      <th>v3対応バージョン</th>
      <th>考慮事項</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><a href="/docs/ja-JP/ja-jp/customize/extensions/authorization-extension/v2">認可拡張機能</a></td>
      <td>2.5.0+</td>
      <td>旧バージョンを使用している場合は、<a href="https://manage.auth0.com/#/extensions">拡張機能</a>ページから拡張機能を手動で更新する必要があります。</td>
    </tr>

    <tr>
      <td><a href="/docs/ja-JP/ja-jp/customize/extensions/delegated-admin/v3">委任管理</a></td>
      <td>3.1+</td>
      <td>旧バージョンを使用している場合は、<a href="https://manage.auth0.com/#/extensions">拡張機能</a>ページから拡張機能を手動で更新する必要があります。ユーザー検索v3のみが利用できるため、`SEARCH_ENGINE`構成設定は3.1にはもう存在しません。</td>
    </tr>
  </tbody>
</table>

<div id="leverage-your-tenant-logs-to-find-usage-of-user-search-v2">
  ## テナントログを利用してユーザー検索v2の使用状況を見つける
</div>

[［Dashboard］](https://manage.auth0.com/#/logs)の[ログ](/docs/ja-JP/ja-jp/deploy-monitor/logs)を利用して、SDKにより実行された呼び出しを含む、ユーザー検索v2エンジンを使用する`/api/v2/users`エンドポイントへの呼び出しを探すことができます。これらのログは、アプリケーション内でコードの変更が必要な場所を特定するのに役立ちます。

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

* v3では異なる結果が生成される可能性があるクエリ
* v3との互換性がない構文を使用したクエリ
* v3のページング要件を満たさないクエリ

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

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