Message Queue

Managed message queue: publish and consume messages, batch, dead-letter queues (DLQ), redrive and push subscriptions.

Overview

Base path: https://api.infrai.cc/v1/queue

Auth header: Authorization: Bearer $INFRAI_API_KEY

bash

# Call any /v1/queue capability over raw HTTP — no SDK to install.
# curl:
curl https://api.infrai.cc/v1/queue/... \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json"

Methods

queue.publish

POST /v1/queue/publish

Publish a message to a queue, optionally delayed.

Parameters

Name	Type	Required	Description
`queue`	`string`	Required	The queue name.
`payload`	`object`	Required	Message payload.
`delay_seconds`	`number`	Optional	Delay before delivery in seconds.
`idempotency_key`	`string`	Optional	Optional dedup key; identical retries return the same result.

Returns

{ message_id }

Example

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."

bash

curl -X POST https://api.infrai.cc/v1/queue/publish \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"queue": "orders", "payload": {"order_id": "o_123"}, "priority": 5}'

python

import os, requests

resp = requests.post(
    "https://api.infrai.cc/v1/queue/publish",
    headers={"Authorization": f"Bearer {os.environ['INFRAI_API_KEY']}"},
    json={'queue': 'orders', 'payload': {'order_id': 'o_123'}, 'priority': 5},
)
resp.raise_for_status()
print(resp.json())

javascript

const resp = await fetch(
  "https://api.infrai.cc/v1/queue/publish",
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.INFRAI_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({"queue": "orders", "payload": {"order_id": "o_123"}, "priority": 5}),
  },
);
console.log(await resp.json());

typescript

const resp = await fetch(
  "https://api.infrai.cc/v1/queue/publish",
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.INFRAI_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({"queue": "orders", "payload": {"order_id": "o_123"}, "priority": 5}),
  },
);
if (!resp.ok) throw new Error(`infrai ${resp.status}`);
const data: unknown = await resp.json();
console.log(data);

queue.create

POST /v1/queue/create

创建一个消息队列

Parameters

Name	Type	Required	Description
`name`	`string`	Required	队列名称
`type`	`"standard" \| "fifo"`	Optional	队列类型：standard 标准 / fifo 先进先出
`dead_letter_queue`	`string`	Optional	接收失败消息的死信队列名（须已存在）
`max_retries`	`number`	Optional	转入 DLQ 前允许的 nack 次数
`message_retention_days`	`number`	Optional	消息保留天数
`visibility_timeout_default`	`number`	Optional	默认可见性超时（租约）秒数
`enable_priority`	`boolean`	Optional	是否启用优先级
`idempotency_key`	`string`	Optional	幂等键，避免重复创建

Returns

QueueRecord { queue, type, dead_letter_queue?, max_retries, visibility_timeout_default }

Example

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."

bash

curl -X POST https://api.infrai.cc/v1/queue/create \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "..."}'

python

import os, requests

resp = requests.post(
    "https://api.infrai.cc/v1/queue/create",
    headers={"Authorization": f"Bearer {os.environ['INFRAI_API_KEY']}"},
    json={'name': '...'},
)
resp.raise_for_status()
print(resp.json())

javascript

const resp = await fetch(
  "https://api.infrai.cc/v1/queue/create",
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.INFRAI_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({"name": "..."}),
  },
);
console.log(await resp.json());

typescript

const resp = await fetch(
  "https://api.infrai.cc/v1/queue/create",
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.INFRAI_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({"name": "..."}),
  },
);
if (!resp.ok) throw new Error(`infrai ${resp.status}`);
const data: unknown = await resp.json();
console.log(data);

queue.get

GET /v1/queue/get/{queue}

获取队列配置详情

Parameters

Name	Type	Required	Description
`queue`	`string`	Required	队列名称

Returns

QueueRecord { queue, type, dead_letter_queue?, max_retries, visibility_timeout_default }

Example

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."

bash

curl -X GET https://api.infrai.cc/v1/queue/get/QUEUE \
  -H "Authorization: Bearer $INFRAI_API_KEY"

python

import os, requests

resp = requests.get(
    "https://api.infrai.cc/v1/queue/get/QUEUE",
    headers={"Authorization": f"Bearer {os.environ['INFRAI_API_KEY']}"},
)
resp.raise_for_status()
print(resp.json())

javascript

const resp = await fetch(
  "https://api.infrai.cc/v1/queue/get/QUEUE",
  {
    method: "GET",
    headers: {
      "Authorization": `Bearer ${process.env.INFRAI_API_KEY}`,
    },
  },
);
console.log(await resp.json());

