已连接应用的访问范围

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 Server2023.3 开始,您还可以在 JWT 中指定此范围,JWT 将用于创建与元数据 API(链接在新窗口中打开) 一起使用的凭据令牌。

    注意:若要为用户和组等管理操作启用 GET 方法,您可以使用它们的单独范围。

  • 单独范围:若要启用受支持的内容和管理操作,您可以使用它们的单独范围。单独范围通常与单个方法和 REST API 类别相关联。

    示例:

    • 若要启用发布或更新数据源操作,您可以分别使用单独的 tableau:datasources:createtableau:datasources:update 范围。
    • 对于添加或移除用户等管理操作,您可以分别使用单独的 tableau:users:createtableau: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:updatetableau: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) 使用请求 URI 中的站点 ID (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 访问令牌后,将 Tableau 凭据令牌添加到所有后续 REST API 请求的标头中。

标头

X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd

然后,使用 Tableau 访问令牌的所有后续 REST API 请求都受 JWT 中的范围限制。

支持 JWT 授权的 REST API 方法

以下范围可以与已连接应用相关联,以定义您的自定义应用程序可以代表用户对 REST API(链接在新窗口中打开) 具有的访问权限和方法。

注意:

通配符 (*) 范围

通配符范围使用通配符 (*) 而不是特定操作,以在特定 REST API 类别中启用多个受支持的操作。这些事件包括:

范围启用的方法
tableau:datasources:*启用创建、更新和更新连接数据源方法。
tableau:metrics:*启用查询、更新和删除指标操作。
tableau:workbooks:*启用发布、更新、下载和预览图像工作簿操作。
tableau:groups:*启用创建、查询、更新和删除组操作。
tableau:projects:*启用创建、删除和更新项目方法。
tableau:users:*启用获取/列出、添加、删除和更新用户方法。
tableau:tasks:*

注意:此范围也是跨类别的。

启用数据提取和订阅任务的获取/列出、添加、删除、更新和运行方法。

启用工作簿数据源的更新方法。

跨类别范围

跨类别范围启用跨多个 REST API 类别的多个受支持的操作。这些事件包括:

范围启用的方法
tableau:content:read启用 Tableau 内容(包括数据源、指标、视图、工作簿、项目和站点)的读取/列出方法。
tableau:tasks:run启用数据源、工作簿和数据提取的运行方法。
tableau:views:download启用视图数据和工作簿的下载方法。
tableau:tasks:*

注意:此范围也是通配符。

启用数据提取和订阅任务的获取/列出、添加、删除、更新和运行方法。

启用工作簿数据源的更新方法。

个别范围

方法范围描述
(没有范围的方法)(无)如果在 JWT 中未定义任何范围,则拒绝访问 REST API。
登录(无需范围)让您以用户身份登录 Tableau Server 上的指定站点
注销(无需范围)让您退出当前会话。
(内容读取范围)tableau:content:read启用 Tableau 内容的读取/列出t操作:数据源、指标、视图、工作簿和项目。

标签

  
删除标签tableau:labels:delete根据 LUID 删除数据标签。
删除标签tableau:labels:delete删除一个或多个资产上的数据标签。
获取标签tableau:labels:read通过 LUID 获取数据标签。
获取标签tableau:labels:read显示有关一个或多个资产的数据标签的信息。
更新标签tableau:labels:update通过 LUID 更新标签。
更新标签tableau:labels:update在一个或多个资产上创建或更新标签。

数据源

  
(所有 tableau:datasources: 方法)tableau:datasources:*启用创建数据源、更新数据源和更新数据源连接方法。
发布数据源tableau:datasources:create将数据源发布到站点或将数据附加到现有的已发布数据源。
查询数据源tableau:content:read获取有关已发布数据源的信息。
查询数据源tableau:content:read获取有关站点上所有已发布数据源的信息。
查询数据源连接tableau:content:read获取有关已发布数据源的服务器地址、端口、用户名或密码信息。
更新数据源tableau:datasources:update更新数据源的所有者、项目或认证状态。
更新数据源连接tableau:datasources:update更新数据源连接的服务器地址、端口、用户名或密码。
立即更新数据源tableau:tasks:run运行数据提取刷新。

数据提取

  
(所有 tableau:tasks: 方法)tableau:tasks:*启用数据提取、订阅、更新数据源(对于具有数据提取的数据源)和更新工作簿方法的创建、删除、获取、列出、运行和更新刷新操作。
列出站点中的数据提取刷新任务tableau:tasks:read列出站点中配置的数据提取刷新任务。
运行数据提取刷新任务tableau:tasks:run运行数据提取刷新任务。

流程

  
发布流程tableau:flows:create发布流程。

指标

旧版指标功能的停用

Tableau 的旧版指标功能在 Tableau Cloud 2024 年 2 月版和 Tableau Server 版本 2024.2 中已停用。2023 年 10 月,Tableau 停用了将旧版指标嵌入到 Tableau Cloud 和 Tableau Server 版本 2023.3 的功能。借助 Tableau Pulse,我们开发了一种改进的体验来跟踪指标和询问数据问题。有关详细信息,请参见使用 Tableau Pulse 创建指标以了解新体验,并参见创建指标并排查其问题(已停用)了解已停用的功能 。

(所有 tableau:metrics: 方法)tableau:metrics:*启用查询、更新和删除指标操作。
(所有 tableau:metrics: 方法)tableau:metrics:*启用查询、更新和删除指标操作。
获取指标tableau:content:read获取指标。
删除指标tableau:metrics:delete删除指标。
列出指标tableau:content:read获取站点的指标列表。
查询指标数据tableau:metrics:download以逗号分隔值 (.csv) 格式获取指标的基础数据。
更新指标tableau:metrics:update更新指标的所有者、项目、暂停状态和名称。

订阅

  
(所有 tableau:tasks: 方法)tableau:tasks:*启用数据提取、订阅、更新数据源(对于具有数据提取的数据源)和更新工作簿方法的创建、删除、获取、列出、运行和更新刷新操作。
创建订阅tableau:tasks:create创建订阅。
删除订阅tableau:tasks:delete删除订阅。
获取订阅tableau:tasks:read获取订阅的详细信息。
列出订阅tableau:tasks:read列出站点中的订阅。
更新订阅tableau:tasks:update更新订阅。

视图

  
删除自定义视图tableau:views:update删除指定的自定义视图。
获取自定义视图tableau:content:read获取指定自定义视图的详细信息。
获取自定义视图图像tableau:views:download下载指定自定义视图的 .png 格式图像文件。
获取视图tableau:content:read获取有关视图的详细信息。
按路径获取视图tableau:content:read使用指定名称获取站点上所有视图的详细信息。
列出自定义视图tableau:content:read获取站点上的自定义视图列表。
查询视图数据tableau:views:download获取以逗号分隔值 (.csv) 格式呈现的视图。
查询视图 PDFtableau:views:download以 PDF (.pdf) 文件形式获取视图。
查询视图图像tableau:views:download以图像 (.png) 文件形式获取视图。
查询站点的视图tableau:content:read获取站点的所有视图。
查询工作簿的视图tableau:content:read获取指定工作簿的所有视图。
查询视图预览图像tableau:views:download获取视图的缩略图 (.png)。
更新自定义视图tableau:views:update更改现有自定义视图的所有者或名称。

工作簿

  
(所有 tableau:workbooks: 方法)tableau:workbooks:*启用发布、更新、下载和预览图像工作簿操作。
发布工作簿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:file_uploads:create上载数据块并将其附加到已上载的数据中 - 在使用“启动文件上载”方法启动上载后使用。
启动文件上载tableau:file_uploads:create启动文件的上载过程。

下载

  
下载数据源tableau:datasources:download下载数据源 (.tdsx)。
下载视图交叉表 Exceltableau:views:download从视图下载包含交叉表数据的 Excel (.xlsx) 文件。
下载工作簿tableau:workbooks:download下载工作簿(.twb 或 .twbx)。
下载工作簿修订版tableau:workbooks:download下载特定版本的工作簿(.twb 或 .twbx)。
下载工作簿 PDFtableau:views:download下载包含工作簿中工作表图像的 PDF (.pdf) 文件。
下载工作簿 PowerPointtableau:views:download下载包含工作簿中工作表幻灯片的 PowerPoint (.pptx) 文件。

用户

  
(所有 tableau:users 方法)tableau:users:*启用添加、查询、更新和移除用户操作。
将用户添加到组tableau:groups:update将用户添加到组。
将用户添加到站点tableau:users:create添加用户并将用户分配给站点。
获取组中的用户tableau:groups:read获取组中的用户列表。
获取站点上的用户tableau:users:read获取站点上的所有用户。
查询站点上的用户tableau:users:read获取站点上的用户。
从组中移除用户tableau:groups:update从组中移除用户。
从站点中移除用户tableau:users:delete从站点中移除用户。

  
(所有 tableau:groups: 方法)tableau:groups:*启用创建、查询、更新和删除组操作。
创建组tableau:groups:create创建组。
删除组tableau:groups:delete删除组。
获取用户的组tableau:users:read获取用户所属的组列表。
查询组tableau:groups:read获取站点上的组列表。
更新组tableau:groups:update更新组。

项目

  
(所有 tableau:projects: 方法)tableau:projects:*启用创建、更新和删除项目操作。
创建项目tableau:projects:create创建一个项目。
删除项目tableau:projects:delete删除一个项目。
查询项目tableau:content:read获取项目列表。
更新项目tableau:projects:update更新项目的名称、描述或项目层次结构。

权限

  
(所有 tableau:permissions: 方法)tableau:permissions:*启用添加、查询、更新、删除权限操作。
添加数据源权限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:sites: 方法)tableau:sites:*启用创建、查询、更新和删除站点操作。
创建站点tableau:sites:create在 Tableau Server 上创建站点。
获取最近查看的站点tableau:content:read获取登录用户最近创建、更新或访问的视图和工作簿详细信息。
查询站点tableau:sites:read列出 Tableau Server 上的所有站点。
查询站点的视图tableau:content:read列出站点上的所有视图。
更新站点tableau:sites:update更新站点。

故障排除范围

401001 - 登录错误

如果您遇到错误 401001,登录响应正文将附加以下附加的特定于已连接应用的错误代码之一:16、10084 或 10085。

例如,在以下响应正文中,“10084”是已连接应用错误代码,您可以使用它来帮助解决使用 JWT for 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:无法获取密文以验证客户端 ID 的签名 — 出现此错误的原因可能如下:

    • 指定的“iss”中的客户端 ID 不正确
    • 对于直接信任,指定了不正确的“kid”(密文 ID)
    • 对于 EAS ,无法从 JWKSource 获取密文

401002 - 未经授权的访问错误

如果您遇到错误 401002 并且已确认您具有发出请求的适当权限,请确保 JWT 中包含的范围是正确的并且与您尝试发出的请求相匹配。有关端点和受支持范围的列表,请参见上面支持 JWT 授权的 REST API 方法部分。

感谢您的反馈!您的反馈已成功提交。谢谢!