Embedded API ​

WorkatoのEmbedded PartnerプラットフォームAPIを使用すると、パートナーは顧客およびレシピやコネクションを含むアセットをプログラムで作成および管理できます。

ベースURL ​

Embedded Partner APIは、顧客、レシピなどを操作するためのエンドポイントの集合です。 各エンドポイントには、オブジェクトへのbase URLとresource pathが含まれます。

エンドポイントのbase URLは、使用するデータセンターによって異なります。 Workatoの各データセンターのbase URLは次のとおりです:

USデータセンター

https://www.workato.com/api/

EUデータセンター

https://app.eu.workato.com/api/

JPデータセンター

https://app.jp.workato.com/api/

SGデータセンター

https://app.sg.workato.com/api/

AUデータセンター

https://app.au.workato.com/api/

ILデータセンター

https://app.il.workato.com/api/

CNデータセンター

https://app.workatoapp.cn/api/

KRデータセンター

https://app.kr.workato.com/api/

Environmentを使用したEmbedded API ​

Embedded APIを使用すると、Environmentをプログラムでプロビジョニングできます。 Embedded API構造では、顧客向けにEnvironment機能を使用する際に、各Environment（Development、テスト、プロダクション）を正確にターゲット指定することもできます。

Environment機能のプロビジョニングの詳細については、Embedded API Environmentを参照してください。

Environmentなしのアクセス ​

Embedded APIでは、顧客にEnvironmentがプロビジョニングされているかどうかに関係なく、顧客を操作できます。 Environmentがプロビジョニングされていない顧客を操作するには、managed_user_idをエンドポイント/api/managed_users/:managed_user_idに直接追加する必要があります。

ターゲット指定Environmentアクセス ​

Environmentがプロビジョニングされている顧客を操作する場合、APIによりDevelopment、テスト、プロダクションEnvironmentへのターゲット指定アクセスが可能になります。 Environment要件に基づいて、次のエンドポイントを使用します:

• Development: /api/managed_users/:managed_user_id_devを使用してDevelopment Environmentにアクセスします
• テスト: /api/managed_users/:managed_user_id_testを使用してテストEnvironmentにアクセスします
• プロダクション: /api/managed_users/:managed_user_id_prodを使用してプロダクションEnvironmentにアクセスします

正しいEnvironmentをターゲット指定する方法については、WorkatoドキュメントのEmbedded Environment APIセクションを参照してください。

認証 ​

APIに認証するには、APIクライアントを作成する必要があります。 詳細を見る。

APIトークンをbearerトークンとして指定する ​

APIクライアントのAPIトークンを、リクエストヘッダーでbearerトークンとして指定します。

curl -X GET 'https://www.workato.com/api/managed_users/19029/properties' \
      -H 'Authorization: Bearer <api_token>'

サポートされている形式 ​

APIに送信するリクエストには、ヘッダーにContent-type: application/jsonを含める必要があります:

curl  -X GET 'https://www.workato.com/api/managed_users/19029/properties?prefix=salesforce_sync.' \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \

レスポンスはapplication/json; charset=utf-8を使用してエンコードされます。

HTTPレスポンスコード ​

• 200 成功
• 400 不正なリクエスト
• 401 未認証
• 403 禁止
• 404 見つかりません
• 500 サーバーエラー

200 成功 ​

200 Successレスポンスは、リクエストがサーバーによって正常に処理されたことを示します。 レスポンス本文は、実行されたエンドポイントとオペレーションによって異なりますが、通常はリクエストされたデータ、または実行されたアクションの確認が含まれます。

サンプル応答 ​

{
    "success": true
}

400 Bad Request ​

400 Bad Requestエラーは、クライアント側の問題によりサーバーがリクエストを処理できなかったことを示します。 一般的な原因には、不正な形式のリクエスト、無効なフィールド、サポートされていないデータ型などのフィールド制約違反が含まれます。

サンプル応答 ​

{
    "errors": [
        {
            "code": 400,
            "title": "No workspaces found matching the specified workspace filter conditions."
        }
    ]
}

401 Unauthorized ​

401 Unauthorizedエラーは、リクエストに有効な認証資格情報がない場合に返されます。 一般的な原因には、トークンの欠落、無効なトークン、または誤った資格情報が含まれます。

サンプル応答 ​

{
    "errors": [
        {
            "code": 401,
            "title": "未認証"
        }
    ]
}

403 禁止 ​

403 Forbiddenエラーは、クライアントは認証されているものの、リクエストされたリソースにアクセスするために必要な権限がないことを示します。

サンプル応答 ​

{
    "errors": [
        {
            "code": 403,
            "title": "禁止"
        }
    ]
}

404 Not Found ​

404 Not Foundエラーは、リクエストされたリソースが存在しない場合、または見つからない場合に返されます。 これは、URLが正しくない場合、またはリソースが削除されている場合に発生することがあります。

サンプル応答 ​

{
    "errors": [
        {
            "code": 404,
            "title": "見つかりません"
        }
    ]
}

500 サーバーエラー ​

500 Server Errorコードは、サーバーが予期しない状況に遭遇し、リクエストを完了できなかったことを示します。 このエラーは通常、サーバー側の問題が原因で発生します。

サンプル応答 ​

{
    "errors": [
        {
            "code": 500,
            "title": "サーバーエラー",
            "detail": "3188c2d0-29a4-4080-908e-582e7ed82580"
        }
    ]
}

x-correlation-idの使用 ​

Embedded APIでx-correlation-idを使用すると、リクエストを追跡して関連付けることができます。 これにより、デバッグ、トレーサビリティ、およびロギングが向上します。

リクエストヘッダーに独自のx-correlation-idを指定することも、Workatoに生成させることもできます。 独自のx-correlation-idを指定すると、応答には指定したx-correlation-idとWorkatoからのx-correlation-idの両方が含まれます。