Перейти к содержимому

SDK ​

Официальные клиентские библиотеки для API Pocket Alert. Они лёгкие и типизированные: аутентификация, типы запросов и ответов, классы ошибок, повторные попытки и пагинация выполняются за вас.

ЯзыкПакетУстановкаИсходный код
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

Каждый SDK читает API-ключ из переменной окружения POCKETALERT_API_KEY, если вы не передали ключ явно. Создать ключ можно на странице API-ключи.

Отправка сообщения ​

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
Вебхуки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. Используйте его, чтобы сгенерировать клиент для любого другого языка.

Документация Pocket Alert