APIプロキシ変換 ​

APIプロキシ変換を使用すると、WorkatoのAPIゲートウェイを通過するAPIプロキシリクエストとレスポンスを変更できます。 受信リクエストデータをターゲットエンドポイントに転送する前に変換したり、ターゲットレスポンスをクライアントに返す前に変換したりできます。 変換によりAPIの利用が効率化され、データの整合性が向上し、異なるスキーマとデータ形式を整合させることができるため、API利用状況をより詳細に制御できます。

APIプロキシ変換フロー

主要概念 ​

変換プロセスを開始する前に、次の主要概念を確認してください。

• クライアント

• APIプロキシエンドポイントにリクエストを送信するユーザーまたはアプリケーション。

• プロキシスキーマ

• クライアントとAPIプロキシの間で交換されるリクエストとレスポンスの構造を指定する、Workato内で定義されたスキーマ。 APIのクライアント向けインターフェイスとして機能します。

• ターゲット

• APIプロキシによって転送されたAPIリクエストを処理するバックエンドサービス。

• ターゲットスキーマ

• バックエンドAPIまたは外部APIとも呼ばれる、バックエンドサービスのスキーマ。 このスキーマは、ターゲットに転送されるリクエストと、ターゲットから返されるレスポンスの構造を定義します。 変換により、プロキシスキーマとターゲットスキーマが異なる場合の互換性が確保され、受信リクエストデータをバックエンドサービスの要件に、レスポンスをクライアントの期待に整合させることができます。

サポートされている変換タイプ ​

APIプロキシ変換では、リクエストとレスポンスに対する次の変更がサポートされています。

• スキーマ操作

• プロキシまたはターゲットのリクエストとレスポンスの両方のスキーマを変更し、適切な構造とデータフローを確保します。

• キーと値のペアのマッピング

• 機密データのマスキングやカスタムヘッダーの追加など、リクエストまたはレスポンス内のパラメーターを作成または変更します。

• インラインFormula

• WorkatoのFormula機能を使用して、リクエストまたはレスポンス内の値を操作します。 静的または動的な値（データピルを使用）を適用し、データに基づいて計算または書式設定を実行できます。

• 条件付きレスポンスマッピング

• 特定の条件に基づいて異なるHTTPステータスまたはレスポンスを返すために、条件ロジックを適用します。

• リクエストメソッド変換

• プロキシとターゲット間のHTTPメソッドを変更します。 たとえば、プロキシでのGETリクエストをターゲットでのPOSTリクエストに変換します。 メソッド変換は、リクエストをターゲットに転送アクションでリクエストを変換を選択した場合にのみ使用できます。

部分的にサポートされている変換タイプ ​

APIプロキシ変換では、リクエストとレスポンスに対する次の変更が部分的にサポートされています。

• リクエスト本文およびレスポンス本文で部分的にサポートされるコンテンツタイプ
• XMLは部分的にサポートされているため、リクエスト本文またはレスポンス本文を変換するときに、text/plainコンテンツタイプを使用してXML本文を構築できます。

サポートされていない変換タイプ ​

APIプロキシ変換ではリクエストとレスポンスを柔軟に変更できますが、次の変換はサポートされていません。

• 動的パス変換

• ターゲットURLパスには、データピルまたはFormulaによる動的変換を使用できません。 静的テキストパスのみ使用できます。

• クエリパラメーター内の配列またはオブジェクトの変換

• GETおよびDELETEリクエストでは、クエリパラメーター内の配列またはオブジェクトを変換できません。 ただし、リクエスト本文では引き続き配列とオブジェクトを使用できます。

• リクエスト本文およびレスポンス本文でサポートされていないコンテンツタイプ

• リクエスト本文とレスポンス本文の両方で、特定のコンテンツタイプに変換を適用することはできません。 これには、multipart form data、URLエンコードフォーム、プレーンテキスト、バイナリデータが含まれます。

• 複数の条件付きレスポンス

• 単一のプロキシエンドポイントに対して、複数のレスポンスステータスコードを異なる条件にマッピングすることはできません。 条件ロジックを使用した複数のステータスコードマッピングの処理はサポートされていません。

Formulaの制限 ​

Workatoでは、Formulaを使用してリクエストとレスポンスを変換でき、データを動的に変換する柔軟性が提供されます。 文書化されているほとんどのFormulaはサポートされていますが、一部例外があります。

制限に遭遇した場合、または追加のFormulaサポートが必要な場合は、Customer Success Manager（CSM）にお問い合わせください。

プロキシリクエストの変換 ​

プロキシリクエストを変換すると、受信リクエストデータをターゲットエンドポイントに転送する前に変更できます。 要件に基づいて、HTTPメソッド、エンドポイントパス、クエリパラメーター、ヘッダー、またはリクエスト本文を設定できます。 クライアントスキーマがターゲットスキーマと異なる場合に変換を使用して、不一致のデータ形式または構造を調整します。

プロキシリクエストの変換には、主に2つのステップがあります。

