SOAP APIレシピウォークスルー ​

このウォークスルーでは、WorkatoでSOAPエンドポイントを手動で構築する方法を示します。 エンドポイントはraw XMLを受け入れ、レシピはリクエストをprivate serverでホストされているターゲットAPIに渡す前に、SOAPエンベロープを解析して検証します。 これにより、外部のビジネスパートナーや内部の関係者は、ターゲットAPIに直接接続することなくAPIのデータにアクセスできます。

このウォークスルーでは、ターゲットAPI自体ではなく、ターゲットAPIの前にあるWorkato側のエンドポイントを構築します。 ターゲットAPIが利用可能になる前にエンドポイントの大部分を構築してテストできますが、そのAPIに到達可能になって初めて、レシピはターゲットAPIからデータを返すことができます。

構築するもの ​

このウォークスルーでは、次のコンポーネントを構築します:

• XMLリクエストを受け入れ、リクエストされた操作を識別し、その操作が承認されているかどうかを確認して、承認済みリクエストをターゲットAPIに転送するSOAP APIレシピ。
• SOAP APIを説明するWSDLを返す別のAPIレシピ。
• 両方のレシピをエンドポイントとして公開するAPIレシピコレクション。

SOAP APIレシピでは、次の3つのレスポンスパスを使用します:

• ターゲットAPIリクエストが成功した場合はsuccess。
• リクエストされた操作が承認済みリストにない場合はnot_found。
• ターゲットAPIへのリクエストが失敗した場合はerror。

前提条件 ​

SOAP APIレシピを作成する前に、次の点を確認してください:

• API platformへのアクセス。 API platformは、特定の料金プランのお客様が利用できます。 詳細については、料金プランと契約を参照してください。
• APIコレクションとエンドポイントおよびレシピの作成権限。
• エンドポイントで許可するSOAP操作を含むルックアップ テーブル。
• ターゲットAPI用のHTTPコネクション。 private serverでホストされているAPIに到達するには、オンプレミスグループを使用するようにコネクションを設定します。
• ターゲットAPIを呼び出すために必要なリクエストの詳細（URL、メソッド、ヘッダー、ペイロード形式など）。
• このウォークスルーでWSDLエンドポイントを公開する予定がある場合は、SOAP APIを説明するWSDL。 このウォークスルーでは、WSDLを返す方法を示します。WSDLを作成する方法ではありません。

SOAP APIレシピを作成する ​

SOAP APIレシピを作成するには、次の手順を実行します:

Build an API endpoint開始ポイントでは、New API requestトリガーとRespond to API requestアクションを含むレシピが自動的に作成されます。

レシピのトリガーを定義する ​

New API requestトリガーは、エンドポイントのリクエスト構造とレスポンス構造を定義します。

1. リクエスト構造を定義する
2. レスポンス構造を定義する

リクエスト構造を定義する ​

リクエスト構造を定義するには、次の手順を実行します:

レスポンス構造を定義する ​

レスポンス構造は、SOAP APIレシピが返すことができる出力を定義します。 このレシピでは、3つのレスポンスを使用します: success、承認済みリストにない操作用のnot_found、ターゲットAPIリクエストが失敗した場合のerror。

レスポンス構造を定義するには、次の手順を実行します:

SOAPリクエストを処理する ​

SOAPエンベロープを解析し、リクエストされた操作を検証して、ターゲットAPIを呼び出すステップをレシピに追加します:

1. XMLペイロードを解析して検査する
2. 操作が承認されているかどうかを確認する
3. ターゲットサービスを呼び出してエラーを処理する

XMLペイロードを解析して検査する ​

SOAPリクエストは、リクエスト本文内のSOAPエンベロープとして到着します。 例:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <OperationName>
      <Parameter>value</Parameter>
    </OperationName>
  </soap:Body>
</soap:Envelope>

XMLペイロードを解析して検査するには、次の手順を実行します:

操作が承認されているか確認する ​

リクエストされた操作がルックアップ テーブルに含まれているかどうかに基づいて、レシピを分岐します。

ターゲットサービスを呼び出してエラーを処理する ​

