Amazon Simple Queue Service
开发人员指南
AWS 服务或AWS文档中描述的功能,可能因地区/位置而异。请点击 Amazon AWS 入门,可查看中国地区的具体差异

提出查询 API 请求

在本节中,您将了解如何构建 Amazon SQS 终端节点,如何提出 GETPOST 请求以及如何解释响应。

构建终端节点

为了使用 Amazon SQS 队列,您必须构建一个终端节点。有关特定于区域的 Amazon SQS 终端节点的信息,请参阅 Amazon Web Services 一般参考

每个 Amazon SQS 终端节点都是独立的。例如,如果有两个名为 MyQueue 的队列,其中一个队列具有终端节点 sqs.cn-north-1.amazonaws.com.cn,另一个队列具有终端节点 sqs.cn-northwest-1.amazonaws.com.cn,则这两个队列不会相互共享任何数据。

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

https://sqs.cn-north-1.amazonaws.com.cn/ ?Action=CreateQueue &DefaultVisibilityTimeout=40 &QueueName=MyQueue &Version=2012-11-05 &AUTHPARAMS

注意

队列名称和队列 URL 区分大小写。

AUTHPARAMS 的结构取决于 API 请求的签名。有关更多信息,请参阅 Amazon Web Services 一般参考 中的签署 AWS API 请求

提出 GET 请求

Amazon SQS 的 GET 请求被构建为由以下部分组成的 URL:

  • 终端节点 – 作为请求执行对象的资源 (队列名称和 URL),例如:https://sqs.us-east-2.amazonaws.com/123456789012/MyQueue

  • 操作 – 要对终端节点执行的 API 操作。终端节点与操作之前用问号 (?) 分隔,例如:?Action=SendMessage&MessageBody=Your%20Message%20Text

  • 参数 – 任何请求参数 — 每个参数之前用“和”符号 (&) 分隔,例如:&Version=2012-11-05&AUTHPARAMS

以下是一个 GET 请求的示例,该请求向 Amazon SQS 队列发送一条消息。

https://sqs.us-east-2.amazonaws.com/123456789012/MyQueue ?Action=SendMessage&MessageBody=Your%20message%20text &Version=2012-11-05 &AUTHPARAMS

注意

队列名称和队列 URL 区分大小写。

因为 GET 请求是 URL,因此您必须对所有参数值进行 URL 编码。由于 URL 中不允许使用空格,因此每个空格将在 URL 中编码为“%20”。(示例的其余部分没有进行 URL 编码,以方便您阅读。)

提出 POST 请求

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

下面是一个 Content-Type 设置为 application/x-www-form-urlencoded 的 HTTP 标头的示例。

POST /MyQueue HTTP/1.1 Host: sqs.us-east-2.amazonaws.com Content-Type: application/x-www-form-urlencoded

该标头后跟一个 form-urlencoded POST 请求,该请求向 Amazon SQS 队列发送一条消息。各参数以和号 (&) 分隔。

Action=SendMessage &MessageBody=Your+Message+Text &Expires=2017-10-15T12%3A00%3A00Z &Version=2012-11-05 &AUTHPARAMS

注意

Content-Type HTTP 标头是必需的。AUTHPARAMS 对于 GET 请求是相同的。

根据客户端的 HTTP 版本,您的 HTTP 客户端可能会向 HTTP 请求添加其他项目。

对请求进行身份验证

身份验证是用于识别和验证发送请求的当事方的过程。在身份验证的第一个阶段,AWS 将验证创建者的身份以及创建者是否已注册使用 AWS (有关更多信息,请参阅Create an AWS AccountCreate an IAM User)。接下来,AWS 将按照以下步骤操作:

  1. 创建者 (发件人) 获取必要的证书。

  2. 创建者向使用者 (接收方) 发送请求和凭证。

  3. 使用者使用证书来验证创建者是否发送了该请求。

  4. 将出现以下三种情况之一:

    • 如果身份验证成功,使用者将处理该请求。

    • 如果身份验证失败,使用者将拒绝请求并返回错误。

使用 HMAC-SHA 的基本身份验证过程

