HTTP メソッド

このセクションでは、Workato でサポートしているさまざまな HTTP メソッドについて説明します。これらのメソッドの大部分については、すでに馴染みがあるかもしれません。ここでは、HTTP 呼び出しのレスポンス後処理を行う方法についても説明します。そうした後処理を利用すると、データを操作して、コネクターコード内で後で簡単に使用できるフォーマットにすることができます。

HTTP 動詞メソッド

HTTP 動詞	メソッド	例
GET	get()	get("url", parameters)
POST	post()	post("url", payload)
PUT	put()	put("url", payload)
PATCH	patch()	patch("url", payload)
DELETE	delete()	delete("url", parameters)
OPTIONS	options()	options("url", parameters)

リクエストの作成

各 HTTP 動詞メソッドには、最初の引数として url 文字列を与える必要があります。2番目の引数 (省略可能) には2種類の形式があります。

まず、input は、単一のハッシュとして渡すことができます。このハッシュは、たとえば次のように、単純に execute または poll の引数の input 引数でも構いません。

execute: lambda do |connection, input|
  get("https://www.some_api_endpoint.com/api", input)
end

このハッシュは、次のように、あらかじめ構成することもできます。

execute: lambda do |connection, input|
  params = {
    "id" => input["id"]
  }

  get("https://www.some_api_endpoint.com/api", params)
end

Workato SDK フレームワークは、このハッシュの値を処理して各種のデータフォーマットに変換します。GET リクエスト、DELETE リクエスト、OPTIONS リクエストの場合、ハッシュのデータは URL クエリーパラメータに変換されます。

POST、PUT、PATCH の場合、ペイロードは、指定されたフォーマットのリクエスト本文の形に変換されます。さまざまなデータフォーマットの扱い方については、こちらを参照してください。

他にも、リクエストデータを渡す方法には、一連のキーと値のペアとして渡すやり方があります。

execute: lambda do |connection, input|
  post("https://www.some_api_endpoint.com/api", name: input["name"], email: input["email"])
end

最初の引数の後のすべての引数は、リクエストデータに変換されます。この場合、デフォルトのデータフォーマットは JSON なので、次のようなリクエスト本文が作成されます。

{
  "name": "Ee Shan",
  "email": "[email protected]"
}

GET リクエストでは、次のように URL パラメータを作成します。

execute: lambda do |connection, input|
  get("https://www.some_api_endpoint.com/api", name: input["name"], email: input["email"])
end

完全なリクエスト URL 文字列は次のようになります。

https://www.some_api_endpoint.com/api?name%3DEe%20Shan%26email%3Deeshan%40workato.com

その他の認証形式があれば、それも付加されます。上記の例では、認証は不要ということを前提にしています。認証は、connection オブジェクト内で定義される apply ブロックを通じて適用されます。

リクエスト作成に向けた、その他のヘルパーメソッド

Workato では、最初の HTTP 動詞メソッドの後につなげることで、その他のさまざまなヘルパーメソッドを使用できます。以下に、いくつかの役立つメソッドを示します。

payload

このメソッドでは、リクエストにペイロードを追加できます。これは上で解説したものと同じ構文に従います。

execute: lambda do |connection, input|
  post("https://www.some_api_endpoint.com/api")
    .payload(name: input["name"], email: input["email"])
end

これにより、次のような POST リクエストのペイロードが生成されます。

{
  "name": "Ee Shan",
  "email": "[email protected]"
}

params

このメソッドでは、リクエストにクエリーパラメータを追加できます。これは上で解説したものと同じ構文に従います。これらの値は URL エンコードされます。

execute: lambda do |connection, input|
  get("https://www.some_api_endpoint.com/api")
    .params(name: input["name"], email: input["email"])
end

https://www.some_api_endpoint.com/api?name%3DEe%20Shan%26email%3Deeshan%40workato.com

header

このメソッドでは、リクエストにヘッダーを追加できます。これは上で解説したものと同じ構文に従います。ここで定義されるヘッダーでは、 大文字と小文字が区別されません。

execute: lambda do |connection, input|
  get("https://www.some_api_endpoint.com/api")
    .headers(Authorization: "Bearer HTB674HJK1")
end

TIP

