--- schema_version: "1" id: e9ec9f96b518f545f64a80bfb014b9ebe0122e710abd69bc086977e026131399 title: 已连接应用的访问范围 collection: tableau version: next locale: zh-cn portal_url: https://docs.salesforce.com/tableau/next/zh-cn/server-linux/connected_apps_scopes.md canonical_url: https://help.tableau.com/v0.0/server-linux/zh-cn/connected_apps_scopes.htm source_site: help.tableau.com content_type: documentation content_hash: f62dd6e1e8a7aed8aa5958c5f33d87dae4e20d844ac4a34a566fdeed1af4a017 description: Reference of access scopes that authorize REST API methods for connected apps via JWT. --- [跳转到主要内容](#main-content) # 已连接应用的访问范围 从 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 方法](#scopes)（见下文）授予对内容或管理操作的访问权限。范围是一个以冒号分隔的字符串，以命名空间 `tableau` 开头，后跟被授予访问权限的 Tableau 资源，例如 `datasources`,并以允许对资源执行的操作结尾，例如 `update`。 范围可进行的操作包括： - `create` - `read` - `run` - `update` - `download` - `delete` 例如，允许您的自定义应用程序调用[更新数据源](https://help.tableau.com/current/api/rest_api/zh-cn/REST/rest_api_ref_data_sources.htm#update_data_source)方法的范围如下所示：`tableau:datasources:update` ## 范围类型 您使用的范围类型取决于您要启用的内容或管理操作。范围通常属于以下类型之一：内容读取、个人、通配符和跨类别。 - **内容读取范围：**内容读取范围 `tableau:content:read` 为 Tableau 内容启用受支持的 GET 方法。使用此范围时，您可以跨 REST API 类别启用操作。更具体地说，使用此范围可以为数据源、指标、视图、工作簿、项目和站点启用 GET 方法。从 Tableau Server2023.3 开始，您还可以在 JWT 中指定此范围，JWT 将用于创建与[元数据 API](https://help.tableau.com/current/api/metadata_api/zh-cn/docs/meta_api_auth.html) 一起使用的凭据令牌。从 Tableau Server2025.1 开始，您还可以在 JWT 中指定此范围，JWT 将用于创建与 [VizQL Data Service](https://help.tableau.com/current/api/vizql-data-service/zh-cn/index.html) 一起使用的凭据令牌。 **注意：**若要为用户和组等管理操作启用 GET 方法，您可以使用它们的单独范围。 - **单独范围：**若要启用受支持的内容和管理操作，您可以使用它们的单独范围。单独范围通常与单个方法和 REST API 类别相关联。 示例： - 若要启用发布或更新数据源操作，您可以分别使用单独的 `tableau:datasources:create` 或 `tableau:datasources:update` 范围。 - 对于添加或移除用户等管理操作，您可以分别使用单独的 `tableau:users:create` 或`tableau:users:delete` 范围。 **注意：**有一些单独的范围可以跨 REST API 类别启用操作。例如，`tableau:views:download`在视图数据和工作簿 REST API 类别中启用操作。 - **[通配符范围：](#wildcard)**对于某些范围，您可以将操作替换为通配符 (\*)，以启用特定 REST API 类别中支持的操作。 示例： - 您可以使用 `tableau:projects:*` 通配符范围，用于在项目 REST API 类别中启用创建、删除和更新操作。 - 您可以使用 `tableau:users:*` 通配符范围启用用户 REST API 类别中的获取/列出、添加、删除、更新操作。 - 您可以使用 `tableau:tasks:*` 通配符范围启用数据提取和订阅 REST API 类别中的获取/列出、添加、删除、更新和运行操作。此外，此范围还支持更新数据源（如果是数据提取）和更新工作簿。 - **[跨类别范围：](#cross)**除了内容读取范围之外，还有一些额外的范围，如果使用它们，则支持跨不同 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. 使用以下方法之一**创建已连接应用**： - [使用直接信任配置已连接应用](https://help.tableau.com/v0.0/server-linux/zh-cn/connected_apps_direct.htm) - [使用 OAuth 2.0 信任配置已连接应用](https://help.tableau.com/v0.0/server-linux/zh-cn/connected_apps_eas.htm) 2. **生成有效的 JWT** — 在运行时，您的自定义应用程序将生成一个有效的 JWT，并使用您包含的范围进行配置 3. **发出[登录](https://help.tableau.com/current/api/rest_api/zh-cn/REST/rest_api_ref_authentication.htm#sign_in)请求** — 您的自定义应用程序将使用 JWT 发出登录请求以返回 Tableau 凭据令牌和站点 ID (LUID) 4. **在后续请求中使用 Tableau 访问令牌** — 在后续 REST API 调用中，使用 1) Tableau 凭据令牌作为 [`X-Tableau-Auth`](https://help.tableau.com/current/api/rest_api/zh-cn/REST/rest_api_concepts_auth.htm#using_auth_token) 标头值，以及 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，如下例所示。 ``` ``` **响应正文** 登录请求会生成以下响应正文，其中包括 Tableau 凭据令牌。 ``` ``` 生成 Tableau 凭据令牌后，将其添加到所有后续 REST API 请求的标头中。 **标头** X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd 然后，使用 Tableau 访问令牌的所有后续 REST API 请求都受 JWT 中的范围限制。 ## 支持 JWT 授权的 REST API 方法 已连接应用的范围授予您的自定义应用程序代表用户访问 Tableau REST API 功能的权限 ### 如何查找范围 您可以在 [Tableau REST API](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api.htm) 帮助中 JWT 支持的方法的属性块中找到该方法所需的范围。如果方法的属性块中未列出范围，则 JWT 无法控制对该方法的访问。 例如，允许您在 Tableau REST API 中调用[查询站点](https://help.tableau.com/current/api/rest_api/zh-cn/REST/rest_api_ref_site.htm#query_site)方法的范围是 `tableau:sites:read`。 **注意：** - 从 Tableau Server 2023.3 开始，JWT 授权支持[登录](https://help.tableau.com/current/api/rest_api/zh-cn/REST/rest_api_ref_authentication.htm#sign_in)和[注销](https://help.tableau.com/current/api/rest_api/zh-cn/REST/rest_api_ref_authentication.htm#sign_out)方法，但不需要使用范围。 - 对于 Embedding API v3 支持的范围，请参见以下内容之一： - [使用直接信任配置已连接应用](https://help.tableau.com/v0.0/server-linux/zh-cn/connected_apps_direct.htm) - [使用 OAuth 2.0 信任配置已连接应用](https://help.tableau.com/v0.0/server-linux/zh-cn/connected_apps_eas.htm) - 从 Tableau Server 2025.3 开始，列出的范围子集还支持通过统一访问令牌 (UAT) 进行 REST API 授权。这意味着已连接应用和 UAT 范围是相同的。 ### 范围类型 #### 关于通配符 (\*) 范围 通配符范围使用通配符 (\*) 而不是特定操作，以在特定 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 的问题。 "summary": "Signin Error", "detail": "Error signing in to Tableau Cloud (10084)" 为帮助解决问题，请参阅适用的错误代码及其潜在原因的描述。 - **16：找不到用户** — 这个错误可能是因为指定了不正确的“`sub`”（用户名） - **10084：无法解析访问令牌** — 出现此错误的原因可能如下： - JWT 无效或出现意外问题 - 指定了不正确的“`aud`”（受众） - 对于直接信任，签署密文时出现问题 - **10085：无法获取密文以验证客户端 ID 的签名** — 出现此错误的原因可能如下： - 指定的“`iss`”中的客户端 ID 不正确 - 对于直接信任，指定了不正确的“`kid`”（密文 ID） - 对于 EAS ，无法从 JWKSource 获取密文 ### 401002 - 未经授权的访问错误 如果您遇到错误 401002 并且已确认您具有发出请求的适当权限，请确保 JWT 中包含的范围是正确的并且与您尝试发出的请求相匹配。有关端点和受支持范围的列表，请参见上面[支持 JWT 授权的 REST API 方法](#scopes)部分。