Send Docs Feedback

Note: Most user interface tasks can be performed in Edge Classic or the New Edge experience. For an overview, getting started topics, and release notes specific to the New Edge experience, see the docs.

API プロキシの設計と開発のベストプラクティス

このドキュメントの目的は、Apigee Edge を使用した開発のための規範やベストプラクティスをひととおり紹介することです。取り上げられている話題は、設計、コーディング、ポリシー使用、監視、デバッグです。記載されている情報は、成功を収めた API プログラムを Apigee と協力して実装してきたデベロッパによる経験の集積です。これは生きたドキュメントであり、今後も随時更新されます。

開発の規範

コメントとドキュメント

  • ProxyEndpoint 構成や TargetEndpoint 構成にはインラインコメントを残します。とりわけ、Flow の根底にある機能をポリシーファイル名があまりよく表していない場合、コメントがあるとその Flow のわかりやすさが向上します。
  • 有意義なコメントを残します。自明なコメントは避けてください。
  • インデント、スペースの挿入、縦方向の配置などに一貫性をもたせます。

フレームワークスタイルのコーディング

フレームワークスタイルのコーディングでは、API プロキシリソースをバージョン管理システムに保存して、ローカル開発環境で再利用します。例えば、ポリシーを再利用するには、ポリシーをソース管理に保存し、デベロッパがそれを同期して各自のプロキシ開発環境で使用できるようにします。

  • DRY (don't repeat yourself) を実践するには、できる限り、再利用可能な専用の関数をポリシーの構成やスクリプトに実装します。例えば、リクエストメッセージからクエリーパラメータを抽出する専用のポリシーを ExtractVariables.ExtractRequestParameters とし、CORS ヘッダーを挿入する専用のポリシーを AssignMessage.SetCORSHeaders として作成します。これらのポリシーをソース管理システムに格納すれば、パラメータの抽出や CORS ヘッダーの設定が必要な各 API プロキシに追加でき、冗長な (ひいては管理性を低下させる) 構成を作成する必要がなくなります。
  • 使用しないポリシーやリソース (JavaScript、Java、XSLT など)、特に読み込みや展開の処理速度を低下させかねない大きなリソースを、API プロキシからクリーンアップします。

命名規則

  • ポリシーの name 属性と XML ポリシーファイル名を同じにします。
  • Script ポリシーや ServiceCallout ポリシーの name 属性をリソースファイルの名前と同じにします。
  • DisplayName は、該当する API プロキシの使用経験がまったくない担当者にポリシーの機能が正確に伝わるように指定してください。
  • ポリシーにはその機能にふさわしい名前を付けます。例えば、AssignTargetAuthHeaderAssignMessage.TargetAuthHeaderRaiseFault.InvalidUser などとします。
  • リソースファイルには適切な拡張子を指定してください。.js は JavaScript に、.py は python に、.jar は Java JAR ファイルに、それぞれ使用します。
  • 変数名は決まったスタイルに統一します。特定のスタイル、例えばキャメルケース (camelCase など) やスネークケース (under_score など) を選択したら、API プロキシ全体でそれを採用します。
  • 可能であれば、変数プレフィックスを使用して、目的に基づき変数を整理します。例えば、Consumer.usernameConsumer.password のようにします。

API プロキシの展開

初期設計での考慮事項

Do not call the Edge management API from inside API proxies. The management API is used for administrative management purposes, not API flow logic. Due to longer-lived cache entries on the management API servers, you may not see updated data immediately in your proxy flows, particularly if you are doing quick writes and then reads. Coding workarounds for this behavior can impact your proxies' performance.

Use policies or Node.js in API proxies instead.

  • Apigee Edge のポリシーや機能をできるだけ活かして API プロキシを構築します。プロキシロジックをすべて JavaScript、Java、または Python のリソースでコーディングすることは避けてください。
  • Flow は整理して構築します。同じ PreFlow や Postflow に条件を複数添付するよりは、条件が 1 つだけの Flow を複数使用してください。
  • 「フェイルセーフ」として、ProxyEndpoint の BasePath を / に指定したデフォルトの API プロキシを作成します。これは、ベース API リクエストをデベロッパサイトにリダイレクトするため、カスタムレスポンスを返すため、またはデフォルトの CLASSIFICATION_ERROR を返すことより意味のある別のアクションを実行するために使用できます。
  • TargetServer リソースを使用して、TargetEndpoint 構成を具体的な URL から切り離すことで、環境を超えた昇格に対応できるようにします。
    Load balance API traffic across multiple backend servers」を参照してください。
  • RouteRule が複数ある場合は、1 つを「デフォルト」として、つまり条件のない RouteRule として作成します。デフォルトの RouteRule が条件付き Route リストの最後に定義されていることを確認してください。RouteRule は ProxyEndpoint で上から順に評価されます。
    参照: API proxy configuration reference
  • API プロキシのバンドルサイズ: API プロキシバンドルが 15 MB を超えないようにしてください。Apigee Edge for Private Cloud では、thrift_framed_transport_size_in_mb プロパティの変更によってサイズ制限を変更できます。このプロパティは以下の場所にあります: cassandra.yaml (Cassandra の場合) および conf/apigee/management-server/repository.properties。
  • API versioning: For Apigee's thoughts and recommendations on API versioning, see Versioning in the Web API Design: The Missing Link e-book.

メッセージペイロードサイズ

To prevent memory issues in Edge, message payload size is restricted to 10MB. Exceeding those sizes results in a protocol.http.TooBigBody error.

この問題については、こちらの Apigee コミュニティー投稿でも議論されています。

Edge で大きなメッセージサイズを扱う場合に推奨されるやり方を以下に示します。

  • リクエストとレスポンスをストリーム配信します。ストリーム配信すると、ポリシーがメッセージの内容にアクセスできなくなります。「Streaming requests and responses」を参照してください。 
  • In Edge for Private Cloud version 4.15.07 and earlier, edit the message processor http.properties file to increase the limit in the HTTPResponse.body.buffer.limit parameter. Be sure to test before deploying the change to production.
  • In Edge for Private Cloud version 4.16.01 and later, requests with a payload must include the Content-Length header, or in case of streaming the "Transfer-Encoding: chunked" header. For a POST to an API proxy with an empty payload, you must pass a Content-Length of 0.
  • In Edge for Private Cloud version 4.16.01 and later, set the following properties in /opt/apigee/router.properties or message-processor.properties to change the limits. See Set the message size limit on the Router or Message Processor for more.

    Both properties have a default value of "10m" corresponding to 10MB:
    • conf_http_HTTPRequest.body.buffer.limit
    • conf_http_HTTPResponse.body.buffer.limit

障害処理

  • すべての障害処理に FaultRules を使用します (RaiseFault ポリシーを使用して、メッセージ Flow を止めて処理を FaultRules Flow に渡します)。
  • FaultRules Flow 内では、障害レスポンスの構築に RaiseFault ポリシーではなく AssignMessage ポリシーを使用します。発生した障害の種類に応じて、AssignMessage ポリシーを条件実行してください。
  • デフォルトの「キャッチオール」障害ハンドラを必ず含めて、システムが生成する障害を顧客定義の障害レスポンス形式にマッピングできるようにしてください。
  • 可能であれば、企業やプロジェクトで使用できる標準形式に沿って障害レスポンスを作成します。
  • エラー状況への解決策を指示するような、意味のある判読可能なエラーメッセージを使用します。

See Handling faults.

業界のベストプラクティスについては、RESTful エラーレスポンス設計に関するこちらの投稿を参照してください。

永続性

キー/値マップ

  • キー/値マップはデータセットに限定して使用します。長期的なデータ保存用ではありません。
  • キー/値マップは Cassandra データベースに格納される情報なので、使用に際してはパフォーマンスを考慮してください。

Key Value Map Operations policy」を参照してください。

レスポンスのキャッシュ処理

  • レスポンスに成功しなかった場合、またはリクエストが GET ではなかった場合は、レスポンスキャッシュへの挿入はしないでください。作成、更新、削除はキャッシュしません。<SkipCachePopulation>response.status.code != 200 or request.verb != “GET”</SkipCachePopulation>
  • キャッシュには決まった 1 種類のコンテンツ (XML や JSON など) を挿入します。 responseCache エントリを取得したら、JSONtoXML や XMLToJSON で必要な種類のコンテンツに変換します。これにより、データの二重、三重などの格納を避けられます。
  • キャッシュキーがキャッシュ要件を満たしていることを確認します。多くの場合、request.querystring を一意識別子として使用できます。
  • 明らかな必要性がない限り、API キー (client_id) をキャッシュキーに含めないでください。一般に、キーだけでセキュリティ保護されている API は、与えられたリクエストに対し、すべてのクライアントに同じデータを返します。API キーに基づいて多数のエントリに同じ値を格納するのは非効率的です。
  • 適切なキャッシュ有効期間を設けて、ダーティリードを防ぎます。
  • できる限り、キャッシュへの挿入に関するレスポンスキャッシュポリシーが、ProxyEndpoint レスポンス PostFlow のできるだけ遅い段階で実行されるようにしてください。言い換えると、JavaScript ベースのメディテーションや、JSON と XML の間の変換など、変換手順やメディテーション手順の後に実行します。 メディテーション後のデータをキャッシュすることで、キャッシュデータを取得するたびにメディテーション手順を実行するというパフォーマンスコストを回避できます。

    メディテーションの結果がリクエストに応じて異なる場合は、メディテーションされていないデータをキャッシュすることも考えられます。

  • キャッシュエントリをルックアップするレスポンスキャッシュポリシーを、ProxyEndpoint リクエスト PreFlow で機能するようにしてください。 また、キャッシュキー生成を除き、キャッシュエントリを返す前にロジックを実装しすぎないようにします。そうしないと、キャッシュするメリットが大幅に減ります。
  • 一般に、レスポンスキャッシュルックアップは必ずクライアントリクエストのできるだけ近づけます。逆に、レスポンスキャッシュの挿入は、クライアントレスポンスにできるだけ近づけます。
  • When using multiple, different response cache policies in a proxy, follow these guidelines to ensure discrete behavior for each:
    • Execute each policy based on mutually exclusive conditions. This will help ensure that only one of multiple response cache policies executes.
    • Define different cache resources for each response cache policy. You specify the cache resource in the policy's <CacheResource> element.

Response Cache policy」を参照してください。

ポリシーとカスタムコード

ポリシーか、カスタムコードか?

  • (できる限り) 組み込みポリシーを優先して使用します。Apigee ポリシーは堅実で、最適化されており、サポート対象です。例えば、ペイロードの作成やペイロードからの情報の抽出 (XPath、JSONPath) などには、(できる限り) JavaScript ではなく 標準の AssignMessage ポリシーや ExtractVariables ポリシーを使用してください。
  • JavaScript は Python や Java より好まれています。 ですが、パフォーマンスが最優先であれば、JavaScript ではなく Java を使用してください。

JavaScript

  • JavaScript は、Apigee ポリシーより直感的な場合に使用します (例えば、target.url を多数の異なる URI の組み合わせで設定する場合)。
  • JSON オブジェクトを介したイテレーションや Base64 エンコード/デコードなど、複雑なペイロード解析に使用します。
  • JavaScript ポリシーには時間制限があり、無限ループはブロックされます。
  • Always use JavaScript Steps and put files in jsc resources folder. JavaScript Policy type pre-compiles the code at deployment time.

Programming API proxies with JavaScript」を参照してください。

Java

For Java Callouts, reliance on Java libraries that are included with Apigee Edge is not supported. Those libraries are for Edge product functionality only, and there's no guarantee that a library will be available from release to release.

  • パフォーマンスが最優先の場合、またはロジックを JavaScript では実装できない場合は、Java を使用します。
  • Java ソースファイルをソースコード追跡の対象に含めます。

See Convert the response to uppercase with a Java callout and Java Callout policy for information on using Java in API proxies.

Python

  • どうしても必要な場合を除いて、Python は使用しないでください。Python スクリプトは実行時に解釈されるので、システム実行にパフォーマンスボトルネックが生じかねません。

スクリプトコールアウト (Java、JavaScript、Python)

  • グローバルの try/catch またはそれに相当する機能を使用します。
  • 意味のある例外をスローし、適切にキャッチして、障害レスポンスに使用します。
  • 例外は早めにスローおよびキャッチします。グローバルの try/catch をあらゆる例外の処理に使用することはしないでください。
  • 必要に応じて、null や未定義値をチェックしてください。例えば、省略可能なフロー変数の取得時にチェックします。
  • スクリプトコールアウト内で HTTP/S リクエストを作成しないようにします。代わりに、接続を円滑に処理する Apigee ServiceCallout ポリシーを使用してください。

JavaScript

  • API Platform の JavaScript は XML を E4X として対応しています。

JavaScript object model」を参照してください。

Java

For Java Callouts, reliance on Java libraries that are included with Apigee Edge is not supported. Those libraries are for Edge product functionality only, and there's no guarantee that a library will be available from release to release.

  • メッセージペイロードにアクセスする場合は、context.getMessage() または context.getResponseMessagecontext.getRequestMessage を使用します。これにより、リクエストフローでもレスポンスフローでもペイロードを取得できます。
  • ライブラリは Apigee Edge の組織 (organization) または環境 (environment) に読み込み、JAR ファイルにはインクルードしないでください。これによりバンドルサイズが小さくなり、他の JAR ファイルが同じライブラリリポジトリにアクセスできるようになります。
  • JAR ファイルは、Apigee リソース API を使用して読み込み、API プロキシリソースフォルダには含めません。これにより、展開にかかる時間が短縮され、同じ JAR ファイルを複数の API プロキシが参照できるようになります。他にも、クラスローダーを分離できるという利点があります。
  • Java をリソース処理 (スレッドプールの作成と管理など) には使用しないでください。

See Convert the response to uppercase with a Java callout.

Python

  • 意味のある例外をスローし、適切にキャッチして、Apigee 障害レスポンスで使用してください。

Python Script policy」を参照してください。

ServiceCallout

  • プロキシチェーンの使用については、参考になる使用事例が多数あります。プロキシチェーンでは、ある API プロキシのサービスコールアウトを使用して別の API プロキシを呼び出します。プロキシチェーンを使用する場合は、同じ API プロキシに戻ってくる「無限ループ」の再帰コールアウトを確実に避けてください。

    If you're connecting between proxies that are in the same organization and environment, be sure to see Chaining API proxies together for more on implementing a local connection that avoids unnecessary network overhead.

  • ServiceCallout リクエストメッセージを AssignMessage ポリシーを使用して構築し、リクエストオブジェクトをメッセージ変数に指定します (リクエストペイロード、パス、メソッドの設定など)。
  • ポリシー内で構成される URL には、プロトコル指定が必要です。つまり、URL のプロトコル部分、例えば https:// は、変数では指定できません。また、URL のドメイン部分や URL の残り部分にも、それぞれ変数を使用する必要があります。例: https://{domain}/{path}
  • ServiceCallout のレスポンスオブジェクトは別個のメッセージ変数に格納します。そのうえでメッセージ変数を解析し、元のメッセージペイロードは他のポリシーでの使用に備えて変更なしで残します。

Service Callout policy」を参照してください。

エンティティへのアクセス

AccessEntity ポリシー

  • パフォーマンスを向上させるには、アプリのルックアップにアプリ名ではなく uuid を使用します。

Access Entity policy」を参照してください。

ログへの記録

  • バンドル間や同一バンドル内では、一般的な syslog ポリシーを使用します。これにより、ログ記録形式に一貫性がもたらされます。

Monitor flow violations using RaiseAlert」を参照してください。

監視

クラウドのお客様は、Apigee Edge の個々のコンポーネント (Router、Message Processor など) をチェックする必要はありません。Apigee の Global Operations チームが、あらゆるコンポーネントを徹底的に監視しています。お客様から正常性チェックのご要望があれば、API の正常性チェックも実施します。

Apigee 分析

分析では、エラー率が測定されることから、非クリティカルな API 監視を提供できます。

Use the built-in charts」を参照してください。

トレース

API Edge 管理 UI のトレースツールは、API の開発中や本運用で実行時に発生する API の問題をデバッグするのに便利です。

Trace ツールの使用」を参照してください。

セキュリティ

Help or comments?