Sign inGet Started

Pojęcia SDK

SDK TypeScript, Go, Python i PHP mają wspólny projekt. Każdy zawiera wygenerowaną bazę z typami oraz niskopoziomowego klienta utworzonego ze specyfikacji OpenAPI Bird. Ręcznie napisana warstwa zarządza cyklem życia żądania i udostępnia kuratorowany interfejs. Ta strona opisuje ich wspólne zachowanie. Strony poszczególnych języków omawiają szczegóły idiomatyczne.

Automatyczna idempotentność

Każda mutacja (POST, PUT, PATCH, DELETE) otrzymuje automatycznie wygenerowany nagłówek Idempotency-Key. Klucz jest generowany raz na wywołanie logiczne i używany ponownie przy każdej próbie ponowienia. Zapobiega to podwójnemu zastosowaniu ponowionego zapisu. Jeśli wysyłka przekroczy limit czasu po przetworzeniu przez serwer, ponowienie otrzyma zapisaną odpowiedź. Przekaż własny klucz (opcja per wywołanie idempotencyKey / option.WithIdempotencyKey / idempotency_key), gdy operacja logiczna obejmuje więcej niż jedno wywołanie SDK, na przykład pętlę ponowień w aplikacji wokół SDK. Zobacz Idempotentność, aby poznać protokół po stronie serwera.

Bezpieczne ponawianie

Ponawianie jest domyślnie włączone (maxRetries: 2 w każdym SDK). Klient ponawia błędy przejściowe, w tym błędy sieciowe, przekroczenia limitu czasu per próba, odpowiedzi 429 oraz ponawiane odpowiedzi 5xx. Stosuje wykładniczy backoff z jitterem i respektuje nagłówek Retry-After serwera. Błędy deterministyczne (401, 404, 422 i inne odpowiedzi 4xx) nie są nigdy ponawiane. Ponowne użycie klucza idempotentności sprawia, że ponawianie mutacji jest bezpieczne. Limit czasu dotyczy każdej próby (domyślnie 60 sekund), więc wywołanie z ponowieniami może trwać dłużej. PHP używa limitu czasu wymuszanego przez wstrzykniętego klienta HTTP, ponieważ PSR-18 nie ma przenośnego limitu czasu per żądanie.

Paginacja

Endpointy listujące używają paginacji kursorowej. Każdy SDK obsługuje natywną iterację, która automatycznie pobiera kolejne strony. Aby sterować kursorem ręcznie, użyj akcesora pojedynczej strony. Każda strona zawiera data i next_cursor; przekaż kursor z powrotem jako starting_after, aby przejść dalej.
for await (const message of bird.email.list({ status: "bounced" })) {
  console.log(message.id);
}
const page = await bird.email.list({ limit: 50 }); // page.data, page.next_cursor
Zobacz dokumentację paginacji, aby poznać kursory, limit i include_total.

Wnioskowanie regionu

Klucze Bird API kodują swój region: bk_{region}_{token}. SDK odczytuje prefiks i automatycznie kieruje do https://{region}.platform.bird.com. Opcja region nadpisuje wywnioskowany region. Jawny baseUrl (option.WithBaseURL / base_url) ma pierwszeństwo przed oboma i umożliwia lokalne tworzenie lub wdrożenia self-hosted. Konstrukcja kończy się błędem, gdy klucz nie pasuje do formatu bk_{region}_ i nie ustawiono nadpisania.

Opcje per wywołanie a konfiguracja tylko przy konstrukcji

Konfiguracja ma dwa poziomy. Ustawienia tożsamości i transportu są dostępne tylko przy konstrukcji: klucz API, bazowy URL lub region oraz klient HTTP lub implementacja fetch. Ustawienia cyklu życia można ustawić jako domyślne przy konstrukcji i nadpisać per wywołanie: timeout, maxRetries, klucz idempotentności i dodatkowe nagłówki. TypeScript, Python i PHP używają końcowego obiektu opcji; Go używa wariadycznych opcji option.With…. Nagłówki należące do SDK (Authorization, User-Agent, Idempotency-Key) mają pierwszeństwo przed nagłówkami podanymi przez wywołującego. Domyślne ustawienia kanału, takie jak domyślny e-mail from, działają według tego samego wzorca.

Weryfikacja webhooków

Każdy SDK udostępnia jeden punkt wejścia do weryfikacji: webhooks.unwrap(rawBody, headers). Implementuje Standard Webhooks z HMAC-SHA256 na surowym ładunku i sekrecie podpisującym twojego endpointu. Akceptuje wpisy sygnatury ze znacznikiem v1, odrzuca znaczniki czasu spoza 5-minutowego okna tolerancji i porównuje sygnatury w czasie stałym. Przekaż surowe bajty ciała żądania dokładnie tak, jak je otrzymałeś. Parsowanie i ponowna serializacja JSON zmienia bajty i unieważnia sygnaturę.
Po pomyślnej weryfikacji unwrap zwraca typowane zdarzenie rozróżniane po type, na przykład email.delivered lub email.bounced. Nieznane typy zdarzeń nadal przechodzą weryfikację i dekodowanie, więc obsłuż je w gałęzi default. Błąd weryfikacji to odrębny błąd (BirdWebhookVerificationError / *WebhookVerificationError / WebhookVerificationError); odpowiedz kodem 400. Zobacz Webhooki, aby skonfigurować endpoint i poznać katalog zdarzeń.

Następne kroki

Powiązane zasoby

Kontynuuj z dokumentacją, przewodnikami i przykładami dotyczącymi tego tematu. Zasoby są w języku angielskim.

Uzyskaj brief wdrożeniowy