Linux 版 Tableau Server 帮助

从 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: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. 使用以下方法之一创建已连接应用：
   • 配置 Tableau 已连接应用以启用嵌入内容的 SSO
   • 注册 EAS 以启用嵌入内容的 SSO
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 REST API 帮助中的身份验证方法(链接在新窗口中打开)。
• 从 Tableau Server 2023.3 开始，JWT 授权支持登录(链接在新窗口中打开)和注销(链接在新窗口中打开)方法，但不需要使用范围。
• 对于 Embedding API v3 支持的范围，请参见以下内容之一：
  • 配置 Tableau 已连接应用以启用嵌入内容的 SSO
  • 注册 EAS 以启用嵌入内容的 SSO

通配符 (*) 范围

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

跨类别范围

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

个别范围

故障排除范围

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 方法部分。