SDK
Librerie client ufficiali per l'API di Pocket Alert. Sono leggere e tipizzate: autenticazione, tipi di richiesta e risposta, classi di errore, retry e paginazione sono gestiti per te.
| Linguaggio | Pacchetto | Installazione | Sorgente |
|---|---|---|---|
| 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 |
Ogni SDK legge la chiave API dalla variabile d'ambiente POCKETALERT_API_KEY se non la passi tu. Crea una chiave nella pagina API Keys.
Inviare un messaggio
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,
);Cosa coprono gli SDK
| Risorsa | Metodi |
|---|---|
| Messaggi | send, list (con paginazione), iterate (paginazione automatica), get, delete, mark read, mark all read, stats, usage |
| Messaggi programmati | list, cancel |
| Applicazioni | list, get, create, update, delete |
| Dispositivi | list, get, update, delete |
| Webhook | list, get, create, update, delete, history |
| Chiavi API | list, create, delete |
send supporta tutte le funzionalità dei messaggi: livelli, pulsanti di azione, invio programmato (send_at / delay) e allegati immagine (un URL o una stringa base64, oppure un caricamento di file).
Errori
Le risposte diverse da 2xx generano errori tipizzati: AuthenticationError (401), PermissionDeniedError (403, ad esempio una funzionalità a pagamento sul piano gratuito), NotFoundError (404), RateLimitError (429, con limit, used e resets_at quando viene raggiunto il limite giornaliero), e così via. Go restituisce un *APIError con funzioni di utilità come pocketalert.IsRateLimited(err); PHP lancia eccezioni da PocketAlert\Exception.
Retry e idempotenza
Le richieste di lettura, aggiornamento ed eliminazione vengono ritentate fino a 2 volte in caso di errori di rete e risposte 5xx. L'invio di un messaggio non viene ritentato in questi casi, così una rete instabile non può consegnare due volte la stessa notifica push. Una risposta 429 con un Retry-After breve viene ritentata per ogni richiesta, dato che non è stato salvato nulla.
Ogni chiamata a send include l'header Idempotency-Key. Puoi passare una chiave tua per associare i retry nel tuo codice a un singolo messaggio.
Timestamp
created_at e deliver_at vengono restituiti come stringhe leggibili nel fuso orario del tuo account (DD.MM.YYYY HH:MM:SS); gli SDK le mantengono come stringhe. deliver_at_utc e resets_at sono in formato RFC 3339.
OpenAPI
Gli SDK sono testati sulla descrizione OpenAPI disponibile su pocketalert.app/openapi.json. Usala per generare un client per qualsiasi altro linguaggio.