コネクター構築 - オブジェクトのスキーマの定義

このページは機械翻訳により提供されています。翻訳内容と英語版に相違がある場合は、英語版が優先されます。

次のセクションでは、コネクターの整理方法に関する現時点での考え方を説明します。 この方法論と適切な計画により、オブジェクト定義とmethodsフィールドを使用してコードをDRYに保ちながら、コネクターで新しいオブジェクトのサポートを簡単に追加できます。 これらはすべて、Workatoのインテグレーション開発者が長年にわたって得た知見に基づくガイドラインであり、接続先のアプリケーションやAPIによって多少変わる場合があります。

これは、Workato SDKの機能(高度なトピックを含む)に関するこれまでのドキュメントをすべて読み、ターゲットアプリケーションへのコネクションをすでに定義および確立していることを前提としています。 まだ行っていない場合は、行うことを強くお勧めします。

データ形式

次の例では、JSONを受け入れるAPIに接続していることを前提としています。 ただし、同じアプローチは他のデータ形式を受け入れるAPIにも適用できます。

詳細に入る前に、コネクターコードをどのように整理できるかについて、大まかな概要を示します。

コネクターコードのマインドマップ

主な目的は、コネクターのユーザーが最初に次のような一連のアクションまたはトリガーから選択できるようにすることです:

  1. 新規/更新済みオブジェクト
  2. 新規オブジェクト
  3. オブジェクトの作成
  4. オブジェクトの更新
  5. オブジェクトの検索
  6. オブジェクトの削除

その後、ユーザーはアクションまたはトリガーの設定でオブジェクトを選択します。 ユーザーがオブジェクトを選択した後、コネクターは選択されたオブジェクトに関連する入力フィールドと出力フィールドを取得して表示する必要があります。 これは、ユーザーがconfig_fieldsに入力した内容に基づいて、適切なobject_definitionを呼び出すことで行います。 ユーザーがconfig_fieldに入力した内容は、input_fieldsラムダ関数に渡される引数で確認できます。

executeブロックでは、各動詞とオブジェクトのペア専用の単一メソッドを使用することをお勧めします。 これにより、その動詞とオブジェクトのアクションに固有の入力データの前処理と応答データの後処理に、コード内の専用セクションを用意できます。 after_error_responseまたはafter_responseメソッドなどの一般的なデータフォーマットは、executeブロックに直接含めることができます。

最終的に、これにより各動詞アクションとそれがサポートできるオブジェクトの責任を分離でき、新しいオブジェクトのサポートや既存のオブジェクトに対する動詞アクションをすばやく追加できます。

オブジェクトのスキーマの定義

アクションまたはトリガーのコードを書く前に、APIドキュメントを調べることをお勧めします。 多くの場合、特定のオブジェクトを扱うリクエストとレスポンスで想定されるペイロードは、非常によく似た構造を持っています。

これにより、同じスキーマ定義をさまざまなアクションで使用できる可能性があるため、コードの再利用に大きな相乗効果が生まれます。 たとえば、XYZ accountingの場合、同じ請求書スキーマ定義を“Create”、“Read”、“Update”、“Delete”、“Search”アクションに使用できます。 以下では、スキーマを定義するさまざまなパターンと、簡単に参照できるようにコネクターコード内のどこに配置するかについて説明します。

入力フィールドと出力フィールドのスキーマは、Workatoで動的または静的に決定できます。 詳細については、オブジェクト定義を参照してください。これは、コネクターを構築する対象のAPIでメタデータエンドポイントが利用可能かどうかに大きく依存します。 以下では、最初に例を通じてスキーマを手動で定義する方法を説明し、その後で動的に定義された入力スキーマの例を示します。

スキーマ定義

スキーマ定義は、オブジェクトのプロパティを設定します。 プロパティは、input_fieldsで使用されると入力フィールドとしてレンダリングされ、output_fieldsで使用されると後続のアクションで出力データピルとしてレンダリングされます。

これらのコードブロックには折りたたみ可能なセクションを使用することを検討してください。 非常に長いため、ドキュメント内を移動しにくくなります。

例1: 静的に定義されたスキーマ

XYZ labsへのコネクターを構築する開発者として、アプリケーション内の“Invoice”オブジェクトの表現は次のようになります:

json
  {
    "TxnDate": "2019-09-19",
    "ID": "1",
    "TotalAmt": 362.07,
    "Line": [
      {
        "Description": "Rock Fountain",
        "SalesItemLineDetail": {
          "Qty": 1,
          "UnitPrice": 275
        },
        "Line-Num": 1,
        "Amount": 275.0,
        "Id": "1"
      },
      {
        "Description": "Fountain Pump",
        "SalesItemLineDetail": {
          "Qty": 1,
          "UnitPrice": 12.75
        },
        "LineNum": 2,
        "Amount": 12.75,
        "Id": "2"
      }
    ],
    "DueDate": "2019-10-19",
    "DocNumber": "1037",
    "Deposit": 0,
    "Balance": 362.07,
    "CustomerRef": {
      "name": "Sonnenschein Family Store",
      "value": "24"
    },
    "BillEmail": {
      "Address": "[email protected]"
    },
    "BillAddr": {
      "Line1": "Russ Sonnenschein",
      "Long": "-122.1141681",
      "Lat": "37.4238562",
      "Id": "95"
    },
    "MetaData": {
      "CreateTime": "2014-09-19T13:16:17-07:00",
      "LastUpdatedTime": "2014-09-19T13:16:17-07:00"
    }
  }

“Invoice”作成アクションでは、次のようなPOSTリクエストが必要になる場合があります:

  POST /invoice/create
  Content type:application/json

  {
    "Line": [
      {
        "Description": "Fountain straws",
        "SalesItemLineDetail": {
          "Qty": 100,
          "UnitPrice": 0.075,
        },
        "Line-Num": 1,
        "Amount": 7.50,
        "Id": "192 "
      },
    ],
    "CustomerRef": {
      "value": "1"
    }
  }

“Invoice”更新アクションでは、次のようなPOSTが必要になる場合があります:

  POST /invoice/update
  Content type:application/json

  {
    "ID": "1",
    "Line": [
      {
        "Description": "Fountain straws",
        "SalesItemLineDetail": {
          "Qty": 100,
          "UnitPrice": 0.075,
        },
        "Line-Num": 1,
        "Amount": 7.50,
        "Id": "192 "
      },
    ],
    "CustomerRef": {
      "value": "1"
    }
  }

一般的な経験則として、Workatoでオブジェクトのスキーマを定義する場合、異なるアクション(請求書の作成アクションや請求書の更新アクションなど)間で、できるだけ多くを再利用できるようにします。 したがって、定義するスキーマは、この“Invoice”オブジェクトで考えられるすべてのパラメーターのスーパーセットである必要があります。 次のようなものになります:

ruby
  object_definitions: {
    invoice: lambda do |connection, config_fields|
      [
        { name: "Id" },
        { name: "TxnDate" },
        { name: "TotalAmt", type: "number" },
        {
          name: "Line",
          type: "array",
          of: "object",
          properties: [
            { name: "Description" },
            {
              name: "SalesItemLineDetail",
              type: "object",
              properties: [
                { name: "Qty", type: "number" },
                { name: "UnitPrice", type: "number" }
              ]
            },
            { name: "Line-Num", type: "number" },
            { name: "Amount", type: "number" },
            { name: "Id" }
          ]
        },
        { name: "Due-Date" },
        { name: "Doc Number" },
        { name: "Deposit", type: "number" },
        { name: "Balance", type: "number" },
        {
          name: "CustomerRef",
          type: "object",
          properties: [
            { name: "name" }
            { name: "value" }
          ]
        },
        {
          name: "BillEmail",
          type: "object",
          properties: [
            { name: "Address" }
          ]
        },
        {
          name: "BillAddr",
          type: "object",
          properties: [
            { name: "Line1" },
            { name: "Lon" },
            { name: "Lat" },
            { name: "Id" }
          ]
        },
        {
          name: "MetaData",
          type: "object",
          properties: [
            { name: "CreateTime", type: "date_time" },
            { name: "LastUpdatedTime", type: "date_time" }
          ]
        }
      ]
    end
  }

このスキーマは、invoiceというobject_definition内に含まれています。

たとえば、請求書IDがXYZ accountingによって自動生成される場合、請求書の作成時にユーザーがIDを定義できないようにする必要があるため、後で入力スキーマから簡単に削除できます。

例2: 動的に定義されたスキーマ

