Product UpdatesStatus PageAutomation Institute
日本語
Get a trial
API プラットフォーム

# API エンドポイント管理

API プラットフォームでは、エンドポイントは API レシピの機能と出力データを公開します。類似するエンドポイントは1つの API コレクションにグループ化され、他のユーザーとアプリは、その API コレクションからエンドポイントを利用できます。

各 API コレクションのページには、そのコレクションに含まれる API エンドポイントが表示されます。 [Tools] > [API platform] > [API collections] に移動し、API コレクションを選択してエンドポイントを表示します。

API コレクションの概要 API コレクションの概要

通常、API コレクションを作成する際は、いくつかのエンドポイントがまとめてアップロードされます。API コレクションを作成したら、さらにエンドポイントをコレクションに追加できます。

以下のセクションでは、新しいエンドポイントの設定について説明します。

# 新しい API エンドポイントの設定

# 前提条件

  • API レシピを作成する
  • API コレクションを作成する
  • 同じ API コレクションに属するエンドポイントを持つ API レシピは、ワークスペース内の同じフォルダーにまとめることをお勧めします。たとえば、営業チームが使用するレシピから呼び出される Salesforce 連携用のエンドポイント群は、1つの API コレクションにまとめることで管理しやすくなります。 これは必須ではありません。 API エンドポイントの URL の詳細については、こちらを参照してください。

# ステップ1: エンドポイントを作成する

開始する前に、エンドポイントのパスのガイドラインを確認してください。

  1. 新しいエンドポイントを作成する API コレクションを選択します。
  2. [Create new endpoint] をクリックします。
    [Add new endpoint] ウィンドウが表示されます。エンドポイントの作成ダイアログ [Add new endpoint] ウィンドウ
  3. 以下の項目に入力します。
    • Name : エンドポイントの分かりやすい名前を入力します。
    • API recipe : ドロップダウンリストから API レシピを選択します。リストには、アクセスできるすべての API レシピが表示されます。
    • Method : HTTP メソッドを選択します。
    • Path : エンドポイントのパスを入力します。パスには、パスパラメータを含めることができます。

    エンドポイントのパスが、これらのガイドラインに従っていることを確認してください。

  4. [Add endpoint] をクリックします。
    API コレクションのページに新しいエンドポイントが表示されます。
    API エンドポイントを変更するときは、エンドポイントの右上隅にある3点リーダー (•••) を選択します。

次にエンドポイントをテストします。

# パスのテンプレート設定

この機能は、接頭辞が有効になっているコレクションでのみ使用できます。

パスパラメータを使用すれば、URL パスでリソース ID を指定できます。API リクエストが作成されると、パスパラメータに入力された値が、API レシピ内の関連するデータピルに渡されます。最初に新規 API リクエストトリガーでデータピルを設定してから、エンドポイントのパスパラメータを設定することをお勧めします。

中括弧 {} を使用して、URL の一部をパスパラメータとしてマークします。例として、以下のスクリーンショットを参照してください。

URL パスのテンプレート設定 URL パスのテンプレート設定

# エンドポイントのパスのガイドライン

  • エンドポイントのパスには、/ で区切られた1つ以上のセグメントを含めることができます。
    たとえば users/{user_id} のようになります。
  • 各セグメントには静的パス (users) またはパラメータ ({user_id}) のいずれかを含めることができますが、両方 (user-{id}) を含めることはできません。
  • パスパラメータ名には、データピル名に応じて英数字または _ 文字を使用できます。
  • エンドポイントのパスには、同じ名前の複数のパラメータを含めることはできません。
  • 各エンドポイントは、メソッドとパスの一意の組み合わせである必要があります。
    • エンドポイント /user/{id} は、/user/{ID} が同じコレクションにすでに存在している場合は使用できません。 ただし、メソッドが異なる場合は使用できます。
    • エンドポイント /user/{id} は、/user/{user_id} が同じコレクションにすでに存在している場合は使用できません。 ただし、メソッドが異なる場合は使用できます。
  • 左から右にパスの照合が行われ、静的セグメントはパラメータ化されたセグメントよりも優先されます。

WARNING

  • レシピまたは API クライアントで使用されたことのあるエンドポイントを更新する場合は、エラーを防ぐために、レシピまたはスクリプトも更新しなければならない場合があります。

# 例

API エンドポイントで salesforce_id が必要な場合は、パスパラメータを使用して Salesforce ID (5003000000D8cuI) を提供できます。

curl -X PUT 'https://apim.workato.com/api-collection/users/5003000000D8cuI' \
    -d '{"Email": "[email protected]","displayName": "Matt Jones","BillingCity": "San Francisco"}'

