API 管理のポリシーに関する解説 [パート 1]: ペイロードを変換または再フォーマットする方法

※この投稿は米国時間 2023 年 2 月 8 日に、Google Cloud blog に投稿されたものの抄訳です。

今日のアプリケーションおよびインテグレーションの世界では、API が多用されています。ここ数年での API の急増に伴い、現在では開発者の 9 割以上が API を使用しています。大部分の開発者が API を利用しているにもかかわらず、ほとんどの場合、日々の仕事の中で API について重点的に考えることはないかもしれません。Statista による最近のレポートでは、API 開発者は自分の時間の 29.5% を API のプログラミングに、17% を API の手動でのデバッグに費やしていることがわかっています。皆様が Apigee での API 構築にかかる時間を短縮できるよう、API 開発の重要な側面のひとつであるポリシーについて、一連のブログで詳しく解説していきます。

今回のブログではまず、ポリシーの基本的な概念について説明した後、API を通過するメッセージを変換するポリシーをいくつか解説します。シリーズのパート 2 では、他のポリシーによってトラフィックを保護および管理し、カスタマイズされた動作を API に実装する方法を説明します。

API 管理におけるポリシーとは

ポリシーとは、受信リクエストを処理する際に API ゲートウェイが適用するルールです。API の採用と API 管理プラットフォームの人気度の向上の鍵となるのは、そうしたポリシーの適用がどの程度一貫しているか、また自動化をどの程度利用できるかです。

たとえば空港でのセキュリティ チェックを考えてみましょう。保安検査員は旅行者の ID の詳細と渡航情報を確認して、セキュリティ ゲートを通る許可を出します。この行動は、API 管理の世界でいうポリシーに類似しています。すなわち、すべての受信リクエストが許可されるべきものである場合、ある特定の行動に従うことが、ポリシーによって要求されます。そうしたポリシーを具体的には「認証ポリシー」や「認可ポリシー」といいます。

Apigee のポリシーが役立つその他のケース

Apigee において、ポリシーは、コードを書いたり管理したりしなくても、一般的なタイプの管理機能を API に追加できるようにすることを目的として作られています。Apigee のポリシーは、機能面から大きく 4 つのカテゴリに分類できます。

• トラフィック管理ポリシー（例: レート制限）: API 内でのリクエストおよびレスポンスのメッセージの流れを制御できます。

• セキュリティ ポリシー（例: OAuth）: すべてのリクエストに対し認証および認可を行い、コンテンツを保護します。

• メディエーション ポリシー（例: CORS）: リクエストとレスポンスのペイロードを積極的に操作できます。

• 拡張機能のポリシー（例: MessageLogging）: カスタムの動作を複数のプログラミング言語で実装できます。

Apigee では、50 以上のポリシーをすぐに利用できます。このブログ投稿では、いくつかのメディエーション ポリシーの機能、ポリシーを使うタイミング、アプリケーションのニーズに基づくポリシーの実装方法について解説します。

使用できるのは、Apigee が提供している一連のポリシータイプだけに限りません。API プロキシの機能を拡張し、Apigee のポリシーが対応する基本的な管理機能を基にイノベーションを実現するカスタム スクリプトとコード（JavaScript など）を作成することもできます。

メディエーション ポリシー: その役割と使用する場面

Apigee でのメディエーション ポリシーは、非常に強力なポリシーです。API 開発者がリクエストやレスポンスの形と値を自身の API にぴったり合わせて調整するためにメディエーション ポリシーを活用できるシチュエーションは多数あります。メディエーション ポリシーを使うと便利な場面をいくつか見てみましょう。

#1 リクエストやレスポンスのメッセージからデータを抽出して変数の形で保存する

天気アプリケーションで、ユーザーの郵便番号に基づいて情報をカスタマイズし、ユーザーの画面に表示したいとします。その場合、郵便番号は API の XML ペイロードを通じて渡されます。このようなユースケースでは、Apigee の ExtractVariables ポリシーがリクエストやレスポンスからコンテンツを抽出して、変数の値をそのコンテンツに設定します。メッセージからは、ヘッダー、URI パス、JSON / XML ペイロード、フォーム パラメータ、クエリ パラメータの任意の部分（AccessEntity ポリシーによって作成されたエンティティや XML オブジェクト、JSON オブジェクトも含む）を抽出できます。このポリシーは、メッセージ コンテンツにテキスト パターンを適用し、一致を検出すると、指定したメッセージ コンテンツに変数を設定します。

