コネクション

コネクションリソースを使用すると、Embedded顧客のコネクションをプログラムで管理できます。

エンドポイントの利用可否

このガイドのエンドポイントはEmbedded APIであり、Embeddedワークスペースが必要です。詳細については、Workato担当者にお問い合わせください。

レート制限

コネクションリソースには、次のレート制限があります:

タイプ	リソース	制限
GET	コネクションを一覧表示: /api/managed_users/:managed_user_id /connections	1分あたり1,000リクエスト
すべて	その他すべてのコネクションエンドポイント	1分あたり60リクエスト

クイックリファレンス

タイプ	リソース	説明
GET	/api/managed_users/:managed_user_id/connections /:adapter_name/input_schema	コネクションの入力に基づいて入力スキーマを返します。
GET	/api/managed_users/:managed_user_id/connections	Embeddedユーザーのアカウントにあるコネクションのリストを返します。
POST	/api/managed_users/:id/connections	Embeddedパートナーが顧客のアカウントにシェルコネクションを追加できるようにします。
PUT	/api/managed_users/:id/connections/:connection_id	顧客ワークスペース内のコネクションを更新します。
POST	/api/managed_users/:id/connections/:connection_id/disconnect	顧客ワークスペース内のコネクションを切断します。
DELETE	/api/managed_users/:id/connections/:connection_id	顧客ワークスペース内のコネクションを削除します。

コネクションエンドポイントを取得

コネクションの入力に基づいて入力スキーマを返します。コネクションの入力によって有効になるextended_settings_schemaの一部である基本入力スキーマの両方を返します。このエンドポイントはWorkatoのコネクションレベルで動作します。

shell

GET /api/managed_users/:managed_user_id/connections/:connection_id/input_schema

get connectorエンドポイントの詳細については、Get connector endpointを参照してください。

URLパラメーター

名前	タイプ	説明
managed_user_id	string 必須	Embedded顧客のアカウントIDまたはExternal ID。 External IDにはプレフィックス'E'を付け、URLエンコードする必要があります。例: 'EA2300'。
connection_id	string 必須	基本入力スキーマを取得する予定のコネクションID。

サンプルリクエスト

shell

curl  -X GET https://www.workato.com/api/managed_users/97/connections/1987654/input_schema \
      -H 'Authorization: Bearer <api_token>'

レスポンス

JSON

{
  "result": [
    {
      "control_type": "text",
      "label": "Api key",
      "disable_formula": true,
      "optional": false,
      "type": "string",
      "name": "apiKey"
    }
  ]
}

コネクションのリスト表示

Embedded顧客ワークスペースのすべてのコネクションと関連データを返します。

shell

GET /api/managed_users/:managed_user_id/connections

URLパラメータ

名前	タイプ	説明
managed_user_id	string 必須	Embedded顧客ID/外部ID。外部IDには`E`をプレフィックスとして付ける必要があり（例: `EA2300`）、生成されたIDはURLエンコードする必要があります。

クエリパラメーター

名前	タイプ	説明
provider	string 任意	コネクションのアプリケーションタイプ。例: `salesforce`
folder_id	string 任意	コネクションを含むプロジェクトまたはフォルダのID。
parent_id	string 任意	親コネクションのID。親コネクションは同じ`provider`タイプである必要があります。詳細。
project_id	string 任意	コネクションを含むプロジェクトのID。
external_id	string 任意	コネクションに割り当てられた外部ID。通常はコネクションを所有するユーザーに付与されます。
include_runtime_connections	string 任意	`"true"`を指定すると、すべてのランタイムユーザーコネクションも返されます。
includes[]	array of strings optional	レスポンスに含める追加フィールドを指定します。値として`tags`を受け入れます。リクエストで`tags`を指定すると、レスポンスには各コネクションの`tags`フィールドが含まれます。このフィールドには、0個以上のタグハンドル（文字列）の配列が含まれます。
updated_after	string 任意	指定した日時より後に更新されたコネクションのみを含むよう、コネクションのリストをフィルタリングします。日時は、次のパターンに従ってISO 8601形式で指定する必要があります: `YYYY-MM-DDTHH:MM:SSZ`。

