Apigee Edge から Apigee X への移行のアンチパターン

Apigee Edge のドキュメントを表示しています。
Apigee X のドキュメントをご覧ください。
info

Apigee Edge をご利用のお客様は、新しい機能やリージョンでの可用性を活用するために、インストールを Apigee X に移行することをおすすめします。

このページでは、Apigee X に移行する前に対応する必要がある構成のアンチパターンと、移行前に把握しておくべき動作の変更について説明します。

Apigee Edge のアンチパターンの広範なリストには、どのような場合でも避けるべき使用方法が記載されています。このページでは、移行をブロックする特定の推奨されない使用方法について説明します。Apigee X への移行時に問題が発生しないように、今すぐ解決してください。

API プロダクトのないアプリ

概要 クライアント サイドの変更が必要ですか? 解決策

API プロダクトのないアプリがあります。

Apigee Edge と Apigee X の違い:

Apigee Edge Apigee X
API プロダクトに関連付けられていないアプリと認証情報を構成できます。このアプリは、事実上すべての API プロダクトにアクセスできます。 各アプリは、少なくとも 1 つの API プロダクトにアクセスするように構成する必要があります。すべての API プロダクトへのアクセス権を暗黙的に付与する方法はありません。すべての API プロダクトにアクセスできるようにアプリを構成できますが、明示的に行う必要があります。
×

解決策: API プロダクトのないアプリ

すべてのアプリ認証情報を 1 つ以上の API プロダクトに関連付けます。この方法の詳細については、アプリの登録と API キーの管理をご覧ください。

簡単な方法は、各アプリにすべての API プロダクトへのアクセス権を割り当てることです。これは、Apigee Edge で可能なことと同等です。最小権限のアプローチを採用する場合は、各アプリの認証情報がアクセスする必要がある API プロダクトの最小リストを決定する必要があります。これは、クライアント ID に基づいて Apigee Edge Analytics レポートで分析できます。

有効期限のないキャッシュ

概要 クライアント サイドの変更が必要ですか? 解決策

キャッシュに有効期限がありません。

Apigee Edge と Apigee X の違い:

Apigee Edge Apigee X
キャッシュ リソース記述子の作成、更新、削除をサポートします。 キャッシュ リソース記述子の作成、更新、削除はサポートされていません。
いいえ

解決策: 有効期限のないキャッシュ

すべてのキャッシュの有効期限を設定します。

非確定パスの JSONPath フィルタ式

概要 クライアント サイドの変更が必要ですか? 解決策

非確定パスの場合、フィルタ式の結果のクエリは JSONPath 仕様の一部ではありません。https://goessner.net/articles/JsonPath/ をご覧ください。

Apigee Edge と Apigee X の違い:

この例の構造をナビゲートする場合、

{
    "books": [
      {
        "name": "A",
      },
      {
        "name": "B",
      }
    ]
}

$..books[?(@.name == 'A')][0] を使用すると、

Apigee Edge Apigee X
出力 ‘{"name": "A"}’ 出力 []

$..books[?(@.name == 'A')][0].name を使用すると、

Apigee Edge Apigee X
出力 "A" 出力 []
はい

解決策: 非確定パスの JSONPath フィルタ式

影響を受けるクエリを検索して置換します。

存在しないインデックスの JSONPath 式

概要 クライアント サイドの変更が必要ですか? 解決策

インデックスが存在しない JSONPath 式は、Apigee X と Apigee Edge で動作が異なります。パスが見つからない場合、Apigee X は PathNotFoundException エラーを返します。

Apigee Edge と Apigee X の違い:

この例の構造をナビゲートする場合、

{
    "books": [
      {
        "name": "A",
      },
      {
        "name": "B",
      }
    ]
}

$.books[3] を使用すると、

Apigee Edge Apigee X
出力 null PathNotFoundException エラーを出力します。
はい

解決策: 存在しないインデックスの JSONPath 式

影響を受けるクエリを検索して置換します。

配列インデックスを含む JSONPath 式が配列オブジェクトを返さない

概要 クライアント サイドの変更が必要ですか? 解決策

配列インデックスまたはスライスを含む JSONPath 式は、Apigee X で配列オブジェクトを返します。

Apigee Edge と Apigee X の違い:

この例の構造をナビゲートする場合、

{
    "books": [
      {
        "name": "A",
      },
      {
        "name": "B",
      }
    ]
}

$.books を使用すると、

Apigee Edge Apigee X
出力 {“name”:”A”, “name”: “B”} 出力 [{“name”:”A”, “name”: “B”}]

$.books[-1] を使用すると、

Apigee Edge Apigee X
出力 {“name”: “B”} 出力 [{“name”: “B”}]

$.books[-2:] を使用すると、

Apigee Edge Apigee X
出力 {“name”:”A”, “name”: “B”} 出力 [{“name”:”A”, “name”: “B”}]
はい

解決策: 配列インデックスを含む JSONPath 式が配列オブジェクトを返さない

アップグレード後に異なる結果を返す可能性がある式を検索して置換します。

キーストア名の制限事項

概要 クライアント サイドの変更が必要ですか? 解決策

Apigee X キーストア名に使用できるのは、英数字とハイフンのみです。Edge キーストア名にはこれらの制限はありません。

いいえ

解決策: キーストア名の制限事項

キーストア名を確認し、必要に応じてサポートされていない文字を削除するように名前を更新します。

API プロキシにデプロイされた複数のベースパス

概要 クライアント サイドの変更が必要ですか? 解決策

API プロキシの複数のリビジョンが環境にデプロイされ、各リビジョンに異なるベースパスが設定されている。

Apigee Edge と Apigee X の違い:

Apigee Edge Apigee X
各リビジョンが異なるベースパスを持つことができる API プロキシの複数のリビジョンのデプロイをサポートします。 プロキシに異なるベースパスがある場合でも、API プロキシの複数のリビジョンのデプロイはサポートされていません。
いいえ

解決策: API プロキシに複数のベースパスがデプロイされている

ベースパスに関係なく、バンドルの 1 つのリビジョンのみが環境にデプロイされるように、すべてのバンドルを更新します。

準拠していない HTTP メッセージ

概要 クライアント サイドの変更が必要ですか? 解決策

クライアントまたは API プロキシが、HTTP 標準に準拠していないメッセージ(リクエストまたはレスポンス)を送信します。たとえば、無効なヘッダー名、一部の制限付きヘッダーの重複などです。

API の実行で次のエラーが 1 つ以上発生している場合は、Apigee X に移行できません。

エラー 詳細
INVALID_CHARACTERS_IN_HEADER 指定されたヘッダーに 1 つ以上の無効な文字が見つかりました。有効なヘッダー名は、英字、数字、ハイフンで構成されます。
MISSING_COLON ヘッダー名とヘッダー値のペアに :(コロン)がありません。
MULTIPLE_CONTENT_LENGTH Content-Length ヘッダーに複数の値が指定されています。
CONTENT_LENGTH_NOT_INTEGER Content-Length ヘッダー値が整数ではありません。
INVALID_UPGRADE Upgrade ヘッダーは WebSocket 接続の有効化にのみ使用する必要がありますが、そうではありません。
URL_HEADER_SIZE_TOO_LONG リクエスト URL とヘッダーの合計サイズが、許容される最大サイズである 15 KB を超えている。
BODY_NOT_ALLOWED 「GET」、「DELETE」、「TRACE」、「OPTIONS」、「HEAD」メソッドではメッセージ本文は許可されません。
UNSUPPORTED_HTTP_VERSION リクエストに 1.1 以外の HTTP バージョンが使用されており、サポートされていません。
ZERO_CONTENT_LENGTH_FOR_POST_OR_PUT 「POST」または「PUT」メソッドに対して、Content-Length ヘッダー フィールドの値がゼロ(「0」)に設定されました。
UNSUPPORTED_RESPONSE_PREFIX サポートされていない「X-Apigee-」ヘッダー接頭辞がレスポンス ヘッダーに存在します。
はい、その可能性があります。

解決策: 準拠していない HTTP メッセージ

Apigee X に移行する前に、HTTP プロトコルのエラーを修正する必要があります。エラーがクライアント アプリケーションから発生した場合は、クライアント アプリのデベロッパーに問題を修正するよう依頼する必要があります。

OAuth 2.0 トークンの有効期限が無効

