接続済みアプリのアクセス スコープ

2022 年 6 月移以降 、Tableau 接続済みアプリを使用すると、Tableau Cloud ユーザーに代わって実行するカスタム アプリケーションを通じて、Tableau REST API をプログラムで呼び出し、アクセスできるようになりました。最初にサインインを要求するときに定義される JSON Web トークン (JWT) を使用することにより、REST API へのアクセスが可能になります。JWT 内のスコープには、カスタムアプリケーションとそのユーザーが連携アプリを通じて利用できる REST API メソッドが定義されている必要があります。

REST API へのアクセスを連携アプリを使用して承認することにより、次を実現します。

  • 効率の向上 — JWT をベアラー トークンとして使用すると、2 つのリクエストではなく、サインイン エンドポイントへの 1 つのリクエストで偽装を簡単化することができます
  • 動的なコンテンツ検索や高度なフィルタリングなど、複雑な Tableau 統合とバックエンド クエリを拡張および自動化します

スコープ アクション

接続済みアプリが使用するスコープは、JWT 認可をサポートする REST API メソッド (下記) を通じて、コンテンツや管理アクションへのアクセス権を付与します。スコープはコロンで区切られた文字列であり、名前空間 tableau で始まり、アクセスが許可されている Tableau リソース (datasources など) が続き、そのリソースに対して許可されているアクション (update など) で終わります。

スコープが実行できるアクションは次のとおりです。

  • create
  • read
  • run
  • update
  • download
  • delete

たとえば、カスタム アプリケーションが 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 へのアクセスをリクエストする手順をまとめたものです。

  1. 次のいずれかの方法を使用して、連携アプリを作成します。
  2. 有効な JWT を生成します。カスタム アプリケーションは、指定したスコープで設定された有効な JWT を実行時に生成します
  3. サインイン(新しいウィンドウでリンクが開く) リクエストを行います。カスタム アプリケーションは、JWT を使用してサインインをリクエストし、Tableau 認証資格情報トークンとサイトID (LUID) を返します。
  4. 後続のリクエストで 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(新しいウィンドウでリンクが開く) に対して持つことができるアクセス権とメソッドを定義できます。

注:

メソッドスコープ説明
スコープなし(スコープなし)JWT でスコープが定義されていない場合、REST API へのアクセスは拒否されます。
サインイン(スコープなし)Tableau Cloud のユーザーとして、にサインインします。
サインアウト(スコープなし)現在のセッションからサインアウトします。
(コンテンツ読み取りスコープ)tableau:content:readTableau コンテンツ (データ ソース、メトリクス、ビュー、ワークブック、プロジェクト) に対するクエリ アクションを有効にする。

データ ソース

  
データ ソースのパブリッシュ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:updateTableau 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) が指定されました
    • OAuth 2.0 信頼 で、JWKSource からキーを取得できませんでした

401002 - 不正アクセス エラー

エラー 401002 が発生し、リクエストを行う適切なパーミッションがあることを確認した場合は、JWT に含まれるスコープが正しく、作成しようとしているリクエストと一致していることを確認してください。エンドポイントとサポートされるスコープのリストについては、上記の「JWT 認可をサポートする REST API メソッド」セクションを参照してください。

ありがとうございます!