サンプルリクエスト

shell

curl  -X GET https://www.workato.com/api/managed_users/98178/connections?includes[]=tags \
      -H 'Authorization: Bearer <api_token>'

レスポンス

json

{
 "result": [
   {
     "id": 36,
     "name": "ACME Production Salesforce connection",
     "provider": "salesforce",
     "authorized_at": "2015-05-26T22:53:52.528Z",
     "authorization_status": "success",
     "authorization_error": null,
     "created_at": "2015-05-26T22:53:52.532Z",
     "updated_at": "2015-05-26T22:53:52.532Z",
     "external_id": "U12904",
     "folder_id": 4515,
     "identity": null,
     "connection_lost_at": null,
     "connection_lost_reason": null,
     "parent_id": 22316,
     "project_id": 12314295,
     "on_prem_group_id": null,
     "tags": [
        "tag-ANgeffPL-3gxQwA"
      ]
   },
   {
     "id": 37,
     "name": "ACME google sheet account",
     "provider": "google_sheets",
     "authorized_at": "2015-05-26T22:53:52.528Z",
     "authorization_status": "success",
     "authorization_error": null,
     "created_at": "2015-05-26T22:53:52.532Z",
     "updated_at": "2015-05-26T22:53:52.532Z",
     "external_id": "U12904",
     "folder_id": 4515,
     "identity": null,
     "connection_lost_at": "2024-06-01T12:00:00Z",
     "connection_lost_reason": "network_failure",
     "parent_id": 22317,
     "project_id": 12314296,
     "on_prem_group_id": null,
     "tags": null
   },
   {
     "id": 51234,
     "name": "ACME Quickbooks account",
     "provider": "quickbooks",
     "authorized_at": "2015-05-26T22:53:52.528Z",
     "authorization_status": "success",
     "authorization_error": null,
     "created_at": "2015-05-26T22:53:52.532Z",
     "updated_at": "2015-05-26T22:53:52.532Z",
     "external_id": "U12904",
     "folder_id": 4515,
     "identity": "[email protected]/1029384756102938",
     "connection_lost_at": null,
     "connection_lost_reason": null,
     "parent_id": 22317,
     "project_id": 12314297,
     "on_prem_group_id": null,
     "tags": [
        "tag-ANgeffPL-3gxQwA"
      ]
   },
   {
     "id": 38,
     "name": "ACME on-prem files connection",
     "provider": "onprem_files",
     "authorized_at": "2015-05-26T22:53:52.528Z",
     "authorization_status": "success",
     "authorization_error": null,
     "created_at": "2015-05-26T22:53:52.532Z",
     "updated_at": "2015-05-26T22:53:52.532Z",
     "external_id": "U12904",
     "folder_id": 4515,
     "identity": null,
     "connection_lost_at": null,
     "connection_lost_reason": null,
     "parent_id": null,
     "project_id": 12314298,
     "on_prem_group_id": 16803,
     "tags": null
   }
 ]
}

QUICKBOOKS REALM IDの取得

コネクションのリスト表示APIを使用して、会社のQuickbooks Realm IDを取得します。最新情報が取得されるように、APIを呼び出す前にWorkatoでQuickbooksコネクションを切断して再接続します。 APIは、レスポンスのidentityフィールドで、メールアドレスに続いてRealm IDを返します。前述の例では、ACMEのRealm IDは1029384756102938です。その他のコネクションの場合、identityフィールドはnullとして返されます。

identityフィールドの設定に関する詳細については、SDK identity lambdaドキュメントを参照してください。 lambdaの出力値は、コネクションのリスト表示APIのidentityフィールドに返されます。

コネクションを作成

顧客のアカウントにコネクションを作成します。このエンドポイントは、顧客ワークスペースで次をサポートしています:

シェルコネクションの追加、または
コネクションの追加および認証

OAuthコネクション