typescript

const resp = await fetch(
  "https://api.infrai.cc/v1/queue/get/QUEUE",
  {
    method: "GET",
    headers: {
      "Authorization": `Bearer ${process.env.INFRAI_API_KEY}`,
    },
  },
);
if (!resp.ok) throw new Error(`infrai ${resp.status}`);
const data: unknown = await resp.json();
console.log(data);

queue.list

GET /v1/queue/list

分页列出所有队列

Parameters

Name	Type	Required	Description
`cursor`	`string`	Optional	分页游标，来自上一页 next_cursor
`limit`	`number`	Optional	每页返回数量

Returns

{ items: QueueRecord[], next_cursor? }

Example

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."

bash

curl -X GET https://api.infrai.cc/v1/queue/list \
  -H "Authorization: Bearer $INFRAI_API_KEY"

python

import os, requests

resp = requests.get(
    "https://api.infrai.cc/v1/queue/list",
    headers={"Authorization": f"Bearer {os.environ['INFRAI_API_KEY']}"},
)
resp.raise_for_status()
print(resp.json())

javascript

const resp = await fetch(
  "https://api.infrai.cc/v1/queue/list",
  {
    method: "GET",
    headers: {
      "Authorization": `Bearer ${process.env.INFRAI_API_KEY}`,
    },
  },
);
console.log(await resp.json());

typescript

const resp = await fetch(
  "https://api.infrai.cc/v1/queue/list",
  {
    method: "GET",
    headers: {
      "Authorization": `Bearer ${process.env.INFRAI_API_KEY}`,
    },
  },
);
if (!resp.ok) throw new Error(`infrai ${resp.status}`);
const data: unknown = await resp.json();
console.log(data);

queue.update

PATCH /v1/queue/update/{queue}

更新队列配置

Parameters

Name	Type	Required	Description
`queue`	`string`	Required	队列名称
`dead_letter_queue`	`string`	Optional	死信队列名
`max_retries`	`number`	Optional	转入 DLQ 前允许的 nack 次数
`message_retention_days`	`number`	Optional	消息保留天数
`visibility_timeout_default`	`number`	Optional	默认可见性超时秒数
`enable_priority`	`boolean`	Optional	是否启用优先级
`idempotency_key`	`string`	Optional	幂等键，避免重复执行

Returns

QueueRecord { queue, max_retries, visibility_timeout_default }

Example

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."

bash

curl -X PATCH https://api.infrai.cc/v1/queue/update/QUEUE \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

python

import os, requests

resp = requests.patch(
    "https://api.infrai.cc/v1/queue/update/QUEUE",
    headers={"Authorization": f"Bearer {os.environ['INFRAI_API_KEY']}"},
    json={},
)
resp.raise_for_status()
print(resp.json())

javascript

const resp = await fetch(
  "https://api.infrai.cc/v1/queue/update/QUEUE",
  {
    method: "PATCH",
    headers: {
      "Authorization": `Bearer ${process.env.INFRAI_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({}),
  },
);
console.log(await resp.json());

typescript

const resp = await fetch(
  "https://api.infrai.cc/v1/queue/update/QUEUE",
  {
    method: "PATCH",
    headers: {
      "Authorization": `Bearer ${process.env.INFRAI_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({}),
  },
);
if (!resp.ok) throw new Error(`infrai ${resp.status}`);
const data: unknown = await resp.json();
console.log(data);

queue.delete

DELETE /v1/queue/delete/{queue}

删除一个队列

Parameters

Name	Type	Required	Description
`queue`	`string`	Required	队列名称
`idempotency_key`	`string`	Optional	幂等键，避免重复执行

Returns

{ queue, deleted }

Example

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."

bash

curl -X DELETE https://api.infrai.cc/v1/queue/delete/QUEUE \
  -H "Authorization: Bearer $INFRAI_API_KEY"

python

import os, requests

resp = requests.delete(
    "https://api.infrai.cc/v1/queue/delete/QUEUE",
    headers={"Authorization": f"Bearer {os.environ['INFRAI_API_KEY']}"},
)
resp.raise_for_status()
print(resp.json())

javascript

const resp = await fetch(
  "https://api.infrai.cc/v1/queue/delete/QUEUE",
  {
    method: "DELETE",
    headers: {
      "Authorization": `Bearer ${process.env.INFRAI_API_KEY}`,
    },
  },
);
console.log(await resp.json());

typescript

const resp = await fetch(
  "https://api.infrai.cc/v1/queue/delete/QUEUE",
  {
    method: "DELETE",
    headers: {
      "Authorization": `Bearer ${process.env.INFRAI_API_KEY}`,
    },
  },
);
if (!resp.ok) throw new Error(`infrai ${resp.status}`);
const data: unknown = await resp.json();
console.log(data);

queue.purge

POST /v1/queue/purge/{queue}

清空队列中所有消息

Parameters

Name	Type	Required	Description
`queue`	`string`	Required	队列名称
`idempotency_key`	`string`	Optional	幂等键，避免重复执行

Returns

{ queue, purged }

Example

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."

bash

curl -X POST https://api.infrai.cc/v1/queue/purge/QUEUE \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"queue": "..."}'

python

import os, requests

resp = requests.post(
    "https://api.infrai.cc/v1/queue/purge/QUEUE",
    headers={"Authorization": f"Bearer {os.environ['INFRAI_API_KEY']}"},
    json={'queue': '...'},
)
resp.raise_for_status()
print(resp.json())

javascript

const resp = await fetch(
  "https://api.infrai.cc/v1/queue/purge/QUEUE",
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.INFRAI_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({"queue": "..."}),
  },
);
console.log(await resp.json());

typescript

const resp = await fetch(
  "https://api.infrai.cc/v1/queue/purge/QUEUE",
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.INFRAI_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({"queue": "..."}),
  },
);
if (!resp.ok) throw new Error(`infrai ${resp.status}`);
const data: unknown = await resp.json();
console.log(data);

