APIレシピを作成 ​

このページは機械翻訳により提供されています。翻訳内容と英語版に相違がある場合は、英語版が優先されます。

このガイドでは、APIレシピを作成する方法について説明します。外部のビジネスパートナーや内部関係者は、Workatoアカウントへのアクセスを必要とせずに、このエンドポイントを使用してデータにアクセスし、利用できます。

前提条件

APIレシピを作成するには、次の前提条件を満たしている必要があります:

  • API platform機能へのアクセス。 API Platform機能は、特定の料金プランのお客様が利用できます。詳細については、ご利用の料金プランおよび契約を参照してください。
  • APIコレクションとエンドポイントおよびレシピの作成権限。

Workato API platformとGoogle Workspaceのインテグレーションを作成し、優先するCLIを使用して、またはBambooHRで新しい従業員が検出されたときにGoogle Workspaceにユーザーを追加できるようにする手順については、Google Workspaceにユーザーを追加ユースケースを参照してください。

サポートされているデータ型 ​

Content typeドロップダウンメニューを使用して、コネクタが受け付けるデータ形式を設定します。 APIレシピは次のオプションをサポートしています:

  • JSON: JavaScript Object Notation形式のデータを受け入れます。ほとんどのREST APIと構造化ペイロードには、これを使用します。
  • テキスト/XML: XML、SOAP、CSV、YAMLなどの未加工コンテンツを受け入れます。非JSON形式またはプレーンテキストのペイロードを処理するには、これを使用します。
  • Multipart: 複数のパートで構成されるリクエストを受け入れます。混合データを含むリクエストには、これを使用します。

追加のデータ処理に関する情報については、Parse the request bodyを参照してください。

トップレベル配列のサポート ​

Request structureおよびResponse structureドロップダウンメニューを使用して、リクエストまたはレスポンスボディの最も外側の構造を、単一オブジェクトかトップレベル配列かで制御します。

  • Object: ボディ内で配列をキーの下に入れ子にする必要がある場合にこのオプションを使用します。例:

    json
    {
      "accounts": [
        { "id": 1, "name": "Acme Corp" },
        { "id": 2, "name": "Globex Inc" }
      ]
    }
  • Array of objects、Array of strings、Array of integers、Array of numbers、Array of booleans、Array of dates、Array of date-times: ボディをトップレベルの配列だけにする必要がある場合に、これらのいずれかのオプションを使用します。例:

    json
    [
      { "id": 1, "name": "Acme Corp" },
      { "id": 2, "name": "Globex Inc" }
    ]

Request bodyセクションとResponse schemaセクションが表示されるのは、構造がObjectまたはArray of objectsに設定されている場合のみです。その他の配列タイプはスカラー値を保持し、定義するスキーマがないためです。選択した構造によって、配列タイプの場合の各アイテムの型が定義されます。

新しいエンドポイントのデフォルトはObjectであり、既存のエンドポイントはこれまでどおり動作します。 OpenAPI 3またはSwagger 2形式の仕様をインポートまたはエクスポートする場合も、トップレベル配列は動作します。

Request structureを配列タイプに設定すると、Request parameters出力グループにList sizeおよびList indexデータピルが含まれるため、リクエストボディ内のアイテムをループ処理できます。

Request bodyとレガシーRequest schema ​

トリガーのRequestセクションでは、パスパラメータ、クエリパラメータ、リクエストボディを個別のセクションで定義します。以前は、クエリパラメータはリクエストスキーマの一部でした。引き続き、リクエストボディ内でクエリパラメータを定義できます。同じフィールドが複数の場所に存在する場合、パスパラメータがクエリパラメータより優先され、クエリパラメータがリクエストボディより優先されます。

既存のエンドポイントでは、保存済みのRequest schemaフィールドが保持され、これは現在レガシーフィールドとなります。 Request schemaフィールドは引き続き完全にサポートされており、そのフィールドから生成されるデータピルはレシピ内で引き続き解決されます。 Workatoは既存のエンドポイントを移行せず、スキーマを更新しても既存のエンドポイントは変更されません。新しいエンドポイントでは、代わりにRequest bodyフィールドが使用されます。 Responseセクションにはレガシーフィールドはありません。 Response structureを使用して、レスポンスの構造を選択します。

