REST API 互換性

REST クライアントが非互換（破壊的）API 変更の影響を軽減できるように、Elasticsearch はリクエストごとにオプトインの API 互換性モードを提供します。

Elasticsearch の REST API は、一般的にバージョン間で安定しています。しかし、一部の改善には以前のバージョンと互換性のない変更が必要です。たとえば、Elasticsearch 7.x は多くの URL パスでカスタムマッピングタイプをサポートしていましたが、Elasticsearch 8.0 以降はサポートしていません（マッピングタイプの削除を参照）。Elasticsearch 8.0 以降に送信されたリクエストでカスタムタイプを指定するとエラーが返されます。しかし、REST API 互換性をリクエストすると、マッピングタイプがもはやサポートされていなくても、Elasticsearch はリクエストを受け入れます。

API が削除される予定であるか、互換性のない方法で変更される場合、元の API は 1 回以上のリリースで非推奨となります。元の API を使用すると、ログに非推奨警告がトリガーされます。これにより、非推奨ログを確認し、アップグレード前に適切なアクションを取ることができます。しかし、場合によっては、非推奨 API が使用されているすべての場所を特定することが難しいことがあります。ここで REST API 互換性が役立ちます。

REST API 互換性をリクエストすると、Elasticsearch は以前の REST API バージョンを尊重しようとします。Elasticsearch は、最も互換性のある URL、リクエストボディ、レスポンスボディ、および HTTP パラメータを適用しようとします。

互換性のある API では、これは影響を与えません—それは、前のバージョンから破壊的な変更がある API への呼び出しにのみ影響します。Elasticsearch が自動的に非互換性を解決できない場合、互換性モードでもエラーが返される可能性があります。

REST API 互換性は、以前のバージョンと同じ動作を保証するものではありません。これは、リクエストがエラーを返すのではなく処理されるように、Elasticsearch に自動的に非互換性を解決するよう指示します。

REST API 互換性は、アップグレードプロセスをスムーズにするための橋渡しであり、長期的な戦略ではありません。REST API 互換性は、1 つのメジャーバージョン間でのみ尊重されます：8.x から 7.x のリクエスト/レスポンスを尊重します。

REST API 互換性を使用してリクエストを送信し、Elasticsearch が非互換性を解決すると、カテゴリ「compatible_api」で非推奨ログにメッセージが書き込まれます。非推奨ログを確認して、使用のギャップや完全にサポートされている機能を特定してください。

特定の破壊的変更および互換性モードをリクエストする影響に関する情報は、REST API 変更を移行ガイドで参照してください。

REST API 互換性のリクエスト

REST API 互換性は、Accept および/または Content-Type ヘッダーを介してリクエストごとに実装されます。

たとえば:

テキスト

  1. Accept: "application/vnd.elasticsearch+json;compatible-with=7"
  2. Content-Type: "application/vnd.elasticsearch+json;compatible-with=7"

Accept ヘッダーは常に必要であり、Content-Type ヘッダーはリクエストにボディが送信される場合にのみ必要です。7.x または 8.x の Elasticsearch サーバーと通信する際に有効な値は次のとおりです:

テキスト

  1. "application/vnd.elasticsearch+json;compatible-with=7"
  2. "application/vnd.elasticsearch+yaml;compatible-with=7"
  3. "application/vnd.elasticsearch+smile;compatible-with=7"
  4. "application/vnd.elasticsearch+cbor;compatible-with=7"

公式にサポートされている Elasticsearch クライアント は、すべてのリクエストに対して REST API 互換性を有効にできます。

Elasticsearch に受信されるすべてのリクエストに対して REST API 互換性を有効にするには、環境変数 ELASTIC_CLIENT_APIVERSIONING を true に設定します。

REST API 互換性ワークフロー

7.17 から 8.15.2 へのアップグレード中に REST API 互換性を活用するには:

  • 1. Elasticsearch クライアント を最新の 7.x バージョンにアップグレードし、REST API 互換性を有効にします。
  • 2. Upgrade Assistant を使用して、すべての重要な問題を確認し、非推奨ログを調査します。一部の重要な問題は、REST API 互換性によって軽減される可能性があります。
  • 3. アップグレードを進める前に、すべての重要な問題を解決します。
  • 4. Elasticsearch を 8.15.2 にアップグレードします。
  • 5. カテゴリ compatible_api のエントリについて非推奨ログを確認します。互換性モードに依存していたリクエストに関連するワークフローを確認します。
  • 6. Elasticsearch クライアントを 8.x にアップグレードし、必要に応じて手動で互換性の問題を解決します。