मुख्य सामग्री पर जाएं

​
हाल की खोज का पेजिनेशन

​
परिचय

खोज क्वेरी आमतौर पर जितने पोस्ट्स से मेल खाती हैं, उनमें से सभी को एक ही API रिस्पॉन्स में लौटाना संभव नहीं होता। जब ऐसा होता है, तो डेटा ‘पेजों’ की एक श्रृंखला में लौटाया जाता है। पेजिनेशन उन तरीकों को संदर्भित करता है जिनसे पूरे डेटा सेट को प्राप्त करने के लिए सभी पेजों का अनुरोध किया जाता है। यहाँ recent search पेजिनेशन के कुछ मूलभूत विवरण दिए गए हैं:
  • recent search endpoints किसी क्वेरी के लिए कम-से-कम एक पेज के साथ रिस्पॉन्स देंगे, और यदि अतिरिक्त पेज उपलब्ध हों, तो अपने JSON रिस्पॉन्स में next_token प्रदान करेंगे। मेल खाने वाले पोस्ट्स पाने के लिए, इस प्रक्रिया को तब तक दोहराया जा सकता है जब तक रिस्पॉन्स में कोई token शामिल न हो।
  • next_token की समय-सीमा समाप्त नहीं होती। एक ही next_token value का उपयोग करने वाले कई अनुरोध, अनुरोध कब किया गया है इसकी परवाह किए बिना, समान परिणाम प्राप्त करेंगे।
  • पोस्ट्स UTC समय-क्षेत्र में reverse-chronological क्रम में दिए जाते हैं। यह individual पेजों के भीतर भी लागू होता है, और कई पेजों में भी: 
    • पहले रिस्पॉन्स का पहला पोस्ट आपकी क्वेरी से मेल खाने वाला सबसे हाल का पोस्ट होगा।
    • आखिरी रिस्पॉन्स का आखिरी पोस्ट आपकी क्वेरी से मेल खाने वाला सबसे पुराना पोस्ट होगा।
  • max_results request parameter आपको प्रति रिस्पॉन्स लौटाए जाने वाले पोस्ट्स की संख्या कॉन्फ़िगर करने देता है। इसका डिफ़ॉल्ट 10 पोस्ट्स है और अधिकतम 100 है। 
  • हर पेजिनेशन implementation में रिस्पॉन्स payload से next_tokens को parse करना और उन्हें ‘next पेज’ search request में शामिल करना होता है। इन ‘next पेज’ requests को कैसे तैयार करें, इसके बारे में अधिक जानकारी के लिए नीचे देखें।  
recent search endpoint को दो मूलभूत उपयोग पैटर्न के समर्थन के लिए डिज़ाइन किया गया था:
  • ऐतिहासिक डेटा प्राप्त करना - रुचि की किसी समयावधि से मेल खाने वाले पोस्ट्स का अनुरोध करना। ये आमतौर पर ऐतिहासिक शोध के लिए किए जाने वाले एकबारगी अनुरोध होते हैं। Search requests, start_time और end_time request parameters पर आधारित हो सकते हैं। recent search endpoint सबसे हाल के मेल खाने वाले पोस्ट से शुरू करते हुए, reverse-chronological क्रम में पोस्ट्स के साथ रिस्पॉन्ड करता है। 
  • पोलिंग - पिछले प्राप्त पोस्ट के बाद किए गए मेल खाने वाले पोस्ट्स का अनुरोध करना। इन उपयोग मामलों का फोकस अक्सर near-real-time होता है और इनकी विशेषता बार-बार अनुरोध करना है, ताकि रुचि के नए पोस्ट्स के लिए “listening” किया जा सके। recent search endpoint ‘पोलिंग’ pattern के समर्थन में since_id request parameter प्रदान करता है। Post IDs के आधार पर नेविगेट करने में मदद के लिए, until_id request parameter भी उपलब्ध है।  
अब हम historical mode पर चर्चा करेंगे। यह recent search endpoint का डिफ़ॉल्ट mode है और पेजिनेशन की मूल बातें समझाता है। इसके बाद हम पोलिंग उपयोग मामलों के उदाहरणों पर चर्चा करेंगे। जब पोलिंग में पेजिनेशन ट्रिगर होता है, तो search requests को प्रबंधित करने के लिए एक अतिरिक्त चरण की आवश्यकता होती है।  

