Table of Contents:
  1. Curl 関数はどういう場合に使うか？
  2. Curl 関数の使い方
  3. Curl関数と利用例
  4. 比較表: Integrate.io Curl 関数とユースケースまとめ
  5. Step-by-Step 例
  6. 最後に

HTTP リクエストを作成する機能に加えて、Integrate.io は、特定のユースケースにおいて有益な様々なCurl関数と高度な機能を提供します。この記事では、ステップバイステップのデモンストレーションに加えて、Curl 関数と機能について紹介します。

 

 Curl関数はどういう場合に使うか？

Integrate.io の Curl関数は、HTTP リクエストを実行し、返されたレスポンスをデータパイプラインの中で使用することができます。Curl 機能を使用して、以下のいずれかを行うことができます。

  • サードパーティのAPIを実行してデータを取得する：このデータは、既存のデータを充実させる（新しいフィールドを追加する）ために使用されるかもしれません。例えば、任意の信用格付けサービスのAPIを使用して、顧客の信用スコアを取得することができます。
  • APIを実行して、パイプライン内のデータフィールドの値を変換する：例えば、FXのAPIを呼び出して、通貨フィールドを最新のレートに従って現地通貨に変換することができます。
  • 外部APIを介してCRUD操作を実行する：例えば、CRUD操作に対応している他のサービスでは、APIを介してデータレコードを作成したり、変更したりすることができます。

Curl関数の使い方

Curl 関数は、任意のフィールド式で使用できる関数のセットを通して利用することができます。ここに例を示します。

thumbnail image

上のスクリーンショットでは、base_urlはAPIのホストアドレスを格納するパッケージ変数です。適切な引数とともにCurlと呼ばれる関数を呼び出してHTTP GETリクエストを行い、レスポンスという名前でエイリアスを付けて返された結果を格納します。 

レスポンスは、Integrate.io関数を使用してさらに解析することができます。例えば、エンドポイントがJSON形式の文字列を返す場合、

{
"life_time_value": 400,
"is_active": true
}

JsonStringToMap(response)#'life_time_value' という式を使って、JSONレスポンスからlife_time_valueフィールドを抽出することができます。

Curl関数と利用例

このセクションでは、Curl 機能のさまざまな機能について詳細に説明し、いくつかのユースケースを見ていきます。

Simple HTTP Requests

Curl 関数は、HTTP リクエストを準備して実行するための基本的な機能をすべて提供します。関数のシグネチャは次のようになります。

Curl(url, method[, headers[, request_body[, username[, password]]]])

この関数の最初の2つの引数(urlとmethod)は必須ですが、他の引数はオプションです。すべての引数を使用した場合の例は以下のとおりです。

Curl(
'https://test-app.com/customers/',
'POST',
'{"Accept":"text/json"}',
'{"name":"Satwik","age":23}',
'some_username','some_password'
)

  1. url 引数にはプロトコルを指定する必要があります (http と https の両方がサポートされています)。
  2. HTTP methodは、GET、PUT、POST、DELETEのいずれかを指定することができます。
  3. headersは、JSON オブジェクトに似たキー-バリュー形式で指定できます。
  4. request_body は、生の文字列形式で渡すことができます。
  5. 最後に、Basic認証用にusernameとpasswordを指定できます。

Curl 関数の戻り値は、3 つのキーで構成されるマップ オブジェクトです。 

  • status - HTTP レスポンスコード 
  • body - 生の文字列形式のレスポンスボディ
  • headers - レスポンスヘッダのマップオブジェクト

Curl 関数は、単純な HTTP リクエストを作成するために必要な基本的な機能をすべてカバーしています。次のセクションでは、ある特定のユースケースに適した、より高度な関数について紹介します。

 

ページングされたリクエスト

CurlWithPagination 関数を使用すると、ページングされた API に対して複数の HTTP リクエストを行い、サーバーからのレスポンスを収集することができます。これは、データをフェッチする API にページングなしでは転送できないデータがたくさんある場合に有効です。

以下が CurlWithPagination 関数の関数シグネチャです。

CurlWithPagination(url, method[, headers[, request_body[, username[, password[, pagination_scheme[, sleep_interval[, max_pages]]]]]]])

この関数は、基本的な Curl 関数のすべての引数をサポートし、ページ分割されたリクエストを希望の方法で作成するためのオプションの引数もサポートします。ここにリクエストの例を示します。

CurlWithPagination(
'https://test-app.com/customers',
'GET',
'', '', '', '',
'LinkHeader'.
100,
10000)

上記のスニペットでは、指定したURLに対して100ms毎に最大10,000回のGETリクエストを行います。ページの詳細は、レスポンスに含まれるリンクヘッダから取得します。

この関数は以下のpagination_schemeの値をサポートしています。

  • Automatic (デフォルト)：Integrate.ioはドメインごとにページネーション方式を検出します。ページネーションをサポートしているドメインのリストはこちらのリンクでご確認いただけます。Integrate.ioに他のエンドポイントのページネーションをサポートさせたい場合は、遠慮なくサポートに連絡してください。
  • NoPagination： この関数をCurl関数と同じように動作させます。
  • LinkHeader：Integrate.ioはRFC 5988の仕様に従ってページをフェッチします。

Curl 関数とは異なり、CurlWithPagination 関数の戻り値は、単一のマップオブジェクトではなく、マップオブジェクトのBag型（ページングされたリクエストごとに1つずつ）です。様々な Integrate.io 関数を使って、これらのマップオブジェクトを期待するフォーマットで照合することができます。

Polling the API 

CurlPoll 関数を使用すると、正規表現にマッチするか、指定されたタイムアウトリミットに達するまで連続的に HTTP リクエストを行うことができます。この関数は、ステータスの変更やエンドポイントからのレスポンスを待つ必要がある非同期タスクで特に便利です。例えば、注文のサマリーレポートをトリガーするエンドポイントがあり、そのエンドポイントのデータ処理は非同期的に行われるとします。このようなAPIは通常、頻繁にポーリングできるステータス/最終レスポンスを取得するためのエンドポイントを持っています。

これが関数のシグネチャです。

CurlPoll(regex_string,interval, timeout, url, method[, headers[, request_body[, username[, password]]]])

この関数は、ポーリング条件を指定するための 3 つの必須引数 (regex_string、interval、timeout) に加えて、基本的な Curl 関数のすべての引数をサポートしています。以下に例を示します。

CurlPoll(
'status="(completed)',
1000,
60000,
'https://test-app.com/customers/5/upgrade_plan',
'GET',
'{"Accept":"text/json"}',
'','','')

上記の関数は、1000ms(1秒)ごとに指定されたURLへのGETリクエストを行います。ポーリングは、関数のレスポンスが status=completed となるか、60000ms(1分)が経過後に終了になります。CurlPoll 関数の戻り値は Curl 関数と同様で、正規表現にマッチしたレスポンス、またはタイムアウトした場合の最後のレスポンスの全体の詳細 (status、body、および headers) が含まれます。

バイナリ形式のレスポンスの取得

BinaryCurl 関数は、バイナリ形式のレスポンスを返す HTTP リクエストを作成するために使用されます。この関数は、API がファイルを返す場合に特に便利です。例えば、API が圧縮された .gz ファイルを返す場合、File Storage Destination コンポーネントを使用してディスクに書き込むことができます。

BinaryCurl 関数のシグネチャは Curl 関数と全く同じです。

BinaryCurl(url, method[, headers[, request_body[, username[, password]]]])

ここではリクエスト例を紹介します。

BinaryCurl(
'https://test-app.com/customers/5/archive.gz',
'GET',
'', '',
'some_username','some_password'
)

BinaryCurlの戻り値は、Curl関数の戻り値と似ています。ただし、戻り値のbody部分にはバイナリデータが含まれています。

Integrate.ioのConnectionを使用した認証