Request bodyフィールドへの移行 ​

レガシーのRequest schemaフィールドを引き続き使用できます。既存のエンドポイントをRequest bodyフィールドに移行する場合は、次の手順を完了します。

1

レシピを開き、New API requestトリガーを選択します。

2

Requestセクションに移動し、レガシーのRequest schemaフィールド内のスキーマをコピーします。フィールドをクリアすると、Workatoはスキーマを削除します。

3

レガシーのRequest schema内のフィールドをクリアします。代わりにRequest bodyフィールドが表示されます。

4

Request bodyフィールドでスキーマを定義します。

5

Query parametersセクションおよびPath parametersセクションで、必要なクエリパラメータやパスパラメータを定義します。

6

Request parametersグループのデータピルを使用している手順を確認します。リクエストボディ用のデータピルはRequest bodyグループに表示されるため、必要に応じて再マッピングする必要があります。

7

レシピを保存してテストします。

レシピを作成 ​

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

トラブルシューティング

発生した問題のトラブルシューティングを容易にするため、小さな手順でレシピを構築し、レシピを頻繁に保存してテストすることをお勧めします。

1

Workatoにサインインします。

2

レシピを作成する予定のプロジェクトを選択します。

3

作成>レシピをクリックするか、C+Rを押します。

新しいレシピを作成新しいレシピを作成

4

Nameフィールドにレシピの名前を入力します。

5

Locationドロップダウンメニューを使用して、レシピを保存するプロジェクトを選択します。

6

ビルドを開始をクリックします。

レシピの構築を開始レシピの構築を開始

7

開始点を選択>APIエンドポイントを構築をクリックします。 Workatoは新規APIリクエストトリガーを自動的に作成します。

8

新規APIリクエストトリガーを選択します。

9
エンドポイントのリクエスト構造を設定します。
1

トリガーのリクエストセクションに移動します。

2

コンテンツタイプドロップダウンメニューを使用して、エンドポイントが受け入れるデータの種類を選択します。たとえば、application/jsonを選択すると、エンドポイントは有効なJSONデータを受け入れます。

3

任意。リクエストヘッダーセクションを使用して、リクエストヘッダーで受け入れるパラメーターを定義します。

4

任意。パスパラメーターセクションを使用して、JSONおよびText/XMLリクエストのエンドポイントパスで受け入れるパラメーターを定義します。サンプルJSONファイルをアップロードするか、フィールドを手動で入力できます。

5

任意。 Query parametersセクションを使用して、JSONおよびText/XMLリクエストでエンドポイントのクエリ文字列内で受け付けるパラメータを定義します。サンプルJSONファイルをアップロードするか、フィールドを手動で入力できます。

6

Request structureドロップダウンメニューを使用して、このエンドポイントが受け付けるリクエストボディの最も外側の構造を選択します。デフォルトはObjectです。利用可能なオプションについては、Top-level array supportを参照してください。

7

Request bodyセクションを使用して、JSONおよびMultipartリクエストのリクエストボディのスキーマを定義します。サンプルJSONファイルをアップロードするか、フィールドを手動で入力できます。

REQUEST BODYとREQUEST STRUCTUREの関係

Request structureがObjectまたはArray of objectsに設定されている場合にのみ、Request bodyセクションが表示されます。

レガシーREQUEST SCHEMA

Request bodyセクションが利用可能になる前に作成されたエンドポイントには、代わりにレガシーのRequest schemaフィールドが表示されます。 Request schemaフィールドは引き続き完全にサポートされます。詳細については、Migrate to the Request body fieldを参照してください。

手順の概要

この手順では、新規APIリクエストトリガーのフィールドを使用して、エンドポイントのリクエスト構造を定義します。

10
エンドポイントのレスポンス構造を設定します。
1

トリガーのレスポンスセクションに移動します。

2

コンテンツタイプドロップダウンメニューを使用して、レスポンスで送信するデータの種類を選択します。

3

任意。レスポンスヘッダーセクションを使用して、レスポンスヘッダーで送信するパラメーターを定義します。

4

レスポンスセクションに移動し、レスポンスを追加を選択します。

5

レスポンス#1セクションでレスポンスの名前を指定します。

6

HTTPステータスコードドロップダウンメニューを使用して、レスポンスのコードを選択します。または、入力フィールドを標準レスポンスからカスタムレスポンスに切り替え、2xxから5xxまでのカスタムHTTPステータスコードを入力できます。

7

Response structureドロップダウンメニューを使用して、このエンドポイントが返すレスポンスボディの最も外側の構造を選択します。デフォルトはObjectです。レスポンスで配列をキーの下に入れ子にする必要がある場合は、Objectを使用します。例えば {"accounts": [...]} のようになります。レスポンスボディをトップレベルの配列だけにする必要がある場合は、配列オプションのいずれかを使用します。例えば [...] のようになります。利用可能なオプションについては、Top-level array supportを参照してください。

8

Response schemaセクションを使用して、レスポンスボディのスキーマを定義します。サンプルJSONファイルをアップロードするか、フィールドを手動で入力できます。

RESPONSE SCHEMAとRESPONSE STRUCTUREの関係

Response structureがObjectまたはArray of objectsに設定されている場合にのみ、Response schemaセクションが表示されます。

プロパティを親要素間でドラッグ&ドロップすることで、入れ子になったスキーマを作成できます。または、Edit schemaボタンをクリックして、使用する予定のスキーマを指定します。

レスポンススキーマレスポンススキーマ

json
[
  {
    "name": "ID",
    "type": "string",
    "optional": false,
    "control_type": "text",
    "label": "ID",
    "hint": "アカウントID"
  },
  {
    "name": "Name",
    "type": "string",
    "optional": false,
    "control_type": "text",
    "label": "名前",
    "hint": "アカウント名"
  }
]

手順の概要

この手順では、新規APIリクエストトリガーのフィールドを使用して、エンドポイントのレスポンス構造を定義します。

11

+ Add stepをクリックし、Handle errorsを選択します。

エラー処理ステップを追加エラー処理ステップを追加

MCPサーバー

APIエンドポイントをMCPサーバーで使用する予定の場合、エラー処理制御ステートメントは不要です。 MCPサーバーがAPI platformに接続する方法についてはMCP local serversを、MCPサーバーを使用してAPIエンドポイントを作成および使用する手順についてはMCP use casesを参照してください。

Handle errors制御ステートメントはどのように機能しますか?

エラー処理制御ステートメントを使用すると、プログラミング言語のtry/catchの概念と同様に、レシピ内のアクションのエラーを監視できます。エラーが発生した場合、次のアクションを実行できます:

  • ネットワークの問題などの一時的なエラーであった場合に備えて、一連のアクションを再試行します。

  • メールまたはアプリ内のエラーメッセージを通じてユーザーにエラーを通知する、ロールバックを実行するなどの修復アクションを実行します。たとえば、作成済みまたは作成途中のレコードを削除することで、ジョブを元に戻すことができます。

この制御ステートメントは、監視ブロックとエラーブロックの2つのブロックで構成されます。エラーを監視する予定のアクションを監視ブロック内に配置します。すべてのアクションが成功した場合、Workatoはエラーブロックを無視します。ただし、監視ブロック内のいずれかのアクションでエラーが発生した場合、エラーブロック内のアクションが実行されます。

12
Monitorブロックを設定します。
1

APIエンドポイントを通じて公開する予定のアクションを、エラーを監視するアクションブロック内に追加します。アプリ固有の接続および設定手順については、Connectorsを参照してください。

エラーを監視するアクションを追加エラーを監視するアクションを追加

2

+ステップを追加>アプリ内のアクションをクリックします。

3

API platform by Workatoを検索して選択します。

4

操作でエラーが発生しない場合に送信するレスポンスの種類を、レスポンスドロップダウンメニューを使用して選択します。このメニューのオプションは、レシピの新規APIリクエストトリガーで定義されたレスポンスによって決まります。

IF条件を使用すると、レシピデータに基づいて異なるレスポンスを送信できます。

5

レシピでエラーが発生しなかった場合にレスポンスボディで返すデータを設定するには、Response bodyセクションを使用します。このセクションの構造は、新規APIリクエストトリガーで定義されたスキーマに基づいて異なります。

