SDK
Официальные клиентские библиотеки для API Pocket Alert. Они лёгкие и типизированные: аутентификация, типы запросов и ответов, классы ошибок, повторные попытки и пагинация выполняются за вас.
| Язык | Пакет | Установка | Исходный код |
|---|---|---|---|
| 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 |
Каждый SDK читает API-ключ из переменной окружения POCKETALERT_API_KEY, если вы не передали ключ явно. Создать ключ можно на странице API-ключи.
Отправка сообщения
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 |
| Вебхуки | 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.
Повторные попытки и идемпотентность
Запросы на чтение, обновление и удаление повторяются до 2 раз при сетевых ошибках и ответах 5xx. Отправка сообщения при таких ошибках не повторяется, поэтому нестабильная сеть не доставит одно и то же push-уведомление дважды. Ответ 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 протестированы на OpenAPI-описании по адресу pocketalert.app/openapi.json. Используйте его, чтобы сгенерировать клиент для любого другого языка.