ハウツーガイド - APIキー認証 ​

APIキー認証は、接続先のアプリケーションでユーザーにAPIキーの生成を求める従来型の認証方法です。 このAPIキーのスコープは、生成したユーザーの権限に設定される場合もあれば、キーごとに権限を設定できる場合もあります。

APIがAPIキーを受け取る方法はさまざまです。 一般的な例は次のとおりです。

• 各リクエストのURLパラメーターに追加する（GET www.api.com/resource?api-key=XXX）
• 各リクエストのヘッダーに追加する（X-API-KEY: XXX）
• 各リクエストのユーザー名またはパスワードフィールドに追加する（-u XXXまたは-u :XXX）

サンプルコネクター - Iterable ​

{
  title: 'Iterable',

  connection: {
    fields: [
      {
        name: 'api_key',
        label: 'API key',
        control_type: 'password',
        optional: false,
        hint: 'Get your <b>standard</b> API key <a href="https://app.' \
        'iterable.com/settings/apiKeys" target="_blank">here</a>.'
      }
    ],

    authorization: {
      type: 'api_key',

      apply: lambda do |connection|
        headers(api_key: connection['api_key'])
      end
    },

    base_uri: lambda do |connection|
      'https://api.iterable.com'
    end
  },

  test: lambda do |connection|
    get('/api/channels')
  end,

  #More connector code here
}

• 完全な例については、Iterableコネクターの完全なコードを参照してください。
• Iterable APIを確認してください

ステップ1 - コネクションフィールドの定義 ​

このコンポーネントは、コネクションを確立しようとしているユーザーに表示するフィールドをWorkatoに指示します。 APIキー認証の場合、ユーザーがIterableで生成したAPI keyが必要です。

これは、ハッシュの配列を受け入れるfieldsキーで実行されます。 この配列内の各ハッシュは、個別の入力フィールドに対応します。

    fields: [
      {
        name: 'api_key',
        label: 'API key',
        control_type: 'password',
        optional: false,
        hint: 'Get your <b>standard</b> API key <a href="https://app.' \
        'iterable.com/settings/apiKeys" target="_blank">here</a>.'
      }
    ],

ステップ2 - authorizationの定義 ​

このコンポーネントは、コネクションを確立するために入力フィールドから受け取った値をどう処理するかをWorkatoに指示します。 これはauthorizationキーで処理されます。 このキーでは、まず認可のtypeを定義します。 APIキー認証の場合は、api_keyを使用する必要があります。

    authorization: {
      type: 'api_key',

      apply: lambda do |connection|
        headers(api_key: connection['api_key'])
      end
    },

ステップ3 - 後続のHTTPリクエストへの認証情報の適用 ​

次に、このコネクターのユーザーから受け取ることを想定しているAPIキーの使用方法をWorkatoに指定する必要があります。 これはapplyキーで行い、connection引数を通じて収集されたAPIキーを参照できます。 applyキーに指定した指示は、コネクションが確立された後、このコネクターが送信するすべてのHTTPリクエストに適用されます。

この例では、受け取ったAPIキー（connection['api_key']）を任意のリクエストのヘッダーに追加するように定義しています。 送信されるすべてのHTTPリクエストで、ヘッダーにはAPIキーであるapi_key: XXXが含まれます。

ステップ4 - APIのbase URIの設定 ​

このコンポーネントは、APIのベースURLをWorkatoに指示します。 このキーは任意ですが、HTTPリクエストを定義する際に、コネクターの残りの部分で相対パスのみを指定できるようになります。 base_uriの設定の詳細については、ベースURI設定を参照してください。

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

    base_uri: lambda do |connection|
      #some code here
    end

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

エンドユーザーから収集する必要があるフィールドと、それらのフィールドからの入力をどう処理するかを定義したので、次にこのコネクションをテストする方法が必要です。 これはtestキーで処理されます。

    test: lambda do |connection|
      get('/api/channels')
    end,

このキーでは、受け取ったばかりの新しい認証情報を使用してサンプルリクエストを送信できるエンドポイントを指定する必要があります。 200 OK HTTPレスポンスを受信すると、コネクションをSuccessfulとして表示します。 上記の例では、/api/channelsエンドポイントにGETリクエストを送信し、APIキーが有効な場合に200レスポンスを期待しています。

バリエーション ​

各リクエストでURLパラメーターまたはユーザーフィールドにAPIキーを送信する必要がある場合は、applyキーを変更するだけです。

URLパラメーター内のAPIキー ​

    authorization: {
      type: 'api_key',

      apply: lambda do |connection|
        params(api_key: connection['api_key']) # For URL parameters
      end
    },

ユーザー名フィールド内のAPIキー ​

    authorization: {
      type: 'api_key',

      apply: lambda do |connection|
        user(connection['api_key']) # For username
        password("") # user method needs to be accompanied with an empty password declaration.
      end
    },

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

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