Tableau Cloud ヘルプ

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 メソッドを有効にします。Tableau Cloud 2023 年 10 月 以降は、メタデータ API(新しいウィンドウでリンクが開く) で使用する認証資格情報トークンの作成に使用される JWT でこのスコープも指定します。

  注: ユーザーやグループなどの管理アクションに対する 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 カテゴリで create、delete、および update アクションを有効にできます。
  • ワイルドカード スコープ tableau:users:* を使用すると、ユーザーの REST API カテゴリで get/list、add、delete、および update アクションを有効にできます。
  • ワイルドカード スコープ tableau:tasks:* を使用すると、抽出とサブスクプションの REST API カテゴリで get/list、add、delete、update、および run アクションを有効にできます。また、このスコープは、データ ソースの更新 (抽出の場合) とワークブックの更新を有効にします。

• クロスカテゴリ スコープ: コンテンツ読み取りスコープに加えて、使用された場合、さまざまな 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. 次のいずれかの方法を使用して、連携アプリを作成します。
   • 直接信頼を使用して接続済みアプリを設定する
   • OAuth 2.0 信頼を使用して接続済みアプリを設定する
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 アクセス トークンが生成されたら、後続のすべての REST API リクエストのヘッダーに追加します。

ヘッダー

X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd

Tableau アクセス トークンを使用する後続のすべての REST API リクエストは、JWT のスコープによって制限されます。

JWT 認可をサポートする REST API メソッド

次のスコープを連携アプリに関連付けて、カスタム アプリケーションがユーザーに代わって REST API(新しいウィンドウでリンクが開く) に対して持つことができるアクセス権とメソッドを定義できます。

注:

• 以下の表にリストアップされていない REST API 機能については、他の認可メカニズムを使用してメソッドにアクセスできます。詳細については、Tableau REST API ヘルプの「認証メソッド(新しいウィンドウでリンクが開く)」を参照してください。
• サインイン(新しいウィンドウでリンクが開く)とサインアウト(新しいウィンドウでリンクが開く)のメソッドは、共に JWT 認証でサポートされていますが、2023 年 6 月 (Tableau 2023.2).以降では、スコープを使用する必要はありません。
• 埋め込み API v3 でサポートされているスコープについては、次のいずれかを参照してください。
  • 直接信頼を使用して接続済みアプリを設定する
  • OAuth 2.0 信頼を使用して接続済みアプリを設定する

ワイルドカード (*) スコープ

ワイルドカード スコープは、特定のアクションではなく、ワイルドカード文字 (*) を使用して、特定の REST API カテゴリ内でサポートされている複数のアクションを有効にします。これらのスコープには以下が含まれます。

クロスカテゴリ スコープ

クロスカテゴリ スコープは、複数の REST API カテゴリにまたがってサポートされている複数のアクションを有効にします。これらのスコープには以下が含まれます。

個別スコープ

トラブルシューティングのスコープ

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 メソッド」セクションを参照してください。