概要 クライアント サイドの変更が必要ですか? 解決策

OAuth 2.0 トークンの有効期限が指定された範囲外です。

Apigee Edge と Apigee X の違い:

Apigee Edge Apigee X
OAuth 2.0 トークンの有効期限に関する制約は現在適用されていませんが、適用が予定されています。制限事項の OAuth セクションのガイドラインをご覧ください。 OAuth 2.0 のアクセス トークンと更新トークンの有効期限を設定する必要があります。サポートされている範囲は次のとおりです。
  • 180 秒 <= OAuth 2.0 アクセス トークンの有効期限 <= 30 日
  • 1 日 <= OAuth 2.0 更新トークンの有効期限 <= 2 年
いいえ

解決策: OAuth 2.0 トークンの有効期限が無効

OAuthV2 ポリシーを使用し、<ExpiresIn><RefreshTokenExpiresIn> で有効期限を指定します。

商品の上限を超えています

概要 クライアント サイドの変更が必要ですか? 解決策

Apigee Edge の構成が、定義されたプロダクトの上限に準拠していません。Apigee Edge では適用されないが、Apigee X では適用されるプロダクトの上限があります。

いいえ

解決策: 商品の上限を超えている

Apigee X に移行する前に、プロダクトの上限を超える使用量を修正します。

エンドポイントとパスの両方のターゲット接続指定子を含む ServiceCallout ポリシー

概要 クライアント サイドの変更が必要ですか? 解決策

ServiceCallout ポリシーでは、<LocalTargetConnection> 要素に <APIProxy> 要素と <ProxyEndpoint> 要素、または <Path> 要素のいずれかを含める必要があります。両方を含めることはできません。詳しくは、<LocalTargetConnection> 要素をご覧ください。

Apigee Edge はこの要件を文書化していますが、強制していません。Apigee X は、両方の構成を含む <LocalTargetConnection> を検出すると、処理を停止します。

いいえ

解決策: エンドポイントとパスの両方のターゲット接続指定子を含む ServiceCallout ポリシー

ServiceCallout ポリシーの構成を確認し、準拠していない <LocalTargetConnection> 構成を削除します。

ターゲット サーバー名の制限

概要 クライアント サイドの変更が必要ですか? 解決策

Apigee X ターゲット サーバー名に使用できるのは、英数字、ハイフン、ピリオドのみです。エッジ ターゲット サーバー名には、これらの制限は適用されません。

いいえ

解決策: ターゲット サーバー名の制限

ターゲット サーバー名を確認し、必要に応じてサポートされていない文字を削除するように名前を更新します。

仮想ホストのトライアル証明書

概要 クライアント サイドの変更が必要ですか? 解決策

1 つ以上の仮想ホストが、Apigee 提供の「無料トライアル」証明書を使用している。これにより、仮想ホストは ORG-ENV.apigee.net などのドメインに対するリクエストに応答します。

Apigee Edge と Apigee X の違い:

Apigee Edge Apigee X
ORG-ENV.apigee.net 形式のドメイン名をサポートするように「default」vhost を自動的に構成します。これらのドメインで TLS を許可するワイルドカード証明書(「無料トライアル証明書」)があります。 ORG-ENV.apigee.net 形式の以前の Apigee ドメインは、Apigee X では使用できません。独自のドメイン名を構成し、証明書を適切にプロビジョニングする必要があります。
はい

解決策: 仮想ホストのトライアル証明書

独自のドメインを構成し、証明書を適切にプロビジョニングする必要があります。

ORG-ENV.apigee.net 形式の以前のドメイン名に依存するクライアント アプリケーションは、新しいドメインを呼び出すように変更する必要があります。

解決されていない DNS

概要 クライアント サイドの変更が必要ですか? 解決策

ターゲット エンドポイントに解決されていないドメイン名があります。

Apigee Edge と Apigee X の違い:

Apigee Edge Apigee X
DNS 解決に失敗した場合、Apigee はドメイン名に .apigee.com を追加し、DNS は 4xx レスポンス コードで正常に解決されます。 DNS 解決に失敗した場合、Apigee はリクエストを実行せず、5xx レスポンス コードを返します。
いいえ

解決策: DNS が解決されない

有効なドメイン名でターゲット エンドポイントを更新します。