メインコンテンツへスキップ

​
はじめに

オペレーティング・システム(OS)におけるグラフィック・ユーザインターフェース(GUI)の登場はコンピューターを巻き込む環境を大きく変えました。 その変化の一つとして操作のしやすさが取り上げられます。GUIによってもはやコンピューターは専門家の道具から、誰でも使えるツールとして我々の生活に定着しています。 しかし、全てにおいて表と裏があるように必ずしも良い影響ばかりではありませんでした。 従来のコマンドライン・インターフェース(CLI)と比べて一般ユーザの利便性を大きく向上させたGUIは、利便性の代わりに視覚的な処理のためにコンピューターのパフォーマンスが低下したり、細かい制御がしにくい、習熟すると逆に操作が遅くなるなどの問題がありました。いわゆる使い慣れている専門家から見ると非効率的な要素が大きいです。 それ故、現存するOSは種を問わずGUIとCLIが共に揃っています。 専門ETLツールである弊社のXplentyは、ノーコード／ローコードツールとしてデータパイプラインの構築に対してGUI環境を提供しております。しかし、上記のOSの例と同じくデータパイプラインを構築と運用が慣れるとGUIによる操作は頻雑になります。 その時のためにXplentyではCLIベースでご利用できるRest APIを提供しています。今回の記事ではXplentyが提供しているRest APIの中で閲覧系について詳しく見てみましょう。

​
事前準備

​
制限事項

この記事は下記の前提で説明を行います。ご了承ください。
  1. データパイプライン(Xplentでは、パッケージ)は、作成済みである
  2. Crul、Postman、InsomniaなどのHTTP/HTTPSクライアントの使用経験がある
  3. Rest APIの操作に慣れている
  4. 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にて取得可能
intermediate-part09-jp image 1
  • <reosurce_name>についてはXplentyの主なリソースの紹介の部分をご参考ください。
  • 認証方式
    • HTTP Basicを使用しており、全てのXplenty Rest APIは認証が必須である。
    • ユーザ名は、XplentyのAPI KEYを指定し、パスワードはなし
      • curlでの指定 - -d <API_KEY>:
    • <API KEY>は、XplentyのSettings - Developer Settings - Access tokenにて取得可能
intermediate-part09-jp image 2
  • 但し、現時点でAPI KEYのお求めの場合は、Live Chatにてお問い合わせください！！
  • 呼び出しの回数制限
    • ユーザごとに１時間当たり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上で指定のパッケージを指定のクラスタで実行します。
  1. Rest APIのURLをアドレスバーに設定
  2. 上記のURLに対して適切なメソッド(ここではGET)を選択
  3. 認証(Authentication)で方法をBasicに選択してから、usernameにはAPI_KEYを入れてpasswordは空白のままにしておく
intermediate-part09-jp image 3
  1. Headerに呼び出し時に必要なHeaderを該当APIのドキュメントを参照して適切に設定
intermediate-part09-jp image 4
  1. Sendボタンを押してレスポンスを確認
intermediate-part09-jp image 5

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

コマンドラインによる操作に慣れている方の場合、curlを当たり前のように使っていると思います。curlの操作方法が知りたい方は下記の２つの資料をご参考頂ければ幸いです。 前のPostmanと同じ操作がcurlコマンドにて行います。 呼び出し時に必要な情報は下記のオプションを使って設定してください。
  1. -X -メソッドの指定(GETを指定)
  2. -u - Baisc認証の設定(<API_KYE>:)
  3. URL - ジョブリスト取得のREST APIのURL
  4. -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を見て頂きたいですが、主に使うパラメータは下記の通りです。
クエリパラメータ値例説明
sortcreated / updated / その他sort=createdソートの基準属性を指定する
directionasc / descdirection=descsortパラメータで指定された属性を基準で昇順、または降順に並べる
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の利便性を２週間の無料トライアルで、ぜひお試しください。
最終更新日 2026年7月13日