52 lines
1.9 KiB
Markdown
52 lines
1.9 KiB
Markdown
# 队列接口 v1
|
||
|
||
状态：P1 已实现创建与查询。更新、暂停、实际派发并发与速率控制随 P2–P3 实现；当前参数是后续执行所需的持久化配置。
|
||
|
||
## POST /v1/queues
|
||
|
||
需要 queues:manage 和当前命名空间内全部队列范围。鉴权、请求体、幂等键及错误信封与 [任务接口](tasks.md) 一致。
|
||
|
||
| 字段 | 类型 | 要求 |
|
||
| --- | --- | --- |
|
||
| name | string | 1–128 字符，以 ASCII 字母/数字开头，其后允许字母、数字、`_ . : -`；命名空间内唯一 |
|
||
| max_concurrency | uint32 | 必填，1–100000 |
|
||
| rate_per_second | uint32 | 必填，1–1000000 |
|
||
|
||
```sh
|
||
curl "$ORBIT_URL/v1/queues" \
|
||
-H "Authorization: Bearer $ORBIT_TOKEN" \
|
||
-H 'Content-Type: application/json' \
|
||
-H 'Idempotency-Key: queue-images-v1' \
|
||
--data '{"name":"images","max_concurrency":8,"rate_per_second":100}'
|
||
```
|
||
|
||
首次 201：
|
||
|
||
```json
|
||
{
|
||
"request_id":"44444444444444444444444444444444",
|
||
"data":{
|
||
"deduplicated":false,
|
||
"queue":{
|
||
"id":"11111111111111111111111111111111",
|
||
"namespace_id":"33333333333333333333333333333333",
|
||
"name":"images","paused":false,"max_concurrency":8,"rate_per_second":100,"revision":"1"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
同键同内容返回 200、deduplicated=true。同键不同内容返回 409 IDEMPOTENCY_CONFLICT；换键创建同名队列返回 409 STATE_CONFLICT。创建、幂等记录和管理审计同事务提交。
|
||
|
||
SDK：`Client.CreateQueue(ctx, key, orbit.CreateQueueRequest{...})`。
|
||
|
||
## GET /v1/queues/{queue_id}
|
||
|
||
权限：queues:read 和对应队列范围。200 的 data 直接为上方 queue 对象；资源不存在或单资源范围不匹配返回 404。
|
||
|
||
```sh
|
||
curl "$ORBIT_URL/v1/queues/$ORBIT_QUEUE_ID" -H "Authorization: Bearer $ORBIT_TOKEN"
|
||
```
|
||
|
||
SDK：`Client.GetQueue(ctx, queueID)`。范围限制、重复创建和同名冲突已纳入 [P1 回归](../reports/phase-1.md)。这些配置上限不是生产容量承诺。
|