大文字と小文字を区別するヘッダーは RFC (opens new window) から逸脱していますが、headers ではなく case_sensitive_headers メソッドを使用することにより、そのようなヘッダーも HTTP メソッドで使用できます。

tls_client_cert

このメソッドでは、SSL 証明書、キー、パスフレーズ、および中間証明書を追加できます。

execute: lambda do |connection, input|
  get("https://www.some_api_endpoint.com/api")
    .tls_client_cert(
      certificate: connection['ssl_client_cert'],
      key: connection['ssl_client_key'],
      passphrase: connection['ssl_key_passphrase'],
      intermediates: connection['ssl_client_intermediate_cert']
    )
end

レスポンス後処理

デフォルトのレスポンスデータ

デフォルトでは、すべての HTTP 動詞メソッドがリクエストのレスポンス本文を返します。たとえば、 Okta では、次のリクエストでユーザーが作成されます。

execute: lambda do |connection, input|
  response = post("/api/v1/users", profile: { login: input["email"], displayName: input["name"] })
end

変数 response は、次のようなハッシュになります。

{
  "id": "00ub0oNGTSWTBKOLGLNR",
  "status": "STAGED",
  "created": "2018-03-13T21:36:25.344Z",
  "activated": null,
  "statusChanged": null,
  "lastLogin": null,
  "lastUpdated": "22018-03-13T21:36:25.344Z",
  "passwordChanged": null,
  "profile": {
    "firstName": "Ee Shan",
    "lastName": "Sim",
    "email": "[email protected]",
    "login": "[email protected]",
    "mobilePhone": null
  },
  "credentials": {
    "provider": {
      "type": "OKTA",
      "name": "OKTA"
    }
  }
}

レスポンス処理

after_response は、HTTP 動詞メソッドにつなげて HTTP レスポンスのさまざまな部分を処理できる、任意利用のブロックです。例を見てみましょう。ここでも再び、 Okta API を利用します。

リクエストが List all users (opens new window) のエンドポイントに送信されると、切り詰められたレスポンスは次のようになります。

HTTP/1.1 200 OK
Content-Type: application/json
Link: <https://workatotest.okta.com/api/v1/users?limit=200>; rel="self"

[
  {
    "id": "00utti9t3j1xO9jOm2p6",
    "status": "ACTIVE",
    "created": "2018-03-15T08:23:05.000Z",
    "activated": null,
    "statusChanged": "2018-03-15T08:39:39.000Z",
    "lastLogin": "2018-03-15T08:39:40.000Z",
    "lastUpdated": "2018-03-15T08:39:40.000Z",
    "passwordChanged": "2018-03-15T08:39:39.000Z",
    "profile": {},
    "credentials": {},
    "_links": {}
  }
]

このレスポンスは、HTTP レスポンス コード 、 ヘッダー 、および 本文 という3つの部分に分けられます。

after_response を使用することで、HTTP レスポンスの3つの部分すべてを処理できます。たとえば、すべてのユーザーをリスト化し、レスポンス全体 (ヘッダーから既存のページへのリンクを含む) を出力するアクションがあるとします。

execute: lambda do |connection, input|
  get("/api/v1/users").after_response do |code, body, headers|
    {
      code: code,
      next_link: headers["link"],
      users: body
    }
  end
end

このアクションの結果の出力には、レスポンスの3つの部分すべてが含まれます。

{
  "code": 200,
  "next_link": "<https://workatotest.okta.com/api/v1/users?limit=200>; rel=\"self\"",
  "users": [
    {
      "id": "00utti9t3j1xO9jOm2p6",
      "status": "ACTIVE",
      "created": "2018-03-15T08:23:05.000Z",
      "activated": null,
      "statusChanged": "2018-03-15T08:39:39.000Z",
      "lastLogin": "2018-03-15T08:39:40.000Z",
      "lastUpdated": "2018-03-15T08:39:40.000Z",
      "passwordChanged": "2018-03-15T08:39:39.000Z",
      "profile": {},
      "credentials": {},
      "_links": {}
    }
  ]
}

テスト

カスタムコネクターを開発しながら、容易にこれを検証することができます。リクエスト後処理を含めている場合、出力タブには期待される JSON オブジェクトが反映されるはずです。

レスポンスコードとヘッダー値を含む出力*