初めてのコネクターを構築する
このガイドでは、Connector SDKとStar Wars API（SWAPI）を使用してカスタムコネクターを構築する方法を説明します。 SWAPIでは、Star Warsのキャラクター、乗り物、その他のリソースに関する情報に無料でアクセスできます。
カスタムコネクターを作成する
新しいカスタムコネクターを作成するには、次の手順を完了します:
Workatoアカウントにサインインします。
ツール > Connector SDKに移動します。
ツール＞Connector SDKに移動
コネクターを作成をクリックして、Connector SDKウィザードを開きます。
「コネクターを作成」をクリック
開始点としてWorkatoテンプレートに沿って進めるを選択し、次へをクリックします。
開始点を選択
このコネクターはどのアプリケーション用ですか?フィールドにStar Wars Informationと入力します。
PNGまたはJPGファイルをロゴを追加フィールドにドラッグアンドドロップするか、デバイスからアップロードをクリックします。
カスタムコネクターの名前を入力
エディターへ移動をクリックします。
これらの手順を実行するとConnector SDKが開き、コネクションの詳細を定義してコネクターを設定できます。
コネクションを作成する
APIに接続するには、まず必要な認証方法を特定する必要があります。 SWAPIでは認証が不要なため、本人確認を行わずにSWAPIへリクエストを送信できます。
SWAPIコネクションを作成するには、次の手順を完了します:
ソースコードタブを開きます。
次のコードスニペットをコピーしてコードエディターに貼り付けます:
{
title: 'Star Wars Information',
connection: {
fields: [
{
name: "object",
hint: "Enter the object you plan to use to test your connection.",
}
]
},
test: lambda do |connection|
get("https://swapi.tech/api/#{connection["object"]}")
end,
# More code below but hidden for now!
}このコードスニペットはどのように機能しますか。
このコードスニペットには、次のキーが含まれています:
connection- ユーザーがコネクターに接続するときに表示される入力フィールドを定義します。
fields- 入力フィールドを宣言します。 このキー内で収集されたユーザー入力は、カスタムコネクターコードの他の部分で使用できます。
test- ユーザーが接続をクリックしたときに実行されるテストを宣言します。 このキーにより、Workatoはコネクションが成功したか失敗したかに関するフィードバックを提供できます。
このテストは何を実行しますか。
SWAPIコネクターは指定されたURLエンドポイントにGETリクエストを送信し、リクエストが200ステータスコードを返すとテストが成功します。 testキーは、get()関数を使用してリクエストを実行することで、この機能を定義します。
この例では、入力によってHTTP呼び出しのターゲットURLが決まります。 スニペットはconnectionキー、具体的にはconnection["object"]を通じて入力を参照します。
コネクション名フィールドに名前を入力します。
コネクション設定用の入力フィールドの例
オブジェクトフィールドに、次の有効な入力のいずれかを入力します:
filmspeopleplanetsspeciesstarshipsvehicles
Connectをクリックしてコネクションを確立します。 コネクションが成功すると、次の確認メッセージが表示されます:
成功したコネクション
MCP検証済みユーザーアクセス用のSDKコネクションを作成する
MCP検証済みユーザーアクセスは、OAuth 2.0認可コードグラントを使用するコネクションのみをサポートします。 このコネクションタイプでは、Workatoがユーザーの認証情報を保存する前に、エンドユーザーを外部アプリケーションにリダイレクトしてアクセスを認可します。
コネクションを作成するには、次の手順を実行します:
ソースコードタブを開きます。
次のコードスニペットをコピーしてコードエディターに貼り付けます:
{
title: 'Example App',
connection: {
fields: [
{
name: 'host',
label: 'Host',
hint: 'e.g. https://your-instance.example.com',
optional: false
},
{
name: 'client_id',
label: 'Client ID',
optional: false
},
{
name: 'client_secret',
label: 'Client secret',
control_type: 'password',
optional: false,
preserve_in_runtime_connection: true
}
],
authorization: {
type: 'oauth2',
authorization_url: lambda do |connection|
"#{connection['host']}/oauth/authorize?client_id=#{connection['client_id']}&response_type=code"
end,
acquire: lambda do |connection, auth_code, redirect_uri|
response = post("#{connection['host']}/oauth/token").
payload(client_id: connection['client_id'],
client_secret: connection['client_secret'],
grant_type: 'authorization_code',
code: auth_code,
redirect_uri: redirect_uri).
request_format_www_form_urlencoded
[response, nil, nil]
end,
refresh: lambda do |connection, refresh_token|
post("#{connection['host']}/oauth/token").
payload(client_id: connection['client_id'],
client_secret: connection['client_secret'],
grant_type: 'refresh_token',
refresh_token: refresh_token).
request_format_www_form_urlencoded
end,
detect_on: [401],
apply: lambda do |connection, access_token|
headers('Authorization' => "Bearer #{access_token}")
end
},
base_uri: lambda do |connection|
connection['host']
end
},
test: lambda do |connection|
get('/api/me')
end,
# More code below but hidden for now!
}このコードスニペットはどのように機能しますか。
fields- コネクション入力フィールド
host、client_id、client_secretを宣言します。 MCP検証済みユーザーアクセスには、UIで値をマスクするためにcontrol_type: 'password'を使用するclient_secretを含むOAuth 2.0認可コードグラントが必要です。 authorization- OAuth 2.0認可コードグラントフローを宣言します。
authorization_urlは、エンドユーザーのリダイレクト先URLを構築します。acquireは、返された認可コードをアクセストークンと交換します。refreshは、更新トークンを新しいアクセストークンと交換します。applyは、コネクターが行うすべてのリクエストにアクセストークンを添付します。 base_urihostフィールドから構築される、リクエストのベースURLを宣言します。test- ユーザーが接続をクリックしたときに実行されるテストを宣言します。
client_secretでpreserve_in_runtime_connection: trueが設定される理由
このプロパティの詳細については、ランタイムユーザーコネクションのフィールドを設定するを参照してください。
コネクション名フィールドに名前を入力します。
テストアプリケーションのホスト、クライアントID、クライアントシークレットを入力します。
接続をクリックします。 Workatoはアクセスを認可するために外部アプリケーションにリダイレクトし、その後Workatoにリダイレクトします。 コネクションが成功すると、Workatoに確認メッセージが表示されます。
ランタイムユーザーコネクションのフィールドを設定する
エンドユーザーはMCP検証済みユーザーアクセスを通じて認証します。 その後、Workatoはランタイムユーザーコネクションを作成し、設定したソースコネクションから設定をコピーします。 control_type: 'password'を使用するフィールドは、デフォルトではランタイムユーザーコネクションにコピーされません。 これにより、APIシークレットなど、各エンドユーザーのコネクションのコピー全体で共有すべきでない認証情報が保護されます。
OAuth 2.0トークン交換用の共有client_secretなど、各ランタイムユーザーコネクションで同じパスワードフィールド値が必要な場合は、その値を明示的に保持する必要があります。 Workatoによる値のコピー方法を制御するには、フィールド定義にpreserve_in_runtime_connectionを設定します:
| 値 | 動作 |
|---|---|
true | control_type: 'password'を使用している場合でも、このフィールドの値を常にランタイムコネクションにコピーします。 |
false | 深さやネストに関係なく、このフィールドの値をランタイムコネクションにコピーしません。 |
nil（デフォルト、省略） | デフォルトの動作: パスワードフィールドは削除され、その他すべてのフィールドはコピーされます。 |
例:
{
name: 'client_secret',
label: 'Client secret',
control_type: 'password',
optional: false,
preserve_in_runtime_connection: true
}パスワードフィールドにpreserve_in_runtime_connection: trueを設定する前に確認してください
すべてのエンドユーザーがランタイムユーザーコネクションでその値を必要とする場合にのみ、パスワードフィールドにpreserve_in_runtime_connection: trueを設定します。 共有シークレットをすべてのランタイムユーザーコネクションにコピーすると、1つのランタイムコネクションが侵害された場合の漏えいリスクが増加します。
アクションを作成する
SWAPIでは、人物、惑星、映画など、Star Warsに関する情報を取得できます。 この例では、Star Warsキャラクターに関する情報を取得するGet person by IDという名前のアクションを構築する方法を説明します。 返された情報には、後続のレシピステップでデータピルを使用してアクセスし、利用できます。
Get person by IDアクションを作成
アクションを作成するには、次の手順を完了します。
ソースコードタブの既存のコードを次のスニペットに置き換えます:
{
title: 'Star Wars Information',
connection: {
fields: [
{
name: "object",
hint: "Enter the object you plan to use to test your connection.",
}
]
},
test: lambda do |connection|
get("https://swapi.tech/api/#{connection["object"]}")
end,
actions: {
get_person_by_id: {
input_fields: lambda do
[{
name: 'id',
label: 'Person ID',
type: 'integer',
default: '1',
optional: false
}]
end,
execute: lambda do | connection, input |
get("https://swapi.tech/api/people/#{input["id"]}")
end,
output_fields: lambda do
[{
name: "message",
label: "Message",
type: "string"
},
{
name: "result",
label: "Result",
type: "object",
properties: [{
name: "properties",
label: "Properties",
type: "object",
properties: [{
name: "height",
label: "Height",
type: "string"
},
{
name: "mass",
label: "Mass",
type: "string"
},
{
name: "hair_color",
label: "Hair color",
type: "string"
},
{
name: "skin_color",
label: "Skin color",
type: "string"
},
{
name: "eye_color",
label: "Eye color",
type: "string"
},
{
name: "birth_year",
label: "Birth year",
type: "string"
},
{
name: "gender",
label: "Gender",
type: "string"
},
{
name: "created",
label: "Date created",
type: "date_time"
},
{
name: "edited",
label: "Date edited",
type: "date_time"
},
{
name: "name",
label: "Person name",
type: "string"
},
{
name: "homeworld",
label: "Homeworld",
type: "string"
},
{
name: "url",
label: "URL",
type: "string"
}
]
},
{
name: "description",
label: "Description",
type: "string"
},
{
name: "_id",
type: "string"
},
{
name: "uid",
type: "string"
},
{
name: "__v",
type: "integer"
}
]
}
]
end,
},
}
}このコードスニペットはどのように機能しますか。
このコードスニペットには、次のキーが含まれています:
actions- 新しいアクションを宣言します。 インデントを使用して、コードを読みやすくします。
get_person_by_id- Get person by IDアクションを定義します。 アクション名はこのキーを継承し、アンダースコア（
_）をスペースに置き換えます。 キー名がアクションの目的を正確に反映していることを確認してください。 キー名にスペースを使用しないでください。 input_fields- レシピの構築時にユーザーがアクションを設定するときに表示される入力フィールドを宣言します。 この例には、
idという名前の入力フィールドが1つ含まれています。label変数はユーザーに表示される名前を定義し、typeはデータ型を指定します。optionalをfalseに設定すると、このフィールドは必須になります。
execute- HTTPリクエスト、ターゲットURL、およびレシピに必要な追加のアクションを宣言します。 プレースホルダー
#{input["id"]}は、ユーザーが指定したIDを動的に取得し、それをターゲットURLに追加してキャラクターの情報を取得します。 output_fields- アクションによって返されるデータピルを宣言します。 これらの出力フィールドは、
executeキーで指定されたGETリクエストによって返されるJSONオブジェクトと一致している必要があります。
ネストされた配列またはオブジェクトの定義方法
配列を定義するには、typeをarrayに設定します。 これにより、Workatoは複数の値のコレクションを想定します。 of属性を使用して、配列の項目のデータ型を指定します。 たとえば、URLを含む配列の場合はofをstringに設定します。
アクションをテストする
アクションをテストするには、次の手順を完了します:
テストコードタブに移動します。
Get person by IDアクションを選択します。
Get person by IDアクションを選択
情報を取得するStar WarsキャラクターのIDをPerson IDフィールドに入力します。 たとえば、Luke Skywalkerに関する情報を取得するには1と入力します。
Person IDフィールドに入力
アクションをテストをクリックします。 最近のテストタブが開きます。
出力タブをクリックして、Get person by IDアクションの出力を表示します。 次のスクリーンショットは、テストが成功した状態を示しています:
出力を表示
テストが成功した場合、レシピの実行中にエラーが発生しなかったことを示します。 ただし、ロジックエラーなど、その他の問題の可能性がないことを保証するものではありません。
カスタムコネクターをレシピで使用する
これで、作成したSWAPIコネクターとアクションを任意のレシピで使用できます。 開始するには、アプリケーションを選択するときにSWAPIコネクターを検索します。
Star Wars Informationコネクターを選択
最終更新日: