本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 使用 Amazon QuickSight API 在下文中，您可以了解如何开始使用 Amazon QuickSight API。 **Topics** + [提出 API 请求](qs-api-making-api-requests.md) + [Amazon 资源名称 (ARN) QuickSight](qs-arns.md) + [Amazon 权限。 QuickSight 资源](qs-api-permissions.md) + [亚马逊 QuickSight API 错误](qs-api-errors.md) # 提出 API 请求 我们为Amazon 提供 API。 QuickSight，以及使您能够访问亚马逊的亚马逊软件开发工具包 QuickSight 来自您首选的编程语言。使用 Amazon QuickSight，您可以使用 Amazon 开发工具包管理部署的某些方面。 监控拨打Amazon 的电话 QuickSight 你账户的 API，你可以使用AWS CloudTrail. CloudTrail 可以监视由AWS 管理控制台、命令行工具和其他服务。有关更多信息，请参阅《[AWS CloudTrail 用户指南](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/)》。 **Topics** + [先决知识。](#qs-api-required-knowledge) + [Amazon 可以使用的 API 操作 QuickSight](#qs-api-using-libraries) ## 先决知识。 如果您计划访问亚马逊 QuickSight 通过 API，您应该熟悉以下内容： + JSON + Web 服务 + HTTP 请求 + 一种或多种编程语言，如 JavaScript、C\$1、C\$1。 我们建议访问。AWS [开始使用资源中心](https://aws.amazon.com//getting-started/tools-sdks/)了解亚马逊软件开发工具包和工具包必须提供的内容。 尽管您可以使用终端和自己喜欢的文本编辑器，但在集成开发环境 (IDE) 中获得的更直观的用户界面体验可能会使您受益。我们在中提供了 IDE 的列表*AWS开始使用资源中心*中的[IDE 和 IDE 工具箱。](https://aws.amazon.com//getting-started/tools-sdks/#IDE_and_IDE_Toolkits)部分。。。。本网站提供AWS您可以为首选 IDE 下载的工具包。有些IDE 还提供教程，帮助您了解有关编程语言的更多信息。 ## Amazon 可以使用的 API 操作 QuickSight 亚马逊 QuickSight API 提供：API 提供： + 用户和组管理 + 数据管理（数据源、数据集、模板和 SPICE 提取） + 控制面板和分析管理 + 模板管理。 + 权限管理 + 定制管理。 AWS为倾向于使用语言特定的 API 操作而非通过 HTTPS 提交请求来构建应用程序的软件开发人员提供了库、示例代码、教程和其他资源。这些库文件提供可自动执行任务的基本功能，例如以加密方式对请求签名、重试请求和处理错误响应。这些库能帮助您更轻松地入门。 有关下载Amazon 开发工具包的更多信息，请参阅[Amazon 开发工具包开发工具包和](https://aws.amazon.com/tools/). 以下链接是特定于语言的 API 文档的示例。 **AWS Command Line Interface** + [AWS CLI QuickSight 命令参考](https://docs.aws.amazon.com//cli/latest/reference/quicksight/index.html) + [AWS CLI 用户指南](https://docs.aws.amazon.com//cli/latest/userguide/) + [AWS CLI 命令引用](https://docs.aws.amazon.com//cli/latest/reference/) **适用于 .NET 的 AWS SDK** + [亚马逊。快速瞄准](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/index.html?page=QuickSight/NQuickSight.html) + [Amazon.Quicksight](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/index.html?page=QuickSight/NQuickSightModel.html) **适用于 C\$1\$1 的 AWS SDK** + [Aws:QuickSight::QuickSightClient 类参考。](https://sdk.amazonaws.com/cpp/api/LATEST/class_aws_1_1_quick_sight_1_1_quick_sight_client.html) **适用于 Go 的 AWS SDK** + [quicksight](https://docs.aws.amazon.com/sdk-for-go/api/service/quicksight/) **适用于 Java 的 AWS SDK** + [QuickSightClient](https://docs.aws.amazon.com/sdk-for-java/latest/reference//software/amazon/awssdk/services/quicksight/package-frame.html) + [QuickSightModel](https://docs.aws.amazon.com/sdk-for-java/latest/reference//software/amazon/awssdk/services/quicksight/model/package-frame.html) **适用于 JavaScript 的 AWS SDK** + [QuickSight](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/QuickSight.html) **适用于 PHP 的 AWS SDK** + [QuickSightClient](https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-Aws.QuickSight.QuickSightClient.html) **适用于 Python (Boto3) 的 AWS SDK** + [QuickSight](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/quicksight.html) **适用于 Ruby 的 AWS SDK** + [Aws:QuickSight](https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/QuickSight.html) # Amazon 资源名称 (ARN) QuickSight Amazon Resource Name（ARN）唯一标识 AWS 资源。ARN 在所有AWS，例如 IamPolicional Database Service (Amazon Relational Database Service) 检索Amazon 的 ARN QuickSight资源，你可以使用。`Describe`对相关资源进行操作。 您可以使用此部分了解 ARN 的工作原理。此处的材料提供了专门针对亚马逊的示例 QuickSight. **Topics** + [ARN 格式](qs-arn-format.md) + [亚马逊 QuickSight 资源 ARN](qs-resource-arns.md) # ARN 格式 ARN 用冒号分隔，由*段*，它们是用冒号分隔的部分（`:`)。ARN 区段中使用的特定组件和值取决于哪个AWSARN 用于的服务。以下示例演示了ARN 是如何构造的。 ``` arn:partition:service:region:account-id:resource-id arn:partition:service:region:account-id:resource-type/resource-id arn:partition:service:region:account-id:resource-type:resource-id ``` 这些 ARN 包含以下区段： ***`partition`***— 资源所处的分区。对于标准。AWS 区域，分区是*aws*. 如果资源位于其他分区，则分区是*aws-分区名称*. 例如，中国（北京）区域中的资源的分区为 `aws-cn`。 ***`service`***— 标识AWS产品。。。。例如，`quicksight`识别亚马逊 QuickSight、`s3`标识Amazon S3。`iam`标识 IAM。 ***`region`***— 该AWS 区域资源所在的。一些资源的 ARN 不需要使用AWS 区域，因此，在某些情况下，该组成部分可能会被省略。亚马逊 QuickSight ARN 需要一个AWS 区域. ***`account-id`***— 的 ID。AWS 账户拥有资源的第一个版本。当您在 ARN 或 API 操作中使用账号时，可以省略连字符（例如 123456789012）。一些资源的 ARN 不需要账号，因此，该组成部分可能会被省略。亚马逊 QuickSight ARN 需要一个AWS 账户数字。。。。但是，账号和AWS 区域在 S3 存储桶 ARN 中省略，如下所示。 ``` arn:aws:s3:::bucket_name arn:aws:s3:::bucket_name/key_name ``` ***`resource`*要么*`resource-type`***— ARN 这部分的内容因服务而异。资源标识符可以是资源的名称或 ID（例如，`user/Bob`要么`instance/i-1234567890abcdef0`) 或资源路径。。例如，一些资源标识符包括父资源 (`sub-resource-type/parent-resource/sub-resource`) 或限定符，例如版本 (*资源类型。*：*资源名称。*：*预选赛*)。 有些资源 ARN 可以包含路径、变量或通配符。 你可以使用通配符 (`*`和`?`) 在任何 ARN 区段中。星号 (`*`) 表示 0 个或多个字符的任意组合，问号 (`?`) 表示任何单个字符。您可在每个分段中使用多个 \$1 或 ? 字符，但通配符不能跨分段。如果您使用 ARN 获取权限，请避免使用`*`如果可能，则使用通配符来限制对必需元素的访问。下面是使用路径、通配符和变量的一些示例。 在以下示例中，我们将使用 S3 ARN。在 IAMPolicy 中向 S3 授予权限时，可能会使用此功能。此 S3 ARN 显示路径和文件已指定。 **注意** 术语。*键名称。*用来描述路径和文件之后的样子`bucketname/`. 这些名称之所以称为键名，是因为存储桶实际上并不包含计算机文件系统中使用的文件夹结构。相反，斜杠 (`/`) 是一个分隔符，有助于使存储桶的组织更加直观。在这种情况下，存储桶名为`examplebucket`，键名称，键名称为。`developers/design_info.doc`. ``` arn:aws:s3:::examplebucket/my-data/sales-export-2019-q4.json ``` 如果要标识存储桶中的所有对象，可以使用通配符指示 ARN 中包含所有键名称（或路径和文件），如下所示。 ``` arn:aws:s3:::examplebucket/* ``` 您可以使用键名的一部分加上通配符来标识以特定模式开头的所有对象。在这种情况下，它类似于文件夹名称加上通配符，如下所示。但是，此 ARN 还包括内部的任何 “子文件夹”`my-data`. ``` arn:aws:s3:::examplebucket/my-data/* ``` 您可以通过添加通配符来指定部分名称。这个标识任何以开头的对象`my-data/sales-export*`. ``` arn:aws:s3:::examplebucket/my-data/sales-export* ``` 在这种情况下，使用此通配符指定包含名称如下所示的对象： + `my-data/sales-export-1.xlsx` + `my-data/sales-export-new.txt` + `my-data/sales-export-2019/file1.txt` 您可以组合使用两种类型的通配符（星号和问号），也可以单独使用，如下所示。 ``` arn:aws:s3:::examplebucket/my-data/sales-export-2019-q?.* arn:aws:s3:::examplebucket/my-data/sales-export-20??-q?.* ``` 或者，如果您想让 ARN 面向未来，可以用通配符替换整个年份，而不仅仅是最后两位数字使用通配符。 ``` arn:aws:s3:::examplebucket/my-data/sales-export-????-q?.* arn:aws:s3:::examplebucket/my-data/sales-export-*-q?.* ``` 要了解有关 S3 ARN 的更多信息，请参阅[在策略中指定资源](https://docs.aws.amazon.com//AmazonS3/latest/dev/s3-arn-format.html)和[对象键和元数据](https://docs.aws.amazon.com//AmazonS3/latest/dev/UsingMetadata.html)中的*Amazon Simple Storage 服务用户指南* # 亚马逊 QuickSight 资源 ARN 以下资源类型由亚马逊定义 QuickSight：用户、组和仪表板。这些在亚马逊中使用 QuickSight API 调用和作为 iamPermission 语句的元素。查找。up-to-date Amazon 信息。 QuickSight （服务前缀：quicksight）在 IamPermissional 策略中使用的资源、操作和条件上下文键，请参阅[Amazon 的操作、资源和条件键 QuickSight](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_amazonquicksight.html)中的*iaSource。* | 资源类型 | ARN 格式 | 条件键 | | --- | --- | --- | | user | arn: \$1 \$1 \$1 (Parion): \$1 (Parion): \$1 “Acounounount: \$1ResourceId\$1 | 不适用 | | group | arn: \$1 \$1 \$1 (Parion): \$1 (Parion): \$1 (Parounounount): \$1ResourceId\$1 | 不适用 | | 控制面板 | arn: \$1 \$1 (Parion): \$1 (Parion): \$1 (Parounounount): \$1ResourceId\$1 | 不适用 | 资源 ARN 由描述您的资源的区段构成。例如，用于分析的资源 ARN 由以下区段组成。 ``` arn::quicksight:::/ ``` 区段的定义如下： + *`partition`*— 例如，，，，，。`aws`要么`aws-cn`. + *`aws-region`*— 该AWS 区域包含该资源。 + *`aws-account-id`*— 该AWS 账户包含该资源。这不包括连字符。 + *`resource-type`*— 资源的类型。在本例中，它是。`analyses`. 对于仪表板，它是`dashboard`. + *`resource-id`*— 特定资源的唯一标识符。 这些区域有：AWS 区域、资源类型和资源 ID 在您使用 Amazon 时在资源的 URL 中标识 QuickSight 控制台。例如，假设您需要 ARN 的分析的 URL。 ``` https://us-east-2.quicksight.aws.amazon.com/sn/analysis/4036e682-7de6-4c05-8a76-be51b9ec9b29 ``` AWS 区域 为 `us-east-2`。资源类型为。`analysis`. 此 URL 中的资源 ID 为`4036e682-7de6-4c05-8a76-be51b9ec9b29`. 如果您的账号为。`111122223333`，则此分析的 ARN 如下所示。 ``` arn:aws:quicksight:us-east-2:111122223333:analysis/4036e682-7de6-4c05-8a76-be51b9ec9b29 ``` 获取你的。AWS 账户号码，请联系您的系统管理员。 # Amazon 权限。 QuickSight 资源 如果您不确定需要什么权限，可以尝试进行调用。然后，客户端会告诉你缺少的权限是什么。你可以使用星号 (`*`)，而不是指定显式资源。但是，我们强烈建议您尽可能使每个权限简洁。您可以在策略中使用 Amazon 指定或排除资源，从而限制用户访问 QuickSight ARN。。。检索Amazon 的 ARN QuickSight 资源，使用。`Describe`对相关资源进行操作。 在您拨打Amazon 之前 QuickSight API 操作，您需要`quicksight:operation-name`附加到你的 IAMIdentity 的策略中的权限。例如，要调用 `list-users`，您需要 `quicksight:ListUsers` 权限。该模式适用于所有操作。如果您尝试进行调用，则无权调用，生成的错误将为您显示缺少什么权限。因此，我们强烈建议您尽可能限制每个权限。 您可以在IAM中添加条件，以进一步限制在某些情况下对 API 的访问。例如，当您将 `User1` 添加到 `Group1` 时，主资源为 `Group1`。您可以允许或拒绝对特定组的访问。或者您也可以编辑Amazon QuickSight iamKey`quicksight:UserName`添加一个条件来允许或阻止某些用户添加到该组。 有关更多信息，请参阅下列内容： + [操作、资源和条件键](https://docs.aws.amazon.com//IAM/latest/UserGuide/list_amazonquicksight.html) + [IAMJSON 策略元素。](https://docs.aws.amazon.com//IAM/latest/UserGuide/reference_policies_elements.html) 看得最多 up-to-date 亚马逊名单 QuickSight 操作，请参阅[Amazon 定义的操作。 QuickSight](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_amazonquicksight.html#amazonquicksight-actions-as-permissions)中的*IAM 用户指南*. ## 最佳实践 亚马逊 QuickSight 允许您与多达 100 位委托人共享分析、仪表板、模板和主题。一个*校长*的值可以是以下值之一： + Amazon 资源名称 (ARN) QuickSight 与数据源或数据集关联的用户或组。(最常见。) + Amazon 的 ARN。 QuickSight 与分析、仪表板、模板或主题关联的用户、组或命名空间。(最常见。) + 一个的 ARN。AWS账户根根名称：这是一个 IAM ARN，而不是 QuickSight ARN。。。此选项仅用于共享资源（模板）AWS账户。（不太常见。） 如果要与更多委托人共享这些资源，请考虑在组或命名空间级别分配资源权限。例如，如果您将用户添加到群组中并将资源共享到该群组，则该组算作一个委托人，即使该群组共享给群组中的所有人。 # 亚马逊 QuickSight API 错误 亚马逊 QuickSight 具有两种错误代码： + **客户端错误数**— 这些错误一般由客户端执行的操作导致。例如，在请求中指定不正确或无效的参数，或者为无权使用操作或资源的用户使用操作或资源。这些错误伴随 400 系列的 HTTP 响应代码。 + **服务器错误数**— 这些错误一般由AWS服务器端问题。这些错误伴随 500 系列的 HTTP 响应代码。 **Topics** + [常见客户端错误](#qs-api-errors-client) + [客户端错误](#qs-api-errors-table-client) + [服务器错误](#qs-api-errors-table-server) ## 常见客户端错误 接下来，您可以找到所有操作可以返回的常见客户端错误列表。 | 错误代码 | 描述 | | --- | --- | | AuthFailure | 无法验证提供的凭证。您可能无权执行请求。确保您的账户获得使用亚马逊的授权 QuickSight 服务，您的信用卡详细信息正确，您使用的是正确的访问密钥。 | | Blocked | 您的账户当前被阻止。如果您有问题，请联系 aws-verification@amazon.com。 | | DryRunOperation | 用户具有必需的权限，因此请求已成功，但使用了 DryRun 参数。 | | IdempotentParameterMismatch | 此请求使用的客户端令牌与之前不完全相同的请求使用的相同。除非请求相同，否则请勿将客户端令牌重复用于不同的请求。 | | IncompleteSignature | 请求签名不符合AWS标准。。。。 | | InvalidAction | 请求的操作无效。验证操作是否已正确键入。 | | InvalidCharacter | 指定的字符无效。 | | InvalidClientTokenId | 在我们的记录中没有所提供的 X.509 证书或 AWS 访问密钥 ID。 | | InvalidPaginationToken | 指定的分页令牌无效或已过期。 | | InvalidParameter | 在请求中指定的参数无效、不受支持，或无法使用。请求的消息解释错误值。 | | InvalidParameterCombination | 指示参数组合不正确，或缺失参数。 | | InvalidParameterValue | 在参数中指定的值无效、不受支持，或无法使用。确保使用资源的完整 ID 指定资源。请求的消息解释错误值。 | | InvalidQueryParameter | 这些区域有：AWS查询字符串格式错误或未遵循AWS标准。。。。 | | MalformedQueryString | 查询字符串包含语法错误。 | | MissingAction | 请求中遗漏了一个操作或必需参数。 | | MissingAuthenticationToken | 请求中必须包含有效的（已注册的）AWS 访问密钥 ID 或 X.509 证书。 | | MissingParameter | 请求缺少必需的参数。确保为请求提供所有必需参数；例如，资源 ID。 | | OptInRequired | 您无权使用请求的服务。确保您已订阅尝试使用的服务。如果你是新手AWS，则验证您的信用卡详细信息时，可能需要一点时间激活您的账户。 | | PendingVerification | 您的账户待验证。在验证流程完成之前，您可能无法使用此账户执行请求。如果您有任何疑问，请联系 [AWS 支持](https://console.aws.amazon.com/support/home#/)。 | | RequestExpired | 请求到达服务的时间超过请求上的日期戳或请求到期日期（如针对预签名 URL）15 分钟。或者请求上的日期戳在future 15 分钟以上。如果您使用的是临时安全凭证，则此错误还可能在凭证过期的情况下出现。有关更多信息，请参阅《IAM 用户指南》中的[临时安全凭证](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.html)。 | | UnauthorizedOperation | 您没有权限执行此操作。检查您的 IAM 策略，并确保您使用的是正确的访问密钥。 | | UnknownParameter | 提供的参数未知或无法识别。可能导致此错误的请求包括提供拼写错误的参数或指定 API 版本支持的参数。 | | UnsupportedInstanceAttribute | 指定的属性无法修改。 | | UnsupportedOperation | 指定的请求包含不受支持的操作。返回的消息提供不受支持的操作的详细信息。 | | UnsupportedProtocol | 您使用的协议不受支持。 | | ValidationError | 输入未能满足AWS服务。。。。 | ## 客户端错误 在下文中，您可以使用 Amazon 特定的客户端错误列表 QuickSight API。 | 错误代码 | 描述 | | --- | --- | | AccessDeniedException | 您无权访问此内容。无法验证提供的凭证。您可能无权执行请求。确保您的账户获得使用亚马逊的授权 QuickSight 服务，您的策略具有正确的权限，您使用的是正确的访问密钥。 | | DomainNotWhiteListedException | 指定的域不在允许列表上。Amazon 必须将嵌入控制面板的所有域添加到已批准列表 QuickSight admin。。 | | IdentityTypeNotSupportedException | 指定的身份类型不受支持。支持的身份类型包括：我和 QUICKSIGHT | | InvalidNextTokenException | NextToken 值无效。 | | InvalidParameterValueException | 一个或多个参数没有有效值。 | | PreconditionNotMetException | 未满足一个或多个先决条件。 | | QuickSightUserNotFoundException | 找不到用户。这可能发生在需要基于提供的用户名查找用户的任何操作中，如 DeleteUser、DescribeUser，等等。。。。。 | | ResourceExistsException | 指定的资源不存在。 | | ResourceNotFoundException | 无法找到一个或多个资源。 | | SessionLifetimeInMinutesInvalidException | 为会话生命周期指定的分钟数无效。会话生命周期必须介于 15 到 600 分钟之间。 | | ThrottlingException | 访问受限。 | | UnsupportedUserEditionException | 指示您正在 Amazon 上调用某个操作 QuickSight订阅中，版本不支持该操作。亚马逊 QuickSight 当前具有标准版和企业版。每个版本中并未提供所有操作和功能。 | ### 客户端错误的常见原因 执行请求时可能遇到错误的原因有很多。可以通过遵循以下准则来阻止或轻松解决一些错误： + **指定AWS 账户ID 和命名空间 ID。**— 相关AWS 账户每个请求都必须提供身份证件。命名空间必须设置为 `default`。 + **允许最终一致性**— 由于之前的请求未在系统中彻底传播，因此导致了一些错误。 + **在请求速率之间使用休眠间隔**— Amazon QuickSight 将阻止 API 请求，以帮助维护服务性能。如果您的请求受限，您将收到错误。 + **使用资源的完整 ID**— 指定资源时，请确保使用资源的完整 ID，而不是用户提供的资源名称或描述。 + **检查您的服务。**— 确保您已注册尝试使用的所有服务。您可以前往查看您注册的服务**我的账户。**的 部分[AWS主页](https://aws.amazon.com/). + **检查您的权限。**— 确保您具有执行请求所需的权限。 + **检查您的 VPC。**— VPC）之间不能共享某些资源，如安全组。 + **检查您的凭证。**— 请确保您在提出请求时提供访问密钥，并且已正确输入凭据。此外，如果您有多个账户，请确保您使用的是特定账户的正确凭证。如果提供的凭证不正确，则可能会收到以下错误：`Client.AuthFailure`. ## 服务器错误 在下文中，您可以找到服务器会返回的错误列表。 | 错误代码 | 描述 | | --- | --- | | BatchClientRequestTokensNotDistinctException – | 批处理客户端请求令牌不唯一。 | | EmptyBatchRequestException | 批处理请求为空。 | | InternalFailureException | 出现内部故障。 | | InternalServiceError | 服务中存在内部错误。 | | InvalidBatchClientRequestTokenException | 这些区域有：AWS此客户端批处理请求的请求令牌无效。 | | InvalidParameterException | 一个或多个参数具有无效值。 | | LimitExceededException | 超出限制。 | | ResourceUnavailableException | 此资源当前不可用。 | | TooManyEntriesInBatchRequestException | 此批处理请求中的条目过多。 |