このページは Apigee と Apigee ハイブリッドに適用されます。
Apigee Edge のドキュメントを表示する
従来の XML プロキシ バンドルを作成する代わりに、YAML で Apigee API プロキシを定義し、Google Cloud CLI でデプロイできます。プロキシのエンドポイント、ルート、ポリシー、バックエンド ターゲットは、Apigee 機能テンプレートと呼ばれる YAML ファイルに記述します。Apigee は、これらのファイルを標準の API プロキシ バンドルにコンパイルします。
結果は通常の Apigee API プロキシ バンドルであるため、この方法で構築したプロキシは、Apigee UI または XML バンドルで構築したプロキシと同じ Apigee ランタイムで実行され、同じポリシーと動作になります。
YAML を使用してプロキシを定義する理由
従来の Apigee API プロキシ形式は、XML ファイルの ZIP アーカイブです。YAML は、多くのデベロッパーが読み取り、書き込み、レビューをより迅速に行うことができ、AI アシスタント ツールやエージェント ツールとの相性も良い代替手段を提供します。Apigee 機能テンプレートは、次の目的で設計されています。
- 簡潔な宣言型形式を好み、プロキシ構成をソース管理に保持したいAPI デベロッパーとアーキテクト。
- モデル バックエンドの前に Apigee ゲートウェイを配置する標準化された方法を必要とする AI 実務担当者。
- 再利用可能なプロキシ構成をパッケージ化し、多くのプロキシに一貫して適用したいプラットフォーム チームと DevOps チーム。
主なコンセプト
Apigee Feature Templates では、3 種類のドキュメント タイプが使用されます。各ファイルは、type フィールドで識別される YAML ファイルです。
| ドキュメントの種類 | type 値 |
目的 |
|---|---|---|
| テンプレート | template |
デプロイするエントリ ポイント。テンプレートは 1 つ以上の機能を構成し、プロキシのエンドポイントとルートを定義します。 |
| 機能 | feature |
テンプレートに含める再利用可能な構成単位（認証チェック、レート制限、バックエンド ターゲットなど）。Feature にはポリシーとリソースが含まれます。 |
| プロキシ | proxy |
CLI が機能を使用してテンプレートをコンパイルするときに生成する完全に解決されたプロキシ。通常は CLI によって生成される中間出力ですが、プロキシ ファイルを直接インポートして API プロキシ バンドルに変換することもできます。 |
テンプレートと機能を作成します。Apigee は、コンパイル時に プロキシを生成します。
仕組み
テンプレートをインポートすると、Google Cloud CLI は次の手順をローカルで実行し、結果を Apigee にアップロードします。
- コンパイル。CLI は、テンプレートとそれが参照する機能ファイルを読み取り、それらをマージして、単一のプロキシ定義を生成します。
- 変換。CLI は、プロキシ定義を標準の Apigee API プロキシ バンドル（Apigee が想定する XML ファイルの ZIP）に変換します。
- インポート。CLI はバンドルを Apigee にアップロードし、Apigee は新しい API プロキシのリビジョンを作成します。
プロキシをインポートしても、プロキシはライブになりません。別の手順として、他の API プロキシと同様に、リビジョンを環境にデプロイします。
YAML template + feature files | gcloud beta apigee apis import --from-template v API proxy revision (created, not yet serving traffic) | gcloud apigee apis deploy v Deployed proxy (serving traffic in an environment)
手順については、YAML テンプレートから API プロキシを作成するをご覧ください。
最小限の例
次のテンプレートは、2 つの機能（バックエンド ターゲットを追加する機能とレスポンス メッセージを追加する機能）を構成するプロキシを定義します。
gateway: apigee schemaVersion: 1.0.0 name: HelloWorld-v1 type: template description: API proxy for HelloWorld-v1 features: - proxy-apigeemock.yaml - response-helloworld.yaml
参照されるすべての機能ファイルは、テンプレートと同じディレクトリに存在する必要があります。実行可能な完全な例と、その例で使用する機能ファイルについては、YAML テンプレートから API プロキシを作成するをご覧ください。
対応策
- プロキシのエンドポイント、ベースパス、ルート、フロー、バックエンド ターゲットを YAML で定義します。
- 再利用可能なポリシーとリソースを機能としてパッケージ化し、テンプレートで構成します。
- Google Cloud ターゲットのバックエンド認証を追加します（Vertex AI バックエンドの Google アクセス トークンなど）。
- Google Cloud CLI を使用してテンプレートを新しい API プロキシ リビジョンとしてインポートし、標準のデプロイ コマンドでデプロイします。
制限事項
テンプレートと機能を作成する際は、次の点に注意してください。
- フィーチャーはローカル ファイルです。テンプレートは、同じディレクトリにある機能ファイルのみを参照できます。URL または共有カタログから機能を参照することはできません。
- パラメータ値にはデフォルト値が使用されます。機能でパラメータを定義できますが、パラメータ値は機能で定義されたデフォルトに解決されます。インポート時にパラメータ値をオーバーライドするコマンドライン フラグはありません。
- JSONPath パラメータはサポートされていません。
paths（JSONPath）式を使用するパラメータがあると、コンパイルが失敗します。 - テストは対象外です。
testsセクションはスキーマで受け入れられますが、無視され、生成されたバンドルには含まれません。 - スキーマは厳格です。不明なフィールドがあるとエラーが発生します。
gateway: apigeeとschemaVersion: 1.0.0のみがサポートされています。 - トラブルシューティングでは、生成された XML が使用されます。Apigee UI とランタイムは、生成されたバンドルで動作します。UI で YAML ソースに戻ることはできません。