Tableau Cloud 說明

開始從 2022 年 6 月開始，使用 Tableau 已連線應用程式，可以代表 Tableau Cloud 使用者透過自訂應用程式以程式控制方式呼叫和存取 Tableau REST API。對 REST API 的存取可由定義為初始登入請求一部分的 JSON Web 權杖 (JWT) 啟用。JWT 必須包含範圍，該範圍透過已連線應用程式定義可用於自訂應用程式及其使用者的 REST API 方法。

使用已連線應用程式授權對 REST API 的存取可：

• 提高效率 — 使用 JWT 作為持有人權杖可以簡化模擬，向登入端點發出一個請求，而不是兩個請求
• 擴充和自動執行複雜的 Tableau 整合和後端查詢，例如動態內容擷取和進階篩選

範圍動作

已連線應用程式使用的範圍會透過支援 JWT 授權的 REST API 方法授予對內容或管理工作動作的存取權（如下）。範圍是一個以冒號分隔的字串，以命名空間 tableau 開頭，後跟會被授予存取權的 Tableau 資源，例如 datasources，並以允許對資源執行的動作結尾，例如 update。

範圍可以執行的動作包括：

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

例如，允許自訂應用程式呼叫更新資料來源(連結在新視窗開啟)方法的範圍如下所示：

tableau:datasources:update

範圍類型

您使用的範圍類型取決於要啟用的內容或管理動作。範圍通常屬於以下類型之一：內容讀取、個別、萬用字元和跨類別。

• 內容閱讀範圍：內容閱讀範圍，tableau:content:read , 為 Tableau 內容啟用可支援的 GET 方法。使用此範圍時，可以跨 REST API 類別啟用動作。更具體地說，使用此範圍可以為資料來源、指標、檢視、工作簿、專案和站台啟用 GET 方法。從 Tableau Cloud 2023 年 10 月，您也可以在 JWT 中指定此範圍，該範圍將用於建立與 中繼資料 API(連結在新視窗開啟) 一同使用的認證權杖。

  附註：要為使用者與群組等管理動作啟用 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 類別中的獲取/列出、新增、刪除、更新動作。
  • 可以使用 tableau:tasks:* 萬用字元範圍啟用擷取和訂閱 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. 使用以下方法之一建立已連線應用程式：
   • 使用直接信任設定已連線應用程式
   • 使用 OAuth 2.0 信任設定已連線應用程式
2. 產生有效的 JWT — 在執行階段，自訂應用程式將產生有效的 JWT，並設定為已包含的範圍
3. 發出登入(連結在新視窗開啟)請求 — 自訂應用程式將使用 JWT 發出登入請求，以傳回 Tableau 認證權杖和站台識別碼 (LUID)
4. 在後續請求中使用 Tableau 認證權杖 — 在後續 REST API 呼叫中，使用 1) Tableau 認證權杖作為 X-Tableau-Auth(連結在新視窗開啟) 標頭值和 2) 請求 URI 中的站台識別碼 (LUID)

範例

例如，假設已使用直接信任建立已連線應用程式。透過直接信任，呼叫 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 授權支援，但不需要使用自 2023 年 6 月 (Tableau 2023.2) 開始的範圍。
• 對於內嵌 API v3 支援的範圍，請參閱以下內容之一：
  • 使用直接信任設定已連線應用程式
  • 使用 OAuth 2.0 信任設定已連線應用程式

萬用字元 (*) 範圍

萬用字元範圍使用萬用字元 (*) 而不是特定動作，以在特定 REST API 類別中啟用多個受支援的動作。其中包括：

跨類別範圍

跨類別範圍可啟用跨多個 REST API 類別支援的多個動作。其中包括：

個別範圍

權限範圍疑難排解

401001 - 登入錯誤

如果遇到錯誤 401001，登入回應主體將附加以下特定於連線的應用程式附加錯誤程式碼之一：16、10084 或 10085。

例如，在以下回應主體中，「10084」是連線的應用程式錯誤程式碼，可以使用它來幫助解決使用 JWT 進行 REST API 授權登入至 Tableau Cloud 的問題。

<error code="401001">  
  "summary": "Signin Error",
  "detail": "Error signing in to Tableau Cloud (10084)"
</error>

為幫助解決問題，請參閱適用的錯誤程式碼及其潛在原因的描述。

• 16：找不到使用者 — 這個錯誤可能是因為不正確的「sub」（使用者名稱）已指定

• 10084：無法解析存取權杖 — 出現此錯誤的原因可能如下：

  • JWT 無效或出現意外問題
  • 指定不正確「aud」（觀眾）
  • 對於直接信任，簽署密碼時出現問題

• 10085：無法獲取密碼以驗證用戶端識別碼的簽署 — 出現此錯誤的原因可能如下：

  • 指定「iss」中不正確的用戶端識別碼
  • 對於直接信任，指定不正確的「kid」（密碼識別碼）
  • 對於OAuth 2.0 信任，無法從 JWKSource 獲取金鑰

401002 - 未經授權的存取錯誤

如果遇到錯誤 401002 並且已確認您具有發出請求的適當權限，請確保 JWT 中包含的權限範圍是正確的，並且與您嘗試做出的請求相符。有關端點和支援權限範圍的清單，請參閱上方支援 JWT 授權的 REST API 方法區段。