queue.stats

GET /v1/queue/stats/{queue}

获取队列统计指标

Parameters

Name	Type	Required	Description
`queue`	`string`	Required	队列名称

Returns

QueueStats { queue, available, in_flight, dlq, oldest_age_seconds? }

Example

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."

bash

curl -X GET https://api.infrai.cc/v1/queue/stats/QUEUE \
  -H "Authorization: Bearer $INFRAI_API_KEY"

python

import os, requests

resp = requests.get(
    "https://api.infrai.cc/v1/queue/stats/QUEUE",
    headers={"Authorization": f"Bearer {os.environ['INFRAI_API_KEY']}"},
)
resp.raise_for_status()
print(resp.json())

javascript

const resp = await fetch(
  "https://api.infrai.cc/v1/queue/stats/QUEUE",
  {
    method: "GET",
    headers: {
      "Authorization": `Bearer ${process.env.INFRAI_API_KEY}`,
    },
  },
);
console.log(await resp.json());

typescript

const resp = await fetch(
  "https://api.infrai.cc/v1/queue/stats/QUEUE",
  {
    method: "GET",
    headers: {
      "Authorization": `Bearer ${process.env.INFRAI_API_KEY}`,
    },
  },
);
if (!resp.ok) throw new Error(`infrai ${resp.status}`);
const data: unknown = await resp.json();
console.log(data);

queue.publish_batch

POST /v1/queue/publish_batch

批量发布多条消息到队列

Parameters

Name	Type	Required	Description
`queue`	`string`	Required	队列名称
`messages`	`QueueMessage[]`	Required	待发布的消息数组
`idempotency_key`	`string`	Optional	幂等键，避免重复发布

Returns

{ message_ids }

Example

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."

bash

curl -X POST https://api.infrai.cc/v1/queue/publish_batch \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"queue": "...", "messages": []}'

python

import os, requests

resp = requests.post(
    "https://api.infrai.cc/v1/queue/publish_batch",
    headers={"Authorization": f"Bearer {os.environ['INFRAI_API_KEY']}"},
    json={'queue': '...', 'messages': []},
)
resp.raise_for_status()
print(resp.json())

javascript

const resp = await fetch(
  "https://api.infrai.cc/v1/queue/publish_batch",
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.INFRAI_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({"queue": "...", "messages": []}),
  },
);
console.log(await resp.json());

typescript

const resp = await fetch(
  "https://api.infrai.cc/v1/queue/publish_batch",
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.INFRAI_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({"queue": "...", "messages": []}),
  },
);
if (!resp.ok) throw new Error(`infrai ${resp.status}`);
const data: unknown = await resp.json();
console.log(data);

queue.consume

POST /v1/queue/consume

从队列拉取一批消息消费

Parameters

Name	Type	Required	Description
`queue`	`string`	Required	队列名称
`max_messages`	`number`	Optional	单次最多拉取的消息数
`visibility_timeout`	`number`	Optional	本批消息的租约秒数；默认取队列配置

Returns

{ messages: QueueMessage[] }

Example

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."

bash

curl -X POST https://api.infrai.cc/v1/queue/consume \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"queue": "..."}'