CCurlメソッドは、Integrate.io connectionを使用して認証されたリクエストを行うために使用します。この機能は、Integrate.io接続を定義できるサービスの認証を簡素化するのに役立ちます。例えば、新規注文を作成するためにShopifyストアにHTTPリクエストを行いたい場合、Shopifyコネクションを定義し、それを使用してCurl関数で自分で認証を処理するのではなく、それ自身で認証を処理することができます。 

こちらがCCurlのシグネチャーです。

CCurl(url, [method, [headers, [request_body, [connection_id]]]])

Curl メソッドとは異なり、この関数はユーザー名とパスワードの引数を持たないことに注意してください。

以下はリクエストの例です。

CCurl(
'http://test-app.com/customers/',
'POST','{"Accept":"text/json"}',
'{"name":"satwik","age":23}',
'my_connection_12'
)

この例では、my_connection_12 はダッシュボードのConnectionの画面で見ることができるコネクション ID のことです。CCurl 関数の戻り値は Curl 関数の戻り値と全く同じです。

その他の機能

前に説明した機能を組み合わせて、Integrate.io接続での認証を可能にする機能がいくつかあります。

  • CCurlWithPagination： 認証のために Integrate.ioで定義されたコネクションを使用している間、ページングされたリクエストを行うために使用します。
  • CCurlPoll: 認証のために Integrate.ioで定義されたコネクションを使用している間にポーリング要求を行うために使用します。
  • BinaryCCurl: Integrate.ioで定義されたコネクションを使用しているときに使用します。 認証のために Integrate.io 接続を使用しているときに、Binary を返すリクエストを作成するために使用します。

注意点としては、認証にIntegrate.ioで定義されたコネクションを使用するこれらの関数は、その関数を使用する変数を含むパッケージを検証したり、X-consoleで検証したりするとNULLを返すということです。しかし、実際のジョブ実行時には期待通りに動作します。 

比較表: Integrate.io Curl 関数とユースケースまとめ

ユースケースに適した関数を選択するために、次の表を参照してください。

Make HTTP request

Basic Auth

Auth using Integrate.io connections

Retrieve Binary Data

Handle Paginated data

Poll response

Curl

✅

✅

❌

❌

❌

❌

BinaryCurl

✅

✅

❌

✅

❌

❌

CurlWithPagination

✅

✅

❌

❌

✅

❌

CurlPoll

✅

✅

❌

❌

❌

✅

CCurl

✅

❌

✅

❌

❌

❌

BinaryCCurl

✅

❌

✅

✅

❌

❌

CCurlWithPagination

✅

❌

✅

❌

✅

❌

CCurlPoll

✅

❌

✅

❌

❌

✅

 

Step-By-Step 例

API を使用して新しいサービスにデータを移行する一般的なユースケースを考えてみましょう。  顧客データはデータベース テーブルに存在し、そのデータは何らかの前処理を行った後に外部の分析サービスに送信する必要があります。前処理のステップでは、既存のデータを充実させるために内部APIエンドポイント（/customer/summary/<int:customer_id>）を呼び出す必要があります。この API は、次の形式の JSON レスポンスを返します。

{
"email": satwik@example.org,
  "life_time_value": 546,
  "is_active": true
  ... // More such fields
}

「アクティブ」な顧客のみを移行する必要があります。エンリッチメントの後、データはREST APIを介して外部のサービスに渡され、顧客データを入力する必要があります。我々は、JSON形式でデータを渡すAPIを呼び出すためにCurl関数を使用する必要があります。最後に、監査目的でデータベースに移行状況を保存する必要があります。

ソリューション

最後に

Integrate.ioのCurl関数は、様々なシナリオでサードパーティのAPIを使用するための複数のオプションを提供します。提供された表を参照し、ビデオデモにアクセスすることで、Integrate.ioのCurl関数とその可能性をよりよく理解することができます。

Integrate.ioのCurl関数がみなさんのユースケースにどのように適用できるか確認するには、オンラインデモを予約して、デモ後に14日間のリスクなしのトライアルをお試しください。