消息服务 API v2¶

这是由 Zaqar 项目提供的 OpenStack 消息服务 API 的参考文档。

API 版本¶

Zaqar API 仅支持在请求 URL 中表达的 ‘’主要版本’’。

GET

列出主要版本

获取主文档。

此操作获取主文档。

整个 API 可以从一个起点发现，即主文档。要探索整个 API，您只需要知道这个 URI。此文档是可缓存的。

主文档允许您使用关系链接编写客户端，因此客户端无需自行构造 URL。您可以单击并查看浏览器中的 JSON 文档。

有关主文档的更多信息，请参阅 http://tools.ietf.org/html/draft-nottingham-json-home-02。

响应代码¶

成功¶

代码	原因
`300 - 多重选择`	资源对应于多个表示形式。

错误¶

代码	原因
`503 - 服务不可用`	服务现在无法处理请求。

响应参数¶

名称	入参	类型	描述
versions	body	列表	受支持的主要 API 版本列表。

响应示例¶

{
   "versions":[
      {
         "status":"CURRENT",
         "updated":"2014-9-24T04:06:47Z",
         "media-types":[
            {
               "base":"application/json",
               "type":"application/vnd.openstack.messaging-v2+json"
            }
         ],
         "id":"2",
         "links":[
            {
               "href":"/v2/",
               "rel":"self"
            }
         ]
      }
   ]
}

队列 (queues)¶

队列是一个用于分组消息的逻辑实体。理想情况下，每个工作类型创建一个队列。例如，如果您想压缩文件，您将创建一个专门用于此作业的队列。从该队列读取的任何应用程序都只会压缩文件。

如今，Zaqar 中的队列更像一个主题，它是延迟创建的。用户可以在创建队列之前向队列发布消息。Zaqar 会自动创建队列/主题。

GET

/v2/queues

列出队列

列出队列。

当您帐户中没有队列时，请求列出队列会返回 204，而不是 200，因为没有要发送回的信息。

此操作列出项目的队列。队列按名称按字母顺序排序。

在列出队列时，我们可以在查询字符串参数中添加过滤器来过滤队列，例如名称和元数据。如果队列的元数据或名称与过滤器一致，则会将队列列出给用户，否则将过滤掉该队列。

响应代码¶

成功¶

代码	原因
`200 - 正常`	请求成功。

错误¶

代码	原因
`400 - 请求错误`	请求中的某些内容无效。
`401 - 未授权`	用户必须在发出请求之前进行身份验证。
`503 - 服务不可用`	服务现在无法处理请求。

请求参数¶

名称	入参	类型	描述
limit (可选)	查询	整数	请求项目页面大小。返回最多限制值数量的项目。使用 `limit` 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 `marker` 参数值。
marker (可选)	查询	字符串	最后一个已查看项目的 ID。使用 `limit` 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 `marker` 参数值。
详细 (可选)	查询	布尔值	‘detailed’ 指定在查询队列、flavor 和池时是否显示详细信息。
name (可选)	查询	字符串	‘name’ 指定在查询队列时是否按队列名称过滤队列。
with_count (可选)	查询	布尔值	‘with_count’ 指定在查询队列时是否显示队列数量。

响应参数¶

名称	入参	类型	描述
queues	body	列表	队列列表。
links	body	数组	与队列相关的链接。这是一个字典列表，每个字典都包含 `href` 和 `rel` 键。
count (可选)	body	整数	`count` 属性指定当前项目中的队列数量。

响应示例¶

{
   "queues":[
      {
         "href":"/v2/queues/beijing",
         "name":"beijing"
      },
      {
         "href":"/v2/queues/london",
         "name":"london"
      },
      {
         "href":"/v2/queues/wellington",
         "name":"wellington"
      }
   ],
   "links":[
      {
         "href":"/v2/queues?marker=wellington",
         "rel":"next"
      }
   ],
   "count": 3
}

PUT

/v2/queues/{queue_name}

创建队列

创建队列。

此操作创建新队列。

请求的主体为空。

queue_name 是您为队列指定的名称。名称长度不得超过 64 个字节，并且仅限于 US-ASCII 字母、数字、下划线和连字符。

在创建队列时，用户可以为队列指定元数据。目前，Zaqar 支持以下元数据：_flavor、_max_claim_count、_dead_letter_queue、_dead_letter_queue_messages_ttl 和 _enable_encrypt_messages。

为了支持延迟队列，现在添加了一个元数据 _default_message_delay。

响应代码¶

成功¶

代码	原因
`201 - 已创建`	请求已完成，并创建了新资源。
`204 - No Content`	请求已满足，但服务未返回任何内容。

错误¶

代码	原因
`400 - 请求错误`	请求中的某些内容无效。
`401 - 未授权`	用户必须在发出请求之前进行身份验证。
`503 - 服务不可用`	服务现在无法处理请求。

请求参数¶

名称	入参	类型	描述
queue_name	路径	字符串	队列的名称。
_dead_letter_queue (可选)	body	字符串	当消息达到最大声明计数后无法成功处理时，消息将被移动到的目标。不支持将队列 C 作为队列 B 的死信队列添加，而队列 B 已被设置为队列 A 的死信队列。此属性没有默认值。如果未显式设置，则表示当前队列没有死信队列。它是 Zaqar 队列的 `保留属性`之一。
_dead_letter_queue_messages_ttl (可选)	body	整数	移动到死信队列时，消息的新 TTL 设置。如果未设置，将保留当前的 TTL。它是 Zaqar 队列的 `保留属性`之一。
_default_message_delay (可选)	body	字符串	为队列定义的延迟消息。当消息发送到队列时，它将被延迟一段时间，这意味着在延迟过期之前无法声明它。用户可以定义队列级别的延迟值，也可以定义消息级别。后者具有更高的优先级。它是 Zaqar 队列的 `保留属性`之一。
_default_message_ttl	body	整数	为队列定义的默认消息 TTL，这将影响发布到队列的任何消息。因此，如果消息没有定义 TTL，则队列的 _default_message_ttl 将被使用。默认情况下，该值与 zaqar.conf 中定义的 ‘’max_message_ttl’’ 相同。它是 Zaqar 队列的 `保留属性`之一。在显式删除它后，该值将恢复为默认值。
_flavor (可选)	body	字符串	flavor 名称，可以告诉 Zaqar 将使用哪个存储池来创建队列。它是 Zaqar 队列的 `保留属性`之一。
_max_claim_count (可选)	body	整数	消息可以被声明的最大次数。通常，这意味着消息无法成功处理。此属性没有默认值。如果未设置，则表示当前队列未启用此功能。它是 Zaqar 队列的 `保留属性`之一。
_max_messages_post_size	body	整数	为队列定义的最大消息发布大小，这将影响发布到队列的任何消息。因此，用户可以定义队列级别的发布大小上限，该上限不能大于 zaqar.conf 中定义的 max_messages_post_size。它是 Zaqar 队列的 `保留属性`之一。在显式删除它后，该值将恢复为默认值。
_enable_encrypt_messages (可选)	body	布尔值	队列的消息加密开关，这将影响发布到队列的任何消息。默认值为 False。它是 Zaqar 队列的 `保留属性`之一。

请求示例¶

{
    "_max_messages_post_size": 262144,
    "_default_message_ttl": 3600,
    "_default_message_delay": 30,
    "_dead_letter_queue": "dead_letter",
    "_dead_letter_queue_messages_ttl": 3600,
    "_max_claim_count": 10,
    "_enable_encrypt_messages": true,
    "description": "Queue for international traffic billing."
}

此操作不返回响应体。

PATCH

/v2/queues/{queue_name}

更新队列

更新队列。

响应代码¶

成功¶

代码	原因
`200 - 正常`	请求成功。

错误¶

代码	原因
`400 - 请求错误`	请求中的某些内容无效。
`401 - 未授权`	用户必须在发出请求之前进行身份验证。
`404 - Not Found`	找不到请求的资源。
`409 - Conflict`	此资源有一个正在进行的操作，与此请求冲突。
`503 - 服务不可用`	服务现在无法处理请求。

请求参数¶

名称	入参	类型	描述
queue_name	路径	字符串	队列的名称。

在设置更新队列的请求主体时，主体必须是一个列表，其中包含一系列遵循 https://tools.ietf.org/html/draft-ietf-appsawg-json-patch-10 的 json 对象。

