पेजिनेशन

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

सीमित कलेक्शन की एक छोटी संख्या (उदाहरण के लिए, बिलिंग प्लान) बिना पेजिनेशन फ़ील्ड के एक सादा {"data": [...]} array लौटाती है। अन्य endpoint पूर्ण पेजिनेशन कॉन्ट्रैक्ट लागू करते हैं।

रिक्वेस्ट पैरामीटर

पैरामीटर	टाइप	विवरण
limit	integer	प्रति पेज अधिकतम आइटम। 1 और 100 के बीच; डिफ़ॉल्ट 25।
starting_after	string	पिछले रिस्पॉन्स के next_cursor फ़ील्ड से कर्सर। उस स्थिति के तुरंत बाद के आइटम लौटाता है।
ending_before	string	पिछले रिस्पॉन्स के prev_cursor फ़ील्ड से कर्सर। उस स्थिति के तुरंत पहले के आइटम लौटाता है।
include_total	boolean	जब true हो, तो रिस्पॉन्स में total काउंट शामिल होता है। डिफ़ॉल्ट false। केवल मैनेजमेंट endpoint पर उपलब्ध। हाई-वॉल्यूम डेटा endpoint (मैसेज, इवेंट, सप्रेशन) इसे स्वीकार नहीं करते।

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

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

रिस्पॉन्स एन्वेलप

कोड उदाहरण

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

फ़ील्ड	विवरण
data	आइटम का पेज।
next_cursor	अगला पेज लाने के लिए starting_after के रूप में वापस भेजें। जब कोई अगला पेज नहीं होता तो null होता है, जो रुकने का संकेत है।
prev_cursor	पीछे जाने के लिए ending_before के रूप में वापस भेजें। जब कोई पिछला पेज नहीं होता तो null होता है (पहले पेज पर हमेशा null)।
refresh_cursor	एक रिफ़्रेश एंकर: इसे सेव करें, फिर बाद में ending_before के रूप में वापस भेजें ताकि इस रिस्पॉन्स के बाद आए आइटम मिल सकें। जब data खाली नहीं होता तब हमेशा नॉन-नल।
total	सभी पेज पर रिक्वेस्ट के फ़िल्टर से मेल खाने वाले कुल आइटम। केवल तब मौजूद जब include_total=true पास किया गया हो; अन्यथा null/अनुपस्थित।

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

परिणामों में पेजिंग

पहली रिक्वेस्ट में कोई कर्सर नहीं होता। इसके बाद हर रिक्वेस्ट पिछले रिस्पॉन्स का next_cursor starting_after के रूप में भेजती है, और जब वह null लौटे तो आप रुक जाएँ।

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

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 अनुरोध दर सीमा नीति का उपयोग करते हैं, जब तक कि ऑपरेशन किसी प्रोडक्ट नीति का नाम न दे। यह क्षमता रिसोर्स रिट्रीवल, राइट्स और सेंड्स से अलग है। Lazy iteration प्रति पेज अनुरोध एक पॉलिसी यूनिट की खपत करता है; अनुरोधों की संख्या कम करने के लिए एंडपॉइंट द्वारा समर्थित सबसे बड़े पेज साइज़ का उपयोग करें।

पेजिनेशन

रिक्वेस्ट पैरामीटर

रिस्पॉन्स एन्वेलप

परिणामों में पेजिंग

रेट लिमिट

संबंधित

संबंधित संसाधन