[Tableau] Tableau Server REST APIの紹介

「カスタマーストーリー」を支えるツール特集

#Tableau

かんあきひで

2015.09.08

この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。

Tableau Serverには外部のアプリケーションからリソースを参照、更新するためのREST APIが用意されています。このAPIを業務アプリケーションと連携させることで、サーバにある分析データを現場の担当者が業務アプリケーション経由で参照するなど様々な活用方法が考えられます。
今回はすでにTableau Serverにデータが作成されていることを前提として、REST APIの呼び出し手順を簡単に紹介します。 (Tableau Serverについての説明は以下のエントリーを参照してください)
Tableau Serverで出来ることのまとめ

Tableau Server リソースの種類

詳細は以下のヘルプをご確認ください。
Talbleau REST APIのヘルプ

簡単にまとめると以下の種類のデータを持っています。

サイト情報
ユーザー情報
ワークブック情報
ビュー情報

サイト、ユーザー、ワークブック、ビューの相対関係は以下のようになります

サイト > ユーザー > ワークブック > ビューの順でtree構造になっています。

REST APIによるリソース取得

1. サインイン

まずはAPI呼び出しを許可してもらうためにサインインする必要があります。サインインに成功すると一連のAPI呼び出しに必要なトークン情報を取得できます。

curl http://10.88.11.222/api/2.0/auth/signin -X POST -d @signin.xml

パラメータに指定するXMLは以下の内容です。サインインに必要な情報はユーザー名、パスワードとサインインするサイト名が必要です。

<tsRequest>
  <credentials name="username" password="password" >
    <site contentUrl="site-name" />
  </credentials>
</tsRequest>

返却値も残念ながらXMLです（Tableau REST APIすべて返却値はXMLです）。
返却値のXMLの詳細は本家サイトのヘルプで確認できます。返却値は以下の情報です

返却値	説明
credentials token	API呼び出しに必要な認証トークン。有効期間は初期設定で240分です。
site id	サインインしたサイトのIDです。REST APIで参照できる情報はこのサイトの持つ情報のみです（別サイトの情報を参照したい場合は再度、別サイトを指定してサインインしなおす必要があります。
user id	サインインしたユーザーのIDです。少し分かりにくいのですがこのユーザーIDはサイト毎に一意です。例えばサーバ管理者はすべてのサイトの情報を操作できますが、サーバ管理者のユーザーIDは各サイト毎にそれぞれ異なります。

2. サイト一覧API

Tableauサーバに登録してあるすべてのサイトのリストを返却します。また、サインイン時に取得したトークンを「X-Tableau-Auth」というリクエストヘッダーに指定します。
(サインイン後、すべてのAPI呼び出しにトークンの指定が必要になります)

URLの例

http://ホスト名/api/2.0/sites

curlコマンドでAPI呼び出しの例

curl http://10.88.11.222/api/2.0/sites/ -X GET -H "X-Tableau-Auth:690e0769d5d6c9e847e9774a1da6852a"

返却値	説明
site id	サイトのIDです。
site name	サイトの名称です。
contentUrl	サイトのURLです。この情報はあとで紹介するView表示のためのチケット取得APIのパラメータに使用します。

3. ユーザー一覧の取得

指定したサイトに所属するユーザー情報を取得します。URLにサインインAPIで取得したサイトIDを指定します。

URLの例

http://ホスト名/api/2.0/sites/<site-id>/users

curlコマンドでAPI呼び出しの例

curl http://10.88.11.222/api/2.0/sites/5ca1635d-9035-4bd4-91e2-2cbc9f67c558/users -X GET -H "X-Tableau-Auth:690e0769d5d6c9e847e9774a1da6852a"

返却値	説明
user id	指定したサイトに所属するユーザーのIDです。
user name	ユーザー名称です。
user siteRole	ユーザーの権限です。この権限をTableauサーバで設定することにより、参照のみのユーザーや更新のできるユーザーなど細かい権限設定が可能になります。

4. ユーザー用ワークブック一覧の取得

指定したユーザーが所有もしくは読み取り権限を持つワークブックの一覧を取得します。URLにサインインAPIで取得したサイトID、ユーザー一覧で取得したユーザーIDを指定します。

URLの例

http://ホスト名/api/2.0/sites/<site-id>/users/<user-id>/workbooks

curlコマンドでAPI呼び出しの例

curl http://10.88.11.222/api/2.0/sites/5ca1635d-9035-4bd4-91e2-2cbc9f67c558/users/5f2e2cb6-176b-4fe1-9fb1-97a8a32c2907/workbooks -X GET -H "X-Tableau-Auth:690e0769d5d6c9e847e9774a1da6852a"

返却値	説明
workbook id	指定したユーザーが所有するワークブックのIDです。
workbook name	ワークブックの名称（表示名）です。
contentUrl	ワークブックのURLです。名称と同じ場合が多いですが、名称に日本語、記号などが含まれる場合はTableauサーバが独自に一意のURLに変換します。

5. ビュー一覧の取得

指定したワークブックに含まれるビューの一覧を取得します。URLにサインインAPIで取得したサイトIDとワークブック一覧取得APIで取得したワークブックIDを指定します。

URLの例

http://ホスト名/api/2.0/sites/<site-id>/workbooks/<workbook-id>/views

curlコマンドでAPI呼び出しの例

curl http://10.88.11.222/api/2.0/sites/5ca1635d-9035-4bd4-91e2-2cbc9f67c558/workbooks/13d54be2-2de1-4cc1-8ffc-a3763431961a/views -X GET -H "X-Tableau-Auth:690e0769d5d6c9e847e9774a1da6852a"

返却値	説明
view id	指定したワークブックに所属するビューのIDです。
view name	ビューの名称（表示名）です。
contentUrl	ビューのURLです。この文字列は「ワークブックのcontentUrl/sheets/ビューのcontentUrl」という形式になっています。この後で紹介するビューを画面表示する際にこの値を使います。

ビューの表示

ここまで紹介したAPIで取得できる情報はサイトに関する詳細情報だけですが、取得した情報を使いビューを表示することもできます。
ビューの表示については以下のエントリーがわかりやすくまとまっているので参考にしてください。
Tableau ServerのビューをWebページに埋め込む『信頼できる認証』

以下の図のような処理の流れになります。

上記エントリーで説明されていますが、ビューを表示するために必要なことは以下のとおりです

自分のWebアプリケーションが動くサーバのIPアドレスを事前にTableauサーバに「信頼済みサーバ」として登録しておく
WebアプリケーションからTableauサーバに対してビュー表示に必要なチケットを取得するためにAPIを呼び出す。
取得したチケットと表示したいViewのcontentUrlを組み合わせてビューのURLを作り、Webブラウザで表示する。

信頼済みサーバへの登録の方法は以下のヘルプを参照してください
Tableau Server への信頼できる IP アドレスの追加

チケットの取得

信頼済みサーバとしてTaleauサーバにIPアドレスを登録したあと、リクエストを送りチケットを取得します。 HTTPのPOSTメソッドでリクエストを送ります。POSTパラメータにはユーザー一覧APIで取得したユーザー名、サイト一覧APIで取得したcontentUrlを指定します。

URLの例

http://ホスト名/trusted

curlコマンドの例（コマンドを実行するサーバを信頼済みサーバとしてTableauに登録しておくこと）

curl http://10.88.11.222/trusted -d username="username" -d target_site="classmethod"
-FBRcnWZluNa0OMCksjMPrcJ

成功すると上記のようにView表示のためのチケットの値が返却されます。失敗すると「−1」が返却されます。
失敗した場合の対処方法は以下のヘルプを参照してください。
Tableau Server から返されたチケットの値 -1

チケットの取得が成功したら、Webアプリケーションからクライアントサイドにチケットの値を含めたビューのURLを返却します。クライアントサイドは返却されたURLをiframeのURLに設定しViewを表示します。
iframeに指定するURLは以下の形式になります。

http://ホスト名/trusted/<ticket>/t/<site-contentUrl>/views/<view-contentUrl>

URLに指定しているパラメータは以下のとおりです。

パラメータ	説明
ticket	チケット取得APIで取得したチケットの値です
site-contentUrl	表示するViewが所属するサイトのcontentUrlです。サイト一覧APIで取得した値です
view-contentUrl	表示するViewのcontentUrlです。ビュー一覧APIで取得した値です。ビュー一覧で取得した文字列は「workbook_name/sheets/view_name」の構成になっているので、URLに指定する時には「/sheets」の文字列を削除します

サンプルコード

サインインからビュー表示までのプログラムを試しに作ってみます。内容は以下の処理を行います（今回はサイト一覧、ユーザー一覧、ビュー一覧のAPIは省略します）。

ユーザー名、パスワード、サイトを指定してサインインする。
サインインしたユーザーが持つワークブック一覧を取得する。
ワークブックを指定して、ビューの一覧を取得する。
ビュー表示のための信頼済みチケットを取得する。
チケットとビューのcontent_urlを組み合わせてビュー表示のためのURLを作成する

# coding: utf-8
require 'httpclient'
require 'builder/xmlmarkup'
require 'rexml/document'

class TableauClient
  def initialize(user_name, password, site_content_url)
    @user_name = user_name
    @password = password
    @content_url = site_content_url
    @client = HTTPClient.new
  end

  def signin
    builder = Builder::XmlMarkup.new
    body = builder.tsRequest do  |b|
      b.credentials(name: @user_name, password: @password) do
        b.site(contentUrl: @content_url)
      end
    end
    response = @client.post("http://10.88.11.222/api/2.0/auth/signin/", body)
    xml = REXML::Document.new(response.body)
    auth_token = xml.elements['/tsResponse/credentials'].attributes["token"]
    @header = { 'X-Tableau-Auth' => auth_token}
    @signin_user_id = xml.elements['/tsResponse/credentials/user'].attributes["id"]
    @signin_site_id = xml.elements['/tsResponse/credentials/site'].attributes["id"]
  end

  def fetch_workbooks
    url = "http://10.88.11.222/api/2.0/sites/#{@signin_site_id}/users/#{@signin_user_id}/workbooks"
    response = @client.get(url, nil, @header)
    xml = REXML::Document.new(response.body)
    Array.new.tap do |workbook_ary|
      xml.elements.each('/tsResponse/workbooks/workbook') do |elm|
        workbook_ary << Workbook.new(elm.attributes["id"], elm.attributes["name"])
      end
    end
  end

  def fetch_views(workbook_id)
    url = "http://10.88.11.222/api/2.0/sites/#{@signin_site_id}/workbooks/#{workbook_id}/views"
    response = @client.get(url, nil, @header)
    xml = REXML::Document.new(response.body)
    Array.new.tap do |view_ary|
      xml.elements.each('/tsResponse/views/view') do |elm|
        view_ary << View.new(elm.attributes["id"], elm.attributes["name"], elm.attributes["contentUrl"])
      end
    end
  end

  def fetch_trusted_authentication
      client = HTTPClient.new
      body = { username: @user_name, target_site: @content_url }
      res = client.post("http://10.88.11.222/api/2.0/trusted", body)
      res.body
  end

end

class Workbook
  attr_accessor :id, :workbook_name

  def initialize(id, name)
    @id = id; @workbook_name = name
  end
end

class View
  attr_accessor :id, :view_name, :content_url

  def initialize(id, name, content_url)
    @id = id
    @view_name = name
    @content_url = content_url.gsub(/\/sheets/, '')
  end
end

# ここからAPI呼び出しの実行です
if $0 == __FILE__
  # 指定したユーザー名、パスワード、サイトでサインインする
  executor = TableauClient.new("Administrator", "password", "classmethod")
  executor.signin
  # サインインしたユーザーが持つワークブックの一覧を取得
  workbooks = executor.fetch_workbooks
  # 指定したワークブック（今回は先頭のワークブック）のビュー一覧を取得する
  views = executor.fetch_views(workbooks[0].id)
  view_content_url = views[0].content_url.gsub(/\/sheets/, '') # 表示するviewのcontent_url
  # ビュー表示のためのチケットを取得
  ticket = executor.fetch_trusted_authentication
  # ビューのURLを組み立てて出力
  puts "http://10.88.11.222/trusted/#{ticket}/t/classmethod/views/#{view_content_url}"
end

出力したURLの文字列をiframeに指定するとTableauサーバに保存されているビューが表示できます。

まとめ

今回は参照系のAPIのみ呼び出して、最後にTableau Serverに保存してあるビューの表示までを行いました。Tableau REST APIにはこれ以外にも更新系のAPIが多く用意されているので、連携するアプリケーションからTableau ServerリソースのCRUD処理も行うことができます。また、今回使ったビュー一覧、ワークブック一覧はそれぞれプレビューイメージの取得APIも用意されているので、使用すれば文字だけではないリッチなUIも作ることができます。
すでにTableau Serverにデータがあり、また別の業務アプリケーションがあって連携させたい場合はREST APIの使用を検討してみてください。