注意

“Content-Type”标头应为“application/openstack-messaging-v2.0-json-patch”
‘’path’’ 必须以 /metadata 开头，例如，如果键是 ‘’ttl’’，则路径应为 /metadata/ttl

请求示例¶

[
    {
        "op": "replace",
        "path": "/metadata/max_timeout",
        "value": 100
    }
]

响应示例¶

{
    "max_timeout": 100
}

GET

/v2/queues/{queue_name}

显示队列详细信息

显示队列的详细信息。

响应代码¶

成功¶

代码	原因
`200 - 正常`	请求成功。

错误¶

代码	原因
`400 - 请求错误`	请求中的某些内容无效。
`401 - 未授权`	用户必须在发出请求之前进行身份验证。
`503 - 服务不可用`	服务现在无法处理请求。

请求参数¶

名称	入参	类型	描述
queue_name	路径	字符串	队列的名称。

响应参数¶

名称	入参	类型	描述
_max_messages_post_size	body	整数	为队列定义的最大消息发布大小，这将影响发布到队列的任何消息。因此，用户可以定义队列级别的发布大小上限，该上限不能大于 zaqar.conf 中定义的 max_messages_post_size。它是 Zaqar 队列的 `保留属性`之一。在显式删除它后，该值将恢复为默认值。
_default_message_delay	body	字符串	为队列定义的延迟消息。当消息发送到队列时，它将被延迟一段时间，这意味着在延迟过期之前无法声明它。用户可以定义队列级别的延迟值，也可以定义消息级别。后者具有更高的优先级。它是 Zaqar 的 `保留属性`之一。
_default_message_ttl	body	整数	为队列定义的默认消息 TTL，这将影响发布到队列的任何消息。因此，如果消息没有定义 TTL，则队列的 _default_message_ttl 将被使用。默认情况下，该值与 zaqar.conf 中定义的 ‘’max_message_ttl’’ 相同。它是 Zaqar 队列的 `保留属性`之一。在显式删除它后，该值将恢复为默认值。
_max_claim_count	body	整数	消息可以被声明的最大次数。通常，这意味着消息无法成功处理。此属性没有默认值。如果未设置，则表示当前队列未启用此功能。它是 Zaqar 队列的 `保留属性`之一。
_dead_letter_queue	body	字符串	当消息达到最大声明计数后无法成功处理时，消息将被移动到的目标。不支持将队列 C 作为队列 B 的死信队列添加，而队列 B 已被设置为队列 A 的死信队列。此属性没有默认值。如果未显式设置，则表示当前队列没有死信队列。它是 `保留属性`之一。
_dead_letter_queue_messages_ttl	body	整数	移动到死信队列时，消息的新 TTL 设置。如果未设置，将保留当前的 TTL。它是 Zaqar 队列的 `保留属性`之一。
_enable_encrypt_messages (可选)	body	布尔值	队列的消息加密开关，这将影响发布到队列的任何消息。默认值为 False。它是 Zaqar 队列的 `保留属性`之一。

响应示例¶

{
    "_max_messages_post_size": 262144,
    "_default_message_ttl": 3600,
    "description": "Queue used for billing.",
    "_max_claim_count": 10,
    "_dead_letter_queue": "dead_letter",
    "_dead_letter_queue_messages_ttl": 3600,
    "_enable_encrypt_messages": true
}

DELETE

/v2/queues/{queue_name}

删除队列

删除指定的队列。

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

queue_name 是您为队列指定的名称。名称长度不得超过 64 个字节，并且仅限于 US-ASCII 字母、数字、下划线和连字符。

响应代码¶

成功¶

代码	原因
`204 - No Content`	请求已满足，但服务未返回任何内容。

错误¶

代码	原因
`400 - 请求错误`	请求中的某些内容无效。
`401 - 未授权`	用户必须在发出请求之前进行身份验证。
`503 - 服务不可用`	服务现在无法处理请求。

请求参数¶

名称	入参	类型	描述
queue_name	路径	字符串	队列的名称。

此操作不接受请求主体，也不返回响应主体。

GET

/v2/queues/{queue_name}/stats

获取队列统计信息

返回指定队列的统计信息。

此操作返回队列统计信息，包括队列中消息的数量，按状态分类。

如果 total 属性的值为 0，则响应中不包含 oldest 和 newest 消息统计信息。

响应代码¶

成功¶

代码	原因
`200 - 正常`	请求成功。

错误¶

代码	原因
`400 - 请求错误`	请求中的某些内容无效。
`401 - 未授权`	用户必须在发出请求之前进行身份验证。
`503 - 服务不可用`	服务现在无法处理请求。

请求参数¶

名称	入参	类型	描述
queue_name	路径	字符串	队列的名称。

响应示例¶

{
    "messages":{
         "claimed": 10,
         "total": 20,
         "free": 10
    }
}

POST

/v2/queues/{queue_name}/share

预签名队列

为给定的队列创建一个预签名 URL。

注意

对于预签名 URL，不能延迟创建队列。这是为了防止队列被删除而用户仍然拥有有效的 URL。在只有一个池的部署中，这并不是一个大问题。但是，如果部署使用多种类型的池，延迟创建的队列可能会最终进入不希望的池，并且攻击者可能会尝试对该池进行 DoS 攻击。因此，每当创建预签名 URL 时，如果不存在池，则需要创建它。

响应代码¶

成功¶

代码	原因
`200 - 正常`	请求成功。

错误¶

代码	原因
`400 - 请求错误`	请求中的某些内容无效。
`401 - 未授权`	用户必须在发出请求之前进行身份验证。
`404 - Not Found`	找不到请求的资源。
`503 - 服务不可用`	服务现在无法处理请求。

请求参数¶

名称	入参	类型	描述
queue_name	路径	字符串	队列的名称。
paths (可选)	body	列表	预签名队列可以支持的路径列表。它可以是 `messages`、`subscriptions`、`claims` 的集合。
methods (可选)	body	列表	HTTP 方法列表。创建此 URL 的 HTTP 方法。通过选择 HTTP 方法，可以为特定资源提供读取或读写访问权限。
expires (可选)	body	字符串	指示预签名将到期的时刻。

请求示例¶

{
  "paths": ["messages", "claims", "subscriptions"],
  "methods": ["GET", "POST", "PUT", "PATCH"],
  "expires": "2016-09-01T00:00:00"
}

响应参数¶

名称	入参	类型	描述
project	body	字符串	当前项目/租户的 ID。
paths (可选)	body	列表	预签名队列可以支持的路径列表。它可以是 `messages`、`subscriptions`、`claims` 的集合。
methods (可选)	body	列表	HTTP 方法列表。创建此 URL 的 HTTP 方法。通过选择 HTTP 方法，可以为特定资源提供读取或读写访问权限。
expires (可选)	body	字符串	指示预签名将到期的时刻。
signature	body	列表	在创建预签名 URL 后生成签名。可以通过将以下内容添加到 HTTP 标头来使用它 URL-Signature: 6a63d63242ebd18c3518871dda6fdcb6273db2672c599bf985469241e9a1c799 URL-Expires: 2015-05-31T19:00:17Z

响应示例¶

{
    "project": "2887aabf368046a3bb0070f1c0413470",
    "paths": [
        "/v2/queues/test/messages",
        "/v2/queues/test/claims"
        "/v2/queues/test/subscriptions"
    ],
    "expires": "2016-09-01T00:00:00",
    "methods": [
        "GET",
        "PATCH",
        "POST",
        "PUT"
    ],
    "signature": "6a63d63242ebd18c3518871dda6fdcb6273db2672c599bf985469241e9a1c799"
}

POST

/v2/queues/{queue_name}/purge

清除队列

清除队列的特定资源。

注意

现在 Zaqar 支持从队列中清除 “messages” 和 “subscriptions” 资源。

响应代码¶

成功¶

代码	原因
`204 - No Content`	请求已满足，但服务未返回任何内容。

错误¶

代码	原因
`400 - 请求错误`	请求中的某些内容无效。
`401 - 未授权`	用户必须在发出请求之前进行身份验证。
`503 - 服务不可用`	服务现在无法处理请求。

请求参数¶

名称	入参	类型	描述
queue_name	路径	字符串	队列的名称。
resource_types (可选)	body	列表	`resource_types` 属性允许用户清除队列的特定资源。