Workato APIでは、OAuth 2.0コネクションを作成できます。ただし、oauthやoauth2_auth_code_grantなど、通常はサインイン画面にリダイレクトされるコネクションタイプには、アクセストークンとリフレッシュトークンを含むoauth_token_pairオブジェクトが必要です。クライアント資格情報グラントコネクションには、oauth_token_pairオブジェクトは必要ありません。アクセストークンとリフレッシュトークンがない場合は、シェルコネクションを作成できます。

詳細については、コネクションパラメータリファレンスページを参照してください。

shell

POST /api/managed_users/:managed_user_id/connections

URLパラメータ

名前	タイプ	説明
managed_user_id	string 必須	Embedded顧客ID/外部ID。外部IDには`E`をプレフィックスとして付ける必要があり（例: `EA2300`）、生成されたIDはURLエンコードする必要があります。

ペイロード

名前	タイプ	説明
name	string 任意	コネクションの名前。例: `Prod Salesforce connection`
provider	string 任意	コネクションのアプリケーションタイプ。例: `salesforce`
parent_id	string 任意	親コネクションのID。親コネクションは同じ`provider`タイプである必要があります。詳細。
folder_id	string 必須	コネクションを含むプロジェクトまたはフォルダのID。
external_id	string 任意	コネクションに割り当てられた外部ID。通常はコネクションを所有するユーザーに付与されます。
on_prem_group_id	integer optional	このコネクションに関連付けるオンプレミスグループのID。グループIDはオンプレミスグループの一覧エンドポイントから取得できます。
shell_connection	boolean optional	コネクションがシェルコネクションか認証済みコネクションかを指定します。指定しない場合、デフォルトは`false`です。 `shell_connection`が`false`の場合、資格情報が渡され、コネクションがテストおよび確立されます。 `shell_connection`が`true`の場合、資格情報は渡されますが、コネクションはテストまたは確立されず、認証には追加のアクションが必要です。
input	オブジェクト任意	コネクションパラメータ。プロバイダーとコネクションパラメータのリストについては、プラットフォームAPIコネクションパラメータリファレンスを参照してください。

2026年05月07日以降、FOLDER_IDが必須

2026年05月07日以降、このエンドポイントではfolder_idパラメータが必須です。値は、Home assetsフォルダ以外のプロジェクトまたはフォルダを参照する必要があります。 folder_idを省略したリクエスト、またはHome assetsフォルダをターゲットとするリクエストは、エラーを返します。

シェルコネクションリクエスト

これにより、Disconnected状態のコネクションが作成されます。

shell

curl  -X POST https://www.workato.com/api/managed_users/98178/connections \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d  '{
            "name": "jira_connection",
            "provider": "jira",
            "folder_id": 1892,
            "external_id": "128904"
          }'

資格情報を含むコネクション

これにより、コネクションが作成され認証されます。

shell

curl  -X POST https://www.workato.com/api/managed_users/98178/connections \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d  '{
            "name": "jira_connection",
            "provider": "jira",
            "folder_id": 1892,
            "input": {
              "host_name": "acme.atlassian.net",
              "api_token_auth": "true",
              "email": "[email protected]",
              "apitoken": "XXXXXXXX"
            }
          }'

オンプレミスコネクション

これにより、オンプレミスグループに関連付けられたコネクションが作成されます。

shell

curl  -X POST https://www.workato.com/api/managed_users/98178/connections \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d  '{
            "name": "On-prem SQL Server",
            "provider": "sql",
            "folder_id": 1892,
            "on_prem_group_id": 16803,
            "input": {
              "host": "192.0.2.10",
              "port": "1433",
              "database": "production_db",
              "username": "svc_workato"
            }
          }'

レスポンス

json

{
   "id":36,
   "name":"jira_connection",
   "provider":"jira",
   "authorized_at":"2015-05-26T22:53:52.528Z",
   "authorization_status":"success",
   "authorization_error":null,
   "created_at":"2015-05-26T22:53:52.532Z",
   "updated_at":"2015-05-26T22:53:52.532Z",
   "external_id":"U12904",
   "folder_id":1892,
   "parent_id":22318,
   "connection_lost_at": null,
   "connection_lost_reason": null,
   "on_prem_group_id": null
}

