Paginacja

Każdy paginowany endpoint listowy w Bird API stosuje ten sam kontrakt kursorowy: te same parametry żądania, tę samą kopertę odpowiedzi, tę samą semantykę kursorów. Poznaj go raz na GET /v1/email/messages, a będzie działać wszędzie.

Niewielka liczba ograniczonych kolekcji (na przykład plany rozliczeniowe) zwraca zwykłą tablicę {"data": [...]} bez pól paginacji. Pozostałe endpointy implementują pełny kontrakt paginacji.

Parametry żądania

Parametr	Typ	Opis
limit	integer	Maksymalna liczba elementów na stronę. Od 1 do 100; domyślnie 25.
starting_after	string	Kursor z pola next_cursor poprzedniej odpowiedzi. Zwraca elementy bezpośrednio po tej pozycji.
ending_before	string	Kursor z pola prev_cursor poprzedniej odpowiedzi. Zwraca elementy bezpośrednio przed tą pozycją.
include_total	boolean	Gdy true, odpowiedź zawiera licznik total. Domyślnie false. Dostępne tylko na endpointach zarządzania. Endpointy danych o dużym wolumenie (wiadomości, zdarzenia, supresje) nie obsługują tego parametru.

Kursory są nieprzezroczyste: nie są identyfikatorami zasobów, a ich format może się zmienić w dowolnym momencie. Odbieraj je w odpowiedziach i przekazuj z powrotem bez zmian. Zniekształcony lub wygasły kursor zwraca 422 z kodem E01012 InvalidCursor. Rozpocznij paginację od nowa, bez kursora.

Większość endpointów listowych akceptuje też specyficzne dla zasobu parametry sort i order; dokumentacja danego endpointu opisuje dozwolone pola sortowania. Zmiana sortowania unieważnia kursory z poprzedniego porządku.

Koperta odpowiedzi

Przykład kodu

{
  "data": [{ "...": "..." }],
  "next_cursor": "WyIyMDI2LTA2LTEwVDA5OjE0OjAzWiIsICJtc2dfMDFr...",
  "prev_cursor": null,
  "refresh_cursor": "WyIyMDI2LTA2LTEwVDEyOjAwOjAwWiIsICJtc2dfMDFr...",
  "total": 1432
}

Pole	Opis
data	Strona elementów.
next_cursor	Przekaż jako starting_after, aby pobrać następną stronę. null, gdy następna strona nie istnieje, co jest sygnałem do zakończenia.
prev_cursor	Przekaż jako ending_before, aby cofnąć się o stronę. null, gdy poprzednia strona nie istnieje (zawsze null na pierwszej stronie).
refresh_cursor	Punkt odniesienia do odświeżenia: zapisz go, a potem przekaż jako ending_before, aby pobrać elementy, które pojawiły się od tej odpowiedzi. Różny od null zawsze, gdy data nie jest pusta.
total	Łączna liczba elementów pasujących do filtrów żądania na wszystkich stronach. Obecne tylko wtedy, gdy przekazano include_total=true; w przeciwnym razie null/brak.

next_cursor i prev_cursor są niezależne: każde z nich jest null dokładnie wtedy, gdy w danym kierunku nie ma kolejnej strony. Sprawdzaj next_cursor, aby zdecydować, czy pobierać dalej.

Przechodzenie przez wyniki

Pierwsze żądanie nie zawiera kursora. Każde kolejne przekazuje next_cursor z poprzedniej odpowiedzi jako starting_after. Kończysz, gdy zwrócona wartość to null.

Każdy Bird SDK udostępnia endpointy listowe w dwóch trybach: leniwa iteracja, która pobiera strony w tle w miarę konsumowania elementów, oraz akcesor pojedynczej strony do ręcznego sterowania kursorem.

for await (const message of bird.email.list({ status: "bounced" })) {
  console.log(message.id);
}

for message in client.email.list(status="delivered"):
    print(message.id)

for msg, err := range client.Email.List(context.Background(), bird.EmailListParams{Status: bird.EmailStatusBounced}) {
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(msg.Id)
}

foreach ($bird->email->list(['status' => 'delivered']) as $message) {
    echo $message->getId(), "\n";
}

bird email list

curl -X GET "https://{region}.platform.bird.com/v1/email/messages" \
  -H "Authorization: Bearer $TOKEN" \
  --url-query "limit=25"

Limity żądań

Endpointy listowe korzystają z ogólnoorganizacyjnej polityki ograniczania liczby żądań api_list, chyba że operacja wskazuje politykę produktową. Ta przepustowość jest odrębna od pobierania zasobów, zapisów i wysyłek. Leniwa iteracja zużywa jedną jednostkę polityki na żądanie strony. Używaj największego rozmiaru strony obsługiwanego przez endpoint, aby zmniejszyć liczbę żądań.

Powiązane

Wiadomości e-mail: reprezentatywny paginowany endpoint listowy
Koncepcje SDK: iteracja i akcesory pojedynczej strony w SDK
Ograniczanie liczby żądań: polityki, nagłówki i obsługa 429

Powiązane zasoby

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

Zrozum koncepcjęShould I use a Bird SDK or call the API directly?Podążaj ścieżką naukiBuild your first integration Przewodnik wdrożeniowySend your first email

Uzyskaj brief wdrożeniowy