请求示例¶

{
    "resource_types": ["messages", "subscriptions"]
}

消息 (messages)¶

消息通过队列发送，直到被接收者删除或由系统根据 TTL（生存时间）值自动删除。

所有与消息相关的操作都需要在标头中包含 Client-ID。这是为了确保消息不会回显给发布它们的客户端，除非客户端明确请求这样做。

POST

/v2/queues/{queue_name}/messages

发布消息

发布指定队列的消息或消息。

此操作发布指定的消息或消息。

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

客户端仅指定消息的主体和 TTL。服务器插入元数据，例如 ID 和年龄。

响应体包含一个资源路径列表，该列表对应于请求中提交的每个消息，顺序与消息提交的顺序一致。如果在提交消息的处理过程中发生服务器端错误，则返回一个部分列表，并将 partial 属性设置为 true，客户端尝试再次发布剩余的消息。如果服务器无法将任何消息入队，服务器将返回一个 503 Service Unavailable 错误消息。

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

以下规则适用于最大大小

发布的消息的最大大小是整个请求文档的最大大小（而不是早期版本中各个消息体字段值的总和）。如果发生错误，客户端现在将收到超出限制的程度的通知。

大小限制为 256 KB，包括空格。

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

ttl 属性指定服务器在将消息标记为过期并从队列中删除之前等待的时间。 ttl 的值必须在 60 到 1209600 秒（14 天）之间。请注意，服务器可能不会在消息的年龄达到 (ttl + 60) 秒之前实际删除该消息，以便在存储实现方面提供灵活性。

delay 属性指定消息可以被声明的最长时间。 delay 的值必须在 0 到 900 秒（15 分钟）之间。

响应代码¶

成功¶

代码	原因
`201 - 已创建`	请求已完成，并创建了新资源。

错误¶

代码	原因
`400 - 请求错误`	请求中的某些内容无效。
`401 - 未授权`	用户必须在发出请求之前进行身份验证。
`404 - Not Found`	找不到请求的资源。
`503 - 服务不可用`	服务现在无法处理请求。

请求参数¶

名称	入参	类型	描述
queue_name	路径	字符串	队列的名称。

请求示例¶

{
  "messages": [
    {
      "ttl": 300,
      "delay": 20,
      "body": {
        "event": "BackupStarted",
        "backup_id": "c378813c-3f0b-11e2-ad92-7823d2b0f3ce"
      }
    },
    {
      "body": {
        "event": "BackupProgress",
        "current_bytes": "0",
        "total_bytes": "99614720"
      }
    }
  ]
}

响应参数¶

名称	入参	类型	描述
resources (可选)	body	列表	消息 URL 的列表。

响应示例¶

{
  "resources": [
    "/v2/queues/demoqueue/messages/51db6f78c508f17ddc924357",
    "/v2/queues/demoqueue/messages/51db6f78c508f17ddc924358"
  ]
}

GET

/v2/queues/{queue_name}/messages

列出消息

列出指定队列中的消息。

当队列未找到或未找到消息时，请求列出消息将返回 204，而不是 200，因为没有信息可以发送回去。具有格式错误 ID 或未按 ID 找到的消息将被忽略。

此操作获取指定队列中的消息或消息。

消息 ID 和标记是不透明字符串。客户端不应对其格式或长度做出任何假设。此外，客户端应假设标记和消息 ID 之间没有关系（即，一个不能从另一个推导出来）。这允许各种存储驱动程序实现。

结果按年龄排序，最旧的消息在前。

响应代码¶

成功¶

代码	原因
`200 - 正常`	请求成功。

错误¶

代码	原因
`400 - 请求错误`	请求中的某些内容无效。
`401 - 未授权`	用户必须在发出请求之前进行身份验证。
`404 - Not Found`	找不到请求的资源。
`503 - 服务不可用`	服务现在无法处理请求。

请求参数¶

名称	入参	类型	描述
queue_name	路径	字符串	队列的名称。
marker (可选)	查询	字符串	最后一个已查看项目的 ID。使用 `limit` 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 `marker` 参数值。
limit (可选)	查询	整数	请求项目页面大小。返回最多限制值数量的项目。使用 `limit` 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 `marker` 参数值。
echo（可选）	查询	布尔值	指示是否可以将消息回显给发布它们的客户端。
include_claimed（可选）	查询	布尔值	指示消息列表是否应包含已声明的消息。
include_delayed（可选）	查询	布尔值	指示消息列表是否应包含延迟的消息。

响应参数¶

名称	入参	类型	描述
messages	body	列表	消息列表。
links	body	数组	与队列相关的链接。这是一个字典列表，每个字典都包含 `href` 和 `rel` 键。

响应示例¶

{
    "messages": [
        {
            "body": {
                "current_bytes": "0",
                "event": "BackupProgress",
                "total_bytes": "99614720"
            },
            "age": 482,
            "href": "/v2/queues/beijing/messages/578edfe6508f153f256f717b",
            "id": "578edfe6508f153f256f717b",
            "ttl": 3600,
            "checksum": "MD5:abf7213555626e29c3cb3e5dc58b3515"
        },
        {
            "body": {
                "current_bytes": "0",
                "event": "BackupProgress",
                "total_bytes": "99614720"
            },
            "age": 456,
            "href": "/v2/queues/beijing/messages/578ee000508f153f256f717d",
            "id": "578ee000508f153f256f717d",
            "ttl": 3600,
            "checksum": "MD5:abf7213555626e29c3cb3e5dc58b3515"
        }
    ],
    "links": [
        {
            "href": "/v2/queues/beijing/messages?marker=17&echo=true",
            "rel": "next"
        }
    ]
}

GET

/v2/queues/{queue_name}/messages

获取一组消息

从指定队列获取指定的一组消息。

与使用一系列单独的 GET 相比，此操作提供了一种更有效的方法来查询多个消息。请注意，ID 列表不能超过 20 个。如果提供格式错误的 ID 或不存在的消息 ID，则会忽略它，并返回剩余的消息。

与获取消息操作不同，客户端自己的消息始终在此操作中返回。如果使用 ids 参数，则不使用 echo 参数，如果指定了该参数，则会被忽略。

消息属性定义如下：href 是一个不透明的相对 URI，客户端可以使用它来唯一标识消息资源并与之交互。 ttl 是在发布消息时设置的 TTL。消息在 (ttl - age) 秒后过期。 age 是相对于服务器时钟的秒数。 body 是提交到原始发布消息请求的任意文档。 checksum 是 body 的哈希摘要，默认算法是 MD5。

响应代码¶

成功¶

代码	原因
`200 - 正常`	请求成功。

错误¶

代码	原因
`400 - 请求错误`	请求中的某些内容无效。
`401 - 未授权`	用户必须在发出请求之前进行身份验证。
`404 - Not Found`	找不到请求的资源。
`503 - 服务不可用`	服务现在无法处理请求。

请求参数¶

名称

入参

类型

描述

queue_name

路径

字符串

队列的名称。

ids（可选）

查询

列表

消息 ID 的列表。 pop & ids 参数互斥。在请求中使用它们会导致 HTTP 400。

注意：实际上，它不是一个真正的列表，而是用逗号分隔的许多消息 ID 的字符串，例如：/messages?ids=578f0055508f153f256f717e,578f0055508f153f256f717f

响应参数¶

名称	入参	类型	描述
messages	body	列表	消息列表。

响应示例¶

{
    "messages": [
        {
            "body": {
                "current_bytes": "0",
                "event": "BackupProgress",
                "total_bytes": "99614720"
            },
            "age": 443,
            "href": "/v2/queues/beijing/messages/578f0055508f153f256f717f",
            "id": "578f0055508f153f256f717f",
            "ttl": 3600
        }
    ]
}

DELETE

/v2/queues/{queue_name}/messages

删除一组消息

提供消息的批量删除。

此操作立即删除指定的消息。如果任何消息 ID 格式错误或不存在，则会忽略它们。剩余的有效消息 ID 将被删除。请注意，用户应输入 ids 或 pop 参数，否则此 API 将不删除任何内容。如果提供 pop，则该值必须至少为 1，并且不得大于 conf 中的 max_messages_per_claim_or_pop。如果提供 ids，则它应包含至少一个 ID，并且不得大于 conf 中的 max_messages_per_page。

