How to ガイド - ヘッダー認証

ヘッダー認証が要求される API の場合、ユーザー入力項目を通してユーザーにトークンを直接提供してもらうことで、この認証を容易に達成できます。

サンプルコネクター - 一般的なコネクター

{
  title: 'My connector',

  connection: {

    fields: [
      {
        name: "token",
        control_type: "string",
        label: "Bearer token",
        optional: false,
        hint: "Available in 'My Profile' page"
      }
    ],

    authorization: {
      type: 'custom_auth',

      apply: lambda do |connection|
        headers("Authorization": "Bearer #{connection["token"]}")
      end
    },

    base_uri: lambda do |connection|
      "https://api.acmestudios.com"
    end
  },

  test: lambda do |connection|
    get('/me')
  end,
}

ステップ1 - コネクション項目の定義

connection キーの中の fields キー内で、入力項目を定義します。この定義は、ハッシュからなる配列で行われます。その配列内のハッシュは、それぞれが1つの入力項目を表現します。定義内では、入力項目の名前や、エンドユーザーに表示されるヒントといったパラメータを宣言できます。この例では、トークン (token) という入力項目を定義しています。

TIP

項目を定義する際は、少なくとも name キーを指定する必要があります。optional、hint、control_type といった追加的な属性を指定すると、その項目のほかの要素をカスタマイズできます。クライアントシークレットのような機密情報に対しては、必ず control_type を password として使用してください。

Workato 内の入力項目を定義する方法について、詳しくはこちらを参照してください。

ステップ2 - 以降の HTTP リクエストに対するトークンの適用

apply キー内の header() で、ユーザーから提供されたトークンをキーと値のペアの形式で渡しています。そうすることで、Workato はコネクターが生成する毎回の HTTP リクエストにそのトークンを付加し、それぞれのリクエストの認証を手助けするようになります。

ステップ3 - API のベース URI の設定

この部分では、API のベース URL を Workato に指示します。このキーは任意ですが、これを利用すると、コネクターのほかの部分で HTTP リクエストを定義する際に相対パスのみを入力できるようになります。base_uri の設定方法については、こちらを参照してください。

    base_uri: lambda do |connection|
      "https://api.acmestudios.com"
    end

TIP

この lambda 関数では引数 connection にもアクセスできます。これは、API のベース URI がユーザーのインスタンスに基づいて変化する場合に特に便利です。引数 connection には次の形式でアクセスできます。

    base_uri: lambda do |connection|
      "https://#{connection['domain'].com/api}"
    end

ステップ4 - コネクションのテスト

エンドユーザーから収集する必要のある項目と、それらの項目からの入力をどう利用するかを定義したので、次はこのコネクションをテストする手段が必要です。これは test キー内で扱われます。

    test: lambda do |connection|
      get("/me")
    end

このブロックではエンドポイントを指定する必要があります。このエンドポイントは、直前に受け取った新しい資格情報を使ってサンプルリクエストを送信するために利用されます。HTTP レスポンスとして200 OK を受け取った場合、接続は成功となります。上記の例では、エンドポイントの例である /me に GET リクエストを送信し、入力されたトークンが有効であればレスポンスとして200 OK を受け取ることが期待されています。

コネクションの SDK リファレンス

connection キー内で使用可能なキーとそのパラメータについての詳細は、SDK リファレンスを確認してください。