このページは 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 Feature Template は、次の目的で設計されています。
- 簡潔な宣言型形式を好み、プロキシ構成をソース管理に保持したいAPI デベロッパーとアーキテクト。
- モデル バックエンドの前に Apigee ゲートウェイを配置する標準化された方法を必要とする AI 実務担当者。
- 再利用可能なプロキシ構成をパッケージ化し、多くのプロキシに一貫して適用したいプラットフォーム チームと DevOps チーム。
主なコンセプト
Apigee Feature Templates では、3 つのドキュメント タイプを使用します。それぞれが type フィールドで識別される YAML ファイルです。
| ドキュメントの種類 | type 値 |
目的 |
|---|---|---|
| テンプレート | template |
デプロイするエントリ ポイント。テンプレートは 1 つ以上の機能を構成し、プロキシのエンドポイントとルートを定義します。 |
| 機能 | feature |
テンプレートに含める再利用可能な構成単位（認証チェック、レート制限、バックエンド ターゲットなど）。機能にはポリシーとリソースが含まれます。 |
| プロキシ | proxy |
CLI がテンプレートをその機能でコンパイルするときに生成する、完全に解決されたプロキシ。通常、CLI によって生成される中間出力ですが、プロキシ ファイルを直接インポートして API プロキシ バンドルに変換することもできます。 |
テンプレートと機能を作成します。Apigee は、コンパイル時にプロキシを生成します。
仕組み
テンプレートをインポートすると、Google Cloud CLI は次の手順をローカルで実行し、結果を Apigee にアップロードします。
- コンパイル。CLI は、テンプレートとそれが参照する機能ファイルを読み取り、それらを統合して、単一のプロキシ定義を生成します。
- 変換。CLI は、プロキシ定義を標準の Apigee API プロキシ バンドル（Apigee が想定する XML ファイルの ZIP）に変換します。
- インポートします。CLI はバンドルを Apigee にアップロードし、新しい API プロキシのリビジョンを作成します。
プロキシをインポートしても、プロキシはライブになりません。別の手順として、他の API プロキシの場合と同様に、リビジョンを環境にデプロイします。
YAML template + feature files | gcloud 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 ソースに戻ることはできません。