6

レシピでエラーが発生しなかった場合にレスポンスヘッダーで返すデータを設定するには、Response headersセクションを使用します。このセクションの構造は、新規APIリクエストトリガーで定義したスキーマに基づいて異なります。

手順の概要

この手順では、APIエンドポイントを通じて公開するレシピロジックと、レシピでエラーが発生しない場合に送信するレスポンスデータを定義します。

13
Error found?を設定します。ブロック。
1

Error found?ブロックでDo not retryを選択します。

2

Monitorブロックのアクションを再試行しますか?ドロップダウンメニューを使用して、失敗したアクションを再試行する回数を選択します。 Workatoでは最大3回まで再試行できます。

3

Select an app and actionをクリックします。

4

API platform by Workatoを検索して選択します。

5

操作でエラーが発生した場合に送信するレスポンスの種類を、レスポンスドロップダウンメニューを使用して選択します。このメニューのオプションは、レシピの新規APIリクエストトリガーで定義したレスポンスによって決まります。

IF条件を使用すると、レシピデータに基づいて異なるレスポンスを送信できます。

6

レシピでエラーが発生した場合にレスポンスボディで返すデータを設定するには、Response bodyセクションを使用します。このセクションの構造は、新規APIリクエストトリガーで定義したスキーマに基づいて異なります。

7

レシピでエラーが発生した場合にレスポンスヘッダーで返すデータを設定するには、Response headersセクションを使用します。このセクションの構造は、新規APIリクエストトリガーで定義したスキーマに基づいて異なります。

手順の概要

この手順では、再試行設定と、レシピでエラーが発生した場合に送信するレスポンスデータを定義します。

APIレシピをテストして実装する準備ができました。

設定済みのAPIレシピ設定済みのAPIレシピ

APIパフォーマンス

APIレシピでレイテンシーを低減する必要がある場合は、レシピの設定>データリテンションタブに移動し、ジョブデータリテンション設定を構成してログの作成を無効にできます。

詳細については、レシピのデータリテンションの定義ガイドを参照してください。

リクエスト本文を解析 ​

必要に応じて、Workatoのデータ処理コネクターを使用して、エンドポイントが受信したデータからデータピルを作成できます。

リクエスト本文を解析するには、次の手順を実行します:

1

+ステップを追加>アプリ内のアクションをクリックします。

2

データ処理コネクターを検索して選択します。例: XML tools by Workato。

3

コネクターのドキュメントを解析アクションを選択します。例: XMLドキュメントを解析。

4

コネクター固有のフィールドを設定するには、コネクターのドキュメントを参照してください。

5

入力の想定構造を定義するサンプルドキュメントを入力します。 Workatoはこれを使用して出力スキーマを生成します。

6

新規APIリクエストトリガーの出力からリクエスト本文ステップ 1データピルをドキュメントフィールドにマッピングします。

データ解析手順が完了しました。 Workatoは、サンプルドキュメントフィールドで定義された構造に基づいてデータピルを生成します。

APIエンドポイントを公開 ​

レシピを作成した後、次の手順はAPIレシピをAPI platformのエンドポイントとして公開することです。これにより、エンドポイントをプロダクションにリリースする前にテストし、期待どおりに動作することを確認できます。

レシピをエンドポイントとして公開するには、次の手順を実行します:

1

プラットフォーム>API platform>APIコレクションに移動します。

2

ワークスペースに既存のコレクションがない場合は、新しいAPIコレクションを作成します。

エンドポイント管理 ​

APIエンドポイントは次のツールを使用して管理できます:

  • APIレシピコレクションは、配布とバージョン管理のためにエンドポイントをグループに整理します。
  • APIクライアントは、APIアクセス管理のためにユーザーをグループに整理します。
  • APIキーは、APIクライアントに安全な認証を提供します。
  • APIアクセスポリシーは、クライアントのレート制限とリクエストクォータを適用します。
  • レシピOpsコネクターを使用すると、ワークスペースを監視および管理するレシピを構築できます。たとえば、API同時実行しきい値超過トリガーを使用して、ワークスペース内の同時実行クォータを監視できます。

最終更新日: