コネクターのウォークスルー

この章では、手始めに、ほとんどの人が認識できるコンテンツである、 スターウォーズ への簡単なコネクターを作成します。使用する API は無料であり、スターウォーズのキャラクターや乗り物などの情報にアクセスすることができます。わかりやすくするために、この API を SWAPI と呼ぶことにします。 SWAPI については、こちらをご覧ください。 (opens new window)

このウォークスルーでは、Workato のソフトウェア開発キット (SDK) を使用してカスタムコネクターを作成し、この API から情報を取得する方法と、作成したカスタムコネクターをレシピの作成時に使用する方法について説明します。

今回のウォークスルー用に作成された完全なカスタムコネクターについては、こちら (opens new window)を参照してください。コネクターコードを確認するには、コネクターをインストールするための有効な Workato アカウントが必要になります。

はじめに

新しいカスタムコネクターを作成するには、Tools > Connector SDK にあるコネクター SDK ページに移動する必要があります。

Workato の最上位のナビゲーションバーに配置されている

以下のページでは、右上隅にコネクターを作成するボタンがあります。ボタンをクリックすると、新しいカスタムコネクター用のホームページが表示されます。

カスタムコネクターの名前を入力する

この例では、カスタムコネクターに Star Wars information という名前を付けました。スターウォーズの情報を返すコネクターですからね。また、このコネクターを使用するレシピに表示される、かっこいい Star Wars ロゴも追加しました。この後、以下のコードエディター内にスケルトンコードがあれば削除します。

新しいカスタムコネクターには、適切な名前、説明、ロゴを必ず指定してください。レシピの作成時、アプリの検索バーに表示される多くのコネクターから目的のコネクターを見つけるときは、コネクターの名前を使用します。

接続の確立

API に接続するときは、最初に、特定の API が必要とする認証メソッドを見つける必要があります。認証は、アプリケーションがユーザーに情報を送信する前に、ユーザーの本人確認をするために使用するプロセスです。これは、ユーザー名とパスワードを設定し、本人確認を強制することでソーシャルメディアアカウントを保護することと同じです。API の認証タイプには、基本認証や OAuth 2.0など多種多様な形式があります。

これらの認証用語を初めて耳にした場合でも心配しないでください。このウォークスルーでは、SWAPI は最もシンプルな認証形式 (認証なし) を使用します。他の認証タイプについては、この後の章で説明します。

Workato はほとんどの認証形式に対応していますが、SWAPI では認証は不要です。つまり、最初に本人確認を行わなくても、インターネット経由で API にリクエストを送信できます。

サンプルコードスニペット

{
  title: 'Star Wars information',

  connection: {
    fields:
    [
      {
        name: "object",
        hint: "Type in the object you would like to test your connection with",
      }
    ]
  },

  test: lambda do |connection|
    get("https://swapi.dev/api/people/1")
  end,

  # More code below but hidden for now!
}

このウォークスルーでは、最初にサンプルコードを紹介してから、各コンポーネントを確認していきます。このサンプルコードを自由にコードエディターにコピーして、このウォークスルーに従ってください。

connection

SWAPI はユーザーに何も求めないため、connection キーは比較的空白が多く見えます。connection キーの中で宣言できるものの1つは入力項目です。入力項目は、ユーザーがコネクターを使用して最初に接続を確立したときに表示されます。このユーザー入力は後から参照できます。

connection キーには、入力項目を宣言した fields キーがネストされています。ユーザーにどのように表示されるかを見るには、ページの下部のデバッガーコンソールまでスクロールして、[Connection] タブを開きます。

エンドユーザーへの入力項目の見え方

fields キーに入力されたユーザー入力は、connection キーの外部であっても、カスタムコネクターコードの他の場所で必要に応じて使用できます。他にも fields のように、connection キー内にネストして宣言できるキーがあります。これについては、認証についてのセクションで詳しく説明します。

test

connection キーの外部 (波括弧内の connection: { ... } の外部) には、接続を確立するための重要な機能がもう1つあります。Workato では、接続が正常に確立されたかどうかについて、あなたやあなたのコネクターのユーザーにフィードバックを提供する必要があるため、Link your account ボタンが押されたときに実行される簡単なテストを宣言しなければなりません。

HTTP リクエストを特定の URL に送信すると、テストが実行されます。HTTP リクエストは、アプリケーションがインターネット経由で互いにやり取りする際に使用する手段の1つです。HTTP リクエストに分類される呼び出しにはいくつかの種類がありますが、よくわからない場合は、今回のテストでは GET リクエストを使っているということを認識しているだけで十分です。

SWAPI コネクターの場合は、GET リクエストを任意の URL エンドポイントに送信するよう設定しました。このエンドポイントから情報が正常に送り返されたら、リクエストが受け付けられたという確認になります (レスポンスがコード200で返されます)。test キーで宣言されている get() 関数では、丸括弧内の URL に対する GET リクエストが実行されることがわかります。ここでは、connection["object"] 経由で connection キー内のユーザー入力を参照することで、そのユーザー入力を使用しました。上記のサンプルコードスニペットでは、ユーザー入力を参照して、HTTP 呼び出しの送信先の URL を判断しています。

文字列内の変数を参照するときは、必ず、変数参照の先頭と最後にそれぞれ #{ と } を付加する必要があります。

リクエストの送信先の URL によって、接続が成功するかどうかが左右されます。SWAPI は、ここ (opens new window)に記載されているいくつかの URL のみで GET リクエストをリッスンします。つまり、「films」、「people」、「planets」、「species」、「starships」、「vehicles」のいずれかを入力項目に入力して、有効な URL にリクエストを送信する必要があります。

接続テスト

これでデバッガーコンソールの [Link your account] ボタンを押すことができます。Object の有効な入力項目により、成功メッセージが表示されるはずです。

おめでとうございます！接続は確立されました

それほど難しくなかったのではないでしょうか？接続が確立されたので、アクションを作成しましょう。トリガーがレシピを開始するのに対して、アクションはユーザーが Workato 上で設定できる後続のステップになります。アクションはもともと、作成、削除、取得などの操作を行いますが、レシピ内でつなげて複雑なワークフローを作成することができます。

アクションの作成

SWAPI では、GET リクエストを送信し、スターウォーズに登場する人物、惑星、さらには映画など、ほとんどの情報を受け取ることができます。今回は、Get person by ID というアクションを作成する方法について説明します。このアクションは、スターウォーズのキャラクターに関する情報を取得し、返された情報をデータピルを通してレシピの後続ステップで使用できるようにします。

レシピを作成する際の Get person by ID アクションの見え方

サンプルコードスニペット

{
  title: 'Star Wars information',

  # Code for connection key is hidden but identical to the code snippet above.
  connection: {
    # Some code here
  },

  test: {
    # Some code here
  },

  actions: {
    get_person_by_id: {
      input_fields: lambda do
        [
          {
            name: 'id',
            label: 'Person ID',
            type: 'integer',
            optional: false
          }
        ]
      end,

      execute: lambda do |connection, input|
        get("https://swapi.dev/api/people/#{input["id"]}/")
      end,

      output_fields: lambda do
        [
          {
            name: "name",
            label: "Person name",
            type: "string"
          },
          {
            name: "birth_year",
            label: "Birth year",
            type: "string"
          },
          {
            name: "eye_color",
            label: "Eye color",
            type: "string"
          },
          {
            name: "gender",
            label: "Gender",
            type: "string"
          },
          {
            name: "hair_color",
            label: "Hair color",
            type: "string"
          },
          {
            name: "height",
            label: "Height"
          },
          {
            name: "mass",
            label: "Weight"
          },
          {
            name: "vehicles",
            label: "Vehicles",
            type: "array",
            of: "string"
          },
        ]
      end
    },
  },
}

actions

サンプルコードスニペットには、connection キーや test キーと同様の、もう1つの高レベルのキーである actions があります。actions キーには、新しいアクションを宣言するために使用するコードが含まれています。コードを読みやすくし、波括弧と丸括弧で混乱しないように、必ずインデントを使用してください。

get_person_by_id

いよいよ Get person by ID アクションを定義します。このキーには自分の好きな名前を付けることができますが、名前はアクションが実行しようとしている内容に一致していなければなりません。アクションもこの名前を引き継ぎますが、_ はスペースで置き換えられます。

TIP

アクションキーの名前にはスペースを含めないでください。代わりにアンダースコアを使用します。このアンダースコアは、フロントエンドでスペースに置き換えられます。

アクションキーを作成したら、アクションキーでいくつかのことを宣言する必要があります。

キー	説明
input_fields:	ここでは、入力項目を宣言できます。この入力項目は、レシピの作成時、ユーザーがアクションを設定する際に表示されます。
execute:	ここでは、HTTP リクエスト、HTTP リクエストの送信先 URL、その他の必要な後続のアクションを宣言できます。
output_fields:	ここでは、アクションから返されるデータピルを宣言できます。

input_fields

スターウォーズの登場人物を ID で取得するアクションでは、ユーザーがこのアクションに、SWAPI に送信する ID を渡す必要があります。そのためには、input_fields 内に、ID を取り込める入力項目を定義する必要があります。

これを行うには、lambda 関数内に Ruby ハッシュの配列 (input_fields キー内の角括弧 []) を宣言します。これらのハッシュ (複数のハッシュをカンマで区切ると、複数の入力項目を表すことができます) には、ID をユーザーに表示する方法や、後から ID を参照する方法を Workato に伝えるために定義しなければならない、いくつかの項目が含まれています。

lambda 関数はキーとも呼ばれます。ただし {} は lambda do および end に置き換わります。

例に戻りましょう。name を id にして1つの入力項目を宣言しました。フロントエンドでユーザーに表示される入力項目の名前は、label を使用して宣言できます。変数 type は、予想される入力データ型として、ユーザーに何が表示されるかを定義します。最後に、このアクションでは入力が必須であることを示すため、変数 optional を false に設定します。

レシピでの入力項目の見え方

execute

execute キーでは、Workato でレシピを実行中に、このアクションが実行されるとどのようなことが起きるかを定義します。ここでは execute キーが実行され、lambda do と end の間のすべてのコード行の最終出力が、Workato に出力として渡されます。

この例では、URL https://swapi.dev/api/people/#{input["id"]}/ への GET リクエストを宣言しました。この URL の input["id"] は、ユーザーの入力項目から参照されます。ここで参照される input["id"] は、name が input_fields キー内の id である項目のユーザー入力と一致します。

output_fields

execute が実行された後、カスタムコネクターは GET リクエストからの戻り値を解釈する方法を把握している必要があります。Workato では、入力項目と出力項目は、ハッシュの配列を使用する場合とまったく同じ方法で定義されます。内部のさまざまな変数は、出力項目の表示方法とフロントエンドでの動作を変更します。

Get person by ID アクションおよびその他のほとんどのアクションの場合、execute キーの GET リクエストから返された JSON オブジェクトに対応するよう出力項目が適切に定義されます。ID = 1の GET リクエストから返されるオブジェクト (切り詰められている) を調べて、これがどのように行われるかを見てみましょう。

ID = 1の SWAPI から返される JSON オブジェクトのサンプル

{
  "name":"Luke Skywalker",
  "height":"172",
  "mass":"77",
  "hair_color":"blond",
  "skin_color":"fair",
  "eye_color":"blue",
  "birth_year":"19BBY",
  "gender":"male",
  "vehicles":[
    "https://swapi.co/api/vehicles/14/",
    "https://swapi.co/api/vehicles/30/"
  ],
  # Some portions of the response have been omitted
}

output_fields キーを正しく定義するために重要なのは、execute キーから返されるオブジェクトの内容について何が予想されるかを知ることです。

上記の返されるオブジェクトのサンプルから、output_fields キーで定義する必要のある項目が9以上あることがわかります。上記の output_fields キーでは、配列内の各ハッシュの name が、返される JSON オブジェクトのサンプルに含まれる各変数の名前と一致していることがわかります。

たとえば、返される JSON オブジェクトのサンプルに含まれる height という名前の変数は、name が height である output_fields キーに直接マップされます。ラベルは、レシピ内のデータピルの名前をエンドユーザーにとってわかりやすい名前に変更するのに役立ちます。この場合は、データピルのラベルを height ではなく Height に変更しました。

レシピでの出力項目の見え方

Workato の SDK を使用すると、ネストされた配列およびオブジェクトの出力項目を定義できます。今回の例では、返されるオブジェクトのサンプルに vehicles という名前の配列があり、その中にそれらの車両に関する情報を参照する一連の URL が含まれていることがわかります。Luke Skywalker は複数の車を運転した可能性があるため、これは当然です。配列を定義するには、Workato が、複数の値を指定できる配列を期待できるように、type を array に宣言する必要があります。最後に、of を使用して、配列内にデータを定義する必要があります。URL は文字列として表されるため、string に割り当てられるように of を宣言します。

アクションのテスト

Workato の SDK プラットフォームのコードエディターの下部には、アクションとトリガーを使用してレシピを作成する前に、それらをテストしてデバッグするのに最適なデバッガーコンソールがあります。

デバッガーコンソールは、アクションのテストが正常に終了した後に表示されます

アクションをテストするときは、入力項目の画面が表示されます。現在、ユーザー入力を模倣してアクションをテストする基本的な方法がサポートされています。ポップアップボックスで、入力オブジェクトのスケルトンが生成されていることがわかります。選択したユーザーの ID を入力し、test をクリックするだけで、Get person by ID アクションを実行できます。

デバッガーコンソールが開き、入力した input_fields、生成された出力項目、送信された HTTP リクエスト、受け取ったレスポンスに関するフィードバックが表示されます。アクションの実行中にエラーが発生した場合は [Error] タブが表示され、アクションコード内の任意のポイントで puts メソッドを実行した場合は [Console] タブが表示されます。

puts は、あらゆるものをコンソールに出力できるようにする Ruby メソッドです。このメソッドは、オブジェクトと変数を出力し、[Console] タブでチェックして、予想していたものと一致するかどうかを確認できるため、デバッグに役立ちます。puts の詳細については、こちら (opens new window)を参照してください。

すべてがうまくいった場合 (サンプルコードスニペットをコピーし、 接続の確立後 にアクションを正常に実行できる)、緑色でハイライトされたデバッガーコンソールが開き、アクションが正常に実行されたことが示されます。これはレシピの実行中にエラーが発生しなかったことを意味するだけであり、ロジックエラーなどの他のエラーが残っている可能性があることに注意してください。

新しいカスタムコネクターを使用したレシピの作成

新しい SWAPI カスタムコネクターとアクションにより、アカウント内で作成する任意のレシピでこのアクションを使用できるようになります。アプリケーションを選択して作成を開始するときに、新しい SWAPI コネクターの名前を検索するだけです。

デバッガーコンソールは、アクションのテストが正常に終了した後に表示されます

アクションが使用可能であることを確認するために、デバッガーコンソールでのテストに加え、必ずレシピでアクションをテストしてください。つまり、多くの場合、ユーザーがアクションを簡単に設定できるように、input_fields キーと output_fields キーを定義できる方法を調べる必要があります。