Pagination

Setiap endpoint daftar berpaginasi di Bird API menggunakan kontrak berbasis cursor yang sama: parameter request yang sama, envelope respons yang sama, semantik cursor yang sama. Pelajari sekali di GET /v1/email/messages dan berlaku di mana saja.

Sejumlah kecil koleksi terbatas (misalnya, paket billing) mengembalikan array {"data": [...]} biasa tanpa field pagination. Endpoint lain mengimplementasikan kontrak pagination lengkap.

Parameter request

Parameter	Tipe	Deskripsi
limit	integer	Jumlah item maksimum per halaman. Antara 1 dan 100; default 25.
starting_after	string	Cursor dari field next_cursor respons sebelumnya. Mengembalikan item tepat setelah posisi tersebut.
ending_before	string	Cursor dari field prev_cursor respons sebelumnya. Mengembalikan item tepat sebelum posisi tersebut.
include_total	boolean	Jika true, respons menyertakan jumlah total. Default false. Tersedia hanya pada endpoint manajemen. Endpoint data bervolume tinggi (pesan, event, supresi) tidak menerimanya.

Cursor bersifat opaque: bukan resource ID, dan formatnya dapat berubah kapan saja. Terima dari respons dan kirimkan kembali tanpa perubahan. Cursor yang salah format atau kedaluwarsa mengembalikan 422 dengan kode E01012 InvalidCursor. Mulai ulang pagination tanpa cursor.

Sebagian besar endpoint daftar juga menerima parameter sort dan order spesifik resource; referensi per endpoint mendokumentasikan field pengurutan yang diizinkan. Mengubah pengurutan membatalkan cursor dari urutan pengurutan sebelumnya.

Envelope respons

Contoh kode

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

Field	Deskripsi
data	Halaman item.
next_cursor	Kirimkan kembali sebagai starting_after untuk mengambil halaman berikutnya. null jika tidak ada halaman berikutnya, yang menjadi sinyal untuk berhenti.
prev_cursor	Kirimkan kembali sebagai ending_before untuk mundur ke halaman sebelumnya. null jika tidak ada halaman sebelumnya (selalu null pada halaman pertama).
refresh_cursor	Anchor penyegaran: simpan, lalu kirimkan kembali sebagai ending_before nanti untuk mengambil item yang muncul sejak respons ini. Non-null selama data tidak kosong.
total	Total item yang cocok dengan filter request di semua halaman. Hadir hanya jika include_total=true dikirimkan; jika tidak null/tidak ada.

next_cursor dan prev_cursor bersifat independen: masing-masing bernilai null tepat saat arahnya tidak memiliki halaman lanjutan. Periksa next_cursor untuk memutuskan apakah perlu mengambil lagi.

Menelusuri hasil

Request pertama tidak membawa cursor. Setiap request berikutnya mengirimkan next_cursor dari respons sebelumnya sebagai starting_after, dan Anda berhenti saat nilainya kembali null.

Setiap Bird SDK mengekspos endpoint daftar dalam dua mode: iterasi lazy yang mengambil halaman secara transparan saat Anda mengonsumsi item, dan aksesor halaman tunggal untuk kontrol cursor manual.

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"

Pembatasan laju permintaan

Endpoint list menggunakan kebijakan pembatasan laju permintaan api_list tingkat organisasi, kecuali operasi tersebut menyebutkan kebijakan produk tertentu. Kapasitas ini terpisah dari pengambilan resource, penulisan, dan pengiriman. Iterasi lazy mengonsumsi satu unit kebijakan per permintaan halaman; gunakan ukuran halaman terbesar yang didukung endpoint untuk mengurangi jumlah permintaan.

Terkait

Email messages: contoh representatif endpoint daftar berpaginasi
Konsep SDK: iterasi dan aksesor halaman tunggal di seluruh SDK
Pembatasan laju permintaan: kebijakan, header, dan penanganan 429

Sumber daya terkait

Lanjutkan dengan dokumentasi, panduan, dan contoh untuk topik ini. Sumber daya tersedia dalam bahasa Inggris.

Pahami konsepnyaShould I use a Bird SDK or call the API directly?Ikuti jalur pembelajaranBuild your first integration Panduan implementasiSend your first email

Dapatkan ringkasan implementasi