はじめに

オペレーティング・システム(OS)におけるグラフィック・ユーザインターフェース(GUI)の登場はコンピューターを巻き込む環境を大きく変えました。
その変化の一つとして操作のしやすさが取り上げられます。GUIによってもはやコンピューターは専門家の道具から、誰でも使えるツールとして我々の生活に定着しています。

しかし、全てにおいて表と裏があるように必ずしも良い影響ばかりではありませんでした。
従来のコマンドライン・インターフェース(CLI)と比べて一般ユーザの利便性を大きく向上させたGUIは、利便性の代わりに視覚的な処理のためにコンピューターのパフォーマンスが低下したり、細かい制御がしにくい、習熟すると逆に操作が遅くなるなどの問題がありました。いわゆる使い慣れている専門家から見ると非効率的な要素が大きいです。
それ故、現存するOSは種を問わずGUIとCLIが共に揃っています。

専門ETLツールである弊社のXplentyは、ノーコード／ローコードツールとしてデータパイプラインの構築に対してGUI環境を提供しております。しかし、上記のOSの例と同じくデータパイプラインを構築と運用が慣れるとGUIによる操作は頻雑になります。

その時のためにXplentyではCLIベースでご利用できるRest APIを提供しています。今回の記事ではXplentyが提供しているRest APIの中で閲覧系について詳しく見てみましょう。

事前準備

制限事項

この記事は下記の前提で説明を行います。ご了承ください。

データパイプライン(Xplentでは、パッケージ)は、作成済みである
Crul、Postman、InsomniaなどのHTTP/HTTPSクライアントの使用経験がある
Rest APIの操作に慣れている
APIの詳細についてはgithub(英語)をご参照ください。

Xplenty Rest APIの基本情報

XplentyのRest APIは、Xplentyが提供しているHTTPS基盤のRESTful API群ですので、使い方も普段のRESTful APIの使用と変わりがありません。
この記事では、githubの内容を元にRest APIのハンズオンとして説明致します。

Rest APIのURL
- https://api.xplenty.com/<account_id>/api/<reosurce_name>
  - <account_id>は、XplentyのSettings - Accounting Settings - Profileにて取得可能
  - <reosurce_name>についてはXplentyの主なリソースの紹介の部分をご参考ください。
認証方式
呼び出しの回数制限
- ユーザごとに１時間当たり5000回の呼び出し回数の制限(credit)が存在
- 指定の呼び出し回数が超過した場合、429 Too Many Requestsを返却

Rest APIの呼び出しの見本

では、Xplenty의 Rest APIの呼び出しの見本をそれぞれのHTTP/HTTPS・クライアントにて紹介します。
呼び出し見本の説明は、List Jobsを用いてHTTP/HTTPS・クライアント上の操作は行います。
また、Xplentyが提供している全てのAPIのリストは、このリンクをご参照ください。

GUIアプリによる呼び出し

有名なHTTP/HTTPS・クライアントであるPostmanやInsomniaを使って、XplentyのRest APIを呼び出してみましょう。この見本は、Postman上で指定のパッケージを指定のクラスタで実行します。

Rest APIのURLをアドレスバーに設定
上記のURLに対して適切なメソッド(ここではGET)を選択
認証(Authentication)で方法をBasicに選択してから、usernameにはAPI_KEYを入れてpasswordは空白のままにしておく
Headerに呼び出し時に必要なHeaderを該当APIのドキュメントを参照して適切に設定
Sendボタンを押してレスポンスを確認

Curlコマンドによる呼び出し

コマンドラインによる操作に慣れている方の場合、curlを当たり前のように使っていると思います。curlの操作方法が知りたい方は下記の２つの資料をご参考頂ければ幸いです。

curl tutorial(英語)
簡易ガイド(日本語)

前のPostmanと同じ操作がcurlコマンドにて行います。
呼び出し時に必要な情報は下記のオプションを使って設定してください。

-X -メソッドの指定(GETを指定)
-u - Baisc認証の設定(<API_KYE>:)
URL - ジョブリスト取得のREST APIのURL
-H - Rest APIの呼び出し時に必要なヘッダー情報

Request (Curl Call) Syntax

 curl -X GET -u <API_KEY>: "https://api.xplenty.com/<account_id>/api/jobs" \
  -H "Accept: application/vnd.xplenty+json; version=2"

Response Example

[
  {
    "id": 304,
    "status": "failed",
    "variables":
    {
        "InputPath": "'/today'"
    },
    "owner_id": 1,
    "progress": 0,
    "outputs_count": 0,
    "outputs": [],
    "started_at": "2013-03-04T08:02:20Z",
    "created_at": "2013-03-04T08:02:17Z",
    "updated_at": "2013-03-04T08:03:01Z",
    "failed_at": null,
    "cluster_id": 176,
    "package_id": 103,
    "errors": "Package failed to execute.",
    "runtime_in_seconds": 40,
    "completed_at": "2013-03-04T08:03:01Z",
    "url": "https://api.xplenty.com/xplenation/api/jobs/304",
    "html_url": "https://xplenty.com/xplenation/jobs/304",
    "log_url": "https://api.xplenty.com/xplenation/api/jobs/304/log",
    "creator":
    {
        "type":"Schedule",
        "id":1,
        "display_name": "Schedule 1",
        "url": "https://api.xplenty.com/xplenation/api/schedules/1",
        "html_url": "https://xplenty.com/xplenation/schedules/1"
    },
    "package": {
      "id": 2373,
      "name": "AWS CloudFront Log Analysis",
      "description": "This package processes AWS CloudFront logs and extracts traffic information by time, geography and URIs",
      "variables": {},
      "owner_id": 8,
      "created_at": "2014-03-12T07:09:18Z",
      "updated_at": "2014-04-13T19:38:04Z",
      "url": "https://api.xplenty.com/xplenation/api/packages/2373",
      "status":"active"
    },
    "cluster": {
       "id": 99,
      "name": "Daily Outliers Test #100",
      "description": "Daily Outliers Test",
			:
			:
      "bootstrap_actions": [{
        "script_path": "http://xplenty.s3.amazonaws.com/bootstrap-actions/file1.tar.gz",
        "args": ["arg1", "arg2"]
      }, {
        "script_path": "http://xplenty.s3.amazonaws.com/bootstrap-actions/file1.tar.gz",
        "args": ["arg1"]
      }],
      "creator":
      {
          "type":"Schedule",
          "id":1,
          "display_name": "Schedule 1",
          "url": "https://api.xplenty.com/xplenation/api/schedules/1",
          "html_url": "https://xplenty.com/xplenation/schedules/1"
      }
    }
  },
  {
				:
  				:
  },
  {
				:
  				:
  }
]

Xplentyリソースの閲覧

Xplentyには、データ転送作業に関わる幾つかの概念をリソースと呼んでいます。
作業に該当する適切なリソースを選んで操作を行います。

閲覧系のRest APIは、これらのリソースの存在有無、およびリソースの詳細情報を得るために必須のAPIです。Rest APIで閲覧系は、各々のリソースに対してGETメソッドによって呼び出されます。

Xplentyの主なリソースの紹介

Xplentyで使われる主なリソースは下記の通りです。

リソース	説明
クラスタ(Cluster)	アカウントのユーザーに排他的に割り当てられるマシン (ノード) のグループです。1 つ以上のクラスターを作成し、各クラスタで 1 つ以上のジョブを実行できます。作成したクラスターは、終了するまでアカウントに割り当てられたままになります。
パッケージ(Package)	Xplenty Web アプリケーションで作成するデータフローの定義です。処理する元データ (ローケーション、スキーマ、フィールド)、実行するデータ操作、および出力先 (ローケーション、スキーマ) を記述します。パッケージのワークフローはジョブによって実装されます。
ジョブ(Job)	クラスタ上の特定のパッケージに従ってデータフローを実行するプロセスです。ジョブは、対象範囲のデータを処理するバッチプロセスです。複数のジョブが同じパッケージを同時に実行できます。Xplenty APIを呼び出して新しいジョブを実行するときは、ジョブが実行するワークフローのパッケージ名と、ジョブを実行するクラスタを指定します。
スケジュール(Schedule)	指定された日時にパッケージを定期的に実行します。パッケージは、スケジュールされたクラスタ・サイズに適合する既存のクラスタを使用してスケジュールどおりに実行されます。クラスタが存在しない場合は、指定されたノードの数でクラスタが自動的にプロビジョニングされます。デフォルトでは、パッケージの実行が完了するとすぐにクラスタは停止されます。
その他のリソース	上記のリソース以外に色んなリソースがありますので、リンク先をご参照ください。

主なリソースの閲覧API

主なリソースを閲覧するために下記のAPIを使用します。各々のRest APIには指定可能なパラメータが存在しており、それらの指定によって取得範囲の制限か可能です。詳細内容は該当リンクをご参考頂ければ幸いです。また、下記のRest APIは認証されたユーザのみに許可されております。

閲覧API	説明
List Clusters	クラスタのリストを取得します。基本的に全てのstatus(状態)のクラスタが閲覧出来ますが、特定の状態のクラスタのみの閲覧も可能です。
List Jobs	ジョブのリストを取得します。パッケージIDや状態の指定にて閲覧範囲の絞り込みも可能です。
List Packages	パッケージのリストを取得します。パッケージは２種類(workflow, dataflow)がありますが、基本的に全種類を閲覧出来ます。
List Schedules	スケジュールのリストを取得します。
List Account Connections	ユーザが生成されたコネクションのリストを取得します。typeパラメータによってタイプごとの絞り込みも可能です。typeに関してはこちらのリンクにあるコネクターごとのドキュメントをご参照ください。
その他	リンク先のページでListで始まるAPIのドキュメントをご参照ください。

閲覧APIの主なクエリパラメータ

GETメソッドでリソースを取得する閲覧APIは、リソースの範囲を指定するいくつかのクエリパラメータがあります。詳細は以前の閲覧APIを見て頂きたいですが、主に使うパラメータは下記の通りです。

クエリパラメータ	値	例	説明
sort	`created` / `updated` / その他	sort=created	ソートの基準属性を指定する
direction	`asc` / `desc`	direction=desc	sortパラメータで指定された属性を基準で昇順、または降順に並べる
since	-	since=2023-08-31T15:00:00Z	リソースの取得開始日時を指定しており、日時のフォーマットは、ISO-8601(`YYYY-MM-DDTHH:MM:SSZ`)のUTCである
status	-	status=all or status=active	リソースによって指定できる値が異なるため、APIドキュメントをご参照ください

閲覧時の制限事項(offsetとlimit)

Xpelntyの閲覧APIには、システムの影響を考慮した返却リストの閾値を設けております。閾値に関わるパラメータとしてoffsetとlimitがあります。
２つのパラメータを指定なしで閲覧APIが呼び出された場合、デフォルトとしてoffset = 0とlimit = 20が閲覧APIに付与されます。また、limitの最大値は100まで指定できるので、閲覧用のRest APIを使う際にoffsetとlimitの適切な値の調整をお勧めします。

終わりに

以上でXplentyが提供しているRest APIの中で閲覧系について色々見てみました。次はRest APIを使用してどのようにXplentyにデータ転送を行うかについてご紹介します。

XplentyはITのバッググラウンドがない方のみならず、ITに慣れている方にも便利に使うための柔軟な環境を提供しております。

優れたXplentyの利便性を２週間の無料トライアルで、ぜひお試しください。