python

import os, requests

resp = requests.post(
    "https://api.infrai.cc/v1/queue/consume",
    headers={"Authorization": f"Bearer {os.environ['INFRAI_API_KEY']}"},
    json={'queue': '...'},
)
resp.raise_for_status()
print(resp.json())

javascript

const resp = await fetch(
  "https://api.infrai.cc/v1/queue/consume",
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.INFRAI_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({"queue": "..."}),
  },
);
console.log(await resp.json());

typescript

const resp = await fetch(
  "https://api.infrai.cc/v1/queue/consume",
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.INFRAI_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({"queue": "..."}),
  },
);
if (!resp.ok) throw new Error(`infrai ${resp.status}`);
const data: unknown = await resp.json();
console.log(data);

queue.ack

POST /v1/queue/ack

确认一条已消费的消息

Parameters

Name	Type	Required	Description
`queue`	`string`	Required	队列名称
`message_id`	`string`	Required	消息 ID
`idempotency_key`	`string`	Optional	幂等键，避免重复执行

Returns

{ message_id, acked }

Example

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."

bash

curl -X POST https://api.infrai.cc/v1/queue/ack \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"queue": "...", "message_id": "..."}'

python

import os, requests

resp = requests.post(
    "https://api.infrai.cc/v1/queue/ack",
    headers={"Authorization": f"Bearer {os.environ['INFRAI_API_KEY']}"},
    json={'queue': '...', 'message_id': '...'},
)
resp.raise_for_status()
print(resp.json())

javascript

const resp = await fetch(
  "https://api.infrai.cc/v1/queue/ack",
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.INFRAI_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({"queue": "...", "message_id": "..."}),
  },
);
console.log(await resp.json());

typescript

const resp = await fetch(
  "https://api.infrai.cc/v1/queue/ack",
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.INFRAI_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({"queue": "...", "message_id": "..."}),
  },
);
if (!resp.ok) throw new Error(`infrai ${resp.status}`);
const data: unknown = await resp.json();
console.log(data);

queue.nack

POST /v1/queue/nack

否认一条消息，可重新入队或转入死信

Parameters

Name	Type	Required	Description
`queue`	`string`	Required	队列名称
`message_id`	`string`	Required	消息 ID
`requeue`	`boolean`	Optional	true 重新入队；false 直接转入死信
`idempotency_key`	`string`	Optional	幂等键，避免重复执行

Returns

{ message_id, nacked, requeued }

Example

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."

bash

curl -X POST https://api.infrai.cc/v1/queue/nack \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"queue": "...", "message_id": "..."}'

python

import os, requests

resp = requests.post(
    "https://api.infrai.cc/v1/queue/nack",
    headers={"Authorization": f"Bearer {os.environ['INFRAI_API_KEY']}"},
    json={'queue': '...', 'message_id': '...'},
)
resp.raise_for_status()
print(resp.json())

javascript

const resp = await fetch(
  "https://api.infrai.cc/v1/queue/nack",
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.INFRAI_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({"queue": "...", "message_id": "..."}),
  },
);
console.log(await resp.json());

typescript

const resp = await fetch(
  "https://api.infrai.cc/v1/queue/nack",
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.INFRAI_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({"queue": "...", "message_id": "..."}),
  },
);
if (!resp.ok) throw new Error(`infrai ${resp.status}`);
const data: unknown = await resp.json();
console.log(data);

queue.dlq.list

GET /v1/queue/dlq/list/{queue}

分页列出死信队列中的消息

Parameters

Name	Type	Required	Description
`queue`	`string`	Required	队列名称
`cursor`	`string`	Optional	分页游标，来自上一页 next_cursor
`limit`	`number`	Optional	每页返回数量

Returns

{ items: QueueMessage[], next_cursor? }

Example

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."

bash

curl -X GET https://api.infrai.cc/v1/queue/dlq/list/QUEUE \
  -H "Authorization: Bearer $INFRAI_API_KEY"

python

import os, requests

resp = requests.get(
    "https://api.infrai.cc/v1/queue/dlq/list/QUEUE",
    headers={"Authorization": f"Bearer {os.environ['INFRAI_API_KEY']}"},
)
resp.raise_for_status()
print(resp.json())

javascript

const resp = await fetch(
  "https://api.infrai.cc/v1/queue/dlq/list/QUEUE",
  {
    method: "GET",
    headers: {
      "Authorization": `Bearer ${process.env.INFRAI_API_KEY}`,
    },
  },
);
console.log(await resp.json());

typescript

