已连接应用的访问范围

从 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(链接在新窗口中打开) 一起使用的凭据令牌。从 Tableau Server2025.1 开始，您还可以在 JWT 中指定此范围，JWT 将用于创建与 VizQL Data Service(链接在新窗口中打开) 一起使用的凭据令牌。
注意：若要为用户和组等管理操作启用 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 凭据令牌和站点 ID (LUID)
在后续请求中使用 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 凭据令牌后，将其添加到所有后续 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

注意：

从 Tableau Server 2023.3 开始，JWT 授权支持登录(链接在新窗口中打开)和注销(链接在新窗口中打开)方法，但不需要使用范围。
对于 Embedding 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 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 方法部分。

回到顶部

感谢您的反馈!

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

Linux 版 Tableau Server 帮助