​
ऐतिहासिक डेटा पुनर्प्राप्त करना

यह अनुभाग बताता है कि आप start_time और end_time अनुरोध पैरामीटर का उपयोग करके अपनी रुचि की अवधि के पोस्ट्स कैसे पुनर्प्राप्त कर सकते हैं (फ़िलहाल यह पिछले सात दिनों तक सीमित है)। ऐतिहासिक अनुरोध आमतौर पर शोध और विश्लेषण के लिए एकबारगी अनुरोध होते हैं।  किसी समयावधि के डेटा के लिए अनुरोध करना recent search endpoint का डिफ़ॉल्ट मोड है। अगर कोई search request start_time, end_time, या since_id अनुरोध पैरामीटर निर्दिष्ट नहीं करता है, तो end_time का डिफ़ॉल्ट मान “now” होगा (असल में क्वेरी के समय से 30 सेकंड पहले) और start_time का डिफ़ॉल्ट मान सात दिन पहले होगा। endpoint सबसे हालिया पोस्ट से शुरू करते हुए, पोस्ट्स का पहला ‘पेज’ उल्टे कालानुक्रमिक क्रम में लौटाएगा। रिस्पॉन्स JSON payload में next_token भी शामिल होगा, अगर डेटा के अतिरिक्त पेज उपलब्ध हों। मेल खाने वाले पोस्ट्स का पूरा सेट एकत्र करने के लिए, पेजों की संख्या चाहे जितनी भी हो, तब तक अनुरोध किए जाते हैं जब तक next_token दिया जाना बंद न हो जाए।  उदाहरण के लिए, पिछले सप्ताह के snow कीवर्ड वाले पोस्ट्स के लिए एक प्रारंभिक अनुरोध यहां है: https://api.x.com/2/tweets/search/recent?query=snow रिस्पॉन्स में सबसे हाल के 10 पोस्ट्स शामिल हैं, साथ ही JSON रिस्पॉन्स में ये “meta” attributes भी शामिल होते हैं: 
"meta": {
        "newest_id": "1204860593741553664",
        "oldest_id": "1204860580630278147",
        "next_token": "b26v89c19zqg8o3fobd8v73egzbdt3qao235oql",
        "result_count": 10
    }
अगले 10 पोस्ट्स प्राप्त करने के लिए, इस next_token को मूल अनुरोध में जोड़ा जाता है। अनुरोध इस प्रकार होगा: https://api.x.com/2/tweets/search/recent?query=snow&next_token=b26v89c19zqg8o3fobd8v73egzbdt3qao235oql next_token को ढूँढने और उसे अगले अनुरोध में शामिल करने की प्रक्रिया तब तक दोहराई जा सकती है, जब तक सभी पोस्ट्स (या उनकी कोई निर्धारित संख्या) एकत्र न हो जाएँ, या अनुरोधों की कोई निर्दिष्ट संख्या पूरी न हो जाए। यदि डेटा की पूर्णता (आपकी क्वेरी से मेल खाने वाले सभी परिणामों को एकत्र करना) आपके उपयोग के मामले के लिए महत्वपूर्ण है, तो एक सरल “request.next_token null होने तक दोहराएँ” डिज़ाइन पर्याप्त होगा।

​
पोलिंग और लिसनिंग उपयोग परिदृश्य

