ポリシーとは

Apigee X のドキュメントが表示されています。
Apigee Edge のドキュメントを参照する。

Apigee では、ポリシーを使用することにより、コードを記述することなく API の動作を制御できます。ポリシーは、特定の限定された管理機能を実装するモジュールのようなものです。ポリシーにより、一般的な管理機能を API に簡単に追加できます。ポリシーには、セキュリティ、レート制限、変換、メディエーションの機能などの機能が備わり、自身でコーディングやメンテナンスを行う必要がなくなります。

Apigee が提供している一連のポリシータイプだけに限りません。また、API プロキシの機能を拡張し、Apigee ポリシーでサポートされている基本的な管理機能を基にイノベーションを実現する特別仕様のスクリプトとコード(JavaScript アプリケーションなど)を作成することもできます。

ポリシーの接続と適用の概要については、こちらの動画をご覧ください。

ポリシータイプ

技術的には、ポリシーは XML 形式の構成ファイルです。各ポリシータイプの構造(必要な構成要素や任意の構成要素など)は、XML スキーマによって定義されます。XML ツールを使い慣れている場合は、GitHub の API Platform サンプルのポリシー スキーマに精通しておくことをおすすめします。

Apigee ポリシータイプは、以下の機能カテゴリに分類されます。

トラフィック管理

トラフィック管理カテゴリのポリシーでは、API プロキシを通じて、リクエスト メッセージとレスポンス メッセージのフローを制御できます。このようなポリシーは、運用レベルと業務レベルの両方の制御をサポートします。これを使用すると、そのままのスループットを制御して、アプリ単位でトラフィックを制御することも可能です。トラフィック管理ポリシータイプは割り当てを適用するために使用できます。また、サービス拒否攻撃の防御にも役立ちます。

セキュリティ

セキュリティ カテゴリのポリシーは、認証、認可、コンテンツ ベースのセキュリティをサポートします。

仲介

仲介カテゴリのポリシーでは、API プロキシ内のフローを通過するメッセージをアクティブに操作できます。このポリシーにより、メッセージ形式を XML から JSON(またはその逆)に変換でき、特定の XML 形式を別の XML 形式に変換することもできます。また、メッセージの解析、新しいメッセージの生成、送信メッセージの値の変更もできます。さらに、メディエーション ポリシーは、API Service によって公開される基本的なサービスともやり取りするため、アプリ、デベロッパー、セキュリティ トークン、API 製品に関するデータを実行時に取得できます。

拡張機能

拡張機能カテゴリのポリシーでは、API Service の拡張性を利用して、選択したプログラミング言語でカスタムの動作を実装できます。

各ポリシータイプの詳細については、ポリシー リファレンスの概要をご覧ください。このトピックでは、一般的な使い方について説明し、ポリシーの作成方法と、API プロキシ構成内のフローにポリシーを接続する方法を示します。

ポリシーの変更をデプロイする

ポリシーの変更を有効にするには、API プロキシ リビジョンを環境にデプロイする必要があります。ポリシーを接続するか、既存のポリシーを変更した後、Apigee UI または Apigee API を使用して変更をデプロイします。

ポリシー適用の検証

ポリシーが適切に適用されているかを確認するには、HTTP クライアントで API を呼び出す必要があります。この Quota 構成を確認するには、API に割り当てポリシーで設定した割り当て制限を超える複数のリクエストを送信します(以下のリクエストで ProxyEndpoint のベースパス設定に従って構成された URI パスは /weather です)。

http://{org_name}-test.apigee.net/weather/forecastrss?w=12797282

1 分以内に複数のリクエストを送信すると、次のエラー メッセージが表示されます。

{
   "fault":{
      "faultstring":"policies.ratelimit.QuotaViolation",
      "detail":{
         "errorcode":"policies.ratelimit.QuotaViolation"
      }
   }
}

これは、Quota ポリシーが Apigee によって適用されていることを示します。

ポリシーベースの障害処理

上記のエラー メッセージの形式に注目してください。faultstring プロパティと errorcode プロパティが含まれています。多くの場合、こうしたエラーに対処するためになんらかの動作を実装する必要があります。たとえば、Quota を超えるデベロッパーに対してカスタム メッセージを発行することもできます。

障害処理の詳細については、障害の処理をご覧ください。

おすすめの方法: 一般的なポリシーセット

基本的な管理要件を満たすために、API プロキシは通常、以下のポリシーを適用します。

基本的な API キー検証

ProxyEndpoint リクエスト フロー:
  1. SpikeArrest
  2. XMLThreatProtection または JSONThreatProtection
  3. API キーの検証
  4. Quota
  5. ResponseCache
ProxyEndpoint レスポンス フロー:
  1. ResponseCache

基本的な変換: JSON から XML

リクエスト フロー:
  1. SpikeArrest
  2. JSONThreatProtection
  3. API キーの検証
  4. Quota
  5. JSONtoXML
レスポンス フロー:
  1. XMLToJSON
  2. ResponseCache