本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 在 Amazon SQS 中使用 AWS JSON 协议发出查询 API 请求
<a name="sqs-making-api-requests-json"></a>

本主题介绍了如何构造 Amazon SQS 端点、发出 POST 请求以及解释响应。

**注意**  
AWS 大多数语言变体都支持 JSON 协议。有关受支持语言变体的完整列表，请参阅[亚马逊 SQS APIs 中使用的 AWS JSON 协议支持哪些语言？](sqs-json-faqs.md#json-protocol-supported-languages)。

## 构造端点
<a name="sqs-api-constructing-endpoints-json"></a>

为了使用 Amazon SQS 队列，您必须构造一个端点。有关 Amazon SQS 端点的信息，请参阅 *Amazon Web Services 一般参考*中的以下页面：
+ [区域端点](https://docs.aws.amazon.com/general/latest/gr/rande.html#regional-endpoints)
+ [Amazon Simple Queue Service 端点和配额](https://docs.aws.amazon.com/general/latest/gr/sqs-service)

每个 Amazon SQS 端点都是独立的。例如，如果有两个名为 *MyQueue* 的队列，其中一个队列具有终端节点 `sqs.us-east-2.amazonaws.com`，另一个队列具有终端节点 `sqs.eu-west-2.amazonaws.com`，则这两个队列不会相互共享任何数据。

以下是一个提出创建队列请求的端点的示例。

```
POST / HTTP/1.1
Host: sqs.us-west-2.amazonaws.com
X-Amz-Target: AmazonSQS.CreateQueue
X-Amz-Date: <Date>
Content-Type: application/x-amz-json-1.0
Authorization: <AuthParams>
Content-Length: <PayloadSizeBytes>
Connection: Keep-Alive 
{
    "QueueName":"MyQueue",
    "Attributes": {
        "VisibilityTimeout": "40"
    },
    "tags": {
        "QueueType": "Production"
    }
}
```

**注意**  
队列名称和队 URLs 列区分大小写。  
*`AUTHPARAMS`* 的结构取决于 API 请求的签名。有关更多信息，请参阅[《*亚马逊 Web Services 一般参考*》中的 “签署 AWS API 请求](https://docs.aws.amazon.com/general/latest/gr/signing_aws_api_requests.html)”。

## 发出 POST 请求
<a name="structure-post-request"></a>

Amazon SQS POST 请求在 HTTP 请求的正文中以表单的形式发送查询参数。

以下是将 `X-Amz-Target` 设置为 `AmazonSQS.<operationName>` 的 HTTP 标头以及将 `Content-Type` 设置为 `application/x-amz-json-1.0` 的 HTTP 标头的示例。

```
POST / HTTP/1.1
Host: sqs.<region>.<domain>
X-Amz-Target: AmazonSQS.SendMessage
X-Amz-Date: <Date>
Content-Type: application/x-amz-json-1.0
Authorization: <AuthParams>
Content-Length: <PayloadSizeBytes>
Connection: Keep-Alive 
{
    "QueueUrl": "https://sqs.<region>.<domain>/<awsAccountId>/<queueName>/",
    "MessageBody": "This is a test message"
}
```

此 HTTP POST 请求将消息发送到 Amazon SQS 队列。

**注意**  
HTTP 标头 `X-Amz-Target` 和 `Content-Type` 均为必需项。  
根据客户端的 HTTP 版本，您的 HTTP 客户端可能会向 HTTP 请求添加其他项目。

# 解释 Amazon SQS JSON API 响应
<a name="sqs-json-api-responses"></a>

当您向 Amazon SQS 发送请求时，它会返回包含结果的 JSON 响应。响应结构取决于您使用的 API 操作。

要了解这些响应的详细信息，请参阅：
+ 《Amazon Simple Queue Service API 参考》**的 [API 操作](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_Operations.html)中的特定 API 操作
+ 这些区域有：[亚马逊 SQS AWS JSON 协议 FAQs](sqs-json-faqs.md)

## 成功的 JSON 响应结构
<a name="sqs-json-api-successful-response-structure"></a>

如果请求成功，则主响应元素为 `x-amzn-RequestId`，其中包含请求的通用唯一标识符 (UUID) 以及其他附加的响应字段。例如，以下 [https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_CreateQueue.html](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_CreateQueue.html) 响应包含 `QueueUrl` 字段，后者又包含所创建队列的 URL。

```
HTTP/1.1 200 OK
x-amzn-RequestId: <requestId>
Content-Length: <PayloadSizeBytes>
Date: <Date>
Content-Type: application/x-amz-json-1.0
{
    "QueueUrl":"https://sqs.us-east-1.amazonaws.com/111122223333/MyQueue"
}
```

## JSON 错误响应结构
<a name="sqs-api-error-response-structure"></a>

如果请求失败，则 Amazon SQS 将返回主响应，包括 HTTP 标头和正文。

在 HTTP 标头中，`x-amzn-RequestId` 包含请求的 UUID。`x-amzn-query-error` 包含两条信息：错误类型，以及错误是创建者错误还是使用者错误。

在响应正文中，`"__type"` 表示其他错误详细信息，`Message` 以可读的格式指明错误情况。

以下是 JSON 格式的错误响应示例：

```
HTTP/1.1 400 Bad Request
x-amzn-RequestId: 66916324-67ca-54bb-a410-3f567a7a0571
x-amzn-query-error: AWS.SimpleQueueService.NonExistentQueue;Sender
Content-Length: <PayloadSizeBytes>
Date: <Date>
Content-Type: application/x-amz-json-1.0
{
    "__type": "com.amazonaws.sqs#QueueDoesNotExist",
    "message": "The specified queue does not exist."
}
```

# 亚马逊 SQS AWS JSON 协议 FAQs
<a name="sqs-json-faqs"></a>

本主题涵盖了有关在 Amazon SQS 中使用 AWS JSON 协议的常见问题。

## 什么是 AWS JSON 协议，它与现有的 Amazon SQS API 请求和响应有何不同？
<a name="json-protocol-what-is"></a>

JSON 是在异构系统之间进行通信时最广为使用和接受的连接方法之一。亚马逊 SQS 使用 JSON 作为媒介在 S AWS DK 客户端（例如 Java、Python、Golang JavaScript）和亚马逊 SQS 服务器之间进行通信。Amazon SQS API 操作的 HTTP 请求接受 JSON 形式的输入。系统会执行 Amazon SQS 操作，然后将执行的响应以 JSON 的形式反过来共享给 SDK 客户端。与 AWS 查询相比，JSON 在客户端和服务器之间的数据传输方面效率更高。
+ 亚马逊 SQS AWS JSON 协议充当亚马逊 SQS 客户端和服务器之间的中介。
+ 服务器不理解创建 Amazon SQS 操作所用的编程语言，但它能理解 AWS JSON 协议。
+ 亚马逊 SQS AWS JSON 协议在亚马逊 SQS 客户端和服务器之间使用序列化（将对象转换为 JSON 格式）和反序列化（将 JSON 格式转换为对象）。

## 如何开始使用适用于亚马逊 SQS 的 AWS JSON 协议？
<a name="json-protocol-getting-started"></a>

要开始使用最新版本的 AWS SDK，以便更快地向 Amazon SQS 发送消息，请将您的 AWS 软件开发工具包升级到指定版本或任何后续版本。要详细了解 SDK 客户端，请参阅下表中的“指南”一列。

以下是适用于亚马逊 SQS APIs 的 JS AWS ON 协议跨语言变体的软件开发工具包版本列表：


| 语言 | SDK 客户端存储库 | 所需的 SDK 客户端版本 | 指南 | 
| --- | --- | --- | --- | 
|  C\$1\$1  |  [啊/ aws-sdk-cpp](https://github.com/aws/aws-sdk-cpp)  |  [1.11.98](https://github.com/aws/aws-sdk-cpp/releases/tag/1.11.198)  |  [AWS 适用于 C\$1\$1 的 SDK](https://aws.amazon.com/sdk-for-cpp/)  | 
|  Golang 1.x  |  [啊/ aws-sdk-go](https://github.com/aws/aws-sdk-go)  |  [v1.47.7](https://github.com/aws/aws-sdk-go/releases/tag/v1.47.7)  |  [AWS 适用于 Go 的 SDK](https://aws.amazon.com/sdk-for-go/)  | 
|  Golang 2.x  |  [aws/ 2 aws-sdk-go-v](https://github.com/aws/aws-sdk-go-v2)  |  [v1.28.0](https://github.com/aws/aws-sdk-go-v2/blob/release-2023-11-09/service/sqs/CHANGELOG.md#v1270-2023-11-09)  |  [AWS 适用于 Go V2 的 SDK](https://aws.github.io/aws-sdk-go-v2/docs/)  | 
|  Java 1.x  |  [啊/ aws-sdk-java](https://github.com/aws/aws-sdk-java)  |  [1.12.585](https://github.com/aws/aws-sdk-java/releases/tag/1.12.585)  |  [AWS 适用于 Java 的 SDK](https://aws.amazon.com/sdk-for-java/)  | 
|  Java 2.x  |  [aws/ 2 aws-sdk-java-v](https://github.com/aws/aws-sdk-java-v2)  |  [2.21.19](https://github.com/aws/aws-sdk-java-v2/releases/tag/2.21.19)  |  [AWS 适用于 Java 的 SDK](https://aws.amazon.com/sdk-for-java/)  | 
|  JavaScript v2.x  |  [啊/ aws-sdk-js](https://github.com/aws/aws-sdk-js)  |  [JavaScript on AWS](https://aws.amazon.com/developer/language/javascript/)  | 
|  JavaScript v3.x  |  [aws/ 3 aws-sdk-js-v](https://github.com/aws/aws-sdk-js-v3)  |  [v3.447.0](https://github.com/aws/aws-sdk-js-v3/releases/tag/v3.447.0)  |  [JavaScript on AWS](https://aws.amazon.com/developer/language/javascript/)  | 
|  .NET  |  [啊/ aws-sdk-net](https://github.com/aws/aws-sdk-net)  |  [3.7.681.0](https://github.com/aws/aws-sdk-net/releases/tag/3.7.681.0)  |  [AWS 适用于 .NET 的 SDK](https://aws.amazon.com/sdk-for-net/)  | 
|  PHP  |  [啊/ aws-sdk-php](https://github.com/aws/aws-sdk-php)  |  [3.285.2](https://github.com/aws/aws-sdk-php/releases/tag/3.285.2)  |  [AWS 适用于 PHP 的 SDK](https://aws.amazon.com/sdk-for-php/)  | 
|  Python-boto3  |   [boto/boto3](https://github.com/boto/boto3)   |  [1.28.82](https://github.com/boto/boto3/releases/tag/1.28.82)  |  [AWS 适用于 Python (Boto3) 的 SDK](https://aws.amazon.com/sdk-for-python/)  | 
|  Python-botocore  |   [boto/botocore](https://github.com/boto/botocore/)   |  [1.31.82](https://github.com/boto/botocore/releases/tag/1.31.82)  |  [AWS 适用于 Python (Boto3) 的 SDK](https://aws.amazon.com/sdk-for-python/)  | 
|  awscli  |  [AWS CLI](https://github.com/aws/aws-cli)  |  [1.29.82](https://github.com/aws/aws-cli/releases/tag/1.29.82)  |  [AWS命令行界面](https://aws.amazon.com/cli/)  | 
|  Ruby  |  [啊/ aws-sdk-ruby](https://github.com/aws/aws-sdk-ruby)  |  [1.67.0](https://rubygems.org/gems/aws-sdk-sqs/versions/1.67.0)  |  [AWS 适用于 Ruby 的 SDK](https://aws.amazon.com/sdk-for-ruby/)  | 

## 为我的 Amazon SQS 工作负载启用 JSON 协议有什么风险？
<a name="json-protocol-risks"></a>

如果您使用软件开发工具包的自定义实现或自定义客户端和 AWS AWS 软件开发工具包的组合来与生成基于 AWS 查询（又名基于 XML）的响应的 Amazon SQS 进行交互，则可能与 JSON 协议不兼容。 AWS 如果您遇到任何问题，请联系 Supp AWS ort。

## 如果我已经使用最新的 AWS SDK 版本，但我的开源解决方案不支持 JSON，该怎么办？
<a name="json-protocol-sdk-version-open-source"></a>

您必须将 SDK 版本更改为当前所用版本之前的版本。有关[如何开始使用适用于亚马逊 SQS 的 AWS JSON 协议？](#json-protocol-getting-started)更多信息，请参阅。 AWS 中列出的软件开发工具包版本[如何开始使用适用于亚马逊 SQS 的 AWS JSON 协议？](#json-protocol-getting-started)使用适用于 Amazon SQS APIs 的 JSON 有线协议。如果您将 AWS 软件开发工具包更改为先前版本，则您的 Amazon SQS APIs 将使用该查询。 AWS 

## 亚马逊 SQS APIs 中使用的 AWS JSON 协议支持哪些语言？
<a name="json-protocol-supported-languages"></a>

Amazon SQS 支持所有通用语言变体 (GA)。 AWS SDKs 目前，我们不支持 Kotlin、Rust 或 Swift。要详细了解其他语言变体，请参阅[用于在 AWS上进行构建的工具](https://aws.amazon.com/developer/tools/)。

## 亚马逊 SQS 中使用的 AWS JSON 协议支持哪些区域 APIs
<a name="json-protocol-supported-regions"></a>

亚马逊 SQS 在所有提供亚马逊 SQS 的[AWS 地区](https://docs.aws.amazon.com/general/latest/gr/sqs-service.html)都支持 AWS JSON 协议。

## 使用 JS AWS ON 协议升级到适用于 Amazon SQS 的指定 AWS 软件开发工具包版本时，我可以期待哪些延迟改善？
<a name="json-protocol-upgrading-sdk"></a>

AWS 与查询协议相比，JSON 协议在请求和响应的序列化和反序列化方面效率更高。 AWS 根据对 5 KB 消息负载的 AWS 性能测试，适用于 Amazon SQS 的 JSON 协议可将 end-to-end消息处理延迟减少多达 23%，并减少应用程序客户端 CPU 和内存使用量。

## AWS 查询协议会被弃用吗？
<a name="query-protocol"></a>

AWS 将继续支持查询协议。只要你的 AWS SDK 版本设置了除[如何开始使用 Amazon SQS 的 JS AWS ON 协议中列出的版本之外的任何先前版本，你就可以继续使用 AWS 查询协议](#json-protocol-getting-started)。

## 在哪里可以找到有关 AWS JSON 协议的更多信息？
<a name="json-protocol-more-info"></a>

您可以在 *Smithy* 文档的 [AWS JSON 1.0 协议](https://smithy.io/2.0/aws/protocols/aws-json-1_0-protocol.html)中找到有关 JSON 协议的更多信息。有关使用 AWS JSON 协议的 Amazon SQS API 请求的更多信息，请参阅[在 Amazon SQS 中使用 AWS JSON 协议发出查询 API 请求](sqs-making-api-requests-json.md)。