IFブロック内で、ターゲットAPIへの呼び出しをHandle errors制御ステートメントでラップします。 これにより、ターゲットAPIリクエストが失敗した場合に、エンドポイントは定義済みAPIレスポンスを返すことができます。

次の手順を完了します:

WSDLを返すレシピを作成する ​

SOAP APIを説明するWSDLを返す別のAPIレシピを作成します。 このレシピをSOAP APIレシピと同じフォルダに作成し、両方のレシピを同じAPIレシピコレクションに追加できるようにします。

WSDLはWorkato FileStorageに保存できます。 WSDLを取得し、その内容をレスポンス本文として返すようにレシピを設定します。

WSDL APIレシピ

レシピロジックをテストする ​

SOAP APIレシピを構築しながら保存してテストします。 小さなステップでレシピを構築すると、エンドポイント全体をテストする前に問題を切り分けやすくなります。

リクエスト解析と操作検証をテストする ​

トリガー、XML解析、ルックアップ テーブルロジックをテストするために、ターゲットAPIに到達可能である必要はありません。

Send requestアクションをスキップし、サンプルSOAPリクエストを送信して、次の点を確認します:

• レシピが、リクエストされた操作の識別に使用される値を解析する。
• 承認済み操作がIF分岐に進む。
• ルックアップ テーブルにない操作がELSE分岐に進み、not_foundレスポンスを返す。

エラーパスをテストする ​

ターゲットAPIが利用可能になる前に、errorレスポンスをテストすることもできます。 Send requestアクションを有効のままにし、ターゲットAPIが利用できない状態、またはHTTPリクエストが失敗する原因となる状態で、そのステップに到達するリクエストを送信します。

失敗したリクエストはError found?ブロックに入り、設定済みの再試行後にerrorレスポンスを返します。

パブリックAPIで成功パスをテストする ​

ターゲットAPIが利用可能になる前にレシピの成功パスをテストするために、Send requestアクションをhttps://jsonplaceholder.typicode.com/todosなどの到達可能なパブリックテストAPIに一時的に向けることができます。

このテストでJSONPlaceholderを使用する場合:

• private target APIではなく、パブリックテストエンドポイント用にSend requestアクションを設定します。
• Request content typeフィールドを、送信するペイロードに合わせます。
• Response content typeフィールドをTextに設定して、レスポンスをXMLまたはJSONとして解析せずにそのまま渡します。
• レシピフローを検証したら、Send requestアクションを実際のターゲットAPI設定に戻します。

レシピをコレクションにグループ化する ​

SOAP APIレシピとWSDLレシピをAPIレシピコレクションにグループ化します。 Use existing recipesを選択し、両方のレシピを含むフォルダを選択します。

これにより、SOAPリクエストを処理するエンドポイントとWSDLを返すエンドポイントの2つが作成されます。

エンドポイントをエンドツーエンドでテストする ​

エンドポイントをアクティブ化し、APIに到達可能になったら、実際のターゲットAPIでSOAPエンドポイントをテストできます。

承認済み操作を送信し、フロー全体を確認します:

1. エンドポイントはSOAPリクエストをraw XMLとして受け入れる。
2. レシピはSOAP本文を解析し、リクエストされた操作を識別する。
3. ルックアップ テーブルは、その操作が承認されていることを確認する。
4. HTTPアクションはリクエストをターゲットAPIに送信する。
5. レシピは、successレスポンスを通じてターゲットAPIペイロードを返す。

curlまたは別のHTTPクライアントでリクエストを送信できます。 Try it outテスターにはrawリクエスト本文用のフィールドが表示されないため、SOAPエンベロープを直接送信できるクライアントを使用します:

curl -X POST 'ENDPOINT_URL' \
  -H 'api-token: API_KEY' \
  -H 'Content-Type: text/xml' \
  --data-binary '<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"><soap:Body><OperationName><Parameter>APPROVED_OPERATION</Parameter></OperationName></soap:Body></soap:Envelope>'

curlリクエストに必要なAPIクライアントとキーの作成方法については、レシピエンドポイントをテストするを参照してください。

SOAP APIレシピをターゲットAPIで実装する準備ができました。