apigee-x-proxy-development

Apigee X API プロキシ開発

Google Cloud の Apigee X プラットフォームで API プロキシを構築するための包括的なスキルです。プロキシ開発の全ライフサイクルを網羅します。バンドル構造、エンドポイント構成、フロー設計、ポリシーの実装、障害処理、JavaScript による拡張、共有フロー、高度なパターンを扱います。

このスキルで扱う内容： API プロキシバンドルの作成、ポリシーの構成（42 種類以上のポリシータイプ）、フロー実行の設計、条件付きルーティング、障害処理、JavaScript コールアウト、共有フロー、高度な開発パターン。

このスキルで扱わない内容： Apigee X のデプロイやプロビジョニング、CI/CD パイプライン、Apigee Hybrid 固有の構成、GCP インフラストラクチャの設定、Apigee 管理 API の使用。対象はプロキシ開発の成果物に限定されます。

このスキルを使用する場面

ユーザーが次の作業を行っている場合に、このスキルを使用してください。

• API プロキシバンドルをゼロから新規作成する
• Apigee ポリシー（セキュリティ、メディエーション、トラフィック管理など）を記述または構成する
• フローパイプライン（PreFlow、条件付きフロー、PostFlow、PostClientFlow）を設計する
• ProxyEndpoints、TargetEndpoints、RouteRules を構成する
• 障害処理（FaultRules、DefaultFaultRule、RaiseFault）を実装する
• Apigee プロキシ用の JavaScript コールアウトコードを記述する
• 共有フローを作成または利用する
• プロキシの実行やポリシーのエラーをデバッグする
• 既存のプロキシ構成の正確性やベストプラクティスへの準拠を確認する
• Apigee X のポリシーの動作、フロー変数、条件について質問する

ユーザーが次の作業を行っている場合は、このスキルを使用しないでください。

• Apigee 環境にプロキシをデプロイする（代わりにデプロイツールを使用してください）
• Apigee Hybrid のランタイムインフラストラクチャを構成する
• プロキシバンドル用の CI/CD を設定する
• API を介して Apigee の組織、環境、環境グループを管理する
• Apigee 以外の API ゲートウェイを使用する

公式ドキュメントの参照

特定のポリシー構文の確認、動作の検証、最近の変更の確認が必要な場合：

• ウェブ検索： site:cloud.google.com/apigee を使用して、公式の Apigee X ドキュメントに検索結果を絞り込みます
• ポリシーリファレンス： https://cloud.google.com/apigee/docs/api-platform/reference/policies/[policy-name]-policy を取得します
• 構成リファレンス： https://cloud.google.com/apigee/docs/api-platform/reference/api-proxy-configuration-reference を取得します
• フロー変数： https://cloud.google.com/apigee/docs/api-platform/reference/variables-reference を取得します
• 条件： https://cloud.google.com/apigee/docs/api-platform/reference/conditions-reference を取得します
• 検証済みの例： https://github.com/GoogleCloudPlatform/apigee-samples を参照して、本番環境でのパターンを確認します

重要： docs.apigee.com は使用しないでください。これは Apigee Edge の旧ドキュメントです。Apigee X では常に cloud.google.com/apigee を使用してください。

API プロキシバンドルのクイックリファレンス

apiproxy/
├── MyProxy.xml                    # Root proxy definition (name + revision)
├── proxies/                       # ProxyEndpoint definitions
│   └── default.xml
├── targets/                       # TargetEndpoint definitions
│   └── default.xml
├── policies/                      # All policy XML files
│   ├── AM-SetHeaders.xml
│   ├── EV-ExtractPath.xml
│   └── ...
└── resources/                     # Custom code and resources
    ├── jsc/                       # JavaScript files
    ├── java/                      # Java JAR files
    └── xsl/                       # XSLT transformations

ポリシーの命名規則

GoogleCloudPlatform/apigee-samples の [Abbreviation]-[Purpose].xml パターンに従います。

略称	ポリシーの種類	例
AM	AssignMessage	AM-SetHeaders.xml
EV	ExtractVariables	EV-ExtractUserId.xml
SC	ServiceCallout	SC-CallBackend.xml
RF	RaiseFault	RF-InvalidInput.xml
FC	FlowCallout	FC-AuthSharedFlow.xml
SA	SpikeArrest	SA-ProtectBackend.xml
Q	Quota	Q-DailyLimit.xml
RC	ResponseCache	RC-CacheResponse.xml
LC	LookupCache	LC-GetCachedValue.xml
PC	PopulateCache	PC-StoreValue.xml
IC	InvalidateCache	IC-ClearCache.xml
KVM	KeyValueMapOperations	KVM-GetConfig.xml
JS	JavaScript	JS-TransformResponse.xml
JWT	JWT policies	JWT-GenerateToken.xml
OAuth	OAuthV2	OAuth-VerifyToken.xml
VAK	VerifyAPIKey	VAK-CheckKey.xml
ML	MessageLogging	ML-LogToCloud.xml
DC	DataCapture	DC-CaptureMetrics.xml
CORS	CORS	CORS-AllowOrigins.xml
JTP	JSONThreatProtection	JTP-ValidatePayload.xml
XTP	XMLThreatProtection	XTP-ValidateXML.xml
OAS	OASValidation	OAS-ValidateRequest.xml