const resp = await fetch(
  "https://api.infrai.cc/v1/queue/dlq/list/QUEUE",
  {
    method: "GET",
    headers: {
      "Authorization": `Bearer ${process.env.INFRAI_API_KEY}`,
    },
  },
);
if (!resp.ok) throw new Error(`infrai ${resp.status}`);
const data: unknown = await resp.json();
console.log(data);

queue.dlq.redrive

POST /v1/queue/dlq/redrive/{queue}

将死信消息重投回原队列

Parameters

Name	Type	Required	Description
`queue`	`string`	Required	队列名称
`message_id`	`string`	Optional	重投单条消息的 ID；省略则批量重投
`since`	`string`	Optional	批量重投：该时刻及之后进入死信的全部消息
`idempotency_key`	`string`	Optional	幂等键，避免重复重投

Returns

{ queue, redriven }

Example

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."

bash

curl -X POST https://api.infrai.cc/v1/queue/dlq/redrive/QUEUE \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"queue": "orders", "max_messages": 100}'

python

import os, requests

resp = requests.post(
    "https://api.infrai.cc/v1/queue/dlq/redrive/QUEUE",
    headers={"Authorization": f"Bearer {os.environ['INFRAI_API_KEY']}"},
    json={'queue': 'orders', 'max_messages': 100},
)
resp.raise_for_status()
print(resp.json())

javascript

const resp = await fetch(
  "https://api.infrai.cc/v1/queue/dlq/redrive/QUEUE",
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.INFRAI_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({"queue": "orders", "max_messages": 100}),
  },
);
console.log(await resp.json());

typescript

const resp = await fetch(
  "https://api.infrai.cc/v1/queue/dlq/redrive/QUEUE",
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.INFRAI_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({"queue": "orders", "max_messages": 100}),
  },
);
if (!resp.ok) throw new Error(`infrai ${resp.status}`);
const data: unknown = await resp.json();
console.log(data);

queue.push_subscribe

POST /v1/queue/push_subscribe/{queue}

为队列配置推送订阅

Parameters

Name	Type	Required	Description
`queue`	`string`	Required	队列名称
`url`	`string`	Required	https 推送目标地址（经 SSRF 校验）
`secret`	`string`	Optional	对推送请求做 HMAC 签名的密钥
`max_retries`	`number`	Optional	推送失败重试次数
`visibility_timeout`	`number`	Optional	可见性超时秒数
`dead_letter_queue`	`string`	Optional	死信队列名
`idempotency_key`	`string`	Optional	幂等键，避免重复订阅

Returns

PushSubscription { subscription_id, queue, url }

Example

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."

bash

curl -X POST https://api.infrai.cc/v1/queue/push_subscribe/QUEUE \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"queue": "orders", "forward_to": "https://api.acme.com/order-handler"}'

python

import os, requests

resp = requests.post(
    "https://api.infrai.cc/v1/queue/push_subscribe/QUEUE",
    headers={"Authorization": f"Bearer {os.environ['INFRAI_API_KEY']}"},
    json={'queue': 'orders', 'forward_to': 'https://api.acme.com/order-handler'},
)
resp.raise_for_status()
print(resp.json())

javascript

const resp = await fetch(
  "https://api.infrai.cc/v1/queue/push_subscribe/QUEUE",
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.INFRAI_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({"queue": "orders", "forward_to": "https://api.acme.com/order-handler"}),
  },
);
console.log(await resp.json());

typescript

const resp = await fetch(
  "https://api.infrai.cc/v1/queue/push_subscribe/QUEUE",
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.INFRAI_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({"queue": "orders", "forward_to": "https://api.acme.com/order-handler"}),
  },
);
if (!resp.ok) throw new Error(`infrai ${resp.status}`);
const data: unknown = await resp.json();
console.log(data);

All capabilities

Every routed capability in this module — the complete public REST contract. The methods above are the guided walkthrough; this index is the full reference.

