SDK
Pocket Alert API 的官方客户端库。它们轻量且带有类型定义:身份验证、请求与响应类型、错误类、重试和分页都已为你处理好。
| 语言 | 包名 | 安装 | 源码 |
|---|---|---|---|
| Node.js / TypeScript | pocketalert | npm install pocketalert | pocketalert-node |
| Python | pocketalert | pip install pocketalert | pocketalert-python |
| Go | github.com/PocketAlert/pocketalert-go | go get github.com/PocketAlert/pocketalert-go | pocketalert-go |
| PHP | pocketalert/pocketalert-php | composer require pocketalert/pocketalert-php | pocketalert-php |
如果你没有传入 API 密钥,每个 SDK 都会从 POCKETALERT_API_KEY 环境变量中读取。请在 API Keys 页面创建密钥。
发送消息
import PocketAlert from 'pocketalert';
const client = new PocketAlert(); // reads POCKETALERT_API_KEY
await client.messages.send({
title: 'Deploy finished',
message: 'v1.4.2 is live',
level: 'high',
});from pocketalert import PocketAlert
client = PocketAlert() # reads POCKETALERT_API_KEY
client.messages.send(
title="Deploy finished",
message="v1.4.2 is live",
level="high",
)client, err := pocketalert.NewClient() // reads POCKETALERT_API_KEY
if err != nil {
log.Fatal(err)
}
_, err = client.Messages.Send(ctx, pocketalert.SendMessageParams{
Title: "Deploy finished",
Message: "v1.4.2 is live",
Level: pocketalert.LevelHigh,
})use PocketAlert\Client;
use PocketAlert\Level;
$client = new Client(); // reads POCKETALERT_API_KEY
$client->messages->send(
title: 'Deploy finished',
message: 'v1.4.2 is live',
level: Level::High,
);SDK 涵盖的功能
| 资源 | 方法 |
|---|---|
| 消息 | send、list(分页)、iterate(自动分页)、get、delete、mark read、mark all read、stats、usage |
| 定时消息 | list、cancel |
| 应用 | list、get、create、update、delete |
| 设备 | list、get、update、delete |
| Webhooks | list、get、create、update、delete、history |
| API 密钥 | list、create、delete |
send 支持所有消息功能:优先级、操作按钮、定时发送(send_at / delay)以及图片附件(URL 或 base64 字符串,或文件上传)。
错误
非 2xx 响应会抛出带类型的错误:AuthenticationError(401)、PermissionDeniedError(403,例如在免费套餐上使用付费功能)、NotFoundError(404)、RateLimitError(429,当达到每日上限时,附带 limit、used 和 resets_at)等。Go 返回 *APIError,并提供 pocketalert.IsRateLimited(err) 等辅助函数;PHP 则抛出 PocketAlert\Exception 中的异常。
重试与幂等性
读取、更新和删除请求在遇到网络错误或 5xx 响应时最多重试 2 次。发送消息在这些错误下不会重试,因此网络不稳定时不会重复投递同一条推送。带有较短 429 的 Retry-After 响应会对所有请求进行重试,因为此时没有任何数据被存储。
每次 send 调用都会携带 Idempotency-Key 请求头。你可以传入自己的密钥,将代码中的重试与同一条消息关联起来。
时间戳
created_at 和 deliver_at 以你账户时区下的显示字符串形式返回(DD.MM.YYYY HH:MM:SS);SDK 会将它们保留为字符串。deliver_at_utc 和 resets_at 采用 RFC 3339 格式。
OpenAPI
这些 SDK 会针对 pocketalert.app/openapi.json 中的 OpenAPI 描述进行测试。如需为其他语言生成客户端,可以使用该文件。