コネクションを更新

顧客ワークスペース内のコネクションを更新します。

shell

PUT /api/managed_users/:managed_user_id/connections/:connection_id

URLパラメータ

名前	タイプ	説明
managed_user_id	string 必須	Embedded顧客ID/外部ID。外部IDには`E`をプレフィックスとして付ける必要があり（例: `EA2300`）、生成されたIDはURLエンコードする必要があります。
connection_id	string 必須	コネクションのID。

ペイロード

名前	タイプ	説明
name	string 任意	コネクションの名前。例: `Prod Salesforce connection`
parent_id	string 任意	親コネクションのID。詳細。
folder_id	string 任意	コネクションを含むプロジェクトまたはフォルダのID。
external_id	string 任意	コネクションに割り当てられた外部ID。この値は、別のアプリケーション内のレコードを参照できます。
on_prem_group_id	integer optional	このコネクションに関連付けるオンプレミスグループのID。 `null`に設定すると、オンプレミスグループの関連付けが削除されます。グループIDはオンプレミスグループの一覧エンドポイントから取得できます。
shell_connection	boolean optional	コネクションがシェルコネクションか認証済みコネクションかを指定します。指定しない場合、デフォルトは`false`です。 `shell_connection`が`false`の場合、資格情報が渡され、コネクションがテストおよび確立されます。 `shell_connection`が`true`の場合、資格情報は渡されますが、コネクションはテストまたは確立されず、認証には追加のアクションが必要です。
input	object optional	コネクションパラメータ。プロバイダーとコネクションパラメータのリストについては、プラットフォームAPIコネクションパラメータリファレンスを参照してください。

サンプルリクエスト

Jiraコネクションを更新
Outreachコネクションを更新

Jiraコネクションを更新

shell

curl  -X PUT https://www.workato.com/api/managed_users/98178/connections/1678 \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d  '{
            "name": "jira_connection_latest",
            "folder_id": 28940,
            "input": {
              "host_name": "acme.atlassian.net",
              "api_token_auth": "true",
              "email": "[email protected]",
              "apitoken": "XXXXXXXX"
            }
          }'

レスポンス

json

{
   "id":36,
   "name":"jira_connection",
   "provider":"jira",
   "authorized_at":"2015-05-26T22:53:52.528Z",
   "authorization_status":"success",
   "authorization_error":null,
   "created_at":"2015-05-26T22:53:52.532Z",
   "updated_at":"2015-05-26T22:53:52.532Z",
   "external_id":"U12904",
   "folder_id":4515,
   "parent_id":22318,
   "connection_lost_at": null,
   "connection_lost_reason": null,
   "on_prem_group_id": null
}

Outreachコネクションを更新

shell

curl  -X PUT https://www.workato.com/api/managed_users/98178/connections/1678 \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d  '{
            "name": "Outreach scope connection",
            "provider": "outreach",
            "input": {
              "advanced_settings": {
                "scopes": "sequences.all phoneNumbers.all"
              }
        }
    }'

コネクションを切断

顧客ワークスペース内のアクティブなコネクションを切断します。コネクションがすでに切断されている場合、アクションは実行されません。

shell

POST /api/managed_users/:managed_user_id/connections/:connection_id/disconnect

URLパラメータ

名前	タイプ	説明
managed_user_id	string 必須	Embedded顧客ID/外部ID。外部IDには`E`をプレフィックスとして付ける必要があり（例: `EA2300`）、生成されたIDはURLエンコードする必要があります。
connection_id	string 必須	コネクションのID。
force	boolean optional	アクティブなレシピで使用されているアクティブなコネクションを強制的に切断するには、値を`true`にする必要があります。デフォルトは`false`です。

ペイロード

ペイロードは想定されていません

サンプルリクエスト

shell

curl  -X POST https://www.workato.com/api/managed_users/98178/connections/1678/disconnect?force=true \
      -H 'Authorization: Bearer <api_token>'