同じ商用アプリケーション サンプルでの実装例を見てみましょう。次の例では、「Extract-Temperature」というラベルの ExtractVariables ポリシーが、API レスポンスの XML ペイロードから「Temperature」フィールドの値を抽出し、「getcityweather.zipcode」という新しいコンテキスト変数の形でその値を保存します。

ExtractVariables ポリシーの構成: XML から次のように構成します。

#2 リクエストやレスポンスのメッセージを変更する

API 開発者は、次のような作業が要求されるユースケースに対応することがよくあります。

• メッセージの送受信前に、カスタムのヘッダーを追加したり、メッセージのペイロードを変更したりする（または）

• メッセージ ペイロードからデータを抽出する、異なる形式の間でデータを変換するなど、メッセージ コンテンツに対して高度な変換作業を行う（または）

• メッセージ内の変数を使用して、フロー内の異なるポリシーやステップ間でデータを渡す

• さまざまなサービスを呼び出し、そのレスポンスをマッシュアップする

たとえば、Verify API Key ポリシーでは多数の変数が設定されますが、その変数の名前が長すぎてアクセスしにくい場合があります。そのような場合には、AssignMessage ポリシーが非常に便利です。AssignMessage ポリシーは、API プロキシのフロー中に、既存のリクエストやレスポンスのメッセージを変更したり、新しいリクエストやレスポンスのメッセージを作成したりできます。このポリシーを使用すると、そのようなメッセージに対して以下の操作を実行できます。

• 新しいフォーム パラメータ、ヘッダー、クエリ パラメータをメッセージに追加する

• 既存のプロパティをメッセージ間でコピーする

• ヘッダー、クエリ パラメータ、フォーム パラメータ、メッセージ ペイロードをメッセージから削除する

• メッセージに既存のプロパティの値を設定する

AssignMessage では、リクエストとレスポンスいずれかのプロパティの追加、変更、削除ができます。逆に、AssignMessage を使用してカスタム リクエストやレスポンス メッセージを作成し、それを別のターゲットに渡すこともできます。詳しくはカスタム リクエスト メッセージの作成をご覧ください。

AssignMessage ポリシー内の変数にアクセスする方法の例を次に示します。この例では、AssignMessage ポリシー内の Verify API Key で設定されたフロー変数にアクセスし、その値を別の変数に割り当てています。

Apigee で利用可能なその他のメディエーション ポリシー

Apigee は、リクエストやレスポンスのメッセージを API へ渡す際にそのコンテンツの変更や操作に使用できるメディエーション ポリシーを幅広く提供しています。ここでは、これまでに説明した例と、Apigee で利用可能なその他のメディエーション ポリシーをいくつか紹介します。

1. ExtractVariables ポリシーでは、リクエストやレスポンスのメッセージからデータを抽出し、それを変数に格納できます。その後、その変数を API フロー内の別のポリシーやステップで使用したり、クライアント アプリケーションに渡したりすることができます。

2. AssignMessage ポリシーでは、メッセージ コンテンツを追加、変更、削除して、メッセージ変数を設定または取得できます。このポリシーを使用して、リクエストやレスポンスのメッセージのコンテンツと動作をカスタマイズできます。

3. JSONToXML ポリシーでは、JSON 形式のメッセージを XML に変換できます。JSON のメッセージを XML ベースの API で処理したり、メッセージを XML に変換したりする必要がある場合に、このポリシーを使用できます。

4. XMLToJSON ポリシーでは、XML 形式のメッセージを JSON に変換できます。XML のメッセージを JSON ベースの API で処理したり、メッセージを JSON に変換したりする必要がある場合に、このポリシーを使用できます。

前述のとおり、ここに挙げたのはごく一部の例にすぎず、使用可能なメディエーション ポリシーはこれ以外にも多数あります。API プロキシの機能を特殊なユースケース向けに拡張するカスタム スクリプトを作成することもできます。

ぜひ Apigee をご検討ください。詳しい情報は、こちらのドキュメントをご覧ください。さらなる意見交換をお望みの方は、Google Cloud Innovators コミュニティにご参加ください。