• ターゲットエンドポイントスキーマの設定: ターゲットAPIのデータ形式に合わせて、ターゲットエンドポイントのリクエストスキーマを設定します。
• 変換の適用: 変換オプションを使用してリクエストを変更し、クライアントスキーマに一致させるか、特定のターゲットAPI制約に適応させます。

ターゲットエンドポイントスキーマの設定 ​

変換を適用する前に、ターゲットエンドポイントのスキーマを定義する必要があります。 このステップにより、プロキシエンドポイントがターゲットAPIのデータ形式と整合します。 プロセスを完全に制御するために、ガイド付きセットアップまたは手動設定を使用してスキーマを定義できます。

ガイド付きセットアップ ​

ガイド付きセットアップは、ターゲットAPIのスキーマ設定に役立ちます。 このセットアップでは、ターゲットAPIにサンプルリクエストを送信することで、リクエストスキーマとレスポンススキーマが自動的に生成されます。

ガイド付きセットアップを使用するには、次の手順を実行します。

ターゲットスキーマを設定したら、要件に基づいてリクエストを変更するために、プロキシリクエスト変換の適用に進みます。

手動設定 ​

手動セットアップでは、ターゲットAPIにサンプルリクエストを送信せずに、ターゲットエンドポイントのスキーマを設定できます。 この方法では、リクエストとレスポンスの定義を完全に制御できるため、カスタム設定やガイド付きセットアップが適していない場合に最適です。

プロキシリクエストを設定するときは、変換が必要かどうかを判断します。 パススルーリクエストの場合、変換やリクエストスキーマ設定は不要です。 変換が必要な場合は、ターゲットスキーマを定義し、リクエスト変換を設定できるように、フィールドが動的に表示されます。

ターゲットエンドポイントのスキーマを手動で設定するには、次の手順を実行します。

ターゲットスキーマを設定したら、要件に基づいてリクエストを変更するために、プロキシリクエスト変換の適用に進みます。

プロキシリクエスト変換の適用 ​

スキーマのセットアップ後、リクエストをターゲットに転送アクションに戻って変換を設定します。 何を実行しますか?ドロップダウンメニューを使用して、プロキシがリクエストを処理する方法を決定します。

APIプロキシリクエストに対する処理の選択

特定の要件に基づいて、次のいずれかのオプションを選択します。

リクエスト変換を設定して保存したら、必要に応じて、レスポンスをクライアントに返す前にレスポンスを変換するようにレスポンスを返すアクションを設定します。

ターゲットレスポンスの変換 ​

ターゲットレスポンス変換を使用すると、ターゲットから返されたデータをクライアントに返す前に変更できます。 ヘッダーの設定、本文の変更、または条件ロジックの適用により、レスポンスをカスタマイズできます。

レスポンス変換を設定するには、次の手順を実行します。

ターゲットレスポンス変換の適用 ​

APIの要件に一致する変換オプションを選択します。 各オプションは、クライアントに返す前にレスポンスを変更する方法を決定します。

条件付きレスポンスマッピング ​

条件付きレスポンスマッピングを使用すると、定義された条件に基づいて異なるレスポンスを返すことができます。 プロキシリクエストまたはターゲットレスポンスの両方からの動的な値を使用して、1つの条件付きレスポンスを設定できます。 たとえば、HTTPステータスコードなどのフィールドを評価し、条件が満たされているかどうかに応じて指定されたレスポンスを返すことができます。

条件付きレスポンスマッピングを設定するには、次の手順を実行します。

Workato Formulaによるデータの変換 ​

Workato Formulaを使用すると、APIリクエストとレスポンス内のデータを動的に変換できます。 Formulaを使用して、データ形式の効率化、算術計算の実行、文字列の操作を行うことができます。 文書化されているほとんどのFormulaはサポートされていますが、一部例外があります。 詳細については、WorkatoのFormulaドキュメントを参照してください。

Formula変換の例 ​

Formulaを使用して、リクエストパラメーターのデフォルト値を定義できます。 たとえば、入力がない場合にデフォルト値を設定するFormulaを使用して、リクエストパラメーターを定義できます。

リクエストパラメーターの変換

この例では、検索語句Step 1データピルが、Formula.presence || 'Featured products'を使用して検索語句フィールドにマッピングされます。 このFormulaは、検索語句が指定されていない場合に、検索語句リクエストパラメーターをFeatured productsに設定します。

テストリクエストの送信 ​

変換を設定したら、テストリクエストを送信して、すべてが期待どおりに動作することを確認します。 テストリクエストを送信するときは、次の点を確認します。

• リクエスト変換が、パラメーター、ヘッダー、本文に正しく適用されていること。
• レスポンス変換により、クライアントに返す前に、レスポンス本文とヘッダーが意図したとおりに変更されていること。
• HTTPステータスコードが正確で、意図したレスポンス動作を反映していること。
• テストデータが実際のシナリオを反映し、エッジケースを確認できること。

テストにより、APIプロキシ変換が適切に機能し、クライアントとターゲットの要件を満たしていることを確認できます。