ほとんどの場合、入力フィールドと出力フィールドを手動で定義するのではなく、利用可能な場合は常にメタデータエンドポイントを使用して生成することを強くお勧めします。 これにより、ベースオブジェクトに新しいフィールドが追加された場合に必要となる機能強化の数を減らすことができ、アプリケーションがサポートしている場合はカスタムフィールドのサポートも追加できます。 この例では、“Contact”オブジェクトのプロパティを説明するメタデータエンドポイントがこちらにあるHubSpotを使用します。

このような場合、このエンドポイントにリクエストを行い、そのレスポンスを使用して、Workatoが理解できる形式で入力スキーマと出力スキーマを構築します。 以下は、HubSpotのメタデータエンドポイントからのサンプルレスポンスです。JSONオブジェクトの配列が返され、それぞれが“Contact”プロパティを表します。

js
[
  {
    "name": "example_property_name",
    "label": "Example Property Name",
    "description": "Example Description of the property",
    "groupName": "contactinformation",
    "type": "string",
    "fieldType": "text",
    "options": [
      // if property is a drop-down, all options are detailed here
    ],
    "deleted": false,
    "displayOrder": -1,
    "readOnlyValue": false,
    "readOnlyDefinition": false,
    "hidden": false,
    "mutableDefinitionNotDeletable": false,
    "favorited": false,
    "favoritedOrder": -1,
    "calculated": false,
    "externalOptions": false,
    "displayMode": "current_value",
    "formField": true
  },
  // More properties below
]

これを使用して、静的定義に関する先ほどの例と同じaction_type引数を受け取るcontact_schemaというメソッドを定義できます。

ruby
  object_definitions: {
    contact: lambda do |connection, config_fields|
      get('/properties/v1/contacts/properties').map do |property|
        field = {
          name: property['name'],
          label: property['label'],
          hint: property['description'],
          type: call('type_mapping', property['type']),
          control_type: call('control_type_mapping', property['fieldType'])
        }

        if %w[select multiselect].include?(field[:control_type])
          picklist = {
            pick_list: property['options'].
            map { |option| [option['label'], option['value']]  }
          }
          field = field.merge(picklist)
        end

        if %w[boolean select multiselect].include?(field[:control_type])
          togglefield = {
            toggle_hint: 'Select manually',
            toggle_field: {
              name: property['name'],
              label: property['label'],
              type: 'string',
              control_type: 'text',
              toggle_hint: 'Map datapill',
              hint: "Enter in a valid option"
            }
          }
          field = field.merge(togglefield)
        end

        field
      end
    end,
  },

methods: {
    type_mapping: lambda do |input|
      case input
      when 'datetime'
        'date_time'
      when 'number'
        'integer'
      when 'booleancheckbox'
        'boolean'
      when 'bool'
        'boolean'
      when 'enumeration'
        'string'
      else
        input
      end
    end,

    control_type_mapping: lambda do |input|
      case input
      when 'textarea'
        'text-area'
      when 'datetime'
        'date_time'
      when 'booleancheckbox'
        'checkbox'
      when 'bool'
        'checkbox'
      when 'enumeration'
        'select'
      when 'radio'
        'select'
      when 'checkbox'
        'multiselect'
      else
        input
      end
    end
  }

このメソッドでは、HubSpotからレスポンスを取得し、各プロパティについて、その値をWorkatoのスキーマ内の定義済みパラメーターにマッピングします。 また、HubSpotのデータ型(HubSpotではtypeおよびfieldTypeとして定義)を、Workatoのtypeおよびcontrol_typeにそれぞれマッピングする役割を持つtype_mappingcontrol_type_mappingという2つのサービスメソッドも作成しました。

もう1つ注意すべき点は、それらをサポートするcontrol_typesに対するピックリストとトグルフィールドの導入です。 一般に、ピックリストを文字列トグルフィールドと併用することを強くお勧めします。これにより、エンドユーザーは値を静的に選択するか、代わりにデータピルをマッピングできます。 使いやすさの向上に関する詳細は、後で説明します。

メタデータエンドポイント

Workatoでは、独自のAPIへのコネクターを構築する際にメタデータエンドポイントを使用することを強くお勧めします。 これは、カスタムフィールドを持つアプリケーションでは特に重要です。メタデータエンドポイントにより、ユーザーのインスタンスに固有の入力フィールドを生成できるためです。

アクションの構築

選択したベースオブジェクトのスキーマを構築する方法を学んだので、定義したばかりのこれらのメソッドを使用して、最初のアクションの構築を開始します。

Last updated: