接続済みアプリのアクセス スコープ
REST API へのアクセスを連携アプリを使用して承認することにより、次を実現します。
- 効率の向上 — JWT をベアラー トークンとして使用すると、2 つのリクエストではなく、サインイン エンドポイントへの 1 つのリクエストで偽装を簡単化することができます
- 動的なコンテンツ検索や高度なフィルタリングなど、複雑な Tableau 統合とバックエンド クエリを拡張および自動化します
スコープ アクション
接続済みアプリが使用するスコープは、JWT 認可をサポートする REST API メソッド (下記) を通じて、コンテンツや管理アクションへのアクセス権を付与します。スコープはコロンで区切られた文字列であり、名前空間 tableau で始まり、アクセスが許可されている Tableau リソース (datasources など) が続き、そのリソースに対して許可されているアクション (update など) で終わります。
スコープが実行できるアクションは次のとおりです。
createreadrunupdatedownloaddelete
たとえば、カスタム アプリケーションが UpdateDataSource(新しいウィンドウでリンクが開く) メソッドを呼び出せるようにするスコープは次のようになります。
tableau:datasources:update
使用するスコープの種類は、有効にするコンテンツまたは管理アクションによって異なります。スコープは通常、コンテンツ読み取り、個別、ワイルドカード、クロスカテゴリのいずれかのタイプに分類されます。
コンテンツ読み取りスコープ: コンテンツ読み取りスコープ
tableau:content:readは、Tableau コンテンツに対してサポートされている GET メソッドを有効にします。このスコープを使用すると、REST API カテゴリ全体でアクションを有効にできます。具体的には、このスコープを使用して、データ ソース、メトリクス、ビュー、ワークブック、プロジェクト、およびサイトに対する GET メソッドを有効にします。注: ユーザーやグループなどの管理アクションに対する GET メソッドを有効にするには、それらの個別スコープを使用できます。
個別スコープ: サポートされているコンテンツと管理アクションを有効にするには、それらの個別スコープを使用できます。個別スコープは、通常、単一のメソッドと REST API カテゴリに関連付けられています。
例:
- データ ソース アクションのパブリッシュまたは更新を有効にするには、それぞれ個別スコープ
tableau:datasources:createまたはtableau:datasources:updateを使用できます。 - ユーザーの追加または削除などの管理アクションについては、それぞれ個別スコープ
tableau:users:createまたはtableau:users:deleteを使用できます。
注: REST API のカテゴリをまたがるアクションを有効にできる個別スコープもいくつかあります。例えば、
tableau:views:downloadは、データの表示やワークブックの REST API カテゴリでアクションを有効にします。- データ ソース アクションのパブリッシュまたは更新を有効にするには、それぞれ個別スコープ
ワイルドカード スコープ: 特定のスコープでは、アクションをワイルドカード文字 (*) に置き換えて、特定の REST API カテゴリ内でサポートされているアクションを有効にすることができます。
例:
- ワイルドカード スコープ
tableau:projects:*を使用すると、プロジェクトの REST API カテゴリで作成、削除、更新のアクションを有効にできます。 - ワイルドカード スコープ
tableau:users:*を使用すると、ユーザーの REST API カテゴリでクエリ、追加、削除、更新のアクションを有効にできます。
- ワイルドカード スコープ
クロスカテゴリ スコープ: コンテンツ読み取りスコープに加えて、使用すると、異なる REST API カテゴリにまたがってアクションを有効にする、追加スコープがいくつかあります。
例:
tableau:tasks:runスコープを使用すると、データ ソースとワークブックの REST API カテゴリでアクションを有効にします。- 繰り返しになりますが、
tableau:views:downloadスコープを使用すると、データの表示とワークブックの REST API カテゴリでアクションを有効にします。 tableau:permissions:updateまたはtableau:permissions:deleteなどのパブリッシュ スコープを使用すると、データ ソース、ワークブック、およびプロジェクトの REST API カテゴリでアクションを有効にします。
REST API アクセスを認可する方法の概要
次のリストは、JWT を介して REST API へのアクセスをリクエストする手順をまとめたものです。
- 次のいずれかの方法を使用して、連携アプリを作成します。
- 有効な JWT を生成します。カスタム アプリケーションは、指定したスコープで設定された有効な JWT を実行時に生成します
- サインイン(新しいウィンドウでリンクが開く) リクエストを行います。カスタム アプリケーションは、JWT を使用してサインインをリクエストし、Tableau 認証資格情報トークンとサイトID (LUID) を返します。
- 後続のリクエストで Tableau アクセス トークンを使用します。後続の REST API 呼び出しでは、1) Tableau 認証資格情報トークンを
X-Tableau-Auth(新しいウィンドウでリンクが開く) ヘッダー値として使用し、2) サイト ID (LUID) をリクエスト URI で使用します。
例
直接信頼を使用して連携アプリを作成する場合の例です。直接信頼を使用して REST API を呼び出すカスタム アプリケーションは、連携アプリが生成したクライアント ID とクライアント シークレットを使用して有効な JWT を生成します。
JWT のスコープ
REST API へのアクセスを正常に認可するには、JWT に REST API 機能を定義するスコープが含まれている必要もあります。たとえば、データ ソース関連のさまざまなメソッドを有効にするには、JWT に次のようなスコープを含めることができます。
"tableau:content:read","tableau:datasources:create","tableau:datasources:update","tableau:datasources:download","tableau:tasks:run"
または
"tableau:content:read","tableau:datasources:*","tableau:tasks:run"
注: スコープの値はリスト型として渡す必要があります。
サインイン リクエストの URI
REST API を呼び出すには、カスタム アプリケーションは最初にサインイン要求を行い、Tableau 認証資格情報のトークンを生成する必要があります。
POST https://us-west-2b.online.tableau.com/api/3.16/auth/signinリクエスト本文
JWT を使用して REST API へのアクセスを認可するには、サインイン リクエストの本文に次の例のような有効な JWT が含まれている必要があります。
<tsRequest>
<credentials jwt="eyJpc3MiOiI4ZTFiNzE3Mi0zOWMzLTRhMzItODg3ZS1mYzJiNDExOWY1NmQiLCJhbGciOiJIUzI1NiIsImtpZCI6ImIwMTE1YmY5LTNhNGItNGM5MS1iMDA5LWNmMGMxNzBiMWE1NiJ9.eyJhdWQiOiJ0YWJsZWF1Iiwic3ViIjoicm1vaGFuQHRhYmxlYXUuY29tIiwic2NwIjpbInRhYmxlYXU6c2l0ZXM6cmVhZCJdLCJpc3MiOiI4ZTFiNzE3Mi0zOWMzLTRhMzItODg3ZS1mYzJiNDExOWY1NmQiLCJleHAiOjE2NDg2Njg0MzksImp0aSI6IjY1ZWFmMmYxLTNmZTgtNDc5Ny1hZmRiLTMyODMzZDVmZGJkYSJ9.mUv2o4gtBTrMVLEXY5XTpzDQTGvfE2LGi-3O2vdGfT8">
<site contentUrl="mycodotcom"/>
</credentials>
</tsRequest>レスポンス本文
サインイン リクエストに対して、Tableau 認証資格情報トークンを含む、次のようなレスポンス本文が生成されます。
<tsResponse>
<credentials token="12ab34cd56ef78ab90cd12ef34ab56cd">
<site id="9a8b7c6d5-e4f3-a2b1-c0d9-e8f7a6b5c4d" contentUrl=""/>
<user id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d" />
</credentials>
</tsResponse>Tableau アクセス トークンが生成されたら、Tableau 認証資格情報トークンが後続のすべての REST API リクエストのヘッダーに追加されます。
ヘッダー
X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd
Tableau アクセス トークンを使用する後続のすべての REST API リクエストは、JWT のスコープによって制限されます。
JWT 認可をサポートする REST API メソッド
次のスコープを連携アプリに関連付けて、カスタム アプリケーションがユーザーに代わって REST API(新しいウィンドウでリンクが開く) に対して持つことができるアクセス権とメソッドを定義できます。
注:
- 以下の表にリストアップされていない REST API 機能については、他の認可メカニズムを使用してメソッドにアクセスできます。詳細については、Tableau REST API ヘルプの「認証メソッド(新しいウィンドウでリンクが開く)」を参照してください。
- サインイン(新しいウィンドウでリンクが開く)とサインアウト(新しいウィンドウでリンクが開く)のメソッドは、共に JWT 認証でサポートされていますが、スコープを使用する必要はありません。
- 埋め込み API v3 でサポートされているスコープについては、次のいずれかを参照してください。
| メソッド | スコープ | 説明 |
|---|---|---|
| スコープなし | (スコープなし) | JWT でスコープが定義されていない場合、REST API へのアクセスは拒否されます。 |
| サインイン | (スコープなし) | |
| サインアウト | (スコープなし) | 現在のセッションからサインアウトします。 |
| (コンテンツ読み取りスコープ) | tableau:content:read | Tableau コンテンツ (データ ソース、メトリクス、ビュー、ワークブック、プロジェクト) に対するクエリ アクションを有効にする。 |
データ ソース | ||
| データ ソースのパブリッシュ | tableau:datasources:create | データ ソースをサイトにパブリッシュする。または、既存のパブリッシュ済みデータ ソースにデータを追加する。 |
| データ ソースの照会 | tableau:content:read | パブリッシュ済みデータ ソースに関する情報を取得する。 |
データ ソースの照会 | tableau:content:read | サイトでパブリッシュされているすべてのデータ ソースに関する情報を取得する。 |
| データ ソース接続の照会 | tableau:content:read | パブリッシュ済みデータ ソースのサーバー アドレス、ポート、ユーザー名、またはパスワード情報を取得する。 |
| データ ソースの更新 | tableau:datasources:update | データ ソースの所有者、プロジェクト、証明書ステータスを更新する。 |
| データ ソース接続の更新 | tableau:datasources:update | データ ソース接続のサーバー アドレス、ポート、ユーザー名、またはパスワードを更新する。 |
| データ ソースを今すぐ更新 | tableau:tasks:run | 抽出の更新を実行する。 |
| (データ ソース メソッド) | tableau:datasources:* | データ ソース アクションのパブリッシュおよび更新を有効にする。 |
フロー | ||
| フローのパブリッシュ | tableau:flows:create | フローをパブリッシュする。 |
メトリクス | ||
| メトリクスの取得 | tableau:content:read | メトリクスを取得する。 |
| メトリクスの削除 | tableau:metrics:delete | メトリクスを削除する。 |
| メトリクスを一覧表示 | tableau:content:read | サイトのメトリクスの一覧を取得する。 |
| メトリクス データの照会 | tableau:metrics:download | メトリクスの参照元データをカンマ区切り値 (.csv) 形式で取得する。 |
| メトリクスの更新 | tableau:metrics:update | 所有者、プロジェクト、一時停止ステータス、メトリクス名を更新する。 |
| (メトリクス メソッド) | tableau:metrics:* | メトリクス アクションのクエリ、更新、および削除を有効にする。 |
ビュー | ||
| カスタム ビューの削除 | tableau:views:update | 指定されたカスタム ビューを削除します。 |
| カスタム ビューの取得 | tableau:content:read | 指定されたカスタム ビューの詳細を取得します。 |
| カスタム ビュー イメージの取得 | tableau:views:download | 指定したカスタム ビューの .png 形式のイメージ ファイルをダウンロードします。 |
| ビューの取得 | tableau:content:read | ビューに関する詳細を取得する。 |
| パスでビューを取得 | tableau:content:read | 指定された名前を使用して、サイトのすべてのビューの詳細を取得する。 |
| カスタム ビューのリスト | tableau:content:read | サイト上のカスタム ビューのリストを取得します。 |
| ビュー データの照会 | tableau:views:download | レンダリングされたビューをカンマ区切り値 (.csv) 形式で取得する。 |
| ビュー PDF の照会 | tableau:views:download | ビューを PDF ファイル (.pdf) で取得する。 |
| ビュー画像の照会 | tableau:views:download | ビューを画像ファイル (.png) で取得する。 |
| サイトのビューの照会 | tableau:content:read | サイトのすべてのビューを取得する。 |
| ワークブックのビューの照会 | tableau:content:read | 指定されたブックのすべてのビューを取得する。 |
| ビューのプレビュー画像の照会 | tableau:views:download | ビューのサムネイル画像 (.png) を取得する。 |
| カスタム ビューの更新 | tableau:views:update | 既存のカスタム ビューの所有者または名前を変更します。 |
ワークブック | ||
| ワークブックのパブリッシュ | tableau:workbooks:create | ワークブック (.twb または .twbx) をパブリッシュする。 |
| ワークブックの照会 | tableau:content:read | 指定されたワークブックとその詳細を取得する。 |
| サイトのワークブックの照会 | tableau:content:read | サイトにパブリッシュされているワークブックのリストを取得する。 |
| ワークブックのプレビュー画像の照会 | tableau:workbooks:download | ワークブックのサムネイル画像 (.png) を取得する。 |
| ワークブックの更新 | tableau:workbooks:update | 既存のワークブックを変更する。 |
| ワークブック接続の更新 | tableau:workbooks:update | 接続情報を更新する。 |
| 今すぐワークブックを更新 | tableau:tasks:run | スケジュールされたタスクの外でワークブックの更新を開始する。 |
| (ワークブック メソッド) | tableau:workbooks:* | 画像ワークブックのパブリッシュ、更新、ダウンロード、およびプレビュー アクションを有効にする。 |
パブリッシュ | ||
| ファイル アップロードへの追加 | tableau:file_uploads:create | データのブロックをアップロードし、すでにアップロードされているデータに追加する (「ファイル アップロードの開始」メソッドでアップロードが開始された後に使用)。 |
| ファイル アップロードの開始 | tableau:file_uploads:create | ファイルのアップロード プロセスを開始する。 |
ダウンロード | ||
| データ ソースのダウンロード | tableau:datasources:download | データ ソース (.tdsx) をダウンロードする。 |
| ビューのクロス集計 Excel のダウンロード | tableau:views:download | ビューからクロス集計データを含む Excel ファイル (.xlsx) をダウンロードする。 |
| ワークブックのダウンロード | tableau:workbooks:download | ワークブック (.twb または .twbx) をダウンロードする。 |
| ワークブック改訂版のダウンロード | tableau:workbooks:download | ワークブック (.twb または .twbx) の特定のバージョンをダウンロードする。 |
| ワークブック PDF のダウンロード | tableau:views:download | ワークブックのシートの画像を含む PDF ファイル (.pdf) をダウンロードする。 |
| ワークブックの Power Point のダウンロード | tableau:views:download | ワークブックのシートのスライドを含む Power Point ファイル (.pptx) をダウンロードする。 |
ユーザー | ||
| グループへのユーザー追加 | tableau:groups:update | ユーザーをグループに追加する。 |
| サイトへのユーザー追加 | tableau:users:create | ユーザーを追加し、そのユーザーをサイトに割り当てる。 |
| グループ内ユーザーの取得 | tableau:groups:read | グループ内のユーザーの一覧を取得する。 |
| サイト上ユーザーの取得 | tableau:users:read | サイト上のすべてのユーザーを取得する。 |
| サイト上ユーザーの照会 | tableau:users:read | サイト上の 1 人のユーザーを取得する。 |
| グループからのユーザー削除 | tableau:groups:update | ユーザーをグループから削除する。 |
| サイトからのユーザー削除 | tableau:users:delete | ユーザーをサイトから削除する。 |
| (ユーザー メソッド) | tableau:users:* | ユーザー アクションの追加、クエリ、更新、および削除を有効にする。 |
グループ | ||
| グループの作成 | tableau:groups:create | グループを作成する。 |
| グループの削除 | tableau:groups:delete | グループを削除する。 |
| ユーザーのグループの取得 | tableau:users:read | ユーザーが属するグループのリストを取得する。 |
| グループの照会 | tableau:groups:read | サイト上のグループのリストを取得する。 |
| グループの更新 | tableau:groups:update | グループを更新する。 |
| (グループ メソッド) | tableau:groups:* | グループの作成、クエリ、更新、および削除アクションを有効にする。 |
プロジェクト | ||
| プロジェクトの作成 | tableau:projects:create | プロジェクトを作成する。 |
| プロジェクトの削除 | tableau:projects:delete | プロジェクトを削除する。 |
| プロジェクトの照会 | tableau:content:read | プロジェクトのリストを取得する。 |
| プロジェクトの更新 | tableau:projects:update | プロジェクトの名前、説明、プロジェクト階層を更新する。 |
| (プロジェクト メソッド) | tableau:projects:* | プロジェクトの作成、更新、および削除アクションを有効にする。 |
パーミッション | ||
| データ ソース権限の追加 | tableau:permissions:update | Tableau Server のユーザーまたはグループにデータ ソースへのアクセス権限を追加する。 |
| デフォルト権限の追加 | tableau:permissions:update | プロジェクト内のメトリクス、フロー、ワークブック、データ ソース、データの役割、レンズなどのリソースに対するデフォルトの権限機能をユーザーまたはグループに追加する。 |
| プロジェクト権限の追加 | tableau:permissions:update | ユーザーまたはグループにプロジェクトへの権限を追加する |
| 表示権限の追加 | tableau:permissions:update | ユーザーまたはグループにビューへの権限を追加する。 |
| ワークブック権限の追加 | tableau:permissions:update | ユーザーまたはグループに指定されたブックワークへの権限を追加する。 |
| データ ソース権限の削除 | tableau:permissions:delete | プロジェクト内のメトリクス、フロー、ワークブック、データ ソース、データの役割、レンズなどのリソースに対するデフォルトの権限機能をユーザーまたはグループから削除する。 |
| デフォルト権限の削除 | tableau:permissions:delete | プロジェクト内のメトリクス、フロー、ワークブック、データ ソース、データの役割、レンズなどのリソースに対するデフォルトの権限機能をユーザーまたはグループから削除する。 |
| プロジェクト権限の削除 | tableau:permissions:delete | ユーザーまたはグループのプロジェクト権限を削除する。 |
| 表示権限の削除 | tableau:permissions:delete | ユーザーまたはグループの表示権限を削除する。 |
| ワークブック権限の削除 | tableau:permissions:delete | ユーザーまたはグループのワークブック権限を削除する。 |
| データ ソース権限の照会 | tableau:permissions:read | データ ソースの権限のリストを取得する。 |
| デフォルト権限の照会 | tableau:permissions:read | メトリクス、ワークブック、データ ソースに対するユーザーとグループの既定のパーミッション機能を取得します。 |
| プロジェクト権限の照会 | tableau:permissions:read | プロジェクトに対する権限のリストを取得する。 |
| 表示権限の照会 | tableau:permissions:read | ビューに対する権限のリストを取得する。 |
| ワークブック権限の照会 | tableau:permissions:read | ワークブックに対する権限のリストを取得する。 |
| (許可メソッド) | tableau:permissions:* | パーミッションの追加、クエリ、更新、削除アクションを有効にする。 |
サイト | ||
| 最近閲覧したサイトの取得 | tableau:content:read | サインイン ユーザーが最近作成、更新、アクセスしたビューとワークブックの詳細を取得する。 |
| サイトのビューの照会 | tableau:content:read | サイト上のすべてのビューを一覧表示する。 |
| サイトの更新 | tableau:sites:update | サイトを更新する。 |
| (サイト メソッド) | tableau:sites:* | サイトの作成、クエリ、更新、および削除アクションを有効にする。 |
トラブルシューティングのスコープ
401001 - サインイン エラー
エラー 401001 が発生した場合、サインインの応答本文には、追加の接続アプリ固有のエラー コード (16、10084、または 10085) のいずれかが追加されます。
たとえば、次の応答本文では、「10084」は接続アプリのエラー コードであり、REST API 認証に JWT を使用して Tableau Cloud にサインインする際に起こる問題のトラブルシューティングに役立ちます。
<error code="401001"> "summary": "Signin Error", "detail": "Error signing in to Tableau Cloud (10084)" </error>
問題を解決するには、該当するエラー コードとその潜在的な原因の説明を参照してください。
16: Cloud でユーザーが見つかりません - このエラーは、正しくない「
sub」 (ユーザー名) が指定されると発生する可能性があります。
10084: Cloud でアクセス トークンを解析できませんでした - このエラーは、次の理由で発生する可能性があります。
- JWT が無効であるか、予期しない問題が発生しました
- 正しくない [
aud] (オーディエンス) が指定されました - 直接信頼の場合、シークレットの署名に問題がありました
10085: Cloud でクライアント ID の署名を検証するためのシークレットを取得できませんでした - このエラーは、次の理由で発生する可能性があります。
- 指定された [
iss] のクライアント ID が正しくありません - 直接信頼の場合、正しくない [
kid] (シークレット ID) が指定されました
- 指定された [
401002 - 不正アクセス エラー
エラー 401002 が発生し、リクエストを行う適切なパーミッションがあることを確認した場合は、JWT に含まれるスコープが正しく、作成しようとしているリクエストと一致していることを確認してください。エンドポイントとサポートされるスコープのリストについては、上記の「JWT 認可をサポートする REST API メソッド」セクションを参照してください。