詳細については、proxy_bundle_anatomy.md を参照してください。

開発ワークフロー

フェーズ 1：プロキシ構造の定義

1. ルート XML、proxies/、targets/、policies/ を含む apiproxy/ ディレクトリを作成します
2. ProxyEndpoint を設定します：BasePath を設定し、HTTPProxyConnection を定義します
3. TargetEndpoint を設定します：バックエンド URL または LoadBalancer を設定します
4. プロキシをターゲットに接続する RouteRules を設定します

参照：proxy_bundle_anatomy.md、endpoints_and_routing.md

フェーズ 2：フローパイプラインの設計

1. 動詞とパスの条件を使って、API オペレーションを条件付きフローに割り当てます
2. セキュリティポリシーを PreFlow に配置します（すべてのリクエストで実行されます）
3. ビジネスロジックを条件付きフローに配置します（オペレーションごとに実行されます）
4. レスポンスヘッダーとキャッシュを PostFlow に配置します
5. MessageLogging を PostClientFlow に配置します（障害発生時も実行されます。プロキシが PostFlow に到達する前にエラーになると、PostFlow はスキップされます）

参照：flows_and_execution.md、flow_variables_and_conditions.md

フェーズ 3：ポリシーの実装

フロー内では、次の順序に従います。最初にセキュリティ、次にメディエーション、最後にトラフィック管理です。

1. セキュリティ：VerifyAPIKey、OAuthV2、VerifyJWT、AccessControl、脅威対策
2. メディエーション：ExtractVariables、AssignMessage、変換
3. トラフィック管理：SpikeArrest、Quota
4. キャッシュ：ResponseCache（通常は PostFlow のレスポンスで使用）
5. ロギング：MessageLogging（通常は PostClientFlow で使用）

参照：policies_security.md、policies_mediation.md、policies_traffic_management.md、policies_caching.md、policies_integration.md

フェーズ 4：障害処理の追加

1. 既知のエラータイプ（認証の失敗、クォータ超過、バックエンドエラー）に対する FaultRules を定義します
2. 一貫したエラー形式を使用する包括的な DefaultFaultRule を追加します
3. カスタムの検証エラーには RaiseFault を使用します
4. 失敗が許容されるポリシーに限り、continueOnError を設定します

参照：fault_handling.md

フェーズ 5：最適化と拡張

1. 再利用可能なポリシーシーケンスを共有フローに抽出します
2. 適切な箇所にレスポンスキャッシュを追加します
3. プロキシチェーン、複合 API、サーキットブレーカーなどの高度なパターンを検討します
4. ポリシーだけでは不十分な場合に限り、複雑な変換に JavaScript コールアウトを追加します

参考資料：shared_flows.md、javascript_development.md、advanced_patterns.md、anti_patterns_and_best_practices.md

フロー実行モデル

CLIENT REQUEST
     │
     ▼
┌─────────────────────────────────────────────────┐
│  PROXY ENDPOINT                                 │
│  ┌──────────┐  ┌────────────────┐  ┌─────────┐ │
│  │ PreFlow  │→ │ Conditional    │→ │PostFlow │ │
│  │ (Request)│  │ Flows (Request)│  │(Request)│ │
│  └──────────┘  └────────────────┘  └─────────┘ │
│                                                 │
│  RouteRule evaluation → select TargetEndpoint   │
└─────────────────────────────────────────────────┘
     │
     ▼
┌─────────────────────────────────────────────────┐
│  TARGET ENDPOINT                                │
│  ┌──────────┐  ┌────────────────┐  ┌─────────┐ │
│  │ PreFlow  │→ │ Conditional    │→ │PostFlow │ │
│  │ (Request)│  │ Flows (Request)│  │(Request)│ │
│  └──────────┘  └────────────────┘  └─────────┘ │
└─────────────────────────────────────────────────┘
     │
     ▼
  BACKEND SERVICE (request sent, response received)
     │
     ▼