レスポンス

アクティブなコネクション、またはすでに切断されているコネクションが正常に切断されました。

json

{
   "result": {
    "success": true,
    "status": "disconnected"
   }
}

指定されたコネクションIDは存在しません

json

{
   "message": "Not found"
}

コネクションを削除

顧客ワークスペース内のコネクションを削除します。このメソッドは、アクティブ（認証済み）および切断済みのコネクションを削除します。コネクションがアクティブなレシピで使用されている場合、このAPIリクエストは失敗します。

shell

DELETE /api/managed_users/:managed_user_id/connections/:connection_id

URLパラメータ

名前	タイプ	説明
managed_user_id	string 必須	Embedded顧客ID/外部ID。外部IDには`E`をプレフィックスとして付ける必要があり（例: `EA2300`）、生成されたIDはURLエンコードする必要があります。
connection_id	string 必須	コネクションのID。

サンプルリクエスト

shell

curl  -X DELETE https://www.workato.com/api/managed_users/98178/connections/1678 \
      -H 'Authorization: Bearer <api_token>'

レスポンス

アクティブまたは切断済みコネクションの正常な削除
コネクションがアクティブなレシピで使用されています
コネクションIDが存在しません

アクティブまたは切断済みコネクションの正常な削除

アクティブ（認証済み）または切断済みのコネクションを正常に削除すると、このエンドポイントは次のレスポンスを返します:

json

{
    "result": {
        "success": true,
        "status": "deleted"
    }
}

コネクションがアクティブなレシピで使用されています

アクティブなレシピで使用されているコネクションを削除しようとすると、このリクエストは失敗し、エンドポイントは次のレスポンスを返します:

json

{
   "success": false,
   "status": "rejected",
   "message": "You can't delete a connection used by active recipes"
}

コネクションIDが存在しません

顧客のワークスペースに存在しないコネクションIDを指定すると、このリクエストは失敗し、エンドポイントは次のレスポンスを返します:

json

{
   "message": "Not found"
}

Last updated:

コネクション ​

レート制限 ​

クイックリファレンス ​

コネクションエンドポイントを取得 ​

URLパラメーター ​

サンプルリクエスト ​

レスポンス ​

コネクションのリスト表示 ​

URLパラメータ ​

クエリパラメーター ​

サンプルリクエスト ​

レスポンス ​

コネクションを作成 ​

URLパラメータ ​

ペイロード ​

サンプルリクエスト ​

シェルコネクションリクエスト ​

資格情報を含むコネクション ​

オンプレミスコネクション ​

レスポンス ​

コネクションを更新 ​

URLパラメータ ​

ペイロード ​

サンプルリクエスト ​

Jiraコネクションを更新 ​

レスポンス ​

Outreachコネクションを更新 ​

コネクションを切断 ​

URLパラメータ ​

ペイロード ​

サンプルリクエスト ​

レスポンス ​

コネクションを削除 ​

URLパラメータ ​

サンプルリクエスト ​

レスポンス ​

アクティブまたは切断済みコネクションの正常な削除 ​

コネクションがアクティブなレシピで使用されています ​

コネクションIDが存在しません ​

コネクション

レート制限

クイックリファレンス

コネクションエンドポイントを取得

URLパラメーター

サンプルリクエスト

レスポンス

コネクションのリスト表示

URLパラメータ

クエリパラメーター

サンプルリクエスト

レスポンス

コネクションを作成

URLパラメータ

ペイロード

サンプルリクエスト

シェルコネクションリクエスト

資格情報を含むコネクション

オンプレミスコネクション

レスポンス

コネクションを更新

URLパラメータ

ペイロード

サンプルリクエスト

Jiraコネクションを更新

レスポンス

Outreachコネクションを更新

コネクションを切断

URLパラメータ

ペイロード

サンプルリクエスト

レスポンス

コネクションを削除

URLパラメータ

サンプルリクエスト

レスポンス

アクティブまたは切断済みコネクションの正常な削除

コネクションがアクティブなレシピで使用されています

コネクションIDが存在しません