通用头部¶

对消息队列 API 的每个请求都必须包含某些标准和扩展的 HTTP 头部（如以下表格所示）。这些头部向服务器提供主机、代理、身份验证和其他相关信息。下表提供了 API 使用的通用头部。

标头	描述
主机	API 的主机名
Date	当前日期和时间
Accept	要使用的媒体类型。最初，仅支持 `application/json`。注意： “Accept” 头部是必需的。
Accept-Encoding	指定代理接受 gzip 编码的响应主体
Content-Type	`application/json`
Content-Length	对于 `POST` 或 `PUT` 请求，提交的消息文档的字节长度
X-Auth-Token	授权令牌
X-Project-Id	授予 X-Auth-Token 值的项目的 ID。队列在此项目下创建。项目 ID 与帐户 ID（有时也称为租户 ID）相同。
Client-ID	每个客户端实例的 UUID。必须以规范形式提交 UUID（例如，3381af92-2b9e-11e3-b191-71861300734c）。客户端一次生成 Client-ID。Client-ID 在客户端重启之间保持不变，因此客户端应重用相同的 Client-ID。

注意：所有与消息相关的操作都需要在头部中使用“Client-ID”，以确保消息不会回显到发布它们的客户端，除非客户端明确请求这样做。

使用消息队列 API¶

本章包含一个简单的练习，其中包含一些常用的消息队列请求。示例请求以 cURL 形式提供，后跟响应。

有关消息队列可用操作的完整列表，请参阅入门指南。每个操作在消息队列 API v2 参考中都有完整描述。

创建队列¶

创建队列操作在您选择的区域中创建队列。

PUT 请求的主体为空。

模板如下

PUT {endpoint}/queues/{queue_name}

queue_name 参数指定要赋予队列的名称。名称不得超过 64 个字节，并且仅限于 US-ASCII 字母、数字、下划线和连字符。

以下是创建队列请求和响应的示例

curl -i -X PUT https://queues.api.openstack.org/v2/queues/samplequeue \
-H "X-Auth-Token: " \
-H "Accept: application/json" \
-H "X-Project-Id: "

HTTP/1.1 201 Created
Content-Length: 0
Location: /v2/queues/samplequeue

发布消息¶

发布消息操作将一个或多个消息插入队列。

您可以在单个请求中提交最多 10 条消息，但必须将它们封装在集合容器中（JSON 中的数组，即使对于单条消息也是如此 - 如果没有 JSON 数组，您将收到“无效的主体请求”错误消息）。如果需要，您可以使用 location 头部或响应主体中的值来检索创建的消息以供进一步处理。

模板如下

POST {endpoint}/queues/{queue_name}/messages

客户端仅指定消息的主体和 ttl 属性。元数据（例如 id 和 age）会被添加。

响应主体包含一个资源路径列表，该列表对应于请求中提交的每个消息，顺序与提交的顺序相同。

如果在处理提交的消息时发生服务器端错误，则会返回一个部分列表。partial 属性设置为 true，并且客户端会尝试再次发布剩余的消息。

重要提示

partial 属性在 v1.0 API 中已被弃用，并且在 v1.1 API 中不可用。驱动程序现在需要以事务方式运行。换句话说，必须发布所有消息，或者不发布任何消息。

body 属性指定构成所发送消息主体的任意文档。

对于最大大小，适用以下规则

整个请求主体（按原样）的大小限制为 256 KB，包括空格。
发布消息的最大大小是整个请求文档的最大大小（而不是先前版本中各个消息 body 字段值的总和）。发生错误时，客户端会收到有关请求超出限制多少的通知。

文档必须是有效的 JSON。（消息队列服务会对其进行验证。）

ttl 属性指定消息的生存时间。当生存时间到期时，服务器会删除消息并将其从队列中删除。有效值为 60 到 1209600 秒（14 天）。

注意

服务器可能不会在消息的年龄达到 (ttl + 60) 秒时实际删除消息。因此，消息过期后可能存在 60 秒的延迟才能将其删除。

以下是发布消息请求和响应的示例

curl -i -X POST https://queues.api.openstack.org/v1/queues/samplequeue/messages -d \
'[{"ttl": 300,"body": {"event": "BackupStarted"}},{"ttl": 60,"body": {"play": "hockey"}}]' \
-H "Content-type: application/json" \
-H "Client-ID: e58668fc-26eb-11e3-8270-5b3128d43830" \
-H "X-Auth-Token: " \
-H "Accept: application/json" \
-H "X-Project-Id: "

HTTP/1.1 201 Created
Content-Length: 153
Content-Type: application/json; charset=utf-8
Location: /v1/queues/samplequeue/messages?ids=51ca00a0c508f154c912b85c,51ca00a0c508f154c912b85d

{"partial": false, "resources": ["/v1/queues/samplequeue/messages/51ca00a0c508f154c912b85c", "/v1/queues/samplequeue/messages/51ca00a0c508f154c912b85d"]}

声明消息¶

声明消息操作声明一组消息（最多为 limit 参数的值），从最早到最新，并跳过任何已声明的消息。如果队列中没有可用的消息，消息队列服务将返回 HTTP 204 No Content 响应代码。

模板如下

POST {endpoint}/queues/{queue_name}/claims{?limit}
Content-Type: application/json

{
    "ttl": {claim_ttl},
    "grace": {message_grace}
}

客户端（worker）需要在完成处理消息后删除消息。客户端在声明到期之前删除消息，以确保消息仅被处理一次。如果客户端需要更多时间，云服务提供更新声明操作来进行更改。有关此操作的描述，请参阅消息队列 API v1 参考。

声明的年龄是相对于服务器时钟而言的。声明的年龄对于确定消息处理的速度以及给定消息的声明是否即将到期很有用。

当声明到期时，它会释放回队列供其他 worker 声明。（如果原始 worker 无法处理消息，则另一个客户端 worker 可以声明该消息。）

limit 参数指定要声明的消息数。limit 参数是可配置的。默认值为 20。消息是根据可用消息的数量声明的。服务器可能会声明并返回少于请求数量的消息。

ttl 属性指定声明的生存时间。在消息被声明时，它们对其他 worker 不可用。该值必须在 60 到 43200 秒（12 小时）之间。

grace 属性指定消息的宽限期（以秒为单位）。有效值为 60 到 43200 秒（12 小时）。为了处理停止响应的 worker（长达 1209600 秒或 14 天，包括声明生存时间），服务器会将已声明消息的生存时间延长到至少与声明的生存时间一样长，再加上指定的宽限期。如果已声明的消息通常比宽限期长，则其到期时间不会进行调整。它

以下是声明消息请求和响应的示例

curl -i -X POST https://queues.api.openstack.org/v1/queues/samplequeue/claims -d \
'{"ttl": 300,"grace":300}' \
-H "Content-type: application/json" \
-H "Client-ID: e58668fc-26eb-11e3-8270-5b3128d43830" \
-H "X-Auth-Token: " \
-H "Accept: application/json" \
-H "X-Project-Id: "

HTTP/1.1 201 OK
Content-Length: 164
Content-Type: application/json; charset=utf-8
Location: /v1/queues/samplequeue/claims/51ca011c821e7250f344efd6
X-Project-Id:

[
  {
    "body": {
      "event": "BackupStarted"
    },
    "age": 124,
    "href": "\/v1\/queues\/samplequeue\/messages\/51ca00a0c508f154c912b85c?claim_id=51ca011c821e7250f344efd6",
    "ttl": 300
  }
]

使用声明 ID 删除消息¶

删除消息操作删除消息。

模板如下

DELETE {endpoint}/queues/{queue_name}/messages/{message_id}{?claim_id}

message_id 参数指定要删除的消息。

claim_id 参数指定仅当消息具有指定的声明 ID 并且该声明未到期时才删除该消息。此规范对于确保只有一个 worker 处理任何给定消息很有用。当 worker 的声明在删除其已处理的消息之前到期时，worker 必须回滚其采取的任何操作，因为另一个 worker 现在可以声明并处理相同的消息。

以下是删除消息请求和响应的示例

curl -i -X DELETE https://queues.api.openstack.org/v1/queues/samplequeue/messages/51ca00a0c508f154c912b85c?claim_id=51ca011c821e7250f344efd6 \
-H "Content-type: application/json" \
-H "X-Auth-Token: " \
-H "Client-ID: e58668fc-26eb-11e3-8270-5b3128d43830" \
-H "Accept: application/json" \
-H "X-Project-Id: "

HTTP/1.1 204 No Content

释放声明¶

释放声明操作立即释放声明，使与该声明关联的任何剩余的未删除消息可供其他 worker 使用。

模板如下

DELETE {endpoint}/queues/{queue_name}/claims/{claim_id}

当 worker 执行优雅关闭时，无法处理一个或多个消息，或者处理消息花费的时间比预期长并且希望使其他消息可供其他 worker 使用时，此操作很有用。

以下是释放声明请求和响应的示例

curl -i -X DELETE https://queues.api.openstack.org/v1/queues/samplequeue/claims/51ca011c821e7250f344efd6 \
-H "Content-type: application/json" \
-H "X-Auth-Token: " \
-H "Client-ID: e58668fc-26eb-11e3-8270-5b3128d43830"  \
-H "Accept: application/json" \
-H "X-Project-Id: "

HTTP/1.1 204 No Content

删除队列¶

删除队列操作立即删除队列及其所有现有消息。

模板如下

DELETE {endpoint}/queues/{queue_name}

以下是删除队列请求和响应的示例

curl -i -X DELETE https://queues.api.openstack.org/v1/queues/samplequeue \
-H "Content-type: application/json" \
-H "X-Auth-Token: " \
-H "Accept: application/json" \
-H "X-Project-Id: "

HTTP/1.1 204 No Content

常用头部

通用头部¶

使用消息队列 API¶

创建队列¶

发布消息¶

声明消息¶

使用声明 ID 删除消息¶

释放声明¶

删除队列¶

zaqar 21.0.1.dev3

页面内容