このページは Apigee と Apigee ハイブリッドに適用されます。
Apigee Edge のドキュメントを表示する
このページでは、Apigee 機能テンプレートの YAML 形式(template、feature、proxy のドキュメント タイプとそのすべてのフィールド)について説明します。コンセプトの概要については、YAML を使用したプロキシの構成をご覧ください。チュートリアルについては、YAML テンプレートから API プロキシを作成するをご覧ください。
規則
- フィールド名にはキャメルケースを使用します。たとえば、
schemaVersion、basePath、displayName、faultRules、defaultFaultRule、httpTargetConnectionです。 - スキーマは厳格です。不明なフィールドがあると、ファイルのインポート時にエラーが発生します。
- 必須項目。ファイルが解析されるときに検証されるのは、
gatewayとschemaVersionのみです。次の表で「はい」とマークされている他のフィールドは、実際に動作する API プロキシを生成するために必要です。
共通の最上位フィールド
すべての template、feature、proxy ドキュメントは、次のフィールドで始まります。
| 名前 | 説明 | デフォルト | 必須かどうか |
|---|---|---|---|
gateway |
ターゲット ゲートウェイ。apigee を指定します。 |
なし | はい |
schemaVersion |
ドキュメントのスキーマ バージョン。1.0.0 を指定します。 |
なし | はい |
name |
ドキュメントの名前。テンプレートまたはプロキシの場合、これはバンドルに書き込まれた API プロキシ名です。 | なし | はい |
type |
ドキュメント タイプ: template、feature、proxy。 |
なし | はい |
description |
人が読める形式の説明。 | なし | × |
priority |
コンパイル中に機能が適用される順序を制御する整数。数字が小さいほど優先度が高くなります。 | 100 |
× |
ドキュメント タイプ: テンプレート
テンプレートは、インポートするエントリ ポイントです。機能を構成し、プロキシのエンドポイントとルートを定義します。テンプレートにはポリシーやリソースは含まれません。これらは、テンプレートが参照する機能から取得されます。
| 名前 | 説明 | デフォルト | 必須かどうか |
|---|---|---|---|
features |
プロキシに作成する機能ファイルのリスト。各エントリは、テンプレートを含むディレクトリ(./features/spike-arrest.yaml など)を基準とした、特徴ファイルへのパスです。 |
[] |
× |
parameters |
特徴のパラメータの値を設定するパラメータのリスト。エントリの default は、同じ name を持つ機能パラメータの default をオーバーライドします。パラメータをご覧ください。 |
[] |
× |
endpoints |
ベースパスとルートを定義するエンドポイントのリスト。 | [] |
× |
targets |
バックエンド接続を定義するターゲットのリスト。 | [] |
× |
ドキュメントの種類: 機能
機能は、テンプレートに含める再利用可能な構成単位です。機能はポリシーとリソースを保持し、コンパイルされたプロキシにフロー、エンドポイント、ターゲットを提供できます。共通の最上位フィールドに加えて、特徴には次のフィールドがあります。
| 名前 | 説明 | デフォルト | 必須かどうか |
|---|---|---|---|
displayName |
人が読める形式の表示名。 | なし | × |
uid |
テンプレートに機能が複数回含まれている場合に、機能のポリシーとリソースを区別する固有識別子。機能で uid が設定されている場合、CLI は各ポリシー名とリソース名の先頭に UID- を追加し、それらへの参照を更新します。機能で uid が設定されていない場合、CLI は記述された名前を使用します。 |
なし | × |
documentation |
この機能に関する詳細なドキュメント。 | なし | × |
categories |
自由形式のカテゴリラベルのリスト。 | [] |
× |
parameters |
特徴が定義するパラメータのリスト。 | [] |
× |
defaultEndpoint |
プロキシ エンドポイント。そのフローとデフォルトの障害ルールは、コンパイルされたプロキシのすべてのエンドポイントにマージされます。これを使用して、機能のポリシーをリクエスト フローまたはレスポンス フローに接続します。 | なし | × |
defaultTarget |
デフォルトのバックエンド接続として使用されるプロキシ ターゲット。 | なし | × |
endpoints |
プロキシに追加するプロキシ エンドポイントのリスト。既存のエンドポイントと同じ名前のエンドポイントは、既存のエンドポイントを置き換えます。 | [] |
× |
targets |
プロキシに追加するプロキシ ターゲットのリスト。既存のターゲットと同じ名前のターゲットは、既存のターゲットを置き換えます。 | [] |
× |
policies |
この機能が提供するポリシーのリスト。この機能で uid が設定されている場合、CLI はコンパイル時に各ポリシー名の先頭に UID- を追加します(例: sa1-SA-SpikeArrest)。それ以外の場合、CLI はポリシー名をそのまま使用します。 |
[] |
× |
resources |
機能が提供するリソース(JavaScript やプロパティ ファイルなど)のリスト。 | [] |
× |
ドキュメントの種類: 委任状
プロキシは、CLI がテンプレートをコンパイルするときに生成する、完全に解決されたドキュメントです。通常、このタイプを直接作成することはありません。API プロキシ バンドルになる形式であるため、ここで説明します。
プロキシには、endpoints と targets(defaultEndpoint や defaultTarget ではない)を使用し、常に完全なデプロイ可能なプロキシを表す点を除き、機能と同じフィールドがあります。type は proxy です。
ネストされたオブジェクト
パラメータ
パラメータは特徴に値を指定します。機能はパラメータを宣言し、テンプレートは独自の parameters リストでパラメータの値を設定できます。CLI は、テンプレートをコンパイルするときに、各機能パラメータを次のように解決します。
- テンプレートの
parametersリストに、nameが一致し、defaultが空でないエントリがある場合、CLI はその値を使用します。特徴がuidを設定する場合、テンプレート エントリの名前はFEATURE_NAME.UID.PARAMETER_NAMEにする必要があります。 - それ以外の場合、CLI は機能パラメータの
defaultを使用します。 - どちらも値を設定しない場合、パラメータは空の文字列に解決されます。CLI はエラーを報告しません。
インポート時にパラメータ値を設定するコマンドライン フラグはありません。値を変更するには、テンプレートを編集します。
| 名前 | 説明 | デフォルト | 必須かどうか |
|---|---|---|---|
name |
パラメータ名。注目のコンテンツで {name} として参照されます。 |
なし | はい |
displayName |
人が読める形式の名前。 | なし | × |
description |
パラメータの説明。 | なし | × |
default |
機能で、テンプレートで値が設定されていない場合に使用される値。テンプレートでは、同じ名前の機能パラメータの値。CLI は空の値を無視します。CLI は、解決された値を機能の文字列の {name} に置き換えます。 |
なし | × |
examples |
値の例のリスト。 | [] |
× |
maps |
値の置換のマップ。解決された値がマップ内のキーである場合、マッピングされた値に置き換えられます。 | なし | × |
paths |
JSONPath 式のリスト。このリリースではサポートされていません。使用するとエラーが発生します。 | なし | × |
{name} を変更しません。endpoint
テンプレートの endpoints リストで使用されます。
| 名前 | 説明 | デフォルト | 必須かどうか |
|---|---|---|---|
name |
エンドポイント名。 | なし | はい |
basePath |
クライアントがプロキシの呼び出しに使用するベースパス(例: /v1/gemini)。 |
なし | × |
routes |
リクエストをターゲットにマッピングするルートのリスト。 | [] |
× |
proxyEndpoint
機能の defaultEndpoint と endpoints、およびコンパイル済みプロキシで使用されます。フロー処理でエンドポイントを拡張します。
| 名前 | 説明 | デフォルト | 必須かどうか |
|---|---|---|---|
flows |
フローのリスト。PreFlow または PostFlow という名前のフローは、対応する Apigee フローにマッピングされます。その他の名前は、汎用フローコンテナに配置されます。 |
[] |
× |
postClientFlow |
レスポンスがクライアントに送信された後に実行される単一のフロー。 | なし | × |
faultRules |
障害ルールとして使用されるフローのリスト。 | [] |
× |
defaultFaultRule |
他の一致する障害ルールがない場合に実行される障害ルール。 | なし | × |
route
| 名前 | 説明 | デフォルト | 必須かどうか |
|---|---|---|---|
name |
ルート名。 | なし | はい |
target |
ルーティング先のターゲット エンドポイントの名前。 | なし | × |
condition |
このルートを適用するために満たす必要がある条件。 | なし | × |
フロー
| 名前 | 説明 | デフォルト | 必須かどうか |
|---|---|---|---|
name |
フロー名。標準のリクエスト / レスポンス フローには PreFlow または PostFlow を使用します。 |
なし | はい |
mode |
Request または Response。ステップをリクエストで実行するか、レスポンスで実行するかを決定します。 |
Request |
× |
condition |
フローを実行するために満たす必要がある条件。 | なし | × |
steps |
ステップ(ポリシー呼び出し)の順序付きリスト。 | [] |
× |
ステップ
ステップは、フロー内でポリシーを実行します。
| 名前 | 説明 | デフォルト | 必須かどうか |
|---|---|---|---|
name |
実行するポリシーの名前。機能内では、ポリシーのローカル名を使用します。コンパイラは、これを名前空間付きの名前に書き換えます。 | なし | はい |
condition |
ステップを実行するために満たす必要がある条件。 | なし | × |
faultRule
flow を 1 つの追加フィールドで拡張します。
フローから継承された mode フィールドは、障害ルールには適用されません。障害ルールはリクエストが失敗した後に実行されるため、リクエスト フェーズやレスポンス フェーズはありません。そのステップは常に直接実行されます。障害ルールに mode を設定すると、ツールは警告をログに記録し、フィールドを無視します。
| 名前 | 説明 | デフォルト | 必須かどうか |
|---|---|---|---|
alwaysEnforce |
true の場合、デフォルトの障害ルールが常に適用されます。 |
false |
× |
ターゲット
テンプレートの targets リストで使用されます。
| 名前 | 説明 | デフォルト | 必須かどうか |
|---|---|---|---|
name |
ターゲット名。ルートの target によって参照されます。 |
なし | はい |
url |
バックエンド URL。 | なし | × |
auth |
Google Cloud バックエンドの認証スキーム(GoogleAccessToken、GoogleIDToken など)。 |
なし | × |
scopes |
リクエストする OAuth スコープのリスト。auth が設定されている場合に適用されます。 |
[] |
× |
aud |
トークンの対象。auth が設定されている場合に適用されます。 |
なし | × |
proxyTarget
機能の defaultTarget と targets、およびコンパイル済みプロキシで使用されます。フロー処理と未加工接続のオーバーライドを使用して target を拡張します。
| 名前 | 説明 | デフォルト | 必須かどうか |
|---|---|---|---|
flows |
ターゲット リクエストまたはレスポンスで実行されるフローのリスト。 | [] |
× |
faultRules |
障害ルールとして使用されるフローのリスト。 | [] |
× |
defaultFaultRule |
障害ルール。 | なし | × |
httpTargetConnection |
HTTPTargetConnection 要素の未加工の表現。詳細な構成に使用します。設定されている場合、url、auth、scopes、aud よりも優先されます。 |
なし | × |
localTargetConnection |
LocalTargetConnection 要素の未加工の表現。
設定されている場合、HTTP 接続よりも優先されます。 |
なし | × |
ポリシー
ポリシーは機能で定義されます。その構成は、ポリシー コンテンツの規則で説明されている属性 / テキスト規則を使用して content の下に記述されます。
| 名前 | 説明 | デフォルト | 必須かどうか |
|---|---|---|---|
name |
ポリシーの名前です。 | なし | はい |
type |
Apigee ポリシータイプ(VerifyAPIKey、SpikeArrest、Javascript など)。content の単一の最上位キーと一致する必要があります。 |
なし | はい |
content |
1 つのキーが type と等しい単一キーの辞書。ネストされた値は、以下の規則を使用してポリシーの XML を記述します。 |
{} |
はい |
ポリシー コンテンツの規則
Apigee ポリシーは XML です。YAML では、次のルールを使用して content で XML を表します。
content辞書にはキーが 1 つだけあり、ポリシーのtypeと一致する必要があります。- 要素属性は
metadataキーの下に配置されます。 - 要素テキストは
_textキーの下に配置されます。たとえば、<Foo bar="baz">qux</Foo>はFoo: {metadata: {bar: "baz"}, _text: "qux"}になります。要素にテキストのみがあり、属性がない場合は、テキストを値として直接記述できます。 - 子要素は、タグ名の下にネストされます。繰り返しタグはリストになります。
たとえば、次の機能ポリシーがあるとします。
policies: - name: VA-VerifyAPIKey type: VerifyAPIKey content: VerifyAPIKey: metadata: name: VA-VerifyAPIKey enabled: "true" continueOnError: "false" DisplayName: VA-VerifyAPIKey APIKey: metadata: ref: request.header.x-api-key
は、次のポリシー XML にコンパイルされます。
<VerifyAPIKey continueOnError="false" enabled="true" name="verify-api-key-VA-VerifyAPIKey"> <APIKey ref="request.header.x-api-key"></APIKey> <DisplayName>VA-VerifyAPIKey</DisplayName> </VerifyAPIKey>
リソース
リソースは、機能がバンドルに提供するファイル(JavaScript ファイルやプロパティ ファイルなど)です。
| 名前 | 説明 | デフォルト | 必須かどうか |
|---|---|---|---|
name |
ファイル名(例: hello-world.js)。機能で uid が設定されている場合、CLI はコンパイル時にリソース名の先頭に UID- を追加します。それ以外の場合、CLI は記述された名前を使用します。 |
なし | はい |
type |
リソースタイプ。バンドル内のサブディレクトリを決定します(例: jsc(JavaScript)、properties)。 |
なし | はい |
content |
未加工のファイルの内容。 | なし | × |
このリリースでサポートされていないフィールド
- パラメータの
paths(JSONPath)。これを使用すると、コンパイルが失敗します。 - 任意のドキュメントで
tests。このフィールドは受け入れられますが、無視され、生成されたバンドルには含まれません。
上限
生成された API プロキシ バンドルは、圧縮されていない状態で 10 MiB または 256 ファイルを超えないようにする必要があります。