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

このページは Apigee と Apigee ハイブリッドに適用されます。

Apigee Edge のドキュメントを表示する

このページでは、Apigee 機能テンプレートの YAML 形式について説明します。template、feature、proxy のドキュメント タイプと、そのすべてのフィールドについて説明します。コンセプトの概要については、YAML を使用してプロキシを構成するをご覧ください。チュートリアルについては、YAML テンプレートから API プロキシを作成するをご覧ください。

規則

  • フィールド名には camelCase を使用します。たとえば、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 プロキシに構成する機能ファイル名のリスト。各名前は、テンプレートと同じディレクトリ内のファイルに解決される必要があります。 [] ×
parameters 特徴にデフォルト値を指定するパラメータ値のリスト。 [] ×
endpoints ベースパスとルートを定義するエンドポイントのリスト。 [] ×
targets バックエンド接続を定義するターゲットのリスト。 [] ×

ドキュメント タイプ: 機能

機能は、テンプレートに含める再利用可能な構成単位です。機能にはポリシーとリソースが含まれており、コンパイルされたプロキシにフロー、エンドポイント、ターゲットを提供できます。共通の最上位フィールドに加えて、特徴には次のフィールドがあります。

名前 説明 デフォルト 必須かどうか
displayName 人が読める形式の表示名。 なし ×
uid 機能のポリシーとリソースの Namespace に使用される一意の識別子。設定されていない場合、name が使用されます。 なし ×
documentation この機能のドキュメントを拡張しました。 なし ×
categories 自由形式のカテゴリラベルのリスト。 [] ×
parameters 機能が定義するパラメータのリスト。 [] ×
defaultEndpoint フローとデフォルトの障害ルールがコンパイル済みプロキシのすべてのエンドポイントに統合されるプロキシ エンドポイント。これを使用して、機能のポリシーをリクエスト フローまたはレスポンス フローに接続します。 なし ×
defaultTarget デフォルトのバックエンド接続として使用されるプロキシ ターゲット。 なし ×
endpoints プロキシに追加するプロキシ エンドポイントのリスト。既存のエンドポイントと同じ名前のエンドポイントは、既存のエンドポイントを置き換えます。 [] ×
targets プロキシに追加するプロキシ ターゲットのリスト。既存のターゲットと同じ名前のターゲットは、既存のターゲットを置き換えます。 [] ×
policies この機能が提供するポリシーのリスト。ポリシー名には、コンパイル時に機能の uid（または name）が自動的に付加されます。 [] ×
resources JavaScript ファイルやプロパティ ファイルなど、機能が提供するリソースのリスト。 [] ×

ドキュメント タイプ: プロキシ

プロキシは、CLI がテンプレートをその機能でコンパイルするときに生成する完全に解決されたドキュメントです。通常、この型を直接作成することはありません。API プロキシ バンドルの形状になるため、ここで説明します。

プロキシには、endpoints と targets（defaultEndpoint や defaultTarget ではない）を使用し、常に完全なデプロイ可能なプロキシを表すという点を除き、機能と同じフィールドがあります。type は proxy です。

ネストされたオブジェクト

パラメータ

パラメータは、特徴に値を指定します。パラメータの値は default に解決されます。

名前 説明 デフォルト 必須かどうか
name パラメータ名。機能コンテンツで {name} として参照されます。 なし ○
displayName 人が読める形式の名前。 なし ×
description パラメータの説明。 なし ×
default デフォルト値。機能の文字列で {name} の代わりに使用されます。 なし ×
examples 値の例のリスト。 [] ×
maps 値の置換のマップ。解決された値がマップ内のキーである場合は、マッピングされた値に置き換えられます。 なし ×
paths JSONPath 式のリスト。このリリースではサポートされていません - 使用するとエラーが発生します。 なし ×

endpoint

テンプレートの endpoints リストで使用されます。

名前 説明 デフォルト 必須かどうか
name エンドポイント名。 なし ○
basePath クライアントがプロキシの呼び出しに使用するベースパス（/v1/gemini など）。 なし ×
routes リクエストをターゲットにマッピングするルートのリスト。 [] ×

proxyEndpoint

機能の defaultEndpoint と endpoints、およびコンパイル済みプロキシで使用されます。フロー処理で endpoint を拡張します。

名前 説明 デフォルト 必須かどうか
flows フローのリスト。PreFlow または PostFlow という名前のフローは、対応する Apigee フローにマッピングされます。他の名前は、汎用フロー コンテナに配置されます。 [] ×
postClientFlow レスポンスがクライアントに送信された後に実行される単一のフロー。 なし ×
faultRules 障害ルールとして使用されるフローのリスト。 [] ×
defaultFaultRule 他の障害ルールが一致しない場合に実行される障害ルール。 なし ×

route

名前 説明 デフォルト 必須かどうか
name ルート名。 なし ○
target 転送先のターゲット エンドポイントの名前。 なし ×
condition このルートを適用するために満たす必要がある条件。 なし ×

フロー

名前 説明 デフォルト 必須かどうか
name フロー名。標準のリクエスト/レスポンス フローには、PreFlow または PostFlow を使用します。 なし ○
mode Request または Response。ステップがリクエストとレスポンスのどちらで実行されるかを決定します。 Request ×
condition フローを実行するために満たす必要がある条件。 なし ×
steps ステップ（ポリシー呼び出し）の順序付きリスト。 [] ×

ステップ

ステップは、フロー内でポリシーを実行します。

名前 説明 デフォルト 必須かどうか
name 実行するポリシーの名前。機能内では、ポリシーのローカル名を使用します。コンパイラは、それを名前空間名に書き換えます。 なし ○
condition ステップを実行するために満たす必要がある条件。 なし ×

faultRule

フローを 1 つの追加フィールドで拡張します。

フローから継承された mode フィールドは、障害ルールには適用されません。障害ルールはリクエストが失敗した後に実行されるため、リクエスト フェーズやレスポンス フェーズはありません。ステップは常に直接実行されます。障害ルールで mode を設定すると、ツールは警告をログに記録し、フィールドを無視します。

名前 説明 デフォルト 必須かどうか
alwaysEnforce true の場合、デフォルトの障害ルールが常に適用されます。 false ×

ターゲット

テンプレートの targets リストで使用されます。

名前 説明 デフォルト 必須かどうか
name ターゲット名。ルートの target によって参照されます。 なし ○
url バックエンド URL。 なし ×
auth Google Cloud バックエンドの認証スキーム（GoogleAccessToken や GoogleIDToken など）。 なし ×
scopes リクエストする OAuth スコープのリスト。auth が設定されている場合に適用されます。 [] ×
aud トークンの対象。auth が設定されている場合に適用されます。 なし ×

proxyTarget

機能の defaultTarget と targets、およびコンパイル済みプロキシで使用されます。フロー処理と未加工の接続オーバーライドでターゲットを拡張します。

名前 説明 デフォルト 必須かどうか
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（または name）が接頭辞として付加されます。 なし ○
type リソースタイプ。バンドル内のサブディレクトリを決定します（例: jsc（JavaScript）、properties）。 なし ○
content 未加工のファイルの内容。 なし ×

このリリースでサポートされていないフィールド

  • パラメータの paths（JSONPath）。これを使用すると、コンパイルが失敗します。
  • tests を使用して、ドキュメントの共同編集を行うことができます。フィールドは受け入れられますが無視され、生成されたバンドルには含まれません。

上限

生成された API プロキシ バンドルは、非圧縮で 10 MiB または 256 個のファイルを超えてはなりません。

次のステップ