レシピのトリガー出力は次のようになります。

{
    "request": {
        "salesforce_id" : "5003000000D8cuI",
        "Email": "[email protected]",
        "displayName": "Matt Jones",
        "BillingCity": "San Francisco"
    },
    "Context": {+}
}

キーの重複

パスパラメータ、クエリーパラメータ、またはリクエスト本体に同じ名前空間が存在する場合、Workato ではパスパラメータに指定された値が優先されます。

以下の例では、データピル salesforce_id はパスパラメータの値 (5003000000D8cuI) を取ります。

curl -X PUT 'https://apim.workato.com/api-collection/users/5003000000D8cuI' \
     -d '{"salesforce_id" : "068D00000000pgOIAQ","Email": "[email protected]","displayName": "Matt Jones","BillingCity": "San Francisco"}'

# ステップ2: エンドポイントを表示する

API コレクションの概要ページから API エンドポイントを選択し、そのエンドポイントに関する詳細なドキュメントを含むページを表示します。これらの詳細情報は、API コレクションのページからダウンロード可能な OpenAPI ファイルでも確認できます。

情報セクションには、複数のセクションが含まれています。

エンドポイントの情報セクション エンドポイントの情報セクション

# 実装に関する注意事項

これらはレシピの説明から抜き出されたもので、レシピの役割を説明します。

# Parameters

このセクションには、API の呼び出し時に入力する必要のあるパラメータのリストが表示されます。GET メソッドでは、パラメータを URL に含まれるクエリー文字列として送信する必要があります。POST メソッドまたは PUT メソッドでは、パラメータをリクエスト本体に含めて JSON 形式で送信する必要があります。

# レスポンス

エンドポイントが呼び出されると、ステータスメッセージがクライアントに返されます。このセクションには、エンドポイントの呼び出しが成功した場合のレスポンスと、ステータスとともに送信されるレスポンスデータも表示されます。

コード 説明
200 呼び出しが成功した場合は、レスポンスメッセージが「成功応答」で返されます。
エラーコード API の呼び出しが失敗した場合は、エラーステータスが HTTP クライアントに返されます。このセクションには、返される可能性のあるエラーコードが表示されます。

# ステップ3: エンドポイントをテストする

  1. API コレクションのページから、新しいエンドポイントを開きます。

  2. [Try it out] をクリックして、エンドポイントを試験的に呼び出します。
    このボタンは [Parameters] セクションの右側にあります。

  3. エンドポイントの説明の [Parameters] セクションに入力パラメータを入力します。
    多くの場合、テストには、エンドポイントの説明に表示されている [Example value] で十分です。例 :

    [Parameters] の入力 [Parameters] の入力

  4. [Test] をクリックします。成功した場合のレスポンスの例については、以下のスクリーンショットを参照してください。

    テストのレスポンス テストのレスポンス

ここには、「成功」リターンコード (200) が表示されています。

レスポンス値が200でない場合、テスト結果はエラーになります。エラーには多くの理由が考えられます。

API レシピを所有している同じアカウントからテストを実行する際の最も一般的なエラーは、「無効なリクエスト」 (500) です。これは通常、入力パラメータが正しくない、必須パラメータの一部が指定されていない、または対象レシピに対して無効な値が含まれている、のいずれかを示しています。

エンドポイントを設定する場合は、次のセクションに進んでエンドポイントを有効化します。

# エンドポイントの有効化または無効化

WARNING

エンドポイントを削除すると、そのエンドポイントはコレクションから削除され、以前にコレクション経由でエンドポイントにアクセスできていたクライアントは、そのエンドポイントにアクセスできなくなります。

各エンドポイントの横にある [Active] / [Inactive] トグルを使用して、API コレクションのページから呼び出し可能なエンドポイントを制御します。エンドポイントが新しい API コレクションの一部として作成されたか、既存のコレクションに追加された場合、そのエンドポイントは [Inactive] に設定されます。

API コレクションの概要 API コレクションの概要ページ

他のレシピがエンドポイントを呼び出すことができるようにするには、そのエンドポイントを有効化する必要があります。

状態 説明
Active 有効なエンドポイントは API リクエストから呼び出すことができます。エンドポイントを [Active] に設定するには、そのエンドポイントに関連付けられたレシピを最初に実行している必要があります。
Inactive 無効なエンドポイントはリモートから呼び出すことができません。API ゲートウェイは、無効なエンドポイントへの API 呼び出しを拒否します。ただし、関連付けられたレシピは引き続き実行されます。
← Postman への同期
キャッシング →


Last updated: 2024/7/10 18:18:20

On this page