v1 से v2

X API v2 की तुलना में Standard v1.1

यदि आप v1.1 search/posts के साथ काम कर रहे हैं, तो इस गाइड का उद्देश्य स्टैंडर्ड और X API v2 के search Posts endpoint के बीच की समानताओं और अंतरों को समझने में आपकी मदद करना है।

• समानताएँ
  • OAuth 1.0a User Context और OAuth 2.0 App-Only
  • पोस्ट के संपादन इतिहास और मेटाडेटा के लिए समर्थन। 
• अंतर

  • एंडपॉइंट URLs

  • ऐप और Project आवश्यकताएँ

  • रिस्पॉन्स डेटा फ़ॉर्मैट

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

  • नए क्वेरी ऑपरेटर्स

  • AND / OR ऑपरेटर प्रिसीडेन्स 

समानताएँ

OAuth 1.0a User Context और OAuth 2.0 App-Only प्रमाणीकरण

v1.1 search/posts और X API v2 recent search endpoint, दोनों OAuth 1.0a User Context और OAuth 2.0 App-Only का समर्थन करते हैं। 

इसलिए, यदि आप पहले स्टैंडर्ड v1.1 search endpoint का उपयोग कर रहे थे, तो X API v2 संस्करण पर माइग्रेट करने के बाद भी आप वही प्रमाणीकरण विधि इस्तेमाल कर सकते हैं। 

आपकी चुनी हुई प्रमाणीकरण लाइब्रेरी/पैकेज के आधार पर, App-Only प्रमाणीकरण शुरुआत करने का शायद सबसे आसान तरीका है, और इसे एक साधारण request header के साथ सेट किया जा सकता है। App Access Token कैसे जनरेट करें, यह जानने के लिए यह OAuth 2.0 App-Only guide देखें। 

यदि आप X API v2 endpoint के साथ private या advertising metrics प्राप्त करने की क्षमता का लाभ उठाना चाहते हैं, तो आपको OAuth 1.0a User Context का उपयोग करना होगा और उस उपयोगकर्ता से जुड़े user access tokens पास करने होंगे, जिसने वह पोस्ट किया है जिसके लिए आप metrics प्राप्त करना चाहते हैं। 

पोस्ट संपादन इतिहास और मेटाडेटा के लिए समर्थन

दोनों संस्करण ऐसा मेटाडेटा प्रदान करते हैं जो किसी भी संपादन इतिहास का विवरण देता है। अधिक जानकारी के लिए search API References और Post edits fundamentals page देखें। 

अंतर

एंडपॉइंट URLs

• स्टैंडर्ड v1.1 एंडपॉइंट्स:

  • https://api.x.com/1.1/search/tweets

• X API v2 एंडपॉइंट:

  • https://api.x.com/2/tweets/search/recent  

ऐप और Project आवश्यकताएँ

X API v2 एंडपॉइंट्स के लिए आवश्यक है कि आप अपने अनुरोधों को प्रमाणित करते समय ऐसे developer App के क्रेडेंशियल्स का उपयोग करें, जो किसी Project से संबद्ध हो। सभी X API v1.1 एंडपॉइंट्स ऐप्स से, या किसी ऐप से संबद्ध ऐप्स से, क्रेडेंशियल्स का उपयोग कर सकते हैं। 

रिस्पॉन्स डेटा फ़ॉर्मैट

स्टैंडर्ड v1.1 और X API v2 एंडपॉइंट संस्करणों के बीच सबसे बड़े अंतरों में से एक यह है कि आप यह कैसे चुनते हैं कि आपके payload में कौन-से फ़ील्ड्स लौटें।

स्टैंडर्ड एंडपॉइंट्स में आपको डिफ़ॉल्ट रूप से रिस्पॉन्स के कई फ़ील्ड्स मिलते हैं, और फिर parameters का उपयोग करके यह तय करने का विकल्प मिलता है कि payload में कौन-से फ़ील्ड्स या फ़ील्ड्स के समूह लौटने चाहिए।

X API v2 संस्करण डिफ़ॉल्ट रूप से केवल पोस्ट id और text फ़ील्ड्स देता है। किसी भी अतिरिक्त फ़ील्ड्स या ऑब्जेक्ट्स का अनुरोध करने के लिए, आपको fields और expansions parameters का उपयोग करना होगा। इन एंडपॉइंट्स से जिन भी पोस्ट फ़ील्ड्स का आप अनुरोध करेंगे, वे प्राथमिक पोस्ट ऑब्जेक्ट में लौटेंगे। कोई भी expanded user, media, poll, या place ऑब्जेक्ट्स और फ़ील्ड्स आपके रिस्पॉन्स के भीतर एक includes ऑब्जेक्ट में लौटेंगे। इसके बाद, आप पोस्ट और expanded ऑब्जेक्ट, दोनों में मौजूद IDs का मिलान करके expanded ऑब्जेक्ट्स को वापस पोस्ट ऑब्जेक्ट से जोड़ सकते हैं। 

हम आपको प्रोत्साहित करते हैं कि आप इन नए parameters के बारे में उनके संबंधित guides में, या fields and expansions का उपयोग कैसे करें पर हमारी guide पढ़कर, और अधिक जानें। 

हमने एक data format migration guide भी तैयार की है, जो स्टैंडर्ड v1.1 फ़ील्ड्स को नए v2 फ़ील्ड्स से मैप करने में आपकी मदद कर सकती है। यह guide आपको वह specific expansion और field parameter भी बताएगी, जिसे आपको specific फ़ील्ड्स लौटाने के लिए अपने v2 अनुरोध के साथ भेजना होगा।   

कुछ फ़ील्ड्स का अनुरोध करने के तरीके में हुए बदलावों के अलावा, X API v2 API द्वारा लौटाए गए ऑब्जेक्ट्स के लिए नए JSON designs भी पेश करता है, जिनमें पोस्ट और user ऑब्जेक्ट्स शामिल हैं।

• JSON root level पर, स्टैंडर्ड एंडपॉइंट्स पोस्ट ऑब्जेक्ट्स को statuses array में लौटाते हैं, जबकि X API v2 data array लौटाता है। 
• Retweeted और Quoted “statuses” का संदर्भ देने के बजाय, X API v2 JSON Retweeted और Quoted Tweets का संदर्भ देता है। कई legacy और deprecated फ़ील्ड्स, जैसे contributors और user.translator_type, हटाए जा रहे हैं। 
• दोनों favorites (पोस्ट ऑब्जेक्ट में) और favourites (user ऑब्जेक्ट में) का उपयोग करने के बजाय, X API v2 like शब्द का उपयोग करता है। 
• X इस convention को अपना रहा है कि जिन JSON values का कोई मान नहीं है (उदाहरण के लिए, null), उन्हें payload में नहीं लिखा जाता। पोस्ट और user attributes केवल तभी शामिल किए जाते हैं, जब उनके मान non-null हों।   

हमने पोस्ट ऑब्जेक्ट में फ़ील्ड्स का एक नया सेट भी पेश किया है, जिनमें निम्नलिखित शामिल हैं:

• एक conversation_id फ़ील्ड
• दो नए annotations फ़ील्ड्स, जिनमें context और entities शामिल हैं
• कई नए metrics फ़ील्ड्स 
• एक नया reply_setting field, जो यह दिखाता है कि किसी दिए गए पोस्ट का जवाब कौन दे सकता है

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

निम्नलिखित स्टैंडर्ड v1.1 अनुरोध पैरामीटर के समकक्ष X API v2 में उपलब्ध हैं:

Standard search v1.1	Search Posts v2
q	query
	start_time (YYYY-MM-DDTHH:mm:ssZ)
until (YYYY-MM-DD)	end_time (YYYY-MM-DDTHH:mm:ssZ)
since_id	since_id
max_id	until_id
count	max_results
रिस्पॉन्स में search_metadata.next_results दिया जाता है	next_token

स्टैंडर्ड search Posts अनुरोध पैरामीटर का एक समूह ऐसा भी है, जिसे X API v2 में समर्थित नहीं किया जाता:

Standard v1.1 parameter	विवरण
geocode	Search Posts स्थान-आधारित क्वेरी के लिए geo operators का समर्थन करता है।
locale	स्टैंडर्ड search में इसका उपयोग क्वेरी की भाषा निर्दिष्ट करने के लिए किया जाता था, लेकिन इसे कभी पूरी तरह लागू नहीं किया गया।
lang	Search Posts endpoints, रुचि की भाषाओं से मिलान करने के लिए lang query operator उपलब्ध कराते हैं।
include_entities	पोस्ट entities हमेशा शामिल होती हैं।
result_type	Search Posts endpoints, एंगेजमेंट स्तर की परवाह किए बिना सभी मेल खाने वाली पोस्ट्स उपलब्ध कराते हैं।
extended	X API v2 को शुरू से ही 280 वर्णों तक की पोस्ट्स का समर्थन करने के लिए बनाया गया है। v2 में ‘extended’ पोस्ट्स जैसी कोई अवधारणा नहीं है।

यहाँ एक उदाहरण अनुरोध दिया गया है, जो Standard अनुरोध और Search Posts अनुरोध के बीच का अंतर दिखाता है:

Standard v1.1	X API v2
https://api.x.com/1.1/search/tweets.json?q=snow&count=50	https://api.x.com/2/tweets/search/recent?query=snow&max_results=50

ये दोनों अनुरोध keyword snow वाली 50 सबसे हाल की पोस्ट्स लौटाएँगे। v2 अनुरोध, मेल खाने वाली पोस्ट्स के डिफ़ॉल्ट id और text फ़ील्ड्स लौटाएगा। JSON payload में शामिल करने के लिए अतिरिक्त पोस्ट्स और user फ़ील्ड्स निर्दिष्ट करने का एक उदाहरण यहाँ दिया गया है:

X API v2
https://api.x.com/2/tweets/search/recent?query=snow&max_results=50&tweet.fields=id,created_at,author_id,text,source,entities,attachments&user.fields=id,name,username,description

नए query operators

Search Posts, X API v2 की दो नई सुविधाओं के समर्थन में नए operators पेश करता है: 

• Conversation IDs - जैसे-जैसे X पर बातचीत आगे बढ़ती है, बातचीत का हिस्सा होने वाली पोस्ट्स को चिह्नित करने के लिए एक conversation ID उपलब्ध होता है। बातचीत की सभी पोस्ट्स में conversation_id उस पोस्ट ID पर सेट होगा, जिससे वह बातचीत शुरू हुई थी। 
  • conversation_id:
• X Annotations पोस्ट्स के बारे में प्रासंगिक जानकारी प्रदान करते हैं, और इनमें entity तथा context annotations शामिल होते हैं। Entities में लोग, स्थान, उत्पाद और संगठन शामिल होते हैं। Contexts वे domains या topics होते हैं, जिनसे surfaced entities संबंधित होते हैं। उदाहरण के लिए, किसी पोस्ट में उल्लिखित लोगों के context से यह संकेत मिल सकता है कि वे athlete, actor, या politician हैं।  

  • context: उन पोस्ट्स से मेल खाता है जिन्हें रुचि के किसी context के साथ annotate किया गया है। 

  • entity: उन पोस्ट्स से मेल खाता है जिन्हें रुचि की किसी entity के साथ annotate किया गया है। 

     

AND / OR ऑपरेटर प्राथमिकता

सर्च क्वेरी बनाने का मूल आधार OR और AND तार्किक समूहों का उपयोग है। स्टैंडर्ड search API में ORs, ANDs से पहले लागू होते हैं, जबकि Search Posts endpoints (साथ ही premium और enterprise संस्करणों) में ANDs, ORs से पहले लागू होते हैं। दोनों के बीच क्वेरी का अनुवाद करते समय यह अंतर बेहद महत्वपूर्ण है। 

उदाहरण के लिए, स्टैंडर्ड search में अगर आप ऐसे पोस्ट्स का मिलान करना चाहते हैं जिनमें ‘storm’ कीवर्ड हो और साथ ही ‘colorado’ शब्द या #COwx हैशटैग का उल्लेख हो, तो आप यह काम नीचे दी गई सर्च क्वेरी से कर सकते हैं:

storm #COwx OR colorado

Search Posts ऑपरेटर प्राथमिकता में, ANDs को ORs से पहले लागू किया जाता है। इसलिए ऊपर दी गई क्वेरी इसके समकक्ष है: 

(storm #COwx) OR colorado

हालाँकि, ऊपर दिया गया नियम ऐसे किसी भी पोस्ट्स से मेल खाएगा जिनमें ‘Colorado’ का उल्लेख हो, भले ही पोस्ट में ‘storm’ या #COwx हैशटैग का उल्लेख न हो। इसके अलावा, यह उन पोस्ट्स से भी मेल खाएगा जिनमें ‘storm’ कीवर्ड और #COwx हैशटैग दोनों का उल्लेख हो। 

क्वेरी को मूल आशय के अनुसार काम कराने के लिए, OR क्लॉज़ को एक साथ समूहित करना होगा। मूल स्टैंडर्ड क्वेरी का Search Posts में अनुवाद इस प्रकार होगा:

storm (#COwx OR colorado)

इन दोनों नियमों का मिलान व्यवहार बहुत अलग है। अक्टूबर 2019 के महीने में, मूल नियम 1,175,000 से अधिक पोस्ट्स से मेल खाता है, जबकि सही तरीके से अनुवादित नियम लगभग 5,600 पोस्ट्स से मेल खाता है। अपने ANDs और ORs पर ध्यान दें, और जहाँ ज़रूरत हो वहाँ parentheses का उपयोग करें। 

cURL अनुरोध

निम्नलिखित अनुभाग स्टैंडर्ड v1.1 endpoint और v2 में उसके समकक्ष endpoint के लिए cURL अनुरोध दिखाता है।

ये अनुरोध [OAuth 2.0 App-Only](https://developer.x.com(/resources/fundamentals/authentication#app-only-authentication-and-oauth-2-0-bearer-token) का उपयोग करके किए जाते हैं। नीचे दिए गए cURL अनुरोध चलाने के लिए, आपको authorization header में ACCESS_TOKEN को अपने ऐप access token से बदलना होगा। v2 endpoints के लिए, आपका ऐप access token किसी Project के भीतर मौजूद developer App से संबंधित होना चाहिए। 

v1.1 endpoint से लौटाया गया रिस्पॉन्स payload, v2 endpoint से लौटाए गए रिस्पॉन्स payload से अलग होगा। v2 में, रिस्पॉन्स में default फ़ील्ड्स के साथ-साथ fields और expansions parameters के ज़रिए अनुरोध किए गए अन्य फ़ील्ड्स भी शामिल होंगे। आप इन parameters का उपयोग लौटाए जाने वाले फ़ील्ड्स का अलग सेट अनुरोध करने के लिए कर सकते हैं।

स्टैंडर्ड v1.1 GET search/tweets → v2 GET tweets/search/recent

cURL (v1.1)

shellscript

curl --request GET \
  --url 'https://api.x.com/1.1/search/tweets.json?q=from%3AXDevelopers%20-is%3Aretweet&count=100' \
  --header 'Authorization: Bearer $ACCESS_TOKEN'

अगले चरण

X API v2 recent search के लिए हमारी त्वरित शुरुआत मार्गदर्शिका देखें

recent search के लिए API संदर्भ देखें

इन endpoints के लिए कुछ sample code देखें

recent search के लिए अपना पहला अनुरोध करने की चरण-दर-चरण मार्गदर्शिका