Capability	Endpoint	Description
`queue.ack`	`POST /v1/queue/ack`	Acknowledge (ack) a consumed message to remove it from the queue.
`queue.consume`	`POST /v1/queue/consume`	Pull a batch of messages from a queue for processing.
`queue.create`	`POST /v1/queue/create`	Create a message queue (standard or FIFO, with optional dead-letter queue).
`queue.delete`	`DELETE /v1/queue/delete/{queue}`	Delete a message queue and discard all of its pending messages (use queue.purge to keep the queue); idempotent.
`queue.dlq.list`	`GET /v1/queue/dlq/list/{queue}`	List messages in a queue's dead-letter queue (DLQ) with pagination.
`queue.dlq.redrive`	`POST /v1/queue/dlq/redrive/{queue}`	Redrive dead-letter messages back to the source queue, individually or in bulk.
`queue.get`	`GET /v1/queue/get/{queue}`	Retrieve a queue's configuration details.
`queue.list`	`GET /v1/queue/list`	List all message queues with pagination.
`queue.nack`	`POST /v1/queue/nack`	Negatively acknowledge (nack) a message to requeue it or route it to the DLQ.
`queue.publish`	`POST /v1/queue/publish`	Publish a single message to a queue (idempotent).
`queue.publish_batch`	`POST /v1/queue/publish_batch`	Publish multiple messages to a queue in a single batch.
`queue.purge`	`POST /v1/queue/purge/{queue}`	Purge all messages from a queue.
`queue.push_subscribe`	`POST /v1/queue/push_subscribe/{queue}`	Configure a push subscription to deliver queue messages to a callback URL.
`queue.stats`	`GET /v1/queue/stats/{queue}`	Retrieve queue metrics: available, in-flight, and dead-lettered message counts.
`queue.update`	`PATCH /v1/queue/update/{queue}`	Update a queue's DLQ, retry, and retention settings.

End-to-end example

A production-style walkthrough of this module: configure once, then run the flow. It exercises most of the module's APIs.

A copy-paste-runnable single-file Python program (stdlib only, no SDK): set your INFRAI_API_KEY, run it, and walk this module's core flow with REAL billed calls — later steps reuse real fields returned by earlier ones. The 12-line helper is the entire integration.

python

#!/usr/bin/env python3
"""Infrai · queue — runnable real-app example (single file, zero deps).

Copy this file, set your key, run it: every step is a REAL call to
api.infrai.cc, billed at the real (tiny) per-call price, printing the
live JSON response. Get a key at https://infrai.cc/login (Google/
GitHub sign-in grants $2 free credit); add funds at
https://infrai.cc/billing. No SDK — the 12-line helper below is the
entire integration."""
import json
import os
from urllib import error, request

KEY = os.environ.get("INFRAI_API_KEY") or "ifr_..."  # <- your key
BASE = "https://api.infrai.cc"


# Same raw HTTPS POST/GET as every per-method example on this page —
# wrapped once for reuse. There is nothing else to it: no SDK.
def infrai(method, path, body=None):
    req = request.Request(
        BASE + path, method=method,
        data=json.dumps(body).encode() if body is not None else None,
        headers={"Authorization": f"Bearer {KEY}",
                 "Content-Type": "application/json"})
    try:
        with request.urlopen(req, timeout=60) as r:
            return json.loads(r.read())
    except error.HTTPError as e:
        return json.loads(e.read())


def show(label, resp):
    print(f"\n== {label} ==")
    print(json.dumps(resp, indent=2, ensure_ascii=False))
    return resp


# 1) queue.create — POST /v1/queue/create · Create a message queue (standard or FIFO, with optional dead-letter queue).
r1 = show("queue.create", infrai("POST", "/v1/queue/create", {"name":"jobs"}))

# 2) queue.publish — POST /v1/queue/publish · Publish a single message to a queue (idempotent).
r2 = show("queue.publish", infrai("POST", "/v1/queue/publish", {"queue":"jobs","payload":{"hello":"world"}}))

# 3) queue.consume — POST /v1/queue/consume · Pull a batch of messages from a queue for processing.
r3 = show("queue.consume", infrai("POST", "/v1/queue/consume", {"queue":"jobs","max_messages":1}))

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."

bash

# 1) Auth: every call is a raw HTTPS request to the Infrai gateway carrying
#    only your project key. No SDK, no install.
#    Get your key: sign in with Google/GitHub at https://infrai.cc/login for a
#    project key + $2 free credit (email sign-in starts at $0). On 402
#    INSUFFICIENT_CREDIT, add funds at https://infrai.cc/billing (or POST
#    /v1/account/topup and open the returned checkout_url).
export INFRAI_API_KEY="ifr_..."   # from https://infrai.cc/login


# 2) queue.publish
curl -X POST https://api.infrai.cc/v1/queue/publish \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"queue": "orders", "payload": {"order_id": "o_123"}, "priority": 5}'

# 3) queue.create
curl -X POST https://api.infrai.cc/v1/queue/create \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "..."}'

# 4) queue.get
curl -X GET https://api.infrai.cc/v1/queue/get/QUEUE \
  -H "Authorization: Bearer $INFRAI_API_KEY"

