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 キーを読み込みます。API キーは 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 |
| Webhook | 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、1 日の上限に達した場合は limit、used、resets_at を含む)などがあります。Go では *APIError などのヘルパーを備えた pocketalert.IsRateLimited(err) を返します。PHP では PocketAlert\Exception から例外がスローされます。
リトライと冪等性
読み取り、更新、削除のリクエストは、ネットワークエラーおよび 5xx レスポンス時に最大 2 回までリトライされます。メッセージの送信は、これらのエラーではリトライされません。そのため、ネットワークが不安定でも同じプッシュ通知が二重に届くことはありません。短い 429 を伴う Retry-After は、何も保存されていないため、すべてのリクエストでリトライされます。
send の各呼び出しには Idempotency-Key ヘッダーが付与されます。独自のキーを渡すことで、コード内のリトライを 1 つのメッセージに紐付けられます。
タイムスタンプ
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 定義に対してテストされています。他の言語向けのクライアントを生成する際にご利用ください。