跳到正文

SDK ​

Pocket Alert API 的官方客户端库。它们轻量且带有类型定义:身份验证、请求与响应类型、错误类、重试和分页都已为你处理好。

语言包名安装源码
Node.js / TypeScriptpocketalertnpm install pocketalertpocketalert-node
Pythonpocketalertpip install pocketalertpocketalert-python
Gogithub.com/PocketAlert/pocketalert-gogo get github.com/PocketAlert/pocketalert-gopocketalert-go
PHPpocketalert/pocketalert-phpcomposer require pocketalert/pocketalert-phppocketalert-php

如果你没有传入 API 密钥,每个 SDK 都会从 POCKETALERT_API_KEY 环境变量中读取。请在 API Keys 页面创建密钥。

发送消息 ​

ts
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',
});
python
from pocketalert import PocketAlert

client = PocketAlert()  # reads POCKETALERT_API_KEY

client.messages.send(
    title="Deploy finished",
    message="v1.4.2 is live",
    level="high",
)
go
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,
})
php
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
Webhookslist、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 描述进行测试。如需为其他语言生成客户端,可以使用该文件。

Pocket Alert 文档