# 5) queue.list
curl -X GET https://api.infrai.cc/v1/queue/list \
  -H "Authorization: Bearer $INFRAI_API_KEY"

# 6) queue.update
curl -X PATCH https://api.infrai.cc/v1/queue/update/QUEUE \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

# 7) queue.delete
curl -X DELETE https://api.infrai.cc/v1/queue/delete/QUEUE \
  -H "Authorization: Bearer $INFRAI_API_KEY"

# 8) queue.purge
curl -X POST https://api.infrai.cc/v1/queue/purge/QUEUE \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"queue": "..."}'

# 9) queue.stats
curl -X GET https://api.infrai.cc/v1/queue/stats/QUEUE \
  -H "Authorization: Bearer $INFRAI_API_KEY"

python

# 1) Auth: every call is a raw HTTPS request carrying only your project key.
#    No SDK to install — just the `requests` library.
import os, requests

BASE = "https://api.infrai.cc"
HEADERS = {
    "Authorization": f"Bearer {os.environ['INFRAI_API_KEY']}",
    "Content-Type": "application/json",
}


# 2) queue.publish
import os, requests

resp = requests.post(
    "https://api.infrai.cc/v1/queue/publish",
    headers={"Authorization": f"Bearer {os.environ['INFRAI_API_KEY']}"},
    json={'queue': 'orders', 'payload': {'order_id': 'o_123'}, 'priority': 5},
)
resp.raise_for_status()
print(resp.json())

# 3) queue.create
import os, requests

resp = requests.post(
    "https://api.infrai.cc/v1/queue/create",
    headers={"Authorization": f"Bearer {os.environ['INFRAI_API_KEY']}"},
    json={'name': '...'},
)
resp.raise_for_status()
print(resp.json())

# 4) queue.get
import os, requests

resp = requests.get(
    "https://api.infrai.cc/v1/queue/get/QUEUE",
    headers={"Authorization": f"Bearer {os.environ['INFRAI_API_KEY']}"},
)
resp.raise_for_status()
print(resp.json())

# 5) queue.list
import os, requests

resp = requests.get(
    "https://api.infrai.cc/v1/queue/list",
    headers={"Authorization": f"Bearer {os.environ['INFRAI_API_KEY']}"},
)
resp.raise_for_status()
print(resp.json())

# 6) queue.update
import os, requests

resp = requests.patch(
    "https://api.infrai.cc/v1/queue/update/QUEUE",
    headers={"Authorization": f"Bearer {os.environ['INFRAI_API_KEY']}"},
    json={},
)
resp.raise_for_status()
print(resp.json())

# 7) queue.delete
import os, requests

resp = requests.delete(
    "https://api.infrai.cc/v1/queue/delete/QUEUE",
    headers={"Authorization": f"Bearer {os.environ['INFRAI_API_KEY']}"},
)
resp.raise_for_status()
print(resp.json())

# 8) queue.purge
import os, requests

resp = requests.post(
    "https://api.infrai.cc/v1/queue/purge/QUEUE",
    headers={"Authorization": f"Bearer {os.environ['INFRAI_API_KEY']}"},
    json={'queue': '...'},
)
resp.raise_for_status()
print(resp.json())

# 9) queue.stats
import os, requests

resp = requests.get(
    "https://api.infrai.cc/v1/queue/stats/QUEUE",
    headers={"Authorization": f"Bearer {os.environ['INFRAI_API_KEY']}"},
)
resp.raise_for_status()
print(resp.json())

javascript

// 1) Auth: every call is a raw HTTPS request carrying only your project key.
//    No SDK to install — just the built-in fetch().
const BASE = "https://api.infrai.cc";
const HEADERS = {
  "Authorization": `Bearer ${process.env.INFRAI_API_KEY}`,
  "Content-Type": "application/json",
};


// 2) queue.publish
const resp = await fetch(
  "https://api.infrai.cc/v1/queue/publish",
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.INFRAI_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({"queue": "orders", "payload": {"order_id": "o_123"}, "priority": 5}),
  },
);
console.log(await resp.json());

// 3) queue.create
const resp = await fetch(
  "https://api.infrai.cc/v1/queue/create",
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.INFRAI_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({"name": "..."}),
  },
);
console.log(await resp.json());

// 4) queue.get
const resp = await fetch(
  "https://api.infrai.cc/v1/queue/get/QUEUE",
  {
    method: "GET",
    headers: {
      "Authorization": `Bearer ${process.env.INFRAI_API_KEY}`,
    },
  },
);
console.log(await resp.json());