यह अनुभाग बताता है कि आप since_id अनुरोध पैरामीटर के साथ recent search endpoint को पोल करके हाल की पोस्ट्स कैसे प्राप्त कर सकते/सकती हैं।  पोलिंग उपयोग परिदृश्यों में, “क्या रुचि की कोई नई पोस्ट्स हैं?” जैसी क्वेरियाँ लगातार, बार-बार की जाती हैं। ऐतिहासिक उपयोग परिदृश्यों के विपरीत, जो अनुरोधों को समय के आधार पर बनाते हैं, पोलिंग उपयोग परिदृश्य आमतौर पर पोस्ट id के आधार पर अनुरोध करते हैं। पोलिंग उपयोग पैटर्न का मुख्य आधार यह है कि हर नई पोस्ट का एक अद्वितीय id होता है, जो आम तौर पर X प्लेटफ़ॉर्म से आरोही क्रम में ‘जारी’ होता है। यदि किसी एक पोस्ट का id दूसरी पोस्ट से छोटा है, तो इसका मतलब है कि उसे पहले पोस्ट किया गया था। recent search endpoint पोस्ट id के आधार पर पोस्ट संग्रह में नेविगेट करने का समर्थन करता है। endpoint से मिलने वाले रिस्पॉन्स में oldest_id और newest_id पोस्ट id शामिल होते हैं। पोलिंग मोड में, since_id को अब तक प्राप्त सबसे बड़े/नवीनतम id पर सेट करके अनुरोध किए जाते हैं।  उदाहरण के लिए, मान लें कि snow के बारे में नई पोस्ट्स के लिए हर पाँच मिनट में एक क्वेरी की जाती है, और हमें पिछली बार जो सबसे हाल की पोस्ट मिली थी उसका पोस्ट id 10000 था। जब पोल करने का समय आता है, तो अनुरोध इस प्रकार दिखता है: https://api.x.com/2/tweets/search/recent?query=snow&since_id=10000 अब मान लें कि हमारे पिछले अनुरोध के बाद से सात पोस्ट्स की गईं। चूँकि ये सभी एक ही डेटा ‘पेज’ में आ जाती हैं, इसलिए कोई next_token नहीं होता। रिस्पॉन्स सबसे हाल की (नवीनतम) पोस्ट का पोस्ट id देता है: 
"meta": {
        "newest_id": "12000",
        "oldest_id": "10005",
        "result_count": 7
    }
अगली पोलिंग query करने के लिए, इस newest_id मान का उपयोग अगले since_id parameter को सेट करने में किया जाता है: https://api.x.com/2/tweets/search/recent?query=snow&since_id=12000 जब अधिक डेटा उपलब्ध होता है और next tokens दिए जाते हैं, तो केवल परिणामों के पहले पेज का newest_id मान ही आवश्यक होता है। डेटा के हर पेज में newest_id और oldest_id मान शामिल होंगे, लेकिन अगले नियमित पोलिंग request के लिए सिर्फ पहले पेज में दिया गया मान ही चाहिए। इसलिए, यदि आप पोलिंग design लागू कर रहे हैं या ID range के आधार पर पोस्ट्स खोज रहे हैं, तो पेजिनेशन logic थोड़ा अधिक जटिल हो जाता है।  अब मान लें कि 18 और मेल खाने वाले पोस्ट्स हैं। endpoint इस शुरुआती रिस्पॉन्स के साथ उत्तर देगा, जिसमें एक पूरा data पेज और इस पाँच मिनट की अवधि से डेटा के अगले पेज का अनुरोध करने के लिए एक next_token होगा। इसमें पाँच मिनट बाद होने वाले अगले पोलिंग interval के लिए आवश्यक newest Post ID भी शामिल होगी.   
"meta": {
        "newest_id": "13800",
        "oldest_id": "12500",
        "next_token": "fnsih9chihsnkjbvkjbsc",
        "result_count": 10
    }
इस पाँच मिनट की अवधि के लिए सभी मिलान वाला डेटा प्राप्त करने हेतु, अपनी अगली रिक्वेस्ट में पिछले अनुरोध वाले same since_id मान के साथ next_token पास करें। https://api.x.com/2/tweets/search/recent?query=snow&since_id=12000&next_token=fnsih9chihsnkjbvkjbsc 
"meta": {
        "newest_id": "12300",
        "oldest_id": "12010",
        "result_count": 8
    }
यह दूसरा रिस्पॉन्स शेष आठ पोस्ट्स देता है, और इसमें कोई next_token नहीं होता। ध्यान दें कि हम अपना newest_id मान (12300) अपडेट नहीं करते; इसके बजाय, हम अपना अगला since_id अनुरोध पहले रिस्पॉन्स के newest_id मान के आधार पर करते हैं: https://api.x.com/2/tweets/search/recent?query=snow&since_id=13800