本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 在 Amazon SQS 中使用 AWS JSON 通訊協定提出查詢 API 請求
<a name="sqs-making-api-requests-json"></a>

本主題說明如何建構 Amazon SQS 端點、提出 POST 請求，以及解譯回應。

**注意**  
AWS 大多數語言變體都支援 JSON 通訊協定。如需支援的語言變體完整清單，請參閱 [Amazon 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"
    }
}
```

**注意**  
佇列名稱和佇列 URL 區分大小寫。  
*`AUTHPARAMS`* 的結構取決於 API 請求的簽署。如需詳細資訊，請參閱《*Amazon 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 動作中的特定 API 動作](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_Operations.html) 
+ [Amazon 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."
}
```

# Amazon 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 是用於異質系統之間通訊的最廣泛使用和接受的佈線方法之一。Amazon SQS 使用 JSON 在 AWS SDK 用戶端 (例如 Java、Python、Golang、JavaScript) 和 Amazon SQS 伺服器之間進行通訊。Amazon SQS API 操作的 HTTP 請求接受 JSON 格式的輸入。系統會執行 Amazon SQS 操作，而回應會以 JSON 格式傳回 SDK 用戶端。與 AWS 查詢相比，JSON 可更有效率地在用戶端和伺服器之間傳輸資料。
+ Amazon SQS AWS JSON 通訊協定充當 Amazon SQS 用戶端和伺服器之間的中介裝置。
+ 伺服器不了解建立 Amazon SQS 操作的程式設計語言，但了解 AWS JSON 通訊協定。
+ Amazon SQS AWS JSON 通訊協定使用 Amazon SQS 用戶端和伺服器之間的序列化 （將物件轉換為 JSON 格式） 和還原序列化 （將 JSON 格式轉換為物件）。

## 如何開始使用 Amazon SQS 的 AWS JSON 通訊協定？
<a name="json-protocol-getting-started"></a>

若要開始使用最新的 AWS SDK 版本，以實現 Amazon SQS 的更快傳訊，請將您的 AWS SDK 升級到指定的版本或任何後續版本。若要進一步了解 SDK 用戶端，請參閱下表中的「指南」資料欄。

以下是 AWS JSON 通訊協定與 Amazon SQS APIs 搭配使用之不同語言版本的 SDK 版本清單：


| Language | SDK 用戶端儲存庫 | 必要的 SDK 用戶端版本 | 指南 | 
| --- | --- | --- | --- | 
|  C\$1\$1  |  [aws/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/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/aws-sdk-go-v2](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/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 的開發套件](https://aws.amazon.com/sdk-for-java/)  | 
|  Java 2.x  |  [aws/aws-sdk-java-v2](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 的開發套件](https://aws.amazon.com/sdk-for-java/)  | 
|  JavaScript v2.x  |  [aws/aws-sdk-js](https://github.com/aws/aws-sdk-js)  |  [上的 JavaScript AWS](https://aws.amazon.com/developer/language/javascript/)  | 
|  JavaScript v3.x  |  [aws/aws-sdk-js-v3](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 AWS](https://aws.amazon.com/developer/language/javascript/)  | 
|  .NET  |  [aws/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/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 的 SDK (Boto3)](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 的 SDK (Boto3)](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/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 SDK 的自訂實作或自訂用戶端和 AWS SDK 的組合來與產生以 AWS 查詢為基礎 （又稱為 XML 類型） 回應的 Amazon SQS 互動，則可能與 AWS JSON 通訊協定不相容。如果您遇到任何問題，請聯絡 AWS Support。

## 如果我已經使用最新的 AWS SDK 版本，但我的開放原始碼解決方案不支援 JSON，該怎麼辦？
<a name="json-protocol-sdk-version-open-source"></a>

您必須將 SDK 版本變更為您正在使用的版本之前的版本。[如何開始使用 Amazon SQS 的 AWS JSON 通訊協定？](#json-protocol-getting-started) 如需詳細資訊，請參閱 中列出的 AWS SDK 版本[如何開始使用 Amazon SQS 的 AWS JSON 通訊協定？](#json-protocol-getting-started)使用 Amazon SQS APIs的 JSON 線路通訊協定。如果您將 AWS SDK 變更為舊版，Amazon SQS APIs 將使用 AWS 查詢。

## Amazon SQS APIs 中使用的 AWS JSON 通訊協定支援哪些語言？
<a name="json-protocol-supported-languages"></a>

Amazon SQS 支援所有正式推出 AWS SDKs的語言變體 (GA)。目前，我們不支援 Kotlin、Rust 或 Swift。若要深入了解其他語言變體，請參閱[在 AWS上建立的工具](https://aws.amazon.com/developer/tools/)。

## Amazon SQS APIs 中使用的 AWS JSON 通訊協定支援哪些區域
<a name="json-protocol-supported-regions"></a>

Amazon SQS 在所有可使用 Amazon SQS 的[AWS 區域中](https://docs.aws.amazon.com/general/latest/gr/sqs-service.html)支援 AWS JSON 通訊協定。

## 使用 AWS JSON 通訊協定升級至 Amazon SQS 的指定 AWS SDK 版本時，可以預期哪些延遲改善？
<a name="json-protocol-upgrading-sdk"></a>

AWS 與 AWS 查詢通訊協定相比，JSON 通訊協定在序列化和還原序列化請求和回應方面更有效率。根據 5 KB 訊息承載 AWS 的效能測試，Amazon SQS 的 JSON 通訊協定可將end-to-end訊息處理延遲降低高達 23%，並減少應用程式用戶端 CPU 和記憶體使用量。

## AWS 查詢通訊協定是否會棄用？
<a name="query-protocol"></a>

AWS 查詢通訊協定將繼續受到支援。只要 AWS 軟體開發套件版本已設定任何先前版本，且該版本列於如何開始使用 Amazon SQS 的 JSON 通訊協定中，您就可以繼續使用 AWS 查詢通訊協定。 [AWS Amazon SQS](#json-protocol-getting-started)

## 哪裡可以找到 JSON AWS 通訊協定的詳細資訊？
<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)。