// 5) queue.list
const resp = await fetch(
  "https://api.infrai.cc/v1/queue/list",
  {
    method: "GET",
    headers: {
      "Authorization": `Bearer ${process.env.INFRAI_API_KEY}`,
    },
  },
);
console.log(await resp.json());

// 6) queue.update
const resp = await fetch(
  "https://api.infrai.cc/v1/queue/update/QUEUE",
  {
    method: "PATCH",
    headers: {
      "Authorization": `Bearer ${process.env.INFRAI_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({}),
  },
);
console.log(await resp.json());

// 7) queue.delete
const resp = await fetch(
  "https://api.infrai.cc/v1/queue/delete/QUEUE",
  {
    method: "DELETE",
    headers: {
      "Authorization": `Bearer ${process.env.INFRAI_API_KEY}`,
    },
  },
);
console.log(await resp.json());

// 8) queue.purge
const resp = await fetch(
  "https://api.infrai.cc/v1/queue/purge/QUEUE",
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.INFRAI_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({"queue": "..."}),
  },
);
console.log(await resp.json());

// 9) queue.stats
const resp = await fetch(
  "https://api.infrai.cc/v1/queue/stats/QUEUE",
  {
    method: "GET",
    headers: {
      "Authorization": `Bearer ${process.env.INFRAI_API_KEY}`,
    },
  },
);
console.log(await resp.json());

typescript

// 1) Auth: every call is a raw HTTPS request carrying only your project key.
//    No SDK to install — just the built-in fetch(), typed.
const BASE = "https://api.infrai.cc";
const HEADERS: Record<string, string> = {
  "Authorization": `Bearer ${process.env.INFRAI_API_KEY}`,
  "Content-Type": "application/json",
};


// 2) queue.publish
const resp = await fetch(
  "https://api.infrai.cc/v1/queue/publish",
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.INFRAI_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({"queue": "orders", "payload": {"order_id": "o_123"}, "priority": 5}),
  },
);
if (!resp.ok) throw new Error(`infrai ${resp.status}`);
const data: unknown = await resp.json();
console.log(data);

// 3) queue.create
const resp = await fetch(
  "https://api.infrai.cc/v1/queue/create",
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.INFRAI_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({"name": "..."}),
  },
);
if (!resp.ok) throw new Error(`infrai ${resp.status}`);
const data: unknown = await resp.json();
console.log(data);

// 4) queue.get
const resp = await fetch(
  "https://api.infrai.cc/v1/queue/get/QUEUE",
  {
    method: "GET",
    headers: {
      "Authorization": `Bearer ${process.env.INFRAI_API_KEY}`,
    },
  },
);
if (!resp.ok) throw new Error(`infrai ${resp.status}`);
const data: unknown = await resp.json();
console.log(data);

// 5) queue.list
const resp = await fetch(
  "https://api.infrai.cc/v1/queue/list",
  {
    method: "GET",
    headers: {
      "Authorization": `Bearer ${process.env.INFRAI_API_KEY}`,
    },
  },
);
if (!resp.ok) throw new Error(`infrai ${resp.status}`);
const data: unknown = await resp.json();
console.log(data);

// 6) queue.update
const resp = await fetch(
  "https://api.infrai.cc/v1/queue/update/QUEUE",
  {
    method: "PATCH",
    headers: {
      "Authorization": `Bearer ${process.env.INFRAI_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({}),
  },
);
if (!resp.ok) throw new Error(`infrai ${resp.status}`);
const data: unknown = await resp.json();
console.log(data);

// 7) queue.delete
const resp = await fetch(
  "https://api.infrai.cc/v1/queue/delete/QUEUE",
  {
    method: "DELETE",
    headers: {
      "Authorization": `Bearer ${process.env.INFRAI_API_KEY}`,
    },
  },
);
if (!resp.ok) throw new Error(`infrai ${resp.status}`);
const data: unknown = await resp.json();
console.log(data);

// 8) queue.purge
const resp = await fetch(
  "https://api.infrai.cc/v1/queue/purge/QUEUE",
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.INFRAI_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({"queue": "..."}),
  },
);
if (!resp.ok) throw new Error(`infrai ${resp.status}`);
const data: unknown = await resp.json();
console.log(data);

// 9) queue.stats
const resp = await fetch(
  "https://api.infrai.cc/v1/queue/stats/QUEUE",
  {
    method: "GET",
    headers: {
      "Authorization": `Bearer ${process.env.INFRAI_API_KEY}`,
    },
  },
);
if (!resp.ok) throw new Error(`infrai ${resp.status}`);
const data: unknown = await resp.json();
console.log(data);