响应代码¶

成功¶

代码	原因
`200 - 正常`	请求成功。
`204 - No Content`	请求已满足，但服务未返回任何内容。

错误¶

代码	原因
`400 - 请求错误`	请求中的某些内容无效。
`401 - 未授权`	用户必须在发出请求之前进行身份验证。
`404 - Not Found`	找不到请求的资源。
`503 - 服务不可用`	服务现在无法处理请求。

请求参数¶

此操作不接受请求体。

名称

入参

类型

描述

queue_name

路径

字符串

队列的名称。

ids（可选）

查询

列表

消息 ID 的列表。 pop & ids 参数互斥。在请求中使用它们会导致 HTTP 400。

注意：实际上，它不是一个真正的列表，而是用逗号分隔的许多消息 ID 的字符串，例如：/messages?ids=578f0055508f153f256f717e,578f0055508f153f256f717f

pop（可选）

查询

整数

pop 指定将从队列中弹出的消息数量。 pop & ids 参数互斥。在请求中使用它们会导致 HTTP 400。

响应示例¶

只有当使用 pop 查询参数时，此操作才会返回响应体。

{
  "messages": [
    {
      "body": {
        "current_bytes": "0",
        "event": "BackupProgress",
        "total_bytes": "99614720"
      },
      "age": 443,
      "claim_count": 1,
      "claim_id": "51db7067821e727dc24df754",
      "id": "578f0055508f153f256f717f",
      "ttl": 3600
    }
  ]
}

GET

/v2/queues/{queue_name}/messages/{message_id}

获取特定消息

从指定队列获取指定的消息。

此操作从指定队列获取指定的消息。

如果消息 ID 格式错误或不存在，则不返回任何消息。

消息字段定义如下：href 是一个不透明的相对 URI，客户端可以使用它来唯一标识消息资源并与之交互。 ttl 是在发布消息时设置的 TTL。消息在 (ttl - age) 秒后过期。 age 是相对于服务器时钟的秒数。 body 是提交到原始发布消息请求的任意文档。 checksum 是 body 的哈希摘要，默认算法是 MD5。

响应代码¶

成功¶

代码	原因
`200 - 正常`	请求成功。

错误¶

代码	原因
`400 - 请求错误`	请求中的某些内容无效。
`401 - 未授权`	用户必须在发出请求之前进行身份验证。
`404 - Not Found`	找不到请求的资源。
`503 - 服务不可用`	服务现在无法处理请求。

请求参数¶

名称	入参	类型	描述
queue_name	路径	字符串	队列的名称。
message_id	路径	字符串	消息的 ID。

响应示例¶

{
    "body": {
        "current_bytes": "0",
        "event": "BackupProgress",
        "total_bytes": "99614720"
    },
    "age": 1110,
    "href": "/v2/queues/beijing/messages/578f0055508f153f256f717f",
    "id": "578f0055508f153f256f717f",
    "ttl": 3600,
    "checksum": "MD5:abf7213555626e29c3cb3e5dc58b3515"
}

DELETE

/v2/queues/{queue_name}/messages/{message_id}

删除特定消息

从指定队列删除指定的消息。

此操作立即删除指定的消息。

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

如果您没有指定 claim_id，但消息已被声明，则操作将失败。您只能通过提供适当的 claim_id 来删除已声明的消息。

响应代码¶

成功¶

代码	原因
`204 - No Content`	请求已满足，但服务未返回任何内容。

错误¶

代码	原因
`400 - 请求错误`	请求中的某些内容无效。
`401 - 未授权`	用户必须在发出请求之前进行身份验证。
`404 - Not Found`	找不到请求的资源。
`503 - 服务不可用`	服务现在无法处理请求。

请求¶

名称	入参	类型	描述
queue_name	路径	字符串	队列的名称。
message_id	路径	字符串	消息的 ID。

此操作不接受请求主体，也不返回响应主体。

声明（claims）¶

声明是一种标记消息的机制，以便其他 worker 不会处理相同的消息。

POST

/v2/queues/{queue_name}/claims

声明消息

从指定队列声明一组消息。

此操作从最旧到最新声明一组消息（最多为 limit 参数的值），并跳过任何已声明的消息。如果没有可用的未声明的消息，API 将返回 204 No Content 消息。

当客户端（worker）完成处理消息时，应在 claim 过期之前删除该消息，以确保该消息仅处理一次。作为删除操作的一部分，worker 应指定 claim ID（最好是简单地使用提供的 href）。如果 worker 执行这些操作，那么如果 claim 简单地过期，服务器可以返回错误并通知 worker 竞争条件。此操作让 worker 有机会回滚其对给定消息的处理，因为另一个 worker 可以声明该消息并处理它。

claim 的年龄是相对于服务器时钟的。claim 的年龄对于确定消息的处理速度以及给定消息的 claim 是否即将过期非常有用。

当 claim 过期时，它将被释放。如果原始 worker 未能处理该消息，则另一个客户端 worker 可以声明该消息。

请注意，claim 创建是尽力而为的，这意味着 worker 可能会声明并返回少于请求的消息数。

ttl 属性指定服务器在释放 claim 之前等待的时间。ttl 值必须在 60 到 43200 秒（12 小时）之间。您必须在请求中包含此属性的值。

grace 属性指定消息的宽限期（以秒为单位）。 grace 的值必须在 60 到 43200 秒（12 小时）之间。您必须在请求中包含此属性的值。为了处理停止响应的 worker（长达 1209600 秒或 14 天，包括 claim 的生命周期），服务器会将已声明消息的生命周期延长到至少与 claim 本身的生命周期一样长，再加上指定的宽限期。如果已声明的消息的正常生存期长于 claim 的生存期，则其到期时间不会进行调整。

响应代码¶

成功¶

代码	原因
`201 - 已创建`	请求已完成，并创建了新资源。
`204 - No Content`	请求已满足，但服务未返回任何内容。

错误¶

代码	原因
`401 - 未授权`	用户必须在发出请求之前进行身份验证。
`403 - 禁止`	策略不允许当前用户执行此操作。
`404 - Not Found`	找不到请求的资源。
`503 - 服务不可用`	服务现在无法处理请求。

请求参数¶

名称	入参	类型	描述
queue_name	路径	字符串	队列的名称。
limit (可选)	查询	整数	`limit` 指定要声明的最多 20 条消息（可配置）。如果未指定，则 limit 默认为 10。请注意，claim 创建是尽力而为的，这意味着服务器可能会声明并返回少于请求的消息数。
ttl（可选）	body	整数	`ttl` 属性指定服务器在释放 claim 之前等待的时间。ttl 值必须在 60 到 43200 秒（12 小时）之间。您必须在请求中包含此属性的值。
grace（可选）	body	整数	`grace` 属性指定消息的宽限期（以秒为单位）。 `grace` 的值必须在 60 到 43200 秒（12 小时）之间。您必须在请求中包含此属性的值。为了处理停止响应的 worker（长达 1209600 秒或 14 天，包括 claim 的生命周期），服务器会将已声明消息的生命周期延长到至少与 claim 本身的生命周期一样长，再加上指定的宽限期。如果已声明的消息的正常生存期长于 claim 的生存期，则其到期时间不会进行调整。

示例声明消息：JSON 请求

{
    "ttl": 300,
    "grace": 300
}

响应参数¶

示例声明消息：JSON 响应

{
    "messages": [
        {
            "body": {
                "event": "BackupStarted"
            },
            "age": 239,
            "href": "/v2/queues/demoqueue/messages/51db6f78c508f17ddc924357?claim_id=51db7067821e727dc24df754",
            "ttl": 300,
            "checksum": "MD5:82eb2714b7c0237d373947c046cac78d"
        }
    ]
}

GET

/v2/queues/{queue_name}/claims/{claim_id}

查询声明

查询指定队列的指定声明。

此操作查询指定队列的指定声明。格式错误的 ID 或未按 ID 找到的声明将被忽略。

响应代码¶

成功¶

代码	原因
`200 - 正常`	请求成功。

错误¶

代码	原因
`401 - 未授权`	用户必须在发出请求之前进行身份验证。
`403 - 禁止`	策略不允许当前用户执行此操作。
`404 - Not Found`	找不到请求的资源。
`503 - 服务不可用`	服务现在无法处理请求。

请求参数¶

名称	入参	类型	描述
queue_name	路径	字符串	队列的名称。
claim_id	路径	字符串	声明的 ID。

响应参数¶

示例查询声明：JSON 响应

{
  "age": 57,
  "href": "/v2/queues/demoqueue/claims/51db7067821e727dc24df754",
  "messages": [
    {
      "body": {
        "event": "BackupStarted"
      },
      "age": 296,
      "href": "/v2/queues/demoqueue/messages/51db6f78c508f17ddc924357?claim_id=51db7067821e727dc24df754",
      "ttl": 300
    }
  ],
  "ttl": 300
}

PATCH

/v2/queues/{queue_name}/claims/{claim_id}

更新（续订）声明

更新指定队列的指定声明。

此操作更新指定队列的指定声明。ID 格式错误的声明或未按 ID 找到的声明将被忽略。

客户端应在长时间运行的批量作业期间定期更新声明，以避免在处理消息时丢失声明。客户端可以通过向特定声明资源发出 PATCH 命令并包含声明的新 TTL（可以与原始 TTL 不同）来更新声明。服务器重置声明的年龄并应用新的 TTL。

响应代码¶

成功¶

代码	原因
`204 - No Content`	请求已满足，但服务未返回任何内容。

错误¶

代码	原因
`401 - 未授权`	用户必须在发出请求之前进行身份验证。
`403 - 禁止`	策略不允许当前用户执行此操作。
`404 - Not Found`	找不到请求的资源。
`503 - 服务不可用`	服务现在无法处理请求。

请求参数¶

名称	入参	类型	描述
queue_name	路径	字符串	队列的名称。
claim_id	路径	字符串	声明的 ID。
ttl（可选）	body	整数	`ttl` 属性指定服务器在释放 claim 之前等待的时间。ttl 值必须在 60 到 43200 秒（12 小时）之间。您必须在请求中包含此属性的值。
grace（可选）	body	整数	`grace` 属性指定消息的宽限期（以秒为单位）。 `grace` 的值必须在 60 到 43200 秒（12 小时）之间。您必须在请求中包含此属性的值。为了处理停止响应的 worker（长达 1209600 秒或 14 天，包括 claim 的生命周期），服务器会将已声明消息的生命周期延长到至少与 claim 本身的生命周期一样长，再加上指定的宽限期。如果已声明的消息的正常生存期长于 claim 的生存期，则其到期时间不会进行调整。

示例更新声明：JSON 请求

{
  "ttl": 300,
  "grace": 300
}

此操作不返回响应体。

DELETE

/v2/queues/{queue_name}/claims/{claim_id}

删除（释放）声明

释放指定队列的指定声明。

此操作会立即释放声明，使与该声明关联的任何剩余的、未删除的消息可供其他 worker 使用。ID 格式错误的声明或未按 ID 找到的声明将被忽略。

当 worker 执行优雅关闭、未能处理一个或多个消息，或处理消息所需的时间超过预期时，此操作很有用，并且希望使其他 worker 可用剩余的消息。

响应代码¶

成功¶

代码	原因
`204 - No Content`	请求已满足，但服务未返回任何内容。

错误¶

代码	原因
`401 - 未授权`	用户必须在发出请求之前进行身份验证。
`403 - 禁止`	策略不允许当前用户执行此操作。
`404 - Not Found`	找不到请求的资源。
`503 - 服务不可用`	服务现在无法处理请求。

请求参数¶

名称	入参	类型	描述
queue_name	路径	字符串	队列的名称。
claim_id	路径	字符串	声明的 ID。

此操作不接受请求主体，也不返回响应主体。

订阅 (subscriptions)¶

订阅是队列/主题与目标订阅者之间的关系。为特定订阅者（例如电子邮件或 webhook）创建订阅后，当新消息发布到队列时，订阅者将自动收到通知。

GET

/v2/queues/{queue_name}/subscriptions

列出订阅

列出队列的订阅。

此操作列出队列的订阅。订阅按名称按字母顺序排序。

响应代码¶

成功¶

代码	原因
`200 - 正常`	请求成功。

错误¶

代码	原因
`400 - 请求错误`	请求中的某些内容无效。
`401 - 未授权`	用户必须在发出请求之前进行身份验证。
`503 - 服务不可用`	服务现在无法处理请求。

请求参数¶

名称	入参	类型	描述
queue_name	路径	字符串	队列的名称。

查询参数¶

名称	入参	类型	描述
limit (可选)	查询	整数	请求项目页面大小。返回最多限制值数量的项目。使用 `limit` 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 `marker` 参数值。
marker (可选)	查询	字符串	最后一个已查看项目的 ID。使用 `limit` 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 `marker` 参数值。

响应参数¶

名称	入参	类型	描述
subscriptions (可选)	body	列表	订阅列表。
links	body	数组	与队列相关的链接。这是一个字典列表，每个字典都包含 `href` 和 `rel` 键。

响应示例¶

{
  "links": [
    {
      "href": "/v2/queues/test/subscriptions?marker=57692ab13990b48c644bb7e6",
      "rel": "next"
    }
  ],
  "subscriptions": [
    {
      "age": 13,
      "id": "57692aa63990b48c644bb7e5",
      "subscriber": "http://10.229.49.117:5678",
      "source": "test",
      "ttl": 360,
      "options": {}
    },
    {
      "age": 2,
      "id": "57692ab13990b48c644bb7e6",
      "subscriber": "http://10.229.49.117:5679",
      "source": "test",
      "ttl": 360,
      "options": {}
    }
  ]
}

POST

/v2/queues/{queue_name}/subscriptions

创建订阅

创建订阅。

此操作创建新的订阅。

响应代码¶

成功¶

代码	原因
`201 - 已创建`	请求已完成，并创建了新资源。

错误¶

代码	原因
`400 - 请求错误`	请求中的某些内容无效。
`401 - 未授权`	用户必须在发出请求之前进行身份验证。
`503 - 服务不可用`	服务现在无法处理请求。

请求参数¶

名称	入参	类型	描述
queue_name	路径	字符串	队列的名称。
subscriber	body	字符串	`subscriber` 属性指定消息通知到的目标地址。它的设计目的是匹配关于相对统一资源定位符的 Internet RFC。Zaqar 现在支持两种类型的订阅者：http/https 和电子邮件。http/https 订阅者应以 `http/https` 开头。电子邮件订阅者应以 `mailto` 开头。
ttl（可选）	body	整数	`ttl` 属性指定订阅的存活时间。ttl 值必须大于 60 秒。默认值为 3600 秒。
options (可选)	body	dict	`options` 属性指定订阅的额外元数据。该值必须是字典，可以包含任何键值对。如果订阅者是“mailto”。`options` 可以包含 `from` 和 `subject` 以指示电子邮件的作者和标题。

请求示例¶

{
    "subscriber":"http://10.229.49.117:5679",
    "ttl":3600,
    "options":{}
}

{
    "subscriber":"mailto:test@gmail.com",
    "ttl":3600,
    "options":{
      "from": "Jack",
      "subject": "Hello"
    }
}

响应参数¶

名称	入参	类型	描述
subscription_id (可选)	body	字符串	订阅的 ID。

响应示例¶

{
  "subscription_id": "57692ab13990b48c644bb7e6"
}

PATCH

/v2/queues/{queue_name}/subscriptions/{subscription_id}

更新订阅

更新订阅。

响应代码¶

成功¶

代码	原因
`204 - No Content`	请求已满足，但服务未返回任何内容。

错误¶

代码	原因
`400 - 请求错误`	请求中的某些内容无效。
`401 - 未授权`	用户必须在发出请求之前进行身份验证。
`404 - Not Found`	找不到请求的资源。
`409 - Conflict`	此资源有一个正在进行的操作，与此请求冲突。
`503 - 服务不可用`	服务现在无法处理请求。

请求参数¶

名称	入参	类型	描述
queue_name	路径	字符串	队列的名称。
subscription_id	路径	字符串	订阅的 ID。
subscriber	body	字符串	`subscriber` 属性指定消息通知到的目标地址。它的设计目的是匹配关于相对统一资源定位符的 Internet RFC。Zaqar 现在支持两种类型的订阅者：http/https 和电子邮件。http/https 订阅者应以 `http/https` 开头。电子邮件订阅者应以 `mailto` 开头。
ttl（可选）	body	整数	`ttl` 属性指定订阅的存活时间。ttl 值必须大于 60 秒。默认值为 3600 秒。
options (可选)	body	dict	`options` 属性指定订阅的额外元数据。该值必须是字典，可以包含任何键值对。如果订阅者是“mailto”。`options` 可以包含 `from` 和 `subject` 以指示电子邮件的作者和标题。