使用查询 API 访问 Amazon SQS 时,必须提供以下项目来对请求进行身份验证:

  • 用于识别您的 AWS 账户的 AWS 访问密钥 ID,AWS 将使用它来查找您的秘密访问密钥。

  • 使用您的秘密访问密钥计算得出的 HMAC-SHA 请求签名 (秘密访问密钥是一个只有您和 AWS 知道的共享秘密 — 有关更多信息,请参阅 RFC2104)。AWS 开发工具包可处理签名过程;但是,如果您通过 HTTP 或 HTTPS 提交查询请求,则必须在每个查询请求中包含一个签名。

    1. 派生签名版本 4 签名密钥。有关更多信息,请参阅使用 Java 派生签名密钥

      注意

      Amazon SQS 支持签名版本 4,该版本相比以前的版本可提供经过改进的基于 SHA256 的安全性和性能。创建使用 Amazon SQS 的新应用程序时,应使用签名版本 4。

    2. 对请求签名必须采用 Base64 编码。下面的示例 Java 代码将执行此操作:

      package amazon.webservices.common; // Define common routines for encoding data in AWS requests. public class Encoding { /* Perform base64 encoding of input bytes. * rawData is the array of bytes to be encoded. * return is the base64-encoded string representation of rawData. */ public static String EncodeBase64(byte[] rawData) { return Base64.encodeBytes(rawData); } }
  • 请求的 时间戳 (或到期时间)。在请求中使用的时间戳必须是 dateTime 对象,并包含完整的日期以及小时、分钟和秒。例如 2007-01-31T23:59:59Z。尽管没有强制要求,但还是建议您使用协调世界时 (格林威治标准时间) 时区提供该对象。

    注意

    确保您的服务器时间设置正确。如果您指定了时间戳 (而不是过期时间),则请求会在指定的时间过后 15 分钟自动过期 (如果请求的时间戳比 AWS 服务器上的当前时间早 15 分钟以上,则 AWS 不会处理请求)。

    如果您使用的是 .NET,则不得发送过于具体的时间戳 (因为 AWS 和 .NET 对如何确定额外时间精度有不同的解释)。在这种情况下,应手动构造精度不超过 1 毫秒的 dateTime 对象。

第 1 部分:来自用户的请求

以下是在使用 HMAC-SHA 请求签名对 AWS 请求进行身份验证时必须执行的过程。

  1. 构建要发送到 AWS 的请求。

  2. 使用您的秘密访问密钥计算密钥哈希消息验证码 (HMAC-SHA) 签名。

  3. 在请求中包含签名和您的访问密钥 ID,然后将请求发送给 AWS。

第 2 部分:来自 AWS 的响应

AWS 在响应时开始以下过程。

  1. AWS 使用访问密钥 ID 来查找您的秘密访问密钥。

  2. 通过使用与您用于计算您在请求中发送的签名相同的算法,AWS 根据请求数据和秘密访问密钥计算出签名。

  3. 将出现以下三种情况之一:

    • 如果 AWS 生成的签名与您在请求中发送的签名相匹配,AWS 将认为请求是真实的。

    • 如果比较失败,则 AWS 将放弃请求并返回错误。

解释响应

在响应操作请求时,Amazon SQS 会返回包含请求结果的 XML 数据结构。有关更多信息,请参阅 Amazon Simple Queue Service API Reference 中的各个 API 操作。

成功的响应结构

如果请求成功,则主要响应元素将以请求的操作命名并附加上 Response (ActionNameResponse)。

此元素包含以下子元素:

  • ActionNameResult – 包含一个特定于操作的元素。例如,CreateQueueResult 元素包含 QueueUrl 元素,后者又包含所创建的队列的 URL。

  • ResponseMetadata – 包含 RequestId,后者又包含请求的 UUID。

以下是 XML 格式的成功响应的示例:

<CreateQueueResponse xmlns=https://sqs.us-east-2.amazonaws.com/doc/2012-11-05/ xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance xsi:type=CreateQueueResponse> <CreateQueueResult> <QueueUrl>https://sqs.us-east-2.amazonaws.com/770098461991/queue2</QueueUrl> </CreateQueueResult> <ResponseMetadata> <RequestId>cb919c0a-9bce-4afe-9b48-9bdf2412bb67</RequestId> </ResponseMetadata> </CreateQueueResponse>

错误响应结构

如果请求不成功,Amazon SQS 将始终返回主要响应元素 ErrorResponse。此元素包含一个 Error 元素和一个 RequestId 元素。

Error 元素包含以下子元素:

  • Type – 指定错误是创建者错误还是使用者错误。

  • Code – 指定错误类型。

  • Message – 以可读格式指定错误条件。

  • Detail – (可选) 指定有关错误的更多详细信息。

RequestId 元素包含请求的 UUID。

下面是 XML 格式的错误响应的示例:

<ErrorResponse> <Error> <Type>Sender</Type> <Code>InvalidParameterValue</Code> <Message> Value (quename_nonalpha) for parameter QueueName is invalid. Must be an alphanumeric String of 1 to 80 in length. </Message> </Error> <RequestId>42d59b56-7407-4c4a-be0f-4c88daeea257</RequestId> </ErrorResponse>