API プロキシの YAML 構成リファレンス

このページは 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 は、テンプレートをコンパイルするときに、各機能パラメータを次のように解決します。

  1. テンプレートの parameters リストに、name が一致し、default が空でないエントリがある場合、CLI はその値を使用します。特徴が uid を設定する場合、テンプレート エントリの名前は FEATURE_NAME.UID.PARAMETER_NAME にする必要があります。
  2. それ以外の場合、CLI は機能パラメータの default を使用します。
  3. どちらも値を設定しない場合、パラメータは空の文字列に解決されます。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 ファイルを超えないようにする必要があります。

次のステップ