पेजिनेशन

Bird API का हर पेजिनेटेड सूची एंडपॉइंट एक ही कर्सर-आधारित अनुबंध का उपयोग करता है: वही अनुरोध पैरामीटर, वही प्रतिक्रिया संरचना और कर्सर का वही व्यवहार। इसे GET /v1/email/messages पर एक बार समझ लें, फिर यह हर जगह लागू होता है।

कुछ सीमित संग्रह (जैसे बिलिंग प्लान) बिना किसी पेजिनेशन फ़ील्ड के एक सादा {"data": [...]} ऐरे लौटाते हैं। बाकी एंडपॉइंट पूरा पेजिनेशन अनुबंध लागू करते हैं।

अनुरोध पैरामीटर

कर्सर अपारदर्शी होते हैं: ये रिसोर्स ID नहीं हैं, और इनका फ़ॉर्मैट कभी भी बदल सकता है। इन्हें प्रतिक्रियाओं से लें और बिना बदले वापस भेजें। गलत या समाप्त हो चुका कर्सर भेजने पर E01012 InvalidCursor कोड वाला 422 लौटता है। ऐसे में बिना कर्सर के पेजिनेशन फिर से शुरू करें।

अधिकांश लिस्ट एंडपॉइंट रिसोर्स के अनुसार sort और order पैरामीटर भी स्वीकार करते हैं; हर एंडपॉइंट का रेफ़रेंस अनुमत सॉर्ट फ़ील्ड बताता है। सॉर्ट बदलने पर पिछले सॉर्ट क्रम के कर्सर अमान्य हो जाते हैं।

प्रतिक्रिया का ढांचा

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

next_cursor और prev_cursor एक-दूसरे से स्वतंत्र हैं: हर एक ठीक तभी null होता है, जब उसकी अपनी दिशा में कोई और पेज नहीं होता। दोबारा फ़ेच करना है या नहीं, यह तय करने के लिए next_cursor जाँचें।

नतीजों के पेजों से गुज़रना

पहले अनुरोध में कोई कर्सर नहीं होता। उसके बाद का हर अनुरोध पिछली प्रतिक्रिया का next_cursor को starting_after के रूप में भेजता है। जब वह null लौटे, तब आप रुक जाते हैं।

हर Bird SDK लिस्ट एंडपॉइंट को दो मोड में उपलब्ध कराता है: लेज़ी इटरेशन, जो आइटम इस्तेमाल करते समय पेज अपने-आप फ़ेच करता है, और सिंगल-पेज एक्सेसर, जिससे आप कर्सर को खुद नियंत्रित करते हैं।

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"

दर सीमाएँ

लिस्ट एंडपॉइंट पूरे संगठन पर लागू api_list दर-सीमा नीति का उपयोग करते हैं, जब तक ऑपरेशन किसी प्रोडक्ट नीति का नाम न दे। यह क्षमता रिसोर्स प्राप्त करने, लिखने और भेजने की क्षमता से अलग है। लेज़ी इटरेशन हर पेज अनुरोध पर नीति की एक इकाई खर्च करता है। अनुरोधों की संख्या घटाने के लिए एंडपॉइंट द्वारा समर्थित सबसे बड़ा पेज आकार इस्तेमाल करें।

संबंधित

• ईमेल संदेश: पेजिनेशन वाले लिस्ट एंडपॉइंट का एक प्रतिनिधि उदाहरण
• SDK अवधारणाएँ: सभी SDK में इटरेशन और सिंगल-पेज एक्सेसर
• दर सीमाएँ: नीतियाँ, हेडर और 429 को संभालना