# How to ガイド - オブジェクトの作成

ここでは、ターゲットアプリケーション内でオブジェクトを作成するためのアクションの作成について説明します。基本的には、POST HTTP リクエストメソッドを利用して、オブジェクト作成のリクエストを送信することが一般的です。

# サンプルコネクター - Zuora

{
  title: 'My Zuora connector',

  # More connector code here
  actions: {
    create_account: {
      title: 'Create account',

      subtitle: "Creates an account in Zuora",

      description: lambda do |input, picklist_label|
        "Create <span class='provider'>account</span> in " \
        "<span class='provider'>Zuora</span>"
      end,

      help: "Creates a new account in Zuora",

      input_fields: lambda do |object_definitions|
        [
          {
            name: "AccountNumber",
            label: "Account Number",
            hint: "Unique account number assigned to the account. " \ 
            "Leave null to auto-generate."
          },
          {
            name: "AccountName",
            label: "Account name",
            hint: "The name of newly created account."
          },
          {
            name: "Currency",
            label: "Currency",
            hint: "Currency that the customer is billed in.",
            optional: false
          }
        ]
      end,

      execute: lambda do |connection, input|
        post("https://rest.zuora.com/v1/object/account", input).
          after_error_response(/.*/) do |_, body, _, message|
            error("#{message}: #{body}")
          end
      end,

      output_fields: lambda do |object_definitions|
        [
          { name: "Success", type: "boolean", control_type: "checkbox" },
          { name: "Id" },
          {
            name: "Errors",
            type: "array",
            of: "object",
            properties: [{ name: "Code" }, { name: "Message" }]
          }
        ]
      end,

      sample_output: lambda do |connection, input|
        {
          "success" => "true",
          "Id" => "107bb8280175668b1f47e51710214497"
        }
      end
    }
  }
  # More connector code here
}

アカウント作成アクションの選択 アカウント作成アクションの選択

# ステップ1 - アクションのタイトル、サブタイトル、説明、ヘルプ

優れたアクションの作成に向けた最初のステップは、そのアクションが何をどのように実行するかを適切に伝え、さらにユーザーに追加のヘルプを提供することです。そのために Workato では、アクションのタイトルと説明を定義したり、ヒントを提供したりできるようにしています。簡単に言えば、タイトルはアクションの名称であり、サブタイトルはそのアクションのより詳しい内容を表します。続いて、アクションの説明は、接続先となるアプリケーションにおいてそのアクションがどのようなことを達成するかについて、仕様や解説を提供します。最後に、ヘルプのセグメントは、アクションをうまく機能させるために必要な追加情報をユーザーに提供します。

このステップの詳細については、Workato の SDK リファレンスを参照してください。

# ステップ2 - 入力項目の定義

  input_fields: lambda do |object_definitions|
    [
      {
        name: "AccountNumber",
        label: "Account Number",
        hint: "Unique account number assigned to the account. " \
        "Leave null to auto-generate."
      },
      {
        name: "AccountName",
        label: "Account name",
        hint: "The name of newly created account."
      },
      {
        name: "Currency",
        label: "Currency",
        hint: "Currency that the customer is billed in.",
        optional: false
      }
    ]
  end

Create account の入力項目 Create account の入力項目

この部分では、オブジェクトの作成を試みるユーザーに向けて表示すべき項目を Workato に指示します。たとえば Zuora のアカウントを作成する場合、ユーザーは作成する新しいアカウントの AccountNumber (アカウント番号)、AccountName (アカウント名)、および Currency (通貨) を入力する必要があります。入力項目 Currency に関して、"optional" キーに false の値が割り当てられていることに注意してください。これは、ユーザーはカスタマーに請求する通貨の値を指定する必要があることを意味しています。指定していない場合、ユーザーはレシピの作成を進めることができません。

入力/出力項目に関しては、上記で定義したもの以外にも、さまざまなキーと値のペアが存在します。詳細については、こちらを参照してください。

オブジェクトの定義

引数として object_definitions が渡されていることに注意してください。Workato では、コネクターの作成者が "object_definitions" キー内でオブジェクトの定義を独立して記述できるようになっています。このキーは、オブジェクトの定義が長大である場合や、定義が動的に取得される場合に使用されます。

この詳細については、Workato の SDK リファレンスを参照してください。

# ステップ3 - execute キーの定義

execute キーでは、リクエスト送信先となるエンドポイントと、使用する HTTP リクエストメソッドを Workato に指示します。この例では、POST メソッドを使用してリクエストを https://rest.zuora.com/v1/object/account に送信しています。また、リクエストに after_error_response メソッドを付け足すことで、エラーを捕捉してユーザーに表示し、レシピ作成時のデバッグを支援しています。

  execute: lambda do |connection, input|
    post("https://rest.zuora.com/v1/object/account", input).
      after_error_response(/.*/) do |_, body, _, message|
        error("#{message}: #{body}")
      end
  end

Create account のエラー エラーの例

execute キーの詳細については、Workato の SDK リファレンスを参照してください。

# ステップ4 - 出力項目の定義

このセクションでは、トリガーの出力として表示するデータピルを指示します。各データピルの name 属性は、execute キーの出力に含まれるキーに一致している必要があります。

  output_fields: lambda do |object_definitions|
    [
      { name: "Success", type: "boolean", control_type: "checkbox" },
      { name: "Id" },
      {
        name: "Errors",
        type: "array",
        of: "object",
        properties: [{ name: "Code" }, { name: "Message" }]
      }
    ]
  end

Create account の出力項目 Create account の出力項目

出力項目キーの詳細については、Workato の SDK リファレンスを参照してください。

オブジェクトの定義

引数として object_definitions が渡されていることに注意してください。Workato では、コネクターの作成者が "object_definitions" キー内でオブジェクトの定義を独立して記述できるようになっています。このキーは、オブジェクトの定義が長大である場合や、定義が動的に取得される場合に使用されます。

この詳細については、Workato の SDK リファレンスを参照してください。

# ステップ5 - サンプル出力の定義

サンプル出力キーは、コネクターにとって補足的な要素ですが、一般的なデータ型や想定される出力項目の形式をユーザーに伝えることで、ユーザーエクスペリエンスを大幅に向上させます。これにより、ユーザーはより速やかにレシピを作成できるようになります。

  sample_output: lambda do |connection, input|
    {
      "success" => "true",
      "Id" => "107bb8280175668b1f47e51710214497"
    }
  end

サンプル出力キーの詳細については、Workato の SDK リファレンスを参照してください。


Last updated: 2023/8/31 1:07:14