请求示例¶

{
    "subscriber":"http://10.229.49.117:1234",
    "ttl":360,
    "options":{
      "name": "test"
    }
}

此操作不返回响应体。

GET

/v2/queues/{queue_name}/subscriptions/{subscription_id}

显示订阅详情

显示订阅的详细信息。

响应代码¶

成功¶

代码	原因
`200 - 正常`	请求成功。

错误¶

代码	原因
`400 - 请求错误`	请求中的某些内容无效。
`401 - 未授权`	用户必须在发出请求之前进行身份验证。
`503 - 服务不可用`	服务现在无法处理请求。

请求参数¶

名称	入参	类型	描述
queue_name	路径	字符串	队列的名称。
subscription_id	路径	字符串	订阅的 ID。

响应参数¶

名称	入参	类型	描述
age (可选)	body	整数	订阅存在了多长时间。
id (可选)	body	字符串	订阅的 ID。
subscriber	body	字符串	`subscriber` 属性指定消息通知到的目标地址。它的设计目的是匹配关于相对统一资源定位符的 Internet RFC。Zaqar 现在支持两种类型的订阅者：http/https 和电子邮件。http/https 订阅者应以 `http/https` 开头。电子邮件订阅者应以 `mailto` 开头。
source (可选)	body	字符串	订阅注册的队列名称。
ttl（可选）	body	整数	`ttl` 属性指定订阅的存活时间。ttl 值必须大于 60 秒。默认值为 3600 秒。
options (可选)	body	dict	`options` 属性指定订阅的额外元数据。该值必须是字典，可以包含任何键值对。如果订阅者是“mailto”。`options` 可以包含 `from` 和 `subject` 以指示电子邮件的作者和标题。

响应示例¶

{
  "age": 1632,
  "id": "576b54963990b48c644bb7e7",
  "subscriber": "http://10.229.49.117:5679",
  "source": "test",
  "ttl": 3600,
  "options": {
    "name": "test"
  }
}

DELETE

/v2/queues/{queue_name}/subscriptions/{subscription_id}

删除订阅

删除指定的订阅。

响应代码¶

成功¶

代码	原因
`204 - No Content`	请求已满足，但服务未返回任何内容。

错误¶

代码	原因
`400 - 请求错误`	请求中的某些内容无效。
`401 - 未授权`	用户必须在发出请求之前进行身份验证。
`503 - 服务不可用`	服务现在无法处理请求。

请求参数¶

名称	入参	类型	描述
queue_name	路径	字符串	队列的名称。
subscription_id	路径	字符串	订阅的 ID。

此操作不接受请求主体，也不返回响应主体。

POST

/v2/queues/{queue_name}/subscriptions/{subscription_id}/confirm

确认订阅

确认订阅。

此操作可以确认或取消订阅。

响应代码¶

成功¶

代码	原因
`201 - 已创建`	请求已完成，并创建了新资源。

错误¶

代码	原因
`400 - 请求错误`	请求中的某些内容无效。
`401 - 未授权`	用户必须在发出请求之前进行身份验证。
`503 - 服务不可用`	服务现在无法处理请求。

请求参数¶

名称	入参	类型	描述
queue_name	路径	字符串	队列的名称。
subscription_id	路径	字符串	订阅的 ID。
confirmed	body	布尔值	`confirmed` 属性指定是否确认订阅。

请求示例¶

{
    "confirmed": true
}

此操作不返回响应体。

健康 (health)¶

通过健康 API，用户或操作员可以大致了解 Zaqar 服务器的状态。这些信息可用于基本验证、性能检查等。

GET

/v2/ping

Ping

简单的健康检查，供最终用户使用。

当服务器正常工作时，向 Zaqar 服务器发送 ping 请求返回 204，否则返回 503。这对于最终用户检查消息服务是否处于工作状态是一个方便的 API。

响应代码¶

成功¶

代码	原因
`204 - No Content`	请求已满足，但服务未返回任何内容。

错误¶

代码	原因
`503 - 服务不可用`	服务现在无法处理请求。

此操作不接受请求主体，也不返回响应主体。

GET

/v2/health

健康状况

详细的健康检查，供云操作员/管理员使用。

这是一个 admin only API。向 Zaqar 服务器请求详细的健康信息。

响应体将取决于 Zaqar 服务器的存储设置。默认情况下，未创建池。然后响应体将仅包含 catalog_reachable。否则，响应体将包含 catalog_reachable 和每个池的健康状态。

响应代码¶

成功¶

代码	原因
`200 - 正常`	请求成功。

错误¶

代码	原因
`401 - 未授权`	用户必须在发出请求之前进行身份验证。
`403 - 禁止`	策略不允许当前用户执行此操作。
`503 - 服务不可用`	服务现在无法处理请求。

响应参数¶

名称	入参	类型	描述
catalog_reachable	body	布尔值	一个布尔值，指示管理（目录）数据库是否可访问。
storage_reachable (可选)	body	布尔值	一个布尔值，指示消息（池）数据库是否可访问。
operation_status (可选)	body	dict	一个字典，将包含许多不同操作/操作的状态。例如，post_messages、delete_messages、delete queue 等。每个状态都是一个字典，包含三个项目：`seconds`、`ref` 和 `succeeded`。秒数表示操作所花费的时间，succeeded 将指示操作是否成功。如果 succeeded 为 False，则 ref 包含信息，否则为 null。

响应示例¶

{
    "catalog_reachable": true,
    "redis": {
        "storage_reachable": true,
        "operation_status": {
            "post_messages": {
                "seconds": 0.027673959732055664,
                "ref": null,
                "succeeded": true
            },
            "delete_messages": {
                "seconds": 0.0028481483459472656,
                "ref": null,
                "succeeded": true
            },
            "delete_queue": {
                "seconds": 0.017709016799926758,
                "ref": null,
                "succeeded": true
            },
            "bulk_delete_messages": {
                "seconds": 0.03959178924560547,
                "ref": null,
                "succeeded": true
            },
            "create_queue": {
                "seconds": 0.021075963973999023,
                "ref": null,
                "succeeded": true
            },
            "list_messages": {
                "seconds": 0.00003504753112792969,
                "ref": null,
                "succeeded": true
            },
            "delete_claim": {
                "seconds": 0.0006170272827148438,
                "ref": null,
                "succeeded": true
            },
            "claim_messages": {
                "seconds": 0.008388042449951172,
                "ref": null,
                "succeeded": true
            }
        }
    }
}

池 (pools)¶

如果启用了池化，则队列服务使用多个队列数据库以实现水平扩展。可以随时添加池（队列数据库），而无需停止服务。每个池都有一个权重，在创建时分配，但以后可以更改。池化是通过队列完成的，这表示特定队列的所有消息都可以在同一个池（队列数据库）中找到。

GET

/v2/pools

列出池

列出池。

此操作列出项目的池。池按名称按字母顺序排序。

响应代码¶

成功¶

代码	原因
`200 - 正常`	请求成功。

错误¶

代码	原因
`404 - Not Found`	找不到请求的资源。
`401 - 未授权`	用户必须在发出请求之前进行身份验证。

查询参数¶

名称	入参	类型	描述
limit (可选)	查询	整数	请求项目页面大小。返回最多限制值数量的项目。使用 `limit` 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 `marker` 参数值。
marker (可选)	查询	字符串	最后一个已查看项目的 ID。使用 `limit` 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 `marker` 参数值。
详细 (可选)	查询	布尔值	‘detailed’ 指定在查询队列、flavor 和池时是否显示详细信息。

响应参数¶

名称	入参	类型	描述
pools (可选)	body	列表	池的列表。
links	body	数组	与池相关的链接。这是一个字典列表，每个字典都包含 `href` 和 `rel` 键。

响应示例¶

注意：建议从 Queens 开始使用 flavor 代替 group。