┌─────────────────────────────────────────────────┐
│  TARGET ENDPOINT                                │
│  ┌──────────┐  ┌─────────────────┐ ┌─────────┐ │
│  │ PreFlow  │→ │ Conditional     │→│PostFlow │ │
│  │(Response)│  │ Flows (Response)│ │(Response│ │
│  └──────────┘  └─────────────────┘ └─────────┘ │
└─────────────────────────────────────────────────┘
     │
     ▼
┌─────────────────────────────────────────────────┐
│  PROXY ENDPOINT                                 │
│  ┌──────────┐  ┌─────────────────┐ ┌─────────┐ │
│  │ PreFlow  │→ │ Conditional     │→│PostFlow │ │
│  │(Response)│  │ Flows (Response)│ │(Response│ │
│  └──────────┘  └─────────────────┘ └─────────┘ │
└─────────────────────────────────────────────────┘
     │
     ▼
CLIENT RESPONSE SENT
     │
     ▼
┌─────────────────────────────────────────────────┐
│  PostClientFlow (async — after response sent)   │
│  Only: MessageLogging, FlowCallout              │
└─────────────────────────────────────────────────┘

主なルール：

• 条件付きフロー：条件が true と評価された最初のフローのみが実行されます。順序が重要です。
• PostClientFlow：プロキシでエラーが発生した場合でも実行されます。使用できるのは MessageLogging ポリシーと FlowCallout ポリシーのみです。
• FaultRules：ポリシーが障害を発生させたときに実行されます。残りのフローステップをスキップし、エラーフローに入ります。

ポリシーカタログ

トラフィック管理

ポリシー	目的	参考資料
SpikeArrest	バックエンドを保護するため、リクエストレートを制限します	policies_traffic_management.md
Quota	一定期間内の消費量を制限します	policies_traffic_management.md
ResetQuota	サイクルの途中でクォータカウンターを動的に調整します	policies_traffic_management.md

キャッシュ

ポリシー	目的	参考資料
ResponseCache	リクエスト属性に基づいてバックエンドのレスポンスをキャッシュします	policies_caching.md
LookupCache	汎用キャッシュから値を取得します	policies_caching.md
PopulateCache	汎用キャッシュに値を保存します	policies_caching.md
InvalidateCache	キャッシュからエントリーを削除します	policies_caching.md

セキュリティ

ポリシー	目的	参考資料
VerifyAPIKey	ヘッダーまたはクエリパラメーターから API キーを検証します	policies_security.md
BasicAuthentication	Base64 の Basic 認証情報をエンコード／デコードします	policies_security.md
OAuthV2	OAuth 2.0 トークンを生成／検証します	policies_security.md
GenerateJWT	署名付きまたは暗号化された JWT トークンを作成します	policies_security.md
VerifyJWT	JWT の署名とクレームを検証します	policies_security.md
DecodeJWT	署名検証を行わずに JWT をデコードします	policies_security.md
HMAC	ハッシュベースのメッセージ認証コードを計算／検証します	policies_security.md
CORS	クロスオリジンリソース共有を有効にします	policies_security.md
AccessControl	IP ベースの許可／拒否ルールを設定します	policies_security.md
VerifyIAM	Google Cloud IAM ベースの認可を行います	policies_security.md
JSONThreatProtection	悪意のある JSON ペイロードから保護します	policies_security.md
XMLThreatProtection	悪意のある XML ペイロードから保護します	policies_security.md

メディエーション

ポリシー	目的	リファレンス
AssignMessage	リクエストまたはレスポンスのメッセージを変更または作成します	policies_mediation.md
ExtractVariables	メッセージからコンテンツを抽出して変数に格納します	policies_mediation.md
HTTPModifier	HTTP ヘッダーとパラメーターを追加、削除、設定します	policies_mediation.md
XMLtoJSON	XML ペイロードを JSON に変換します	policies_mediation.md
JSONtoXML	JSON ペイロードを XML に変換します	policies_mediation.md
JavaScript	カスタム JavaScript コードを実行します	javascript_development.md

統合と拡張

ポリシー	目的	リファレンス
ServiceCallout	フローの実行中に外部 REST サービスを呼び出します	policies_integration.md
FlowCallout	共有フローを呼び出します	policies_integration.md
ExternalCallout	外部サーバーに gRPC リクエストを送信します	policies_integration.md
KeyValueMapOperations	キーと値のマップエントリーを読み書きします	policies_integration.md
ReadPropertySet	プロパティセットの値を変数に読み込みます	policies_integration.md
AccessEntity	実行時にエンティティプロファイルを検索します	policies_integration.md
RaiseFault	カスタムフォルトレスポンスを生成します	fault_handling.md
AssertCondition	条件文を評価します	policies_integration.md
MessageLogging	Cloud Logging または syslog にログを記録します	policies_integration.md
PublishMessage	Pub/Sub トピックに公開します	policies_integration.md
DataCapture	カスタム分析データを Data Collectors に取り込みます	policies_integration.md

検証

ポリシー	目的	リファレンス
OASValidation	OpenAPI 3.0 仕様に照らして検証します	policies_security.md
GraphQL	GraphQL ペイロードを解析して検証します	policies_security.md

AI/LLM

ポリシー	目的	リファレンス
LLMTokenQuota	トークン消費量の上限を適用します	advanced_patterns.md
PromptTokenLimit	リクエストごとのトークン消費量を制限します	advanced_patterns.md
SanitizeUserPrompt	プロンプトから有害なコンテンツをフィルタリングします	advanced_patterns.md
SanitizeModelResponse	LLM の応答から有害なコンテンツをフィルタリングします	advanced_patterns.md
SemanticCacheLookup	意味的類似性に基づいてキャッシュを検索します	advanced_patterns.md
SemanticCachePopulate	意味的類似性に基づいて応答をキャッシュします	advanced_patterns.md

リファレンスドキュメント

ドキュメント	説明
proxy_bundle_anatomy.md	バンドルのディレクトリ構造、ファイルの種類、命名規則
endpoints_and_routing.md	ProxyEndpoint、TargetEndpoint、RouteRules、プロキシチェーン
flows_and_execution.md	フローパイプライン、PreFlow／PostFlow／条件付きフロー、実行順序
flow_variables_and_conditions.md	変数システム、条件構文、メッセージテンプレート
policies_traffic_management.md	SpikeArrest、Quota、ResetQuota
policies_caching.md	ResponseCache、キャッシュ・アサイドパターン、PopulateCache、LookupCache、InvalidateCache
policies_security.md	API キー、OAuth 2.0、JWT、CORS、脅威対策、IAM
policies_mediation.md	AssignMessage、ExtractVariables、JSON／XML 変換
policies_integration.md	ServiceCallout、FlowCallout、KVM の詳細、PropertySets、ロギング、RaiseFault
load_balancing_and_routing.md	ターゲットサーバー、負荷分散アルゴリズム、ヘルスモニター、高度なルーティング
fault_handling.md	FaultRules、DefaultFaultRule、エラーフロー、エラーレスポンス
javascript_development.md	JavaScript オブジェクトモデル、パターン、ベストプラクティス
shared_flows.md	共有フローの作成と利用、フックフロー
advanced_patterns.md	プロキシチェーン、複合 API、サーキットブレーカー、AI／LLM
anti_patterns_and_best_practices.md	よくある間違い、本番環境でのベストプラクティス
debugging_and_performance.md	デバッグセッション、トレース手法、パフォーマンスの最適化
multi_tenant_patterns.md	マルチテナントルーティング、分離、テナントごとの設定とレート制限
websockets_and_streaming.md	WebSocket プロキシ、SSE、HTTP ストリーミング、タイムアウト時の注意点
end_to_end_examples.md	4 つの完全なプロキシバンドルの解説

クイックスタート：最小構成のプロキシバンドル

apiproxy/MinimalProxy.xml

<?xml version="1.0" encoding="UTF-8"?>
<APIProxy name="MinimalProxy" revision="1">
  <DisplayName>Minimal Proxy</DisplayName>
  <Description>Simple passthrough proxy</Description>
</APIProxy>

apiproxy/proxies/default.xml

<?xml version="1.0" encoding="UTF-8"?>
<ProxyEndpoint name="default">
  <HTTPProxyConnection>
    <BasePath>/v1/minimal</BasePath>
  </HTTPProxyConnection>

  <PreFlow name="PreFlow">
    <Request/>
    <Response/>
  </PreFlow>

  <Flows/>

  <PostFlow name="PostFlow">
    <Request/>
    <Response/>
  </PostFlow>

  <RouteRule name="default">
    <TargetEndpoint>default</TargetEndpoint>
  </RouteRule>
</ProxyEndpoint>

apiproxy/targets/default.xml

<?xml version="1.0" encoding="UTF-8"?>
<TargetEndpoint name="default">
  <HTTPTargetConnection>
    <URL>https://mocktarget.apigee.net</URL>
  </HTTPTargetConnection>

  <PreFlow name="PreFlow">
    <Request/>
    <Response/>
  </PreFlow>

  <Flows/>

  <PostFlow name="PostFlow">
    <Request/>
    <Response/>
  </PostFlow>
</TargetEndpoint>

よく使う開発レシピ

API キー保護を追加する

PreFlow に VerifyAPIKey を追加します。すべてのリクエストに有効なキーが必要になります：

<PreFlow name="PreFlow">
  <Request>
    <Step>
      <Name>VAK-VerifyKey</Name>
    </Step>
  </Request>
</PreFlow>

VerifyAPIKey ポリシーの XML については、policies_security.md を参照してください。

OAuth 2.0 を追加する

トークンエンドポイントのフローを作成し、リソースフローでトークンを検証します：

<Flow name="token">
  <Condition>(proxy.pathsuffix MatchesPath "/token") and (request.verb = "POST")</Condition>
  <Request>
    <Step><Name>OAuth-GenerateToken</Name></Step>
  </Request>
</Flow>
<Flow name="protected-resource">
  <Condition>proxy.pathsuffix MatchesPath "/resource"</Condition>
  <Request>
    <Step><Name>OAuth-VerifyToken</Name></Step>
  </Request>
</Flow>

OAuthV2 ポリシーの設定については、policies_security.md を参照してください。

レート制限を追加する

SpikeArrest（保護）と Quota（SLA の適用）を組み合わせます：

<PreFlow name="PreFlow">
  <Request>
    <Step><Name>SA-ProtectBackend</Name></Step>
    <Step><Name>Q-DailyLimit</Name></Step>
  </Request>
</PreFlow>

policies_traffic_management.md を参照してください。

レスポンスキャッシュを追加する

フローに ResponseCache を配置します。検索と格納の両方を処理します：

<PostFlow name="PostFlow">
  <Response>
    <Step><Name>RC-CacheResponse</Name></Step>
  </Response>
</PostFlow>

policies_caching.md を参照してください。

CORS を追加する

PreFlow に CORS ポリシーを割り当て、プリフライトとレスポンスヘッダーを処理します：

<PreFlow name="PreFlow">
  <Request>
    <Step><Name>CORS-AllowOrigins</Name></Step>
  </Request>
</PreFlow>

CORS ポリシーの XML については、policies_security.md を参照してください。

外部サービスを呼び出す

ServiceCallout を使用すると、リクエスト処理中に外部 API を呼び出せます：

<Flow name="enrich-request">
  <Request>
    <Step><Name>SC-GetUserProfile</Name></Step>
    <Step><Name>EV-ExtractProfile</Name></Step>
  </Request>
</Flow>

policies_integration.md を参照してください。

一貫性のあるエラーレスポンスを構築する

ProxyEndpoint に FaultRules と DefaultFaultRule を追加します：

<FaultRules>
  <FaultRule name="auth-error">
    <Condition>fault.name = "FailedToResolveAPIKey"</Condition>
    <Step><Name>AM-AuthError</Name></Step>
  </FaultRule>
</FaultRules>
<DefaultFaultRule>
  <AlwaysEnforce>true</AlwaysEnforce>
  <Step><Name>AM-GenericError</Name></Step>
</DefaultFaultRule>

fault_handling.md を参照してください。

共有フローの作成と使用

再利用可能なロジックを共有フローに抽出し、FlowCallout で呼び出します。

<PreFlow name="PreFlow">
  <Request>
    <Step><Name>FC-AuthSharedFlow</Name></Step>
  </Request>
</PreFlow>

shared_flows.md を参照してください。

ベストプラクティスのまとめ

• ポリシーの順序：セキュリティ（PreFlow）→ メディエーション → トラフィック管理 → キャッシュ（PostFlow）→ ロギング（PostClientFlow）
• 命名規則：ポリシーファイルには常に [Abbreviation]-[Purpose].xml を使用します
• コードよりポリシー：まず組み込みポリシーを使用し、ポリシーで表現できないロジックに限り JavaScript を使用します
• 障害処理：すべてのプロキシに、一貫したエラーレスポンス形式を返す DefaultFaultRule を設定します
• 共有フロー：2 つ以上のプロキシで使用するポリシーの順序を共有フローに抽出します
• ベースパス：バージョン付きのパス（/v1/resource）を使用し、環境ごとに一意であることを確認します
• 条件：最も具体的な条件付きフローを先に配置します（最初に一致したものが適用されます）
• PostClientFlow：エラーの有無にかかわらず確実に実行されるよう、MessageLogging には常に使用します
• キャッシュ：エラーレスポンスがキャッシュされないよう、ResponseCache の ExcludeErrorResponse を true に設定します
• 大きなペイロード：大きなペイロードを解析するポリシーを最小限にし、パススルーのシナリオではストリーミングを有効にします
• アンチパターン：全項目については anti_patterns_and_best_practices.md を参照してください