已連線應用程式的存取範圍

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

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

增強安全性 - 使用 JWT 作為持有人權杖本質上比透過 .env 檔案在保存庫中儲存和管理管理員使用者密碼更安全
提高效率 — 使用 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 Server 2023.3，您也可以在 JWT 中指定此範圍，該範圍將用於建立與中繼資料 API(連結在新視窗開啟) 一同使用的認證權杖。從 Tableau Server 2025.1 開始，也可以在 JWT 中指定此範圍，JWT 將用於建立與 VizQL 資料服務(連結在新視窗開啟)一起使用的認證權杖。
附註：要為使用者與群組等管理動作啟用 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 的步驟：

使用以下方法之一建立已連線應用程式：
- 使用直接信任設定已連線應用程式
- 使用 OAuth 2.0 信任設定已連線應用程式
產生有效的 JWT — 在執行階段，自訂應用程式將產生有效的 JWT，並設定為已包含的範圍
發出登入(連結在新視窗開啟)請求 — 自訂應用程式將使用 JWT 發出登入請求，以傳回 Tableau 認證權杖和站台識別碼 (LUID)
在後續請求中使用 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://myco/api/3.17/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 方法

已連線應用程式的範圍授與自訂應用程式代表使用者存取 Tableau REST API 功能的權限

可以在 Tableau REST API(連結在新視窗開啟) 說明的屬性區塊中找到 JWT 支援的方法所需的範圍。若範圍未在方法的屬性區塊中列出，則無法透過 JWT 控制對此方法的存取。

例如，允許您在 Tableau REST API 中呼叫查詢站台(連結在新視窗開啟)方法的範圍為 tableau:sites:read

附註：

登入(連結在新視窗開啟)與登出(連結在新視窗開啟)方法均由 JWT 授權支援，但不需要使用自 Tableau Server 2023.3 開始的範圍。
對於內嵌 API v3 支援的範圍，請參閱以下內容之一：
- 使用直接信任設定已連線應用程式
- 使用 OAuth 2.0 信任設定已連線應用程式

關於萬用字元 (*) 範圍

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

範例

範圍	啟用方法
`tableau:datasources:*`	啟用建立、更新和更新連線資料來源方法。
`tableau:metrics:*`	啟用查詢、更新和刪除指標動作。
`tableau:workbooks:*`	啟用發佈、更新、下載和預覽圖像工作簿動作。
`tableau:groups:*`	啟用建立、查詢、更新和刪除群組動作。
`tableau:projects:*`	啟用建立、刪除和更新專案方法。
`tableau:users:*`	啟用獲取/列出、新增、刪除和更新使用者方法。
`tableau:tasks:` 附註：*這個範圍也是跨類別的。	啟用擷取和訂閱任務的獲取/列出、新增、刪除和更新和執行方法。啟用工作簿資料來源的更新方法。

關於跨類別範圍

跨類別範圍可跨多個 Tableau REST API 類別啟用多個支援動作。

範例

範圍	啟用方法
`tableau:content:read`	啟用 Tableau 內容的讀取/列出方法，包括資料來源、指標、檢視、工作簿、專案和站台。
`tableau:tasks:run`	啟用資料來源、工作簿和資料擷取的執行方法。
`tableau:views:download`	啟用查看資料和工作簿的下載方法。
`tableau:tasks:` 附註：*此範圍也是萬用字元。	啟用擷取和訂閱任務的獲取/列出、新增、刪除和更新和執行方法。啟用工作簿資料來源的更新方法。

權限範圍疑難排解

401001 - 登入錯誤

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

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

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

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

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

10084：無法解析存取權杖 — 出現此錯誤的原因可能如下：
- JWT 無效或出現意外問題
- 指定不正確「aud」（觀眾）
- 對於直接信任，簽署密碼時出現問題
10085：無法獲取密碼以驗證用戶端識別碼的簽署 — 出現此錯誤的原因可能如下：
- 指定「iss」中不正確的用戶端識別碼
- 對於直接信任，指定不正確的「kid」（密碼識別碼）
- 對於EAS，無法從 JWKSource 獲取金鑰

401002 - 未經授權的存取錯誤

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

返回頂端

感謝您的意見反應！

已成功提交您的意見回饋。謝謝！

Linux 版 Tableau Server 說明