---
title: "Tableau APIの使い方：REST・埋め込み・Hyper APIの使い分けとPython実装例【2026年11月】"
url: "https://www.issoh.co.jp/tech/details/19588/"
published: 2026-11-11
updated: 2026-11-11
categories: ["データベース"]
publisher: "株式会社一創"
---

# Tableau APIの使い方：REST・埋め込み・Hyper APIの使い分けとPython実装例【2026年11月】

Tableau APIは1つのAPIではありません。管理を自動化するREST API、依存関係を調べるMetadata API、集計結果をJSONで返すVizQL Data Service、Webページにビューを出すEmbedding API v3、抽出ファイルを作るHyper API、イベントを外へ知らせるWebhooksに分かれています。この記事では、2026年11月時点の公式ドキュメントをもとに、6種類の使い分け、PATと接続済みアプリのJWTの選び方、Pythonでの抽出更新、自社Webシステムへの埋め込みとフィルター連携を、コード付きで整理しました。

## まとめ：Tableau APIの選び方は目的と呼び出す場所、認証の主体で決まる

運用の自動化はREST API、Webシステムへの表示はEmbedding API v3、外部システムへの数値の受け渡しはVizQL Data Service、Tableauへのデータ投入はHyper APIが担当します。迷ったら「誰の権限で、どこから呼ぶか」を先に決めてください。

バッチや管理スクリプトはサーバー側でPATか接続済みアプリのJWTを使い、閲覧者ごとの表示は接続済みアプリのJWTを閲覧者単位で発行します。PATを1つ共有して複数の処理から同時に使う構成は採りません。

見送るべき場面もはっきりしています。閲覧者が不特定多数で人数を数えられない顧客向け画面は、Tableauのユーザーとライセンスの前提に合わず、自社開発のグラフのほうが費用を読みやすくなります。

## Tableau APIの全体像：用途で分かれる6種類と呼び出す場所の違い

最初に、どのAPIが何を受け持つかを押さえます。名前が似ていても、呼び出す場所と認証の渡し方が違います。

### REST・Metadata・VDS・埋め込み・Hyper・Webhooksの役割の一覧

6種類の役割と、呼び出す場所を表にしました。

| API                | 主な用途            | 呼び出す場所      |
| ------------------ | --------------- | ----------- |
| REST API           | ユーザー・権限・公開・抽出更新 | サーバー側       |
| Metadata API       | データの系統と影響範囲の照会  | サーバー側       |
| VizQL Data Service | 集計結果のJSON取得     | サーバー側       |
| Embedding API v3   | ビューの表示と操作       | ブラウザ        |
| Hyper API          | .hyperファイルの作成   | ETL処理       |
| Webhooks           | イベントの通知         | Tableauから送信 |

表のうち、REST APIとMetadata APIとVDSは同じサインインのトークンを使い回せます。Hyper APIだけはTableauのサーバーに接続せず、手元でファイルを作るライブラリです。

### サーバー側で呼ぶAPIとブラウザで動くAPIを分けて設計する理由

ブラウザで動くのはEmbedding API v3だけです。ほかはサーバー側で呼びます。この線を守る理由は秘密情報の置き場所にあります。

接続済みアプリのシークレットやPATをJavaScriptに埋めると、閲覧者が開発者ツールで読めてしまいます。公式の[connected-apps-jwt-samples](https://github.com/tableau/connected-apps-jwt-samples)もJWTの生成はサーバー側の言語で示しています。ブラウザに渡すのは、サーバーで発行した有効期限の短いJWTだけにしてください。

## 認証の準備：PATと接続済みアプリのJWT、スコープの付け方

Tableau APIの実装で最初に詰まるのは認証です。用途に応じて2つを使い分けます。

### PATで始める場合の15日失効と同時セッションが使えない制約

個人用アクセストークン（PAT）は、Tableauの画面で発行してすぐ使えるため、検証や管理スクリプトの入口に向きます。ただし[公式ヘルプ](https://help.tableau.com/current/server/ja-jp/security%5Fpersonal%5Faccess%5Ftokens.htm)には、1つのPATで複数のセッションを同時に要求できないこと、15日間使わないと失効すること、使い続けても1年で失効すること、1ユーザー10個までという上限が書かれています。

夜間バッチと手作業のスクリプトが同じPATを使うと、後からサインインした側が先のセッションを無効にします。処理ごとにPATを分けるか、次に述べる接続済みアプリへ移してください。

### 接続済みアプリのJWTに入れるクレームと最大10分の有効期限

接続済みアプリ（Connected Apps）の直接信頼では、Tableau側で発行したクライアントIDとシークレットでJWTに署名します。[公式の設定手順](https://help.tableau.com/current/online/en-us/connected%5Fapps%5Fdirect.htm)によると、署名方式はHS256だけで、`aud`は`tableau`固定、`exp`は最大10分です。スコープは`scope`ではなく`scp`にリストで入れます。PyJWT 2.15系での発行例です。

```
import datetime
import os
import uuid

import jwt  # pip install pyjwt

CLIENT_ID = os.environ["TABLEAU_CA_CLIENT_ID"]
SECRET_ID = os.environ["TABLEAU_CA_SECRET_ID"]
SECRET_VALUE = os.environ["TABLEAU_CA_SECRET_VALUE"]


def issue_tableau_jwt(username: str, scopes: list[str]) -> str:
    now = datetime.datetime.now(datetime.timezone.utc)
    payload = {
        "iss": CLIENT_ID,
        "exp": now + datetime.timedelta(minutes=5),
        "jti": str(uuid.uuid4()),
        "aud": "tableau",
        "sub": username,
        "scp": scopes,
    }
    headers = {"kid": SECRET_ID, "iss": CLIENT_ID}
    return jwt.encode(payload, SECRET_VALUE, algorithm="HS256", headers=headers)
```

`sub`にはTableau上のユーザー名を入れます。発行するサーバーの時計はUTCで合わせておかないと、Tableauが署名を信頼しません。1つの接続済みアプリにシークレットは2つまで持てるため、新旧を並行させて入れ替えられます。JWTの構造そのものは[JWTの構造と署名検証の仕組み](https://www.issoh.co.jp/tech/details/13453/)で解説しています。

### REST APIのスコープはtableau:content:readから最小で付ける

同じJWTをREST APIのサインインにも使えます。そのときは呼び出すメソッドに対応するスコープが必要です。[Access Scopes for Connected Apps](https://help.tableau.com/current/online/en-us/connected%5Fapps%5Fscopes.htm)では、読み取り全般が`tableau:content:read`、抽出更新の実行が`tableau:tasks:run`、ユーザー操作が`tableau:users:*`のように分かれています。

ワイルドカードを最初から付けると、JWTが漏れたときに削除や権限変更までできてしまいます。読み取りから始め、実装したメソッドの分だけ足してください。埋め込み用は`tableau:views:embed`、VDS用は`tableau:viz_data_service:read`、Metadata API用は`tableau:content:read`です。

## REST APIの実装：JWTでのサインインから抽出更新ジョブの完了待ちまで

REST APIはHTTPで呼べるので言語を選びません。Pythonなら公式のTableau Server Client（TSC）が使えます。

### curlでのJWTサインインとX-Tableau-Authヘッダー、版3.30の指定

URLに入る版番号は製品の版で決まります。[REST API and Resource Versions](https://help.tableau.com/current/api/rest%5Fapi/en-us/REST/rest%5Fapi%5Fconcepts%5Fversions.htm)では、2026.3が3.30、2026.1が3.28、2025.3が3.27です。[Authentication](https://help.tableau.com/current/api/rest%5Fapi/en-us/REST/rest%5Fapi%5Fconcepts%5Fauth.htm)に沿って、JWTとサイトのcontentUrlを送ります。

```
curl -s -X POST "https://10ay.online.tableau.com/api/3.30/auth/signin" \
  -H "Content-Type: application/json" -H "Accept: application/json" \
  -d '{"credentials":{"jwt":"'"$TABLEAU_JWT"'","site":{"contentUrl":"mysite"}}}'

# 応答の credentials.token と credentials.site.id を控えて次の呼び出しに使う
curl -s "https://10ay.online.tableau.com/api/3.30/sites/$SITE_ID/datasources" \
  -H "X-Tableau-Auth: $TABLEAU_TOKEN" -H "Accept: application/json"
```

取得したトークンは`X-Tableau-Auth`ヘッダーで渡す方式です。Tableau Serverの既定ではトークンの有効期間は240分で、処理が終わったら`auth/signout`で無効にします。古い版を指定すると、新しいメソッドは失敗します。

### Tableau Server Client 0.42による抽出更新のPython実装例

業務システム側のデータ取り込みが終わった直後にTableauの抽出を更新したい、という要件はよくあります。[Tableau Server Client](https://github.com/tableau/server-client-python)の0.42（2026年10月15日公開・Python 3.10以上）での例です。

```
import os

import tableauserverclient as TSC

auth = TSC.PersonalAccessTokenAuth(
    os.environ["TABLEAU_PAT_NAME"], os.environ["TABLEAU_PAT_SECRET"], site_id="mysite"
)
server = TSC.Server("https://10ay.online.tableau.com", use_server_version=True)

with server.auth.sign_in(auth):
    opts = TSC.RequestOptions()
    opts.filter.add(
        TSC.Filter(TSC.RequestOptions.Field.Name, TSC.RequestOptions.Operator.Equals, "sales_daily")
    )
    datasources, _ = server.datasources.get(opts)
    job = server.datasources.refresh(datasources[0])
    # 抽出更新は非同期ジョブ。完了まで待ち、失敗なら例外になる
    job = server.jobs.wait_for_job(job, timeout=1800)
    print(job.id, job.finish_code)
```

`refresh`はジョブを登録して即座に戻ります。後続の処理が更新後の数字を前提にするなら、`wait_for_job`で完了を待ってから次へ進めてください。Tableau Cloudの抽出更新には時間とメモリの上限があり、その値は[Tableau CloudとServerの違い](https://www.issoh.co.jp/tech/details/18870/)の比較と合わせて確認すると判断しやすくなります。

### Metadata APIのGraphQLで影響範囲を調べる手順とServerでの有効化

データベースの列名を変える前に、どのワークブックが影響を受けるかを知りたい場面ではMetadata APIを使います。[Get Started](https://help.tableau.com/current/api/metadata%5Fapi/en-us/docs/meta%5Fapi%5Fstart.html)によると、エンドポイントは`/api/metadata/graphql`の1つで、認証に必要なのはREST APIと同じトークンです。Tableau Serverでは既定で無効なので、`tsm maintenance metadata-services enable`で有効にします。

```
curl -s -X POST "https://10ay.online.tableau.com/api/metadata/graphql" \
  -H "X-Tableau-Auth: $TABLEAU_TOKEN" -H "Content-Type: application/json" \
  -d '{"query":"{ publishedDatasources(filter: {name: \"sales_daily\"}) { name upstreamTables { name schema } downstreamWorkbooks { name projectName } } }"}'
```

上流のテーブルと下流のワークブックを1回の照会で引けます。有効化のコマンドは一部のサービスを再起動するので、Serverでは業務時間外に実施してください。GraphQLの書き方は[GraphQLのクエリの書き方](https://www.issoh.co.jp/tech/details/2924/)が参考になります。

## Embedding API v3で自社Webシステムにダッシュボードを埋め込む実装

社内ポータルや顧客向けの管理画面にTableauのビューを出すなら、Embedding API v3を使います。

### tableau-viz要素とtoken属性でビューを表示するHTMLの書き方

[Embedding API v3](https://help.tableau.com/current/api/embedding%5Fapi/en-us/index.html)では、ライブラリを読み込んで`tableau-viz`要素を置きます。[Authentication and Embedding](https://help.tableau.com/current/api/embedding%5Fapi/en-us/docs/embedding%5Fapi%5Fauth.html)のとおり、サーバーで発行したJWTを`token`属性に入れると、閲覧者はTableauへのサインイン画面を見ずに済みます。

```
<script type="module"
  src="https://public.tableau.com/javascripts/api/tableau.embedding.3.latest.min.js"></script>

<tableau-viz id="salesViz"
  src="https://10ay.online.tableau.com/t/mysite/views/Sales/Overview"
  token="{{ embed_token }}"
  toolbar="bottom" hide-tabs>
</tableau-viz>
```

`{{ embed_token }}`には、前の章の関数に`["tableau:views:embed"]`を渡して閲覧者ごとに発行した値を入れます。npmでは`@tableau/embedding-api`の3.16系も配布されています。

### 業務画面の操作をapplyFilterAsyncでビューに反映するコード

埋め込みの価値が出るのは、業務画面で選んだ支店や期間がそのままビューに効くときです。[フィルターのドキュメント](https://help.tableau.com/current/api/embedding%5Fapi/en-us/docs/embedding%5Fapi%5Ffilter.html)にある`applyFilterAsync`を、ビューの読み込み完了後に呼びます。

```
import { FilterUpdateType, TableauEventType } from
  "https://public.tableau.com/javascripts/api/tableau.embedding.3.latest.min.js";

const viz = document.getElementById("salesViz");

viz.addEventListener(TableauEventType.FirstInteractive, () => {
  document.getElementById("branchSelect").addEventListener("change", async (e) => {
    const sheet = viz.workbook.activeSheet;
    const targets = sheet.sheetType === "dashboard" ? sheet.worksheets : [sheet];
    for (const ws of targets) {
      await ws.applyFilterAsync("支店", [e.target.value], FilterUpdateType.Replace);
    }
  });
});
```

値が1件だけの場合でも、渡す形式は配列です。ダッシュボードの場合は中のワークシートごとに適用するため、上のように分岐させます。表示の初期値だけ決めたいなら、`viz-filter`要素を`tableau-viz`の中に書く方法もあります。

### 埋め込みで閲覧できない原因：ドメイン許可リストとCookie

本番で「開発環境では見えたのに表示されない」という事態の多くは、接続済みアプリのドメイン許可リストが原因です。既定は全ドメイン許可ですが、公式は本番ドメインだけに絞ることを推奨しています。`https://*myco.com:*`のようにサブドメインとポートをまとめて指定できます。

認証のドキュメントには、ブラウザでサードパーティCookieを許可する必要があるとも書かれています。社外の利用者に見せる画面では、利用者のブラウザ設定を変えてもらえるとは限りません。本番と同じブラウザの設定で表示できるかを、リリース前の検証項目に入れてください。

## データ入出力の判断：Hyper APIとVizQL Data Serviceの使い所

Tableauとほかのシステムの間でデータそのものを受け渡すときは、方向によってAPIが変わります。

### Hyper APIで外部ETLから.hyperファイルを作り公開する流れ

Tableauが直接つなげないデータや、業務システム側で加工済みのデータは、[Hyper API](https://tableau.github.io/hyper-db/docs/)で抽出ファイルを作ります。PyPIのtableauhyperapiは2026年10月17日公開の0.0.26963が最新です。

```
import datetime

from tableauhyperapi import (Connection, CreateMode, HyperProcess, Inserter,
                             SqlType, TableDefinition, TableName, Telemetry)

table = TableDefinition(TableName("Extract", "Extract"), [
    TableDefinition.Column("order_date", SqlType.date()),
    TableDefinition.Column("branch", SqlType.text()),
    TableDefinition.Column("amount", SqlType.big_int()),
])
rows = [(datetime.date(2026, 11, 10), "東京", 182000)]

with HyperProcess(telemetry=Telemetry.DO_NOT_SEND_USAGE_DATA_TO_TABLEAU) as hyper:
    with Connection(hyper.endpoint, "sales_daily.hyper", CreateMode.CREATE_AND_REPLACE) as conn:
        conn.catalog.create_schema("Extract")
        conn.catalog.create_table(table)
        with Inserter(conn, table) as inserter:
            inserter.add_rows(rows)
            inserter.execute()
```

作ったファイルは、TSCの`server.datasources.publish(TSC.DatasourceItem(project_id), "sales_daily.hyper", TSC.Server.PublishMode.Overwrite)`で上書き公開します。既存のETLジョブの最後にこの2段を足すと、Tableau側の更新スケジュールを待たずに鮮度を揃えることが可能です。Tableau Prepのフローで足りる加工なら、[Tableau Prepのフローと定期実行](https://www.issoh.co.jp/tech/details/18872/)のほうがコードを持たずに済みます。

### VizQL Data Serviceのquery-datasourceで集計結果を取る

Tableauで定義した計算や行レベルセキュリティを通した数字を、ほかのシステムで使いたいときは[VizQL Data Service](https://help.tableau.com/current/api/vizql-data-service/en-us/index.html)（VDS）を呼びます。Tableau Serverでは2025.1以降が対象で、データソースにAPI Access権限を付けておく必要があります。認証ヘッダーは[OpenAPIリファレンス](https://help.tableau.com/current/api/vizql-data-service/en-us/reference/index.html)のとおり`X-Tableau-Auth`です。

```
curl -s -X POST "https://10ay.online.tableau.com/api/v1/vizql-data-service/query-datasource" \
  -H "X-Tableau-Auth: $TABLEAU_TOKEN" -H "Content-Type: application/json" \
  -d '{
    "datasource": {"datasourceLuid": "DATASOURCE_LUID"},
    "query": {"fields": [
      {"fieldCaption": "branch", "sortPriority": 1},
      {"fieldCaption": "amount", "function": "SUM"}
    ]},
    "options": {"returnFormat": "OBJECTS"}
  }'
```

[Query a Data Source](https://help.tableau.com/current/api/vizql-data-service/en-us/docs/vds%5Fcreate%5Fqueries.html)には見落としやすい仕様があります。2026.1以降は結果がストリーミングで返り、途中で失敗するとHTTP 200のまま本文に`error`が入ります。ステータスだけでなく本文の`error`も必ず確認してください。30分を超えると408で打ち切られます。AIエージェントから同じVDSを使う方法は[Tableau MCPの導入手順](https://www.issoh.co.jp/tech/details/19586/)で扱いました。

### Webhooksで抽出更新の失敗を業務システムへ通知する受信側の実装

[Tableau Webhooks](https://help.tableau.com/current/developer/webhooks/en-us/index.html)は、抽出更新の失敗やワークブックの公開を外部のURLへPOSTで知らせます。作成はREST APIの[Create a Webhook](https://help.tableau.com/current/api/rest%5Fapi/en-us/REST/rest%5Fapi%5Fref%5Fnotifications.htm)で、管理者だけが呼べます。送信先はhttpsで有効な証明書が必須です。

受信側は2点を実装に入れてください。[Events and Payloads](https://help.tableau.com/current/developer/webhooks/en-us/docs/webhooks-events-payload.html)によると、2xx以外を返すと最大3回再送され、配信失敗が4回たまると自動で無効になります。1つのイベントで同じ内容が複数回届くこともあるため、`resource_luid`と`event_type`と`created_at`の組で重複を捨てます。まず2xxを返してから処理をキューに積む、という受け方が安全です。受信側の冪等性の作り方は[Webhookの作り方と実装方法](https://www.issoh.co.jp/tech/details/1378/)で解説しています。

## Tableau APIで作る範囲の判断：採用する構成と自社開発に切り替える条件

APIでできることが多いぶん、どこまでTableauに寄せるかの線引きが費用を左右します。

### Tableau APIを採用する条件：閲覧者を数えられる社内・取引先向け画面

採用してよいのは、閲覧者がTableauのユーザーとして登録でき、人数を数えられる場合です。接続済みアプリのJWTは`sub`に実在のユーザーを入れる前提なので、社員や取引先の担当者など、アカウントを払い出せる相手向けの画面に向きます。分析の担当者がすでにTableauでダッシュボードを作っている組織なら、画面を作り直さずに業務システムへ載せられる点が大きな利点です。

ViewerやExplorerの人数配分による年額は[Tableauの価格](https://www.issoh.co.jp/column/details/18812/)で試算できます。認証の設計から埋め込み・抽出更新の自動化までまとめて任せたい場合は、一創の[BIツール導入支援](https://www.issoh.co.jp/service/ai/bi/)でご相談を受けています。

### 採用を見送る場面：不特定多数の顧客向け画面と固定帳票の大量配信

一般消費者向けのマイページのように閲覧者が数万人規模で増減する画面には、Tableauの埋め込みを使いません。ユーザーの払い出しとライセンスが閲覧者数に比例し、費用の上限を読めないからです。月次の固定帳票を数千社へ配るだけの用途も同様で、表示の自由度より配信件数が効くため、自社開発のグラフ部品やPDF生成のほうが安く収まります。

実装方式の比較は[組み込み分析の実装方式4種の比較](https://www.issoh.co.jp/column/details/16539/)にまとめています。Power BIでの同等の構成は[Power BI Embeddedの実装手順](https://www.issoh.co.jp/tech/details/19513/)が参考になります。

## よくある質問

Tableau APIについて、実装前によく聞かれる質問に答えます。

### Tableau APIは無料で使えますか？

APIの呼び出し自体に別料金はかかりません。ただしREST APIもEmbedding API v3も、Tableau CloudかTableau Serverの契約と、操作するユーザーのライセンスが前提です。埋め込んだビューを見る人にも、利用量ベースの契約を除いて原則としてユーザーとライセンスが要ります。Hyper APIのライブラリはPyPIから無料で入れられ、ファイルの作成だけならTableauに接続しません。

### Tableau PublicでもAPIは使えますか？

Embedding API v3はTableau Publicのビューも埋め込めます。認証が要らないので、`token`属性なしで表示できます。一方、REST APIやVDS、Webhooksは、Tableau CloudとTableau Serverのサイトに対して使うAPIです。Publicに載せたデータは誰でも見られるため、社内データには使えません。仕様は[Tableau（タブロー）とは](https://www.issoh.co.jp/tech/details/18863/)の製品体系の章で整理しています。

### PythonでTableauのデータを取得するにはどのAPIを使いますか？

集計済みの数字が欲しいならVizQL Data Serviceです。Tableauで定義した計算フィールドや行レベルセキュリティを通した結果をJSONで受け取れます。ビューに表示されている表をそのままCSVで欲しいなら、使うのはREST APIのビューのデータ取得です。TSCならどちらの前段のサインインも同じコードで書けます。元のデータベースに直接つなげる場合は、Tableauを経由しないほうが速く確実です。

### Tableau MCPとTableau APIはどう使い分けますか？

Tableau MCPは、ClaudeなどのAIエージェントがVDSやREST APIを呼べるようにした中継のサーバーです。質問に応じてAIがクエリを組み立てる用途に向きます。決まった集計を毎日業務システムへ渡すなら、VDSやREST APIを直接呼ぶほうが結果が安定し、障害時の切り分けも容易です。版ごとのツールと権限の絞り方は[Tableau MCPとは](https://www.issoh.co.jp/tech/details/19586/)にまとめました。

### Tableau ServerとTableau CloudでAPIの書き方は変わりますか？

エンドポイントの形はほぼ同じで、CloudはURLに`10ay`のようなポッド名が入ります。差が出るのは対応版です。VDSはServer 2025.1以降、Webhooksの作成スコープはServer 2025.3以降、Metadata APIはServerでは有効化のコマンドが要ります。Serverを使う場合は版を先に確かめてください。構築とアップグレードの計画は[Tableau Serverとは](https://www.issoh.co.jp/tech/details/19519/)で解説しています。

## 関連記事

- [Tableau（タブロー）とは：製品の種類・データ接続・権限設計と自社開発との使い分け](https://www.issoh.co.jp/tech/details/18863/)：Tableau全体の構成と権限の考え方
- [Tableau MCPとは：導入手順とClaudeからのデータソース照会、ツールと権限の絞り方](https://www.issoh.co.jp/tech/details/19586/)：AIエージェントからAPIを使う方法
- [Tableau Cloudとは：Serverとの違い・SSOとBridgeの設定・Serverからの移行手順](https://www.issoh.co.jp/tech/details/18870/)：認証と接続の前提になるCloudの設定
- [Tableauの導入支援｜依頼できる範囲と外注先の選び方、費用の決まり方](https://www.issoh.co.jp/column/details/18818/)：API連携を外注するときの範囲と費用
- [組み込み分析とは？実装方式4種の比較と内製・外注の判断基準](https://www.issoh.co.jp/column/details/16539/)：埋め込み方式の比較

---

出典: [Tableau APIの使い方：REST・埋め込み・Hyper APIの使い分けとPython実装例【2026年11月】](<https://www.issoh.co.jp/tech/details/19588/>)（株式会社一創）