{
  "pools": [
    {
      "href": "/v2/pools/test_pool1",
      "group": "",
      "flavor": "poolflavor",
      "name": "test_pool1",
      "weight": 60,
      "uri": "mongodb://192.168.1.10:27017"
    },
    {
      "href": "/v2/pools/test_pool2",
      "group": "",
      "flavor": "poolflavor",
      "name": "test_pool2",
      "weight": 40,
      "uri": "mongodb://192.168.1.20:27017"
    }
  ],
  "links": [
    {
      "href": "/v2/pools?marker=test_pool2",
      "rel": "next"
    }
  ]
}

响应示例¶

注意：在 Rocky 版本中删除 group 并使用 flavor 代替池

{
  "pools": [
    {
      "href": "/v2/pools/test_pool1",
      "group": "poolgroup",
      "flavor": "",
      "name": "test_pool1",
      "weight": 60,
      "uri": "mongodb://192.168.1.10:27017"
    },
    {
      "href": "/v2/pools/test_pool2",
      "group": "poolgroup",
      "flavor": "",
      "name": "test_pool2",
      "weight": 40,
      "uri": "mongodb://192.168.1.20:27017"
    }
  ],
  "links": [
    {
      "href": "/v2/pools?marker=test_pool2",
      "rel": "next"
    }
  ]
}

PUT

/v2/pools/{pool_name}

创建池

创建池。

此操作创建新的池。

pool_name 是您为池指定的名称。名称的长度不得超过 64 个字节，并且仅限于 US-ASCII 字母、数字、下划线和连字符。

响应代码¶

成功¶

代码	原因
`201 - 已创建`	请求已完成，并创建了新资源。

错误¶

代码	原因
`400 - 请求错误`	请求中的某些内容无效。
`401 - 未授权`	用户必须在发出请求之前进行身份验证。
`409 - Conflict`	此资源有一个正在进行的操作，与此请求冲突。

请求参数¶

名称	入参	类型	描述
pool_name	路径	字符串	池的名称。
weight	body	整数	`weight` 属性指定下一个队列分配选择此池的可能性。该值必须是大于 -1 的整数。
uri	body	字符串	`uri` 属性指定与尝试连接到该池的存储客户端（例如 pymongo）兼容的连接字符串。
group (可选)	body	字符串	`group` 属性指定赋予多个池的标签，以便让用户记住属于该组的所有池的目的/功能。注意：在 Rocky 版本中删除 group 并使用 flavor 代替池。
flavor (可选)	body	字符串	`flavor` 属性指定赋予多个池的标签，以便让用户记住属于该 flavor 的所有池的目的/功能。注意：建议从 queen 开始使用 flavor 代替 group。
options (可选)	body	dict	`options` 属性提供存储驱动程序实现使用的存储特定选项。该值必须是字典，并且有效的键值来自给定的存储后端的注册选项。

请求示例¶

注意：建议从 Queens 开始使用 flavor 代替 group。

{
    "weight": 100,
    "uri": "mongodb://127.0.0.1:27017",
    "options":{
        "max_retry_sleep": 1
    },
    "flavor": "poolflavor"
}

请求示例¶

注意：在 Rocky 版本中删除 group 并使用 flavor 代替池

{
    "weight": 100,
    "uri": "mongodb://127.0.0.1:27017",
    "options":{
        "max_retry_sleep": 1
    },
    "group": "poolgroup"
}

此操作不返回响应体。

PATCH

/v2/pools/{pool_name}

更新池

更新池。

响应代码¶

成功¶

代码	原因
`200 - 正常`	请求成功。

错误¶

代码	原因
`400 - 请求错误`	请求中的某些内容无效。
`401 - 未授权`	用户必须在发出请求之前进行身份验证。
`404 - Not Found`	找不到请求的资源。
`503 - 服务不可用`	服务现在无法处理请求。

请求参数¶

名称	入参	类型	描述
pool_name	路径	字符串	池的名称。
weight	body	整数	`weight` 属性指定下一个队列分配选择此池的可能性。该值必须是大于 -1 的整数。
uri	body	字符串	`uri` 属性指定与尝试连接到该池的存储客户端（例如 pymongo）兼容的连接字符串。
group (可选)	body	字符串	`group` 属性指定赋予多个池的标签，以便让用户记住属于该组的所有池的目的/功能。注意：在 Rocky 版本中删除 group 并使用 flavor 代替池。
flavor (可选)	body	字符串	`flavor` 属性指定赋予多个池的标签，以便让用户记住属于该 flavor 的所有池的目的/功能。注意：建议从 queen 开始使用 flavor 代替 group。
options (可选)	body	dict	`options` 属性提供存储驱动程序实现使用的存储特定选项。该值必须是字典，并且有效的键值来自给定的存储后端的注册选项。

请求示例¶

注意：建议从 Queens 开始使用 flavor 代替 group。

{
    "weight": 60,
    "uri": "mongodb://127.0.0.1:27017",
    "options":{
        "max_retry_sleep": 1
    },
    "flavor": "newpoolflavor"
}

响应示例¶

注意：建议从 Queens 开始使用 flavor 代替 group。

{
  "href": "/v2/pools/test_pool",
  "group": "",
  "flavor": "newpoolflavor",
  "name": "test_pool",
  "weight": 60,
  "uri": "mongodb://127.0.0.1:27017"
}

请求示例¶

注意：在 Rocky 版本中删除 group 并使用 flavor 代替池

{
    "weight": 60,
    "uri": "mongodb://127.0.0.1:27017",
    "options":{
        "max_retry_sleep": 1
    },
    "group": "newpoolgroup"
}

响应示例¶

注意：在 Rocky 版本中删除 group 并使用 flavor 代替池

{
  "href": "/v2/pools/test_pool",
  "group": "newpoolgroup",
  "name": "test_pool",
  "weight": 60,
  "uri": "mongodb://127.0.0.1:27017"
}

GET

/v2/pools/{pool_name}

显示池详情

显示池的详细信息。

响应代码¶

成功¶

代码	原因
`200 - 正常`	请求成功。

错误¶

代码	原因
`400 - 请求错误`	请求中的某些内容无效。
`401 - 未授权`	用户必须在发出请求之前进行身份验证。
`503 - 服务不可用`	服务现在无法处理请求。

请求参数¶

名称	入参	类型	描述
pool_name	路径	字符串	池的名称。

响应参数¶

名称	入参	类型	描述
name (可选)	body	字符串	池的名称。
weight	body	整数	`weight` 属性指定下一个队列分配选择此池的可能性。该值必须是大于 -1 的整数。
uri	body	字符串	`uri` 属性指定与尝试连接到该池的存储客户端（例如 pymongo）兼容的连接字符串。
group (可选)	body	字符串	`group` 属性指定赋予多个池的标签，以便让用户记住属于该组的所有池的目的/功能。注意：在 Rocky 版本中删除 group 并使用 flavor 代替池。
flavor (可选)	body	字符串	`flavor` 属性指定赋予多个池的标签，以便让用户记住属于该 flavor 的所有池的目的/功能。注意：建议从 queen 开始使用 flavor 代替 group。
href (可选)	body	字符串	池的 URL。

响应示例¶

注意：建议从 Queens 开始使用 flavor 代替 group。

{
  "href": "/v2/pools/test_pool",
  "group": "",
  "flavor": "testpoolflavor",
  "name": "test_pool",
  "weight": 100,
  "uri": "mongodb://127.0.0.1:27017"
}

响应示例¶

注意：在 Rocky 版本中删除 group 并使用 flavor 代替池

{
  "href": "/v2/pools/test_pool",
  "group": "testpoolgroup",
  "flavor": "",
  "name": "test_pool",
  "weight": 100,
  "uri": "mongodb://127.0.0.1:27017"
}

DELETE

/v2/pools/{pool_name}

删除池

删除指定的池。

此操作会立即删除池。

pool_name 是您为池指定的名称。名称的长度不得超过 64 个字节，并且仅限于 US-ASCII 字母、数字、下划线和连字符。

响应代码¶

成功¶

代码	原因
`204 - No Content`	请求已满足，但服务未返回任何内容。

错误¶

代码	原因
`401 - 未授权`	用户必须在发出请求之前进行身份验证。
`403 - 禁止`	策略不允许当前用户执行此操作。
`503 - 服务不可用`	服务现在无法处理请求。

请求参数¶

名称	入参	类型	描述
pool_name	路径	字符串	池的名称。

此操作不接受请求主体，也不返回响应主体。

风味 (flavors)¶

队列风味允许用户根据存储功能拥有不同类型的队列。通过使用风味，可以允许服务的消费者在持久存储、快速存储等之间进行选择。风味必须由服务管理员创建，并且依赖于池的存在。

GET

/v2/flavors

列出 flavors

列出风味。

此操作列出项目的风味。风味按名称按字母顺序排序。

响应代码¶

成功¶

代码	原因
`200 - 正常`	请求成功。

错误¶

代码	原因
`401 - 未授权`	用户必须在发出请求之前进行身份验证。
`403 - 禁止`	策略不允许当前用户执行此操作。

查询参数¶

名称	入参	类型	描述
limit (可选)	查询	整数	请求项目页面大小。返回最多限制值数量的项目。使用 `limit` 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 `marker` 参数值。
marker (可选)	查询	字符串	最后一个已查看项目的 ID。使用 `limit` 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 `marker` 参数值。
详细 (可选)	查询	布尔值	‘detailed’ 指定在查询队列、flavor 和池时是否显示详细信息。

响应参数¶

名称	入参	类型	描述
flavors (可选)	body	列表	风味列表。
links	body	数组	与风味相关的链接。这是一个字典列表，每个字典都包含 `href` 和 `rel` 键。

响应示例¶

注意：建议从 Queens 开始使用 pool_list 代替 pool_group。

{
  "flavors": [
    {
      "href": "/v2/flavors/test_flavor1",
      "pool_group": "",
      "pool_list": "[testpool1, testpool2]",
      "name": "test_flavor1",
      "pool": "testgroup"
    },
    {
      "href": "/v2/flavors/test_flavor2",
      "pool_group": "",
      "pool_list": "[testpool3, testpool4]",
      "name": "test_flavor2",
      "pool": "testgroup"
    }
  ],
  "links": [
    {
      "href": "/v2/flavors?marker=test_flavor2",
      "rel": "next"
    }
  ]
}

响应示例¶

注意：在Rocky版本中移除pool_group，并使用pool_list代替用于flavor

{
  "flavors": [
    {
      "href": "/v2/flavors/test_flavor1",
      "pool_group": "testgroup",
      "pool_list": "",
      "name": "test_flavor1",
      "pool": "testgroup"
    },
    {
      "href": "/v2/flavors/test_flavor2",
      "pool_group": "testgroup",
      "pool_list": "",
      "name": "test_flavor2",
      "pool": "testgroup"
    }
  ],
  "links": [
    {
      "href": "/v2/flavors?marker=test_flavor2",
      "rel": "next"
    }
  ]
}

PUT

/v2/flavors/{flavor_name}

创建flavor

创建flavor。

此操作创建新的flavor。

flavor_name 是您为flavor指定的名称。名称长度不得超过64字节，并且仅限于US-ASCII字母、数字、下划线和连字符。

响应代码¶

成功¶

代码	原因
`201 - 已创建`	请求已完成，并创建了新资源。

错误¶

代码	原因
`400 - 请求错误`	请求中的某些内容无效。
`401 - 未授权`	用户必须在发出请求之前进行身份验证。
`403 - 禁止`	策略不允许当前用户执行此操作。

请求参数¶

名称	入参	类型	描述
flavor_name	路径	字符串	flavor的名称。
pool_group	body	字符串	`pool_group` 属性指定flavor位于其上方的pool组的名称。注意：在Rocky版本中移除pool_group，并使用pool_list代替flavor。
pool_list (可选)	body	列表	flavor中的pool列表。注意：从Queens版本开始，建议配置pool_list代替pool_group。

请求示例¶

注意：建议从 Queens 开始使用 pool_list 代替 pool_group。

{
    "pool_list": "[testpool1, testpool2]"
}

请求示例¶

注意：在Rocky版本中移除pool_group，并使用pool_list代替用于flavor

{
    "pool_group": "testgroup"
}

此操作不返回响应体。

PATCH

/v2/flavors/{flavor_name}

更新flavor

更新flavor。

响应代码¶

成功¶

代码	原因
`200 - 正常`	请求成功。

请求参数¶

名称	入参	类型	描述
flavor_name	路径	字符串	flavor的名称。
pool_group	body	字符串	`pool_group` 属性指定flavor位于其上方的pool组的名称。注意：在Rocky版本中移除pool_group，并使用pool_list代替flavor。
pool_list (可选)	body	列表	flavor中的pool列表。注意：从Queens版本开始，建议配置pool_list代替pool_group。

请求示例¶

注意：建议从 Queens 开始使用 pool_list 代替 pool_group。

{
    "pool_list": "[testpool1, testpool3]"
}

响应示例¶

注意：建议从 Queens 开始使用 pool_list 代替 pool_group。

{
  "href": "/v2/flavors/testflavor",
  "pool_list": "[testpool1, testpool3]",
  "name": "testflavor",
  "capabilities": [
    "FIFO",
    "CLAIMS",
    "DURABILITY",
    "AOD",
    "HIGH_THROUGHPUT"
  ]
}

请求示例¶

注意：在Rocky版本中移除pool_group，并使用pool_list代替用于flavor

{
    "pool_group": "testgroup"
}

响应示例¶

注意：在Rocky版本中移除pool_group，并使用pool_list代替用于flavor

{
  "href": "/v2/flavors/testflavor",
  "pool_group": "testgroup",
  "name": "testflavor",
  "capabilities": [
    "FIFO",
    "CLAIMS",
    "DURABILITY",
    "AOD",
    "HIGH_THROUGHPUT"
  ]
}

GET

/v2/flavors/{flavor_name}

显示flavor详情

显示flavor的详情。

响应代码¶

成功¶

代码	原因
`200 - 正常`	请求成功。

错误¶

代码	原因
`400 - 请求错误`	请求中的某些内容无效。
`401 - 未授权`	用户必须在发出请求之前进行身份验证。
`403 - 禁止`	策略不允许当前用户执行此操作。
`404 - Not Found`	找不到请求的资源。
`503 - 服务不可用`	服务现在无法处理请求。

请求参数¶

名称	入参	类型	描述
flavor_name	路径	字符串	flavor的名称。

响应参数¶

名称	入参	类型	描述
name	body	字符串	flavor的名称。
capabilities (可选)	body	列表	Capabilities描述了基于存储capabilities，此flavor的功能。它们用于告知最终用户这些功能。
pool_group	body	字符串	`pool_group` 属性指定flavor位于其上方的pool组的名称。注意：在Rocky版本中移除pool_group，并使用pool_list代替flavor。
pool_list (可选)	body	列表	flavor中的pool列表。注意：从Queens版本开始，建议配置pool_list代替pool_group。
href (可选)	body	字符串	flavor的url。

响应示例¶

注意：建议从 Queens 开始使用 pool_list 代替 pool_group。

{
  "href": "/v2/flavors/testflavor",
  "capabilities": [
    "FIFO",
    "CLAIMS",
    "DURABILITY",
    "AOD",
    "HIGH_THROUGHPUT"
  ],
  "pool_group": "",
  "pool_list": "[testpool1, testpool2]"
  "name": "testflavor"
}

响应示例¶

注意：在Rocky版本中移除pool_group，并使用pool_list代替用于flavor

{
  "href": "/v2/flavors/testflavor",
  "capabilities": [
    "FIFO",
    "CLAIMS",
    "DURABILITY",
    "AOD",
    "HIGH_THROUGHPUT"
  ],
  "pool_group": "testgroup",
  "pool_list": ""
  "name": "testflavor"
}

DELETE

/v2/flavors/{flavor_name}

删除flavor

删除指定的flavor。

此操作立即删除flavor。

flavor_name 是您为flavor指定的名称。名称长度不得超过64字节，并且仅限于US-ASCII字母、数字、下划线和连字符。

响应代码¶

成功¶

代码	原因
`204 - No Content`	请求已满足，但服务未返回任何内容。

错误¶

代码	原因
`401 - 未授权`	用户必须在发出请求之前进行身份验证。
`403 - 禁止`	策略不允许当前用户执行此操作。
`503 - 服务不可用`	服务现在无法处理请求。

请求参数¶

名称	入参	类型	描述
flavor_name	路径	字符串	flavor的名称。

此操作不接受请求主体，也不返回响应主体。