चेतावनी: यह पेज, Google के पुराने एपीआई यानी कि Google Data API के बारे में है. यह सिर्फ़ उन एपीआई के बारे में है जो Google Data API डायरेक्ट्री में मौजूद हैं. इनमें से कई एपीआई को नए एपीआई से बदला गया है. किसी नए एपीआई के बारे में जानकारी पाने के लिए, उस नए एपीआई के दस्तावेज़ देखें. नए एपीआई से अनुरोधों को अनुमति देने के बारे में जानकारी पाने के लिए, Google खाते की पुष्टि करना और अनुमति देना देखें.
इस दस्तावेज़ में बताया गया है कि Google API, Google के कई तरह के डेटा प्रोटोकॉल का इस्तेमाल कैसे करता है. इसमें इस बात की जानकारी भी शामिल होती है कि क्वेरी किस तरह की दिखती है, नतीजों में क्या दिखता है, और इसी तरह की दूसरी जानकारी भी शामिल होती है.
Google डेटा प्रोटोकॉल के बारे में ज़्यादा जानकारी के लिए, डेवलपर की गाइड की खास जानकारी देने वाला पेज और प्रोटोकॉल की बुनियादी बातें दस्तावेज़ देखें.
दर्शक
यह दस्तावेज़ उन सभी लोगों के लिए है जिन्हें Google डेटा प्रोटोकॉल को लागू करने वाले एपीआई के इस्तेमाल किए जाने वाले एक्सएमएल फ़ॉर्मैट और प्रोटोकॉल के बारे में ज़्यादा जानकारी चाहिए.
अगर आपको सिर्फ़ ऐसे कोड लिखने हैं जो इनमें से किसी एक एपीआई का इस्तेमाल करते हैं, तो आपको इस जानकारी की ज़रूरत नहीं है. इसके बजाय, भाषा के हिसाब से क्लाइंट लाइब्रेरी का इस्तेमाल किया जा सकता है.
हालांकि, अगर आपको प्रोटोकॉल को समझना है, तो यह दस्तावेज़ पढ़ें. उदाहरण के लिए, हो सकता है कि आप यह दस्तावेज़ पढ़ना चाहें, ताकि आप नीचे दिए गए किसी भी काम में मदद पा सकें:
- Google डेटा प्रोटोकॉल आर्किटेक्चर का आकलन करना
- दी गई क्लाइंट लाइब्रेरी का इस्तेमाल किए बिना, प्रोटोकॉल का इस्तेमाल करके कोडिंग करना
- नई भाषा में क्लाइंट लाइब्रेरी लिखना
इस दस्तावेज़ में यह माना गया है कि आप एक्सएमएल, नेमस्पेस, सिंडिकेट किए गए फ़ीड, और एचटीटीपी में मौजूद GET
, POST
, PUT
, और DELETE
अनुरोधों के साथ-साथ एचटीटीपी के "रिसॉर्स" का सिद्धांत समझते हैं. उन चीज़ों के बारे में ज़्यादा जानकारी के लिए, इस दस्तावेज़ का अतिरिक्त संसाधन सेक्शन देखें.
यह दस्तावेज़ किसी खास प्रोग्रामिंग भाषा पर निर्भर नहीं है. आप ऐसी किसी भी प्रोग्रामिंग भाषा का इस्तेमाल करके Google डेटा प्रोटोकॉल मैसेज भेज और पा सकते हैं, जो आपको एचटीटीपी अनुरोध जारी करने और एक्सएमएल-आधारित जवाबों को पार्स करने देती है.
प्रोटोकॉल की जानकारी
इस सेक्शन में, Google डेटा प्रोटोकॉल दस्तावेज़ के फ़ॉर्मैट और क्वेरी सिंटैक्स की जानकारी दी गई है.
दस्तावेज़ का फ़ॉर्मैट
Google डेटा प्रोटोकॉल और ऐटम एक ही बुनियादी डेटा मॉडल को शेयर करते हैं: ऐसा कंटेनर जिसमें कुछ ग्लोबल डेटा और बहुत सारी एंट्री होती हैं. हर प्रोटोकॉल के लिए, फ़ॉर्मैट को किसी बेस स्कीमा से तय किया जाता है. हालांकि, इसे विदेशी नेमस्पेस का इस्तेमाल करके बढ़ाया जा सकता है.
ऐटम, Google डेटा प्रोटोकॉल का डिफ़ॉल्ट फ़ॉर्मैट है. किसी दूसरे फ़ॉर्मैट में जवाब का अनुरोध करने के लिए, alt
क्वेरी पैरामीटर का इस्तेमाल करें. ज़्यादा जानकारी के लिए, क्वेरी के अनुरोध देखें.
ध्यान दें: ऐटम फ़ॉर्मैट में, ज़्यादातर Google डेटा प्रोटोकॉल फ़ीड, फ़ीड एलिमेंट पर xmlns
एट्रिब्यूट तय करके, ऐटम नेमस्पेस को डिफ़ॉल्ट नेमस्पेस के तौर पर इस्तेमाल करते हैं. इसके बारे में, प्रोटोकॉल की बुनियादी बातों में बताया गया है. इसलिए, इस दस्तावेज़ में दिए गए उदाहरणों में, ऐटम-फ़ॉर्मैट फ़ीड में मौजूद एलिमेंट के लिए साफ़ तौर पर atom:
नहीं बताया गया है.
नीचे दी गई टेबल, स्कीमा के ऐटम को दिखाने का तरीका दिखाती हैं. जिन टेबल में इस डेटा का ज़िक्र नहीं है उन्हें एक्सएमएल की फ़ाइल माना जाता है. जब तक कोई और न बताया जाए, तब तक दिए गए कॉलम के एक्सएमएल एलिमेंट, ऐटम नेमस्पेस में होते हैं.
ध्यान दें: इस खास जानकारी में स्टैंडर्ड XPath नोटेशन का इस्तेमाल होता है. खास तौर पर, स्लैश एलिमेंट के क्रम को दिखाता है और @ चिह्न किसी एलिमेंट के एट्रिब्यूट को दिखाता है.
नीचे दी गई हर टेबल में, हाइलाइट किए गए आइटम डालने ज़रूरी हैं.
नीचे दी गई टेबल में, Google डेटा प्रोटोकॉल फ़ीड के एलिमेंट दिखते हैं:
फ़ीड स्कीमा आइटम | एटम रिप्रज़ेंटेशन |
---|---|
फ़ीड का शीर्षक | /feed/title |
फ़ीड ID | /feed/id |
फ़ीड HTML लिंक | /feed/link[@rel="alternate"] \[@type="text/html"]/@href |
फ़ीड का ब्यौरा | /feed/subtitle |
फ़ीड के लिए भाषा | /feed/@xml:lang |
फ़ीड कॉपीराइट | /feed/rights |
फ़ीड लेखक |
(कुछ मामलों में ज़रूरी; ऐटम की खास जानकारी देखें.) |
फ़ीड के आखिरी बार अपडेट होने की तारीख | /feed/updated (आरएफ़सी 3339 फ़ॉर्मैट) |
फ़ीड की श्रेणी | /feed/category/@term |
फ़ीड श्रेणी स्कीम | /feed/category/@scheme |
फ़ीड जनरेटर | /feed/generator /feed/generator/@uri |
फ़ीड का आइकॉन | /feed/icon |
फ़ीड का लोगो | /feed/logo |
नीचे दी गई टेबल में, Google डेटा प्रोटोकॉल के खोज नतीजों के फ़ीड के एलिमेंट दिखाए गए हैं. ध्यान दें कि प्रोटोकॉल, Search के नतीजों के फ़ीड में OpenSearch 1.1 रिस्पॉन्स एलिमेंट के कुछ हिस्से को दिखाता है.
खोज के नतीजों के फ़ीड का स्कीमा आइटम | एटम रिप्रज़ेंटेशन |
---|---|
खोज के नतीजों की संख्या | /feed/openSearch:totalResults |
खोज के नतीजों के शुरू होने का इंडेक्स | /feed/openSearch:startIndex |
प्रति पेज खोज परिणामों की संख्या | /feed/openSearch:itemsPerPage |
नीचे दी गई टेबल में, Google डेटा प्रोटोकॉल एंट्री के एलिमेंट दिखाए गए हैं:
एंट्री आइटम के लिए स्कीमा | एटम रिप्रज़ेंटेशन |
---|---|
एंट्री आईडी | /feed/entry/id |
एंट्री टाइटल | /feed/entry/title |
एंट्री लिंक | /feed/entry/link |
एंट्री की खास जानकारी |
(कुछ मामलों में ज़रूरी; ऐटम की खास जानकारी देखें.) |
एंट्री कॉन्टेंट |
(अगर कोई कॉन्टेंट एलिमेंट नहीं है, तो एंट्री में कम से कम एक |
एंट्री ऑथर |
(कुछ मामलों में ज़रूरी; ऐटम की खास जानकारी देखें.) |
एंट्री कैटगरी | /feed/entry/category/@term |
एंट्री कैटगरी स्कीम | /feed/entry/category/@scheme |
एंट्री पब्लिकेशन की तारीख | /feed/entry/published (आरएफ़सी 3339) |
एंट्री अपडेट होने की तारीख | /feed/entry/updated (आरएफ़सी 3339) |
क्वेरी
इस सेक्शन में, क्वेरी सिस्टम को इस्तेमाल करने का तरीका बताया गया है.
क्वेरी मॉडल डिज़ाइन टेनेट
क्वेरी मॉडल को समझना बहुत आसान है. बुनियादी सिद्धांत हैं:
- क्वेरी को एचटीटीपी हेडर या पेलोड के हिस्से के तौर पर दिखाने के बजाय एचटीटीपी यूआरआई के तौर पर दिखाया जाता है. इस तरीके का एक फ़ायदा यह है कि आप किसी क्वेरी से लिंक कर सकते हैं.
- प्रेडिकेट का दायरा सिर्फ़ एक आइटम होता है. इस तरह, आपसी संबंध की क्वेरी भेजने का कोई तरीका नहीं है, जैसे कि "आज मुझे कम से कम 10 ईमेल भेजने वाले लोगों के सभी ईमेल ढूंढें."
- जिन प्रॉपर्टी पर क्वेरी के नतीजे दिखाए जा सकते हैं उनका सेट बहुत सीमित है. ज़्यादातर क्वेरी, टेक्स्ट सर्च में आसानी से दिखती हैं.
- नतीजे क्रम में लगाए जाते हैं.
- प्रोटोकॉल सामान्य तौर पर एक्सटेंसिबल होता है. अगर आपको अपनी सेवा में, अतिरिक्त नियमों या नियमों को बिना अनुमति के सार्वजनिक करना है, तो नए पैरामीटर की मदद से ऐसा आसानी से किया जा सकता है.
क्वेरी के अनुरोध
कोई क्लाइंट, एचटीटीपी सेवा GET
का अनुरोध जारी करके, Google की किसी सेवा के बारे में क्वेरी करता है. क्वेरी यूआरआई में संसाधन का यूआरआई (ऐटम में FeedURI कहा जाता है) और उसके बाद क्वेरी पैरामीटर शामिल होते हैं. ज़्यादातर क्वेरी पैरामीटर, परंपरागत ?name=value[&...]
यूआरएल पैरामीटर के तौर पर दिखाए जाते हैं. कैटगरी पैरामीटर अलग-अलग तरीके से मैनेज किए जाते हैं. इन्हें नीचे देखें.
उदाहरण के लिए, अगर FeedURI http://www.example.com/feeds/jo
है, तो आप नीचे दिए गए यूआरआई के साथ क्वेरी भेज सकते हैं:
http://www.example.com/feeds/jo?q=Darcy&updated-min=2005-04-19T15:30:00Z
Google डेटा प्रोटोकॉल एचटीटीपी कंडीशनल GET
के साथ काम करता है. प्रोटोकॉल को लागू करने वाले एपीआई, दिए गए फ़ीड या एंट्री में <atom:updated>
एलिमेंट की वैल्यू के आधार पर, जवाब देने के लिए बदले गए हेडर को सेट करते हैं. अगर कॉन्टेंट बदला नहीं गया है, तो कॉन्टेंट को वापस लाने से रोकने के लिए, क्लाइंट इस वैल्यू को If-Modified-Since अनुरोध हेडर की वैल्यू के तौर पर वापस भेज सकता है. अगर कॉन्टेंट को If-Modified-Since समय से नहीं बदला गया है, तो सेवा 304 (बदलाव नहीं किया गया) एचटीटीपी रिस्पॉन्स दिखाती है.
Google Data प्रोटोकॉल को लागू करने वाले एपीआई को alt
क्वेरी के साथ काम करना चाहिए; दूसरे पैरामीटर के साथ काम करना ज़रूरी नहीं है. किसी स्टैंडर्ड पैरामीटर को पास करने से, दी गई सेवा से मिला रिस्पॉन्स 403 Forbidden
रिस्पॉन्स में नहीं मिलता. काम न करने वाले स्टैंडर्ड पैरामीटर को पास करने से 400 Bad Request
रिस्पॉन्स मिलता है. दूसरे स्टेटस कोड के बारे में जानकारी पाने के लिए, इस दस्तावेज़ का एचटीटीपी स्टेटस कोड सेक्शन देखें.
नीचे दिए गए टेबल में, स्टैंडर्ड क्वेरी पैरामीटर की खास जानकारी दी गई है. सभी पैरामीटर वैल्यू, यूआरएल के लिए कोड में बदली गई होनी चाहिए.
पैरामीटर | मतलब | नोट |
---|---|---|
alt |
वैकल्पिक प्रतिनिधित्व प्रकार |
|
author |
एंट्री लेखक |
|
category |
श्रेणी क्वेरी फ़िल्टर |
|
/-/category |
श्रेणी क्वेरी फ़िल्टर |
|
enterID | वापस मिलने वाली किसी खास एंट्री का आईडी |
|
fields |
रिस्पॉन्स फ़िल्टर |
|
max-results |
वापस लाए जाने वाले नतीजों की ज़्यादा से ज़्यादा संख्या | अगर किसी फ़ीड में डिफ़ॉल्ट फ़ीड max-results (डिफ़ॉल्ट फ़ीड साइज़ को सीमित करना) है, तो उसके लिए बहुत बड़ी संख्या में फ़ीड उपलब्ध कराया जा सकता है. |
prettyprint |
पहचान और लाइन ब्रेक वाला एक्सएमएल रिस्पॉन्स दिखाता है |
|
published-min , published-max |
एंट्री प्रकाशन की तारीख पर सीमाएं |
|
q |
पूरे टेक्स्ट वाली क्वेरी स्ट्रिंग |
|
start-index |
पहले नतीजे का 1-आधारित इंडेक्स वापस लाया जा सकता है |
|
strict |
सख्त क्वेरी पैरामीटर की जांच करना |
|
updated-min , updated-max |
एंट्री अपडेट करने की तारीख पर सीमाएं |
|
कैटगरी से जुड़ी क्वेरी के बारे में जानकारी
हमने कैटगरी की क्वेरी के लिए, थोड़ा अलग फ़ॉर्मैट देने का फ़ैसला किया है. इस तरह की क्वेरी की ज़रूरत नहीं है:
http://example.com/jo?category=Fritz&category=2006
हमने इसका उपयोग संभव बनाया:
http://example.com/jo/-/Fritz/2006
यह तरीका, क्वेरी पैरामीटर का इस्तेमाल किए बिना संसाधन की पहचान करता है. साथ ही, यह क्लीनर यूआरआई बनाता है. हमने कैटगरी के लिए यह तरीका चुना, क्योंकि हमें लगता है कि कैटगरी की क्वेरी सबसे सामान्य क्वेरी में से एक होगी.
इस उपाय का नकारात्मक पहलू यह है कि हम चाहते हैं कि आप इस प्रकार की श्रेणी क्वेरी में /-/
का उपयोग करें, ताकि सेवाएं अन्य संसाधन यूआरआई और http://example.com/jo/MyPost/comments
जैसी श्रेणी क्वेरी में अंतर कर सकें.
क्वेरी के जवाब
क्वेरी में अनुरोध पैरामीटर के आधार पर, ऐटम फ़ीड, ऐटम एंट्री या आरएसएस फ़ीड होता है.
क्वेरी के नतीजों में सीधे तौर पर <feed>
एलिमेंट या <channel>
एलिमेंट के नीचे, OpenSearch के ये एलिमेंट शामिल होते हैं (यह इस बात पर निर्भर करता है कि नतीजे ऐटम या आरएसएस वाले हैं या नहीं):
openSearch:totalResults
- क्वेरी के लिए खोज के नतीजों की कुल संख्या (ज़रूरी नहीं है कि सभी नतीजों के फ़ीड में मौजूद हों).
openSearch:startIndex
- पहले नतीजे का 1-आधारित इंडेक्स.
openSearch:itemsPerPage
- एक पेज पर दिखने वाले आइटम की ज़्यादा से ज़्यादा संख्या. इससे क्लाइंट बाद के पेजों के किसी भी सेट के लिए डायरेक्ट लिंक जनरेट कर सकता है. हालांकि, इस नंबर का इस्तेमाल करने में कोई गड़बड़ी होने पर, क्वेरी का अनुरोध सेक्शन में मौजूद टेबल में,
start-index
से जुड़ा नोट देखें.
ऐटम रिस्पॉन्स फ़ीड और एंट्री में, ऐटम और Data API के साथ-साथ ऐटम की खास जानकारी में शामिल कोई भी एलिमेंट शामिल हो सकता है:
<link rel="http://schemas.google.com/g/2005#feed" type="application/atom+xml" href="..."/>
- उस यूआरआई को बताता है जहां पूरा ऐटम फ़ीड वापस पाया जा सकता है.
<link rel="http://schemas.google.com/g/2005#post" type="application/atom+xml" href="..."/>
- ऐटम फ़ीड की PostURI के बारे में बताता है (जहां नई एंट्री पोस्ट की जा सकती हैं).
<link rel="self" type="..." href="..."/>
- इस संसाधन का यूआरआई है.
type
एट्रिब्यूट की वैल्यू, अनुरोध किए गए फ़ॉर्मैट के हिसाब से तय होती है. अगर इस बीच कोई डेटा नहीं बदलता है, तो इस यूआरआई पर एक और जीईटी भेजने पर भी यही जवाब मिलेगा. <link rel="previous" type="application/atom+xml" href="..."/>
- इस क्वेरी के नतीजे के सेट के पिछले हिस्से का यूआरआई बताता है, अगर उसे अलग किया जाता है.
<link rel="next" type="application/atom+xml" href="..."/>
- इस क्वेरी के नतीजे के सेट के अगले हिस्से का यूआरआई बताता है, अगर इसे अलग किया गया हो.
<link rel="edit" type="application/atom+xml" href="..."/>
- ऐटम एंट्री के EditURI के बारे में बताता है (जहां आप अपडेट की गई एंट्री भेजते हैं).
यहां खोज क्वेरी के जवाब में एक नमूना जवाब दिया गया है:
<?xml version="1.0" encoding="UTF-8"?> <feed xmlns="http://www.w3.org/2005/Atom" xmlns:openSearch="http://a9.com/-/spec/opensearch/1.1/" xmlns:gd='http://schemas.google.com/g/2005' gd:etag='W/"C0QBRXcycSp7ImA9WxRVFUk."'> <id>http://www.example.com/feed/1234.1/posts/full</id> <updated>2005-09-16T00:42:06Z</updated> <title type="text">Books and Romance with Jo and Liz</title> <link rel="alternate" type="text/html" href="http://www.example.net/"/> <link rel="http://schemas.google.com/g/2005#feed" type="application/atom+xml" href="http://www.example.com/feed/1234.1/posts/full"/> <link rel="http://schemas.google.com/g/2005#post" type="application/atom+xml" href="http://www.example.com/feed/1234.1/posts/full"/> <link rel="self" type="application/atom+xml" href="http://www.example.com/feed/1234.1/posts/full"/> <author> <name>Elizabeth Bennet</name> <email>liz@gmail.com</email> </author> <generator version="1.0" uri="http://www.example.com">Example Generator Engine</generator> <openSearch:totalResults>2</openSearch:totalResults> <openSearch:startIndex>0</openSearch:startIndex> <entry gd:etag='W/"C0QBRXcycSp7ImA9WxRVGUo."'> <id>http://www.example.com/feed/1234.1/posts/full/4521614025009481151</id> <published>2005-01-09T08:00:00Z</published> <updated>2005-01-09T08:00:00Z</updated> <category scheme="http://www.example.com/type" term="blog.post"/> <title type="text">This is the title of entry 1009</title> <content type="xhtml"> <div xmlns="http://www.w3.org/1999/xhtml">This is the entry body of entry 1009</div> </content> <link rel="alternate" type="text/html" href="http://www.example.com/posturl"/> <link rel="edit" type="application/atom+xml" href="http://www.example.com/feed/1234.1/posts/full/4521614025009481151"/> <author> <name>Elizabeth Bennet</name> <email>liz@gmail.com</email> </author> </entry> <entry gd:etag='W/"C0QBRXrurSp7ImA9WxRVGUo."'> <id>http://www.example.com/feed/1234.1/posts/full/3067545004648931569</id> <published>2005-01-07T08:00:00Z</published> <updated>2005-01-07T08:02:00Z</updated> <category scheme="http://www.example.com/type" term="blog.post"/> <title type="text">This is the title of entry 1007</title> <content type="xhtml"> <div xmlns="http://www.w3.org/1999/xhtml">This is the entry body of entry 1007</div> </content> <link rel="alternate" type="text/html" href="http://www.example.com/posturl"/> <link rel="edit" type="application/atom+xml" href="http://www.example.com/feed/1234.1/posts/full/3067545004648931569"/> <author> <name>Elizabeth Bennet</name> <email>liz@gmail.com</email> </author> </entry> </feed>
अगर अनुरोध किया गया फ़ीड ऐटम फ़ॉर्मैट में है, तो क्वेरी का कोई पैरामीटर नहीं दिया गया है और नतीजे में सभी एंट्री मौजूद नहीं हैं, तो टॉप-लेवल फ़ीड में यह एलिमेंट शामिल किया जाता है: <link rel="next" type="application/atom+xml" href="..."/>
. यह उस फ़ीड की ओर इशारा करता है जिसमें एंट्री का अगला सेट होता है. बाद के सेट में एक <link rel="previous" type="application/atom+xml" href="..."/>
एलिमेंट शामिल होता है. सभी आगे बढ़ें लिंक पर क्लिक करने से, क्लाइंट को फ़ीड से सभी एंट्री मिल सकती हैं.
एचटीटीपी स्टेटस कोड
नीचे दी गई टेबल में बताया गया है कि डेटा एपीआई के हिसाब से, एचटीटीपी स्टेटस कोड का क्या मतलब है.
कोड | इसका मतलब है |
---|---|
200 ठीक | कोई गड़बड़ी नहीं. |
201 बनाया गया | संसाधन बनाया गया. |
304 संशोधित नहीं | रिसॉर्स, अनुरोध के If-Modified-Since हेडर में बताए गए समय के बाद से नहीं बदला है. |
400 खराब अनुरोध | अमान्य अनुरोध यूआरआई या शीर्षलेख, या असमर्थित गैर-मानक पैरामीटर. |
401 अनधिकृत | स्वीकृति चाहिए। |
403 अनुमति नहीं है | असमर्थित मानक पैरामीटर, प्रमाणीकरण या प्रमाणीकरण विफल. |
404 नहीं मिला | संसाधन (जैसे कि फ़ीड या एंट्री) नहीं मिला. |
409 टकराव | दिया गया वर्शन नंबर, संसाधन के नए वर्शन नंबर से मेल नहीं खाता. |
410 गया | अनुरोध किए गए बदलाव का इतिहास अब सर्वर पर उपलब्ध नहीं है. ज़्यादा जानकारी के लिए, सेवा से जुड़ा दस्तावेज़ देखें. |
500 सर्वर में गड़बड़ी | कोई अंदरूनी गड़बड़ी हुई. यह डिफ़ॉल्ट कोड है, जिसका उपयोग सर्वर की सभी अज्ञात गड़बड़ियों के लिए किया जाता है. |
रिसॉर्स वर्शनिंग (Eटैग)
कभी-कभी आपको किसी खास एंट्री के खास वर्शन का हवाला देने की ज़रूरत पड़ सकती है.
यह दो मामलों में अहम है:
- "शर्त के मुताबिक डेटा वापस पाना" करना, जिसमें आपका क्लाइंट एंट्री का अनुरोध करता है और सर्वर, एंट्री को सिर्फ़ तब भेजता है, जब क्लाइंट ने पिछली बार इसका अनुरोध किया था.
- यह पक्का करना कि कई क्लाइंट अनजाने में एक-दूसरे के बदलावों को ओवरराइट न कर दें. ऐसा तब होता है, जब डेटा क्लाइंट एंट्री के लिए किसी पुराने वर्शन आइडेंटिफ़ायर के बारे में बताता है. ऐसा इसलिए किया जाता है, ताकि डेटा एपीआई अपडेट और डेटा मिटाने की प्रोसेस को पूरा न कर सके.
ये दोनों मामले, 'Google डेटा एपीआई' मैनेज करते हैं. इसके लिए, ये ETag का इस्तेमाल करते हैं, जो एचटीटीपी का स्टैंडर्ड हिस्सा है.
ETag एक आइडेंटिफ़ायर है. यह किसी एंट्री के खास वर्शन के बारे में बताता है. सर्वर, दर्शकों को भेजे जाने वाले एंट्री और फ़ीड एलिमेंट में एक ईटैग जोड़ता है. जब कोई एंट्री या फ़ीड बदलता है, तो उसका ईटैग भी बदल जाता है.
Google Data API, दो जगहों पर ETag उपलब्ध कराते हैं: ETag
एचटीटीपी हेडर में और <feed>
और <entry>
एलिमेंट के gd:etag
एट्रिब्यूट में.
Google डेटा एपीआई में, ईटैग आम तौर पर अक्षरों और संख्याओं की एक स्ट्रिंग होती है. इसमें कभी-कभी हाइफ़न और पीरियड भी शामिल होते हैं. आम तौर पर, स्ट्रिंग कोटेशन मार्क के अंदर होती है. (कोटेशन, ETag का हिस्सा हैं.) उदाहरण के लिए, यहां डेटा एपीआई एंट्री से मिला ETag दिया गया है: "S0wCTlpIIip7ImA0X0QI"
.
ईटैग दो तरह के होते हैं: मज़बूत और कमज़ोर. स्ट्रॉन्ग ई-टैग किसी खास एंट्री के खास वर्शन की पहचान करते हैं. साथ ही, इनका इस्तेमाल दूसरे क्लाइंट के बदलावों को ओवरराइट करने से बचने के लिए किया जा सकता है. Google Data API के हिसाब से, कमज़ोर ETag का इस्तेमाल सिर्फ़ शर्तों के आधार पर डेटा वापस पाने के लिए किया जाता है. कमज़ोर ETag हमेशा W/
से शुरू होता है. उदाहरण के लिए: W/"D08FQn8-eil7ImA9WxZbFEw."
ज़रूरी नहीं कि सभी Google Data API मज़बूत ETag का इस्तेमाल करें. जो ऐसा करते हैं, उनके लिए मज़बूत ई-टैग का इस्तेमाल सिर्फ़ एंट्री के लिए किया जाता है; फ़ीड के ई-टैग हमेशा कमज़ोर होते हैं.
यहां बेहतर ETag की सुविधा देने वाली सेवा से मिले फ़ीड (कुछ एचटीटीपी हेडर सहित) का उदाहरण दिया गया है:
GData-Version: 2.0 ETag: W/"C0QBRXcycSp7ImA9WxRVFUk." ... <?xml version='1.0' encoding='utf-8'?> <feed xmlns='http://www.w3.org/2005/Atom' xmlns:gd='http://schemas.google.com/g/2005' gd:etag='W/"C0QBRXcycSp7ImA9WxRVFUk."'> ... <entry gd:etag='"CUUEQX47eCp7ImA9WxRVEkQ."'> ... </entry> </feed>
Data API के वर्शन 2 के साथ काम करने वाली क्लाइंट लाइब्रेरी, साफ़ तौर पर आपके लिए ETag मैनेज करती हैं. नीचे दी गई जानकारी उन क्लाइंट के लिए है जो क्लाइंट लाइब्रेरी का इस्तेमाल नहीं करते. साथ ही, उन पाठकों के लिए भी है जो प्रोटोकॉल लेवल पर वर्शनिंग को मैनेज करने में दिलचस्पी रखते हैं.
ध्यान दें: डेटा एपीआई के वर्शन 1.0 में इस्तेमाल किए गए रिसॉर्स-वर्शन सिस्टम के बारे में जानकारी पाने के लिए, 1.0 रेफ़रंस गाइड देखें.
शर्तों के साथ डेटा वापस पाना
अगर आपको कोई ऐसी एंट्री दिख रही है जिसे आपने पहले वापस ले लिया था, तो सर्वर को यह जानकारी देने के लिए कि आपने पिछली बार जब से लॉग इन किया था तब से एंट्री को बदलने का मतलब है कि परफ़ॉर्मेंस को बेहतर बनाया जा सकता है.
इस तरह की शर्तों को फिर से हासिल करने के लिए, एचटीटीपी GET
अनुरोध भेजें जिसमें एचटीटीपी If-None-Match
हेडर शामिल हो. हेडर में, एंट्री का ETag बताएं.
यहां If-None-Match
हेडर का एक उदाहरण दिया गया है:
If-None-Match: W/"D08FQn8-eil7ImA9WxZbFEw."
जब सर्वर को यह अनुरोध मिलता है, तो यह पता लगाता है कि आपने जिस एंट्री का अनुरोध किया है उसमें और आपका तय किया गया ETag एक जैसा है या नहीं. अगर ई-टैग का मिलान होता है, तो एंट्री नहीं बदली है और सर्वर एचटीटीपी 304 Not Modified
स्थिति कोड दिखाता है.
अगर ई-टैग मेल नहीं खाता है, तो पिछली बार अनुरोध करने के बाद से एंट्री में बदलाव हो गया है और सर्वर एंट्री वापस कर देता है.
एंट्री अपडेट की जा रही हैं
किसी अन्य क्लाइंट के बदलावों को ओवरराइट करने से बचने का सबसे आसान तरीका सर्वर के लिए है, ताकि यह पक्का किया जा सके कि जब आपका क्लाइंट कोई अपडेट की गई एंट्री भेजे, तो क्लाइंट के लिए शुरू की गई एंट्री का वर्शन, सर्वर से स्टोर किए गए मौजूदा वर्शन के जैसा ही हो. अगर कोई दूसरा क्लाइंट आपके क्लाइंट के ऐप्लिकेशन में किए गए अपडेट से पहले अपडेट करता है, तो आपके क्लाइंट का अपडेट अस्वीकार कर दिया जाएगा. इसकी वजह यह है कि आपका क्लाइंट अब नए वर्शन पर बदलाव करने का अनुरोध नहीं कर रहा है.
जब आपका क्लाइंट बेहतर ETag का समर्थन करने वाली किसी सेवा से डेटा वापस लाता है, तो हर एंट्री में एक ETag होता है जो उस एंट्री के उस वर्शन के खास वर्शन पहचानकर्ता के रूप में काम करता है.
ध्यान दें: ई-टैग इस्तेमाल करके अपडेट करने की सुविधा सिर्फ़ अच्छे ई-टैग के साथ काम करती है. कमज़ोर ई-टैग डालने वाली सेवाओं के लिए सभी अपडेट काम करते हैं. भले ही, आपने वह एंट्री जब से दोबारा शुरू की हो, किसी दूसरे व्यक्ति ने उसे अपडेट कर दिया हो. सबसे नया अपडेट, पहले के किसी भी दूसरे अपडेट को बदल देता है. इसलिए, अपडेट करते या मिटाते समय कमज़ोर ई-टैग न भेजें. ऐसा करने पर आपको एक गड़बड़ी का मैसेज मिलेगा.
इसलिए, जब आपका क्लाइंट किसी मज़बूत ई-टैग सेवा को अपडेट भेजता है, तो उसे यह बताना होता है कि वह एंट्री का कौनसा वर्शन अपडेट कर रहा है. ऐसा करने के दो तरीके हैं:
If-Match
एचटीटीपी हेडर का इस्तेमाल करना.<atom:entry>
एलिमेंट मेंgd:etag
एट्रिब्यूट का इस्तेमाल करें.
हमारा सुझाव है कि जहां तक हो सके, If-Match
तरीका अपनाएं.
If-Match
का इस्तेमाल करके किसी एंट्री को अपडेट करने के लिए, वह एंट्री हासिल करें जिससे अपडेट किया जा रहा है. एंट्री में अपनी पसंद के मुताबिक कोई भी बदलाव करें. इसके बाद, उस नए अनुरोध के साथ एक नया PUT
अनुरोध बनाएं जिसमें बदलाव किया गया हो. (इस्तेमाल किए जाने वाले यूआरएल के ब्यौरे के लिए, सेवा से जुड़े खास दस्तावेज़ देखें.)
PUT
भेजने से पहले, मूल एंट्री से ETag वाला एक HTTP If-Match
हेडर जोड़ें:
If-Match: "S0wCTlpIIip7ImA0X0QI"
इसके बाद, PUT
का अनुरोध भेजें.
अपडेट पूरा होने पर, सर्वर 200 OK
स्टेटस कोड और अपडेट की गई एंट्री की एक कॉपी दिखाता है.
अगर अपडेट इसलिए विफल होता है क्योंकि आपके ज़रिए बताया गया ETag, एंट्री के मौजूदा ETag से मेल नहीं खाता है (जिसका मतलब है कि पिछली बार ऐक्सेस करने के बाद से सर्वर पर एंट्री बदल गई है), तो सर्वर एक एचटीटीपी 412 Precondition Failed
स्थिति कोड दिखाता है.
अगर आपको एचटीटीपी हेडर को आसानी से लिखने में समस्या आ रही है या आपके पास If-Match
हेडर से बचने की कोई और वजह है, तो gd:etag
एट्रिब्यूट का इस्तेमाल करें.
अगर आपने If-Match
हेडर नहीं भेजा है, तो सर्वर अपडेट की गई एंट्री के gd:etag
एट्रिब्यूट की वैल्यू को, If-Match
वैल्यू के तौर पर इस्तेमाल करता है.
वर्शनिंग सिस्टम को बदलने और एंट्री को अपडेट करने के लिए, इस बात पर ध्यान दिए बिना कि क्या आपके अपडेट करने के बाद किसी दूसरे व्यक्ति ने उसे अपडेट किया है, हेडर में ETag डालने के बजाय If-Match: *
का इस्तेमाल करें.
मज़बूत ETag के साथ काम करने वाली सेवाओं के बारे में जानकारी के लिए, डेटा को दूसरी जगह भेजने से जुड़ी गाइड देखें.
एंट्री मिटाई जा रही हैं
मज़बूत ई-टैग इस्तेमाल करने वाली एंट्री मिटा देने जैसा ही है.
एक मज़बूत ETag वाली प्रविष्टि को हटाने के लिए, पहले वह प्रविष्टि फिर से पाएं जिसे आप हटाना चाहते हैं, फिर आप उस प्रविष्टि के संपादन URL को DELETE
अनुरोध भेजते हैं.
अगर आप यह पक्का करना चाहते हैं कि आप किसी ऐसी एंट्री को न मिटाएं जिसे किसी दूसरे क्लाइंट ने हासिल कर लिया हो, तो उसमें एचटीटीपी If-Match
हेडर शामिल करें जिसमें मूल एंट्री का ईटैग मान शामिल हो.
अगर आप वर्शनिंग सिस्टम को बदलना चाहते हैं और इस एंट्री को मिटाना चाहते हैं, तो इस पर ध्यान दिए बिना कि हेडर को फिर से पाने के बाद किसी और ने उसे अपडेट किया है या नहीं, If-Match: *
का इस्तेमाल करें.
अगर किसी एंट्री में बेहतर ईटैग नहीं है, तो DELETE
अनुरोध हमेशा सफल होता है.
आंशिक जवाब (प्रयोग के तौर पर)
डिफ़ॉल्ट रूप से, सर्वर अनुरोधों को प्रोसेस करने के बाद, टारगेट रिसॉर्स को पूरी तरह से दिखाता है. आंशिक जवाब की मदद से, पूरे रिसॉर्स के बजाय सिर्फ़ एलिमेंट या पसंद के एट्रिब्यूट का अनुरोध किया जा सकता है. यह आपके क्लाइंट ऐप्लिकेशन को बिना काम वाले फ़ील्ड ट्रांसफ़र करने, पार्स करने, और सेव करने से बचाता है, ताकि वह नेटवर्क, सीपीयू, और मेमोरी संसाधनों का बेहतर तरीके से इस्तेमाल कर सके.
यह जानने के लिए कि इस्तेमाल किए जा रहे प्रॉडक्ट के लिए कुछ जवाब उपलब्ध है या नहीं, उसका एपीआई दस्तावेज़ देखें.
कुछ हिस्से का अनुरोध करने के लिए, fields
क्वेरी पैरामीटर का इस्तेमाल करके, बताएं कि आपको किन एलिमेंट या एट्रिब्यूट को लौटाना है. यहां उदाहरण देखें:
http://www.example.com/feeds?fields=link,entry(@gd:etag,id,updated,link[@rel='edit']))
सर्वर के रिस्पॉन्स में, फ़ीड के सिर्फ़ लिंक और एंट्री एलिमेंट शामिल होते हैं; एंट्री एलिमेंट में सिर्फ़ ETag, आईडी, अपडेट, और लिंक की जानकारी में बदलाव करें. fields
क्वेरी पैरामीटर सिंटैक्स की जानकारी यहां दिए गए सेक्शन में दी गई है. जवाब के बारे में ज़्यादा जानकारी पाने के लिए, आंशिक जवाबों को मैनेज करना देखें.
ध्यान दें: fields
क्वेरी पैरामीटर का इस्तेमाल ऐसे किसी भी अनुरोध के साथ किया जा सकता है जिससे डेटा मिलता हो. GET
के अलावा, इसमें POST
और PUT
के साथ-साथ PATCH
भी शामिल है. इसका इस्तेमाल आंशिक अपडेट करने के लिए किया जाता है. हालांकि, fields
क्वेरी पैरामीटर सिर्फ़ रिस्पॉन्स डेटा पर असर डालता है. इससे, उस डेटा पर कोई असर नहीं पड़ता जो आपको उपलब्ध कराना है या कौनसा फ़ील्ड अपडेट करना है या बनाया जाना है.
फ़ील्ड पैरामीटर सिंटैक्स की खास जानकारी
fields
क्वेरी पैरामीटर की वैल्यू का फ़ॉर्मैट XPath सिंटैक्स पर आधारित होता है; हालांकि, यह मान्य XPath एक्सप्रेशन के सिर्फ़ सबसेट के साथ काम करता है. इसके साथ काम करने वाले सिंटैक्स की खास जानकारी नीचे दी गई है. साथ ही, नीचे दिए गए सेक्शन में कुछ और उदाहरण दिए गए हैं.
- कई फ़ील्ड चुनने के लिए, कॉमा लगाकर अलग की गई सूची का इस्तेमाल करें.
- एलिमेंट
a
में नेस्ट किए गए एलिमेंटb
को चुनने के लिए,a/b
का इस्तेमाल करें;b
में नेस्ट किए गए एलिमेंट को चुनने के लिए,a/b/c
का इस्तेमाल करें. - दिए गए नाम वाले एट्रिब्यूट की पहचान करने के लिए,
'@'
प्रीफ़िक्स का इस्तेमाल करें. किसी एलिमेंट के बारे में बताने के लिए,'@'
प्रीफ़िक्स को हटाएं. - कुछ शर्तों से मेल खाने वाले एलिमेंट को चुनने के लिए, फ़ील्ड शर्तों को लागू करें. इसके लिए, जिस एलिमेंट को सीमित करना है उसके बाद, "
[ ]
" को ब्रैकेट में रखें.उदाहरण के लिए,
fields=entry[author/name='Elizabeth']
सिर्फ़ फ़ीड की एंट्री दिखाता है जिनके लिए एलिज़ाबेथ लेखक हैं. - किसी खास एलिमेंट के बाद, "
( )
" को ब्रैकेट में रखकर, सिर्फ़ खास एट्रिब्यूट या सब-एलिमेंट का अनुरोध करने के लिए, फ़ील्ड के सब- सिलेक्टर को बताएं.उदाहरण के लिए,
fields=entry(id,author/email)
हर फ़ीड एंट्री के लिए सिर्फ़ आईडी और लेखक का ईमेल दिखाता है. - डबल या सिंगल कोट का इस्तेमाल करके, स्ट्रिंग की संख्या सीमित की जा सकती है
.
डबल या सिंगल कोट से बचने के लिए, कोटेशन को दोहराएं. उदाहरण के लिए,
"""Hello,"" he said"
"Hello," he said
स्ट्रिंग बनाता है और'''Hello,'' he said'
,'Hello,' he said
स्ट्रिंग बनाता है. - चुने गए फ़ील्ड में वाइल्डकार्ड का इस्तेमाल किया जा सकता है.
उदाहरण के लिए,
entry/gd:*
,gd
नेमस्पेस में एंट्री के सभी चाइल्ड एलिमेंट को चुनता है औरentry/@gd:*
एक ही नेमस्पेस में चाइल्ड एलिमेंट एट्रिब्यूट को चुनता है.
fields
क्वेरी पैरामीटर, आउटपुट फ़िल्टर की तरह काम करता है. इसका मतलब है कि आंशिक जवाब की गिनती सिर्फ़ क्वेरी के बाकी हिस्से को प्रोसेस करने के बाद की जाती है. उदाहरण के लिए, अगर आप max-results
क्वेरी पैरामीटर भी तय करते हैं, ताकि आप यह बता सकें कि आपको हर पेज पर 20 नतीजे चाहिए, तो पहले 20 नतीजे जनरेट किए जाते हैं और उसी से कुछ नतीजे कैलकुलेट किए जाते हैं. अगर fields
की खास जानकारी, क्वेरी के चुने गए शुरुआती 20 एंट्री में से किसी एक से मेल नहीं खाती है, तो आपको खाली फ़ीड वापस मिलता है; आपको मिलान की पहली 20 एंट्री नहीं दिखती हैं.
ध्यान दें: फ़ील्ड से जुड़ी शर्तों को क्वेरी सिलेक्टर के तौर पर इस्तेमाल करने की कोशिश न करें. इसका मतलब है कि पूरा फ़ीड फिर से पाने की कोशिश न करें. साथ ही, बहुत बड़े डेटा सेट से पसंदीदा आइटम फ़िल्टर करने के लिए फ़ील्ड की शर्तें लागू न करें. जब भी हो सके, क्वेरी के दूसरे पैरामीटर, जैसे कि start-index
और max-results
का इस्तेमाल करें. इससे हर क्वेरी के नतीजों को मैनेज किए जा सकने वाले साइज़ में बदला जा सकेगा. ऐसा न होने पर, पूरी तरह से काम न करने की वजह से परफ़ॉर्मेंस पर असर पड़ सकता है. ऐसा, परफ़ॉर्मेंस में होने वाले गंभीर उतार-चढ़ाव की वजह से हो सकता है.
फ़ील्ड पैरामीटर वैल्यू को फ़ॉर्मैट करना
यहां दिए गए दिशा-निर्देशों में, fields
क्वेरी पैरामीटर वैल्यू को बनाने का तरीका बताया गया है. हर दिशा-निर्देश में उदाहरण शामिल होते हैं. साथ ही, यह भी बताया जाता है कि पैरामीटर वैल्यू, रिस्पॉन्स को कैसे प्रभावित करती है.
ध्यान दें: क्वेरी पैरामीटर की सभी वैल्यू की तरह ही, fields
पैरामीटर की वैल्यू भी यूआरएल के कोड में होनी चाहिए. पढ़ने में आसान बनाने के लिए, यहां दिए गए उदाहरण, कोड में बदलने के तरीके को नहीं दिखाते हैं.
- उन फ़ील्ड की पहचान करें जिन्हें आप लौटाना चाहते हैं या फ़ील्ड चुनें.
fields
क्वेरी पैरामीटर वैल्यू, एलिमेंट या एट्रिब्यूट की कॉमा-सेपरेटेड लिस्ट होती है (जिन्हें फ़ील्ड कहा जाता है) और हर फ़ील्ड को रिसॉर्स के रीप्रज़ेंटेशन के रूट एलिमेंट के हिसाब से तय किया जाता है. इसलिए, अगर आप कोई फ़ीड फिर से पा रहे हैं, तो फ़ील्ड<feed>
एलिमेंट के हिसाब से तय की जाती हैं और अगर आप एक ही एंट्री फिर से हासिल कर रहे हैं, तो फ़ील्ड<entry>
एलिमेंट के हिसाब से बताए जाते हैं. अगर चुना गया एलिमेंट, फ़ीड में मौजूद किसी एलिमेंट का हिस्सा है (या उसका हिस्सा है), तो सेवा उस एलिमेंट के सभी इंस्टेंस दिखाती है.
फ़ीड के कुछ उदाहरण यहां दिए गए हैं:
उदाहरण असर entry
उन एंट्री के सभी <entry>
एलिमेंट और सभी सब-एलिमेंट दिखाता है, लेकिन<feed>
का कोई दूसरा चाइल्ड एलिमेंट नहीं दिखाता.id,entry
फ़ीड <id>
और सभी<entry>
एलिमेंट दोनों दिखाता है.entry/title
सभी फ़ीड एंट्री के लिए, <title>
एलिमेंट दिखाता है.
जब भी कोई नेस्ट किया गया एलिमेंट वापस किया जाता है, तो रिस्पॉन्स में किसी भीपैरंट एलिमेंट के लिए टैग शामिल होते हैं. पैरंट टैग में किसी भी दूसरे चाइल्ड एलिमेंट या एट्रिब्यूट को तब तक शामिल नहीं किया जाता, जब तक कि उन्हें साफ़ तौर पर नहीं चुना जाता.
entry/author/uri
सभी फ़ीड एंट्री के लिए, <author>
एलिमेंट के सिर्फ़<uri>
सब-एलिमेंट दिखाता है.entry/*:rating
सभी फ़ीड एंट्री के लिए, किसी भी नेमस्पेस में सिर्फ़ लोकल नाम rating
वाले सब-एलिमेंट दिखाता है.
एंट्री-लेवल के कुछ उदाहरण यहां दिए गए हैं:
उदाहरण असर author
टारगेट एंट्री का <author>
चाइल्ड एलिमेंट दिखाता है.@gd:etag
टारगेट एंट्री का etag
एट्रिब्यूट दिखाता है.author/uri
टारगेट एंट्री के लिए, <author>
एलिमेंट के<uri>
सब-एलिमेंट को दिखाता है.media:group/media:*
टारगेट एंट्री के लिए, media
नेमस्पेस में<media:group>
के सभी सब-फ़ील्ड दिखाता है.- चुने गए फ़ील्ड से मेल खाने वाले नतीजे पर पाबंदी लगाएं, जो कुछ शर्तों को पूरा करता है या फ़ील्ड की शर्तें इस्तेमाल करें.
- डिफ़ॉल्ट रूप से, अगर आपका अनुरोध ऐसे एलिमेंट के बारे में बताता है जो एक से ज़्यादा बार होता है, तो आंशिक जवाब में उस एलिमेंट के सभी इंस्टेंस शामिल होंगे. हालांकि, यह भी बताया जा सकता है कि रिस्पॉन्स में सिर्फ़ वे एलिमेंट शामिल होने चाहिए जो किसी खास एट्रिब्यूट की वैल्यू रखते हों या ऐसे एलिमेंट जिनमें "
[ ]
" सिंटैक्स का इस्तेमाल करके, कुछ अन्य शर्तें पूरी की गई हों. इसके बारे में, नीचे दिए गए उदाहरणों में दिखाया गया है. ज़्यादा जानकारी के लिए, फ़ील्ड कंडीशन सिंटैक्स सेक्शन देखें.उदाहरण असर entry[link/@rel='edit']
फ़ीड की उन एंट्री को दिखाता है जिनमें <link>
एट्रिब्यूट होता है, जिसमेंrel
एट्रिब्यूट की'edit'
वैल्यू होती है.entry/title[text()='Today']
अगर कॉन्टेंट 'Today'
है, तो फ़ीड एंट्री में दिखने वाले<title>
एलिमेंट को दिखाता है.entry/author[name='Jo']
फ़ीड एंट्री में होने वाले ऐसे सभी <author>
एलिमेंट दिखाता है जिनमें<name>
कॉन्टेंट'Jo'
होता है.author[name='Jo']
अगर इसमें <author>
'Jo'
एलिमेंट वाला सब-एलिमेंट है, तो टारगेट एंट्री में<author>
एलिमेंट दिखाता है. - सिर्फ़ चुने गए एलिमेंट के हिस्सों का अनुरोध करें या फ़ील्ड सब-सिलेक्शन का इस्तेमाल करें.
- डिफ़ॉल्ट रूप से, अगर आपका अनुरोध कुछ खास एलिमेंट की जानकारी देता है, तो सेवा एलिमेंट को पूरी तरह से दिखाती है. आपके पास यह तय करने का विकल्प होता है कि रिस्पॉन्स में, चुने गए एलिमेंट के अंदर सिर्फ़ कुछ सब-एलिमेंट शामिल हों. आप नीचे दिए गए उदाहरणों की तरह, "
( )
" उप-चुनाव सिंटैक्स का इस्तेमाल करके ऐसा करते हैं.उदाहरण असर entry/author(uri)
फ़ीड एंट्री में लेखकों के लिए सिर्फ़ <uri>
सब-एलिमेंट दिखाता है.entry/author[name='Jo'](uri)
'Jo'
के लेखक नाम वाली किसी भी एंट्री के लिए,<author>
का सिर्फ़<uri>
सब-एलिमेंट दिखाता है.entry(link(@rel,
@href))
फ़ीड एंट्री में, हर <link>
एलिमेंट के लिए सिर्फ़rel
औरhref
एट्रिब्यूट की वैल्यू दिखाता है.entry(title,link[@rel='edit'])
यह हर फ़ीड के लिए, बदलाव rel
की विशेषताओं वाले<title>
और<link>
एलिमेंट दिखाता है.entry(title,author(uri)
यह हर फ़ीड के लिए, <title>
एलिमेंट और लेखक<uri>
एलिमेंट दिखाता है.
फ़ील्ड कंडीशन सिंटैक्स के बारे में ज़्यादा जानकारी
आप फ़ील्ड या सब-फ़ील्ड के साथ फ़ील्ड की शर्तों का इस्तेमाल कर सकते हैं. चुने गए फ़ील्ड को नतीजों में शामिल करने के लिए, शर्त का 'सही' होना ज़रूरी है.अगर कोई फ़ील्ड कंडीशन नहीं है, तो चुने गए टाइप के सभी फ़ील्ड शामिल हो जाते हैं.
चुने गए फ़ील्ड की टेक्स्ट वैल्यू का इस्तेमाल तुलना करने के लिए किया जाता है. इस संदर्भ में, अगर फ़ील्ड एक एलिमेंट है, तो टेक्स्ट वैल्यू उसकी सामग्री होती है; अगर फ़ील्ड एक एट्रिब्यूट है, तो टेक्स्ट की वैल्यू, एट्रिब्यूट की वैल्यू होती है. अगर फ़ील्ड में कोई टेक्स्ट वैल्यू नहीं है, तो तुलना नहीं की जा सकती और फ़ील्ड को नतीजों में शामिल नहीं किया जाता.
नीचे दी गई टेबल में वे XPath ऑपरेटर दिखाए गए हैं जो फ़ील्ड की स्थिति के हिसाब से काम करते हैं. साथ ही, यहां कुछ उदाहरण दिए गए हैं.
ऑपरेटर | सिंटैक्स | उदाहरण |
---|---|---|
स्ट्रिंग तुलना |
|
|
तार्किक तुलना | and |
|
अंक की तुलना | = या eq != या ne > या gt > = या ge < या lt <= या le
|
|
तारीख की तुलना करना | संख्या में तुलना करने वाले ऑपरेटर का इस्तेमाल करें, जैसा कि उदाहरण में दिखाया गया है. | तारीख या तारीख/समय की तुलना करने के लिए,
|
मौजूदगी | उदाहरण में दिखाए गए एलिमेंट या एट्रिब्यूट का नाम इस्तेमाल करें. |
|
बूलियन | true() false()
|
जांच के दौरान बूलियन उपयोगी हो सकते हैं, ताकि फ़ील्ड की स्थितियों को सही या गलत पर सेट किया जा सके.
|
कुछ जवाबों को मैनेज करना
आंशिक रिस्पॉन्स की सुविधा देने वाले सर्वर की मदद से एक मान्य अनुरोध प्रोसेस किया जाता है, जिसमें fields
क्वेरी पैरामीटर शामिल होता है. इसके बाद, यह अनुरोध किए गए एट्रिब्यूट या एलिमेंट के साथ एचटीटीपी 200 OK
स्टेटस कोड वापस भेजता है. अगर fields
क्वेरी पैरामीटर में कोई गड़बड़ी है या वह गलत है, तो सर्वर एचटीटीपी 400 Bad Request
स्टेटस कोड दिखाता है.
टारगेट यूआरआई के हिसाब से, रिस्पॉन्स का रूट एलिमेंट <feed>
या <entry>
होता है. रूट एलिमेंट के कॉन्टेंट में उस फ़ीड या एंट्री के लिए, सिर्फ़ चुने गए फ़ील्ड शामिल होते हैं. साथ ही, फ़ीड में सभी पैरंट एलिमेंट के लिए टैग शामिल होते हैं.
अनुरोध के fields
क्वेरी पैरामीटर की वैल्यू को दो तरीकों से फिर से दिखाया जा सकता है:
- रूट एलिमेंट में एक
gd:fields
एट्रिब्यूट होता है, जो अनुरोध में बताए गएfields
क्वेरी पैरामीटर की वैल्यू दिखाता है. - अगर टारगेट यूआरआई कोई फ़ीड है, तो बदलाव की जा सकने वाली हर एंट्री में एक
gd:fields
एट्रिब्यूट होता है. यह एट्रिब्यूट उसfields
चुनाव का हिस्सा दिखाता है जो इस पर लागू होता है.
ध्यान दें: इन gd:fields
विशेषता मानों को अपने आंशिक जवाब में देखने के लिए, आपको उन्हें अपने fields
क्वेरी पैरामीटर की खास बातों में शामिल करना होगा. साफ़ तौर पर ऐसा करने के लिए, @gd:fields
का इस्तेमाल किया जा सकता है या @gd:*
का इस्तेमाल किया जा सकता है. इसमें सामान्य ई-टैग जानकारी भी शामिल होती है.
यहां दिए गए उदाहरण में, सर्वर को एक दस्तावेज़ देने के लिए कहा गया है, जिसमें सिर्फ़ gd
नेमस्पेस (फ़ीड और एंट्री लेवल, दोनों पर) के साथ-साथ फ़ीड आईडी, शीर्षक, और हर फ़ीड एंट्री के 'बदलाव करें' लिंक की जानकारी दी गई है:
http://example.com/myFeed?fields=@gd:*,id,entry(@gd:*,title,link[@rel='edit'])
सर्वर कुछ एचटीटीपी रिस्पॉन्स के साथ एक 200 Successful
एचटीटीपी स्टेटस कोड दिखाता है:
<?xml version='1.0' encoding='utf-8'?> <feed xmlns='http://www.w3.org/2005/Atom' xmlns:gd='http://schemas.google.com/g/2005' gd:etag='W/"DEAEQH47eCp7IWA9WxBVGUo."' gd:fields='@gd:*,id,entry(@gd:*,title,link[@rel='edit'])> <id>http://example.com/myFeed</id> <entry gd:etag='"EksPTg1Bfyp7IWA6WhJT"' gd:fields="@gd:*,title,link[@rel='edit']"> <link rel='edit' href='http://example.com/myFeed/1/'/> <title>This year</title> </entry> <entry gd:etag='"EksPQA1Cdyp7IWA6WhJT"' gd:fields="@gd:*,title,link[@rel='edit']"> <link rel='edit' href='http://example.com/myFeed/2/'/> <title>Last year</title> </entry> <entry d:etag='"EksPQAxHeCp7IWA6WhJT"' gd:fields="@gd:*,title,link[@rel='edit']"> <link rel='edit' href='http://example.com/myFeed/3/'/> <title>Today</title> </entry> </feed>
अगर चुने गए फ़ील्ड मेल नहीं खाते हैं, तब भी सेवा 200 Successful
एचटीटीपी स्टेटस कोड दिखाती है, लेकिन आंशिक जवाब एक खाली फ़ीड होता है:
<?xml version='1.0' encoding='utf-8'?> <feed xmlns='http://www.w3.org/2005/Atom' xmlns:gd='http://schemas.google.com/g/2005' gd:etag='W/"DEAEQH47eCp7IWA9WxBVGUo."' gd:fields='@gd:*,id,entry(@gd:*,title,link[@rel='edit'])> </feed>
आंशिक अपडेट (प्रयोग के तौर पर)
ऐसे प्रॉडक्ट जो कुछ हिस्सों में ही काम करते हैं और जिनमें बदलाव किए जा सकते हैं, वे भी पार्शियल अपडेट का इस्तेमाल कर सकते हैं. आंशिक अपडेट के साथ, पूरे संसाधन प्रतिनिधित्व का बदला गया वर्शन भेजने के बजाय, आप सिर्फ़ वे फ़ील्ड भेजते हैं जिन्हें आप अपडेट करना चाहते हैं. इससे आपके क्लाइंट ऐप्लिकेशन अपडेट करते समय और डेटा वापस पाने के लिए आंशिक जवाब का इस्तेमाल करते समय ज़्यादा बेहतर तरीके से काम कर पाते हैं.
हालांकि, PUT
का इस्तेमाल करने के बजाय, आपको कुछ अपडेट करते समय PATCH
के अनुरोध का इस्तेमाल करना चाहिए. PATCH
के सिमेंटिक इतने मज़बूत हैं कि आप किसी खास एंट्री के लिए, खास अनुरोध, सिर्फ़ एक अनुरोध के साथ जोड़ सकते हैं, उन्हें बदल सकते हैं, और किसी खास फ़ील्ड को मिटा सकते हैं.
आपके इस्तेमाल किए जा रहे प्रॉडक्ट के लिए कुछ अपडेट उपलब्ध हैं या नहीं, यह जानने के लिए प्रॉडक्ट के हिसाब से दिए गए दस्तावेज़ देखें.
आंशिक अपडेट अनुरोध सबमिट किया जा रहा है
आंशिक अपडेट का अनुरोध सबमिट करने के लिए, आपको उस यूआरएल पर एचटीटीपी PATCH
अनुरोध भेजना होगा जिसका इस्तेमाल आप रिसॉर्स को अपडेट करने के लिए PUT
के साथ करेंगे. PATCH
अनुरोध का मुख्य हिस्सा, <entry>
एलिमेंट है. यह उन फ़ील्ड के बारे में बताता है जिन्हें आपको जोड़ना या उनमें बदलाव करना है. एंट्री का gd:fields
एट्रिब्यूट, उन फ़ील्ड को दिखाता है जिन्हें आपको मिटाना है.
सर्वर PATCH
अनुरोधों को एक खास क्रम में प्रोसेस करता है:
- यह पहले
gd:fields
एट्रिब्यूट के ज़रिए बताए गए फ़ील्ड को संसाधन दिखाने से हटा देता है.gd:fields
एट्रिब्यूट का सिंटैक्स,fields
रिस्पॉन्स पैरामीटर के लिए इस्तेमाल किए जाने वाले सिंटैक्स के जैसा ही है. ज़्यादा जानकारी के लिए, काम करने वाले सिंटैक्स देखें. - इसके बाद, इसे अनुरोध के मुख्य हिस्से में दिए गए डेटा को मौजूदा संसाधन के तौर पर मर्ज किया जाता है.
डेटा मर्ज करने के तरीके के बारे में ज़्यादा जानकारी, नीचे दिए गए फ़ील्ड जोड़ना या अपडेट करना सेक्शन में दी गई है.
ध्यान दें: PATCH
अनुरोध का मुख्य हिस्सा, ऐटम सिंडिकेशन फ़ॉर्मैट के नियमों का पालन नहीं करता. इसलिए, PATCH
अनुरोध के साथ जिस Content-Type
का इस्तेमाल किया जाता है वह application/xml
होता है.
यहां कुछ हद तक अपडेट के अनुरोध का एक उदाहरण दिया गया है:
PATCH /myFeed/1/1/ Content-Type: application/xml <entry xmlns='http://www.w3.org/2005/Atom' xmlns:gd='http://schemas.google.com/g/2005' gd:fields='description'> <title>New title</title> </entry>
PATCH
अनुरोध, टारगेट यूआरआई की एंट्री के लिए सर्वर पर सेव किए गए संसाधन के प्रतिनिधित्व में नीचे दिए गए बदलाव करता है:
<description>
एलिमेंट हटाता है.<title>
एलिमेंट को अपडेट करता है.
आंशिक अपडेट अनुरोध के सीमेंटिक
नीचे दिए गए निर्देशों में, किसी एंट्री में खास फ़ील्ड को मिटाने, जोड़ने या अपडेट करने के लिए PATCH
अनुरोध सेट अप करने का तरीका बताया गया है. एक ही PATCH
अनुरोध में ये दोनों काम किए जा सकते हैं.
फ़ील्ड मिटाना. संसाधन से उस फ़ील्ड को पहचानने के लिए,
<entry>
एलिमेंट केgd:fields
एट्रिब्यूट का इस्तेमाल करें जिसे आपको मिटाना है. यह नमूना अनुरोध, किसी एंट्री से जुड़े शीर्षक और खास जानकारी को मिटा देता है. हालांकि, अनुरोध में एंट्री के लिए कोई और डेटा जोड़ा या अपडेट नहीं किया जाता.PATCH /myfeed/1/1/ Content-Type: application/xml <entry xmlns='http://www.w3.org/2005/Atom' xmlns:gd='http://schemas.google.com/g/2005' gd:fields='title,summary'/>
फ़ील्ड जोड़ना या अपडेट करना. उस डेटा की जानकारी देने के लिए
<entry>
एलिमेंट के मुख्य हिस्से का इस्तेमाल करें जिसे आप किसी संसाधन के लिए जोड़ना या अपडेट करना चाहते हैं. यहां दिए गए नियमों के मुताबिक, डेटा मिटाने के बाद, इन फ़ील्ड को संसाधन के मौजूदा डेटा में मर्ज कर दिया जाता है:ऐसे फ़ील्ड जो पहले से मौजूद नहीं हैं, उन्हें जोड़ दिया जाता है. अगर संसाधन डेटा में पहले से ही किसी फ़ील्ड की वैल्यू नहीं दी गई है, तो फ़ील्ड को मौजूदा डेटा में जोड़ दिया जाता है. उदाहरण के लिए, अगर किसी एंट्री का शीर्षक नहीं है और आपके
PATCH
अनुरोध में<title>
एलिमेंट है, तो एंट्री में नया शीर्षक जोड़ा जाता है.पहले से मौजूद फ़ील्ड बदले गए या जोड़े गए. संसाधन डेटा में पहले से तय फ़ील्ड को मर्ज करने का खास तरीका, फ़ील्ड की विशेषताओं पर निर्भर करता है:
दोहराए जाने वाले फ़ील्ड को बदल दिया जाता है. अगर संसाधन डेटा में बार-बार दोहराए जाने वाले एलिमेंट के लिए वैल्यू पहले से मौजूद है, तो
PATCH
अनुरोध में तय की गई वैल्यू, उस एलिमेंट की मौजूदा वैल्यू की जगह ले लेती है. उदाहरण के लिए, नीचे दिए गए उदाहरण में नया शीर्षक, मौजूदा शीर्षक की जगह ले लेगा.PATCH /myFeed/1/1/ Content-Type: application/xml <entry xmlns='http://www.w3.org/2005/Atom' xmlns:gd='http://schemas.google.com/g/2005'> <title>New Title</title> </entry>
ज़्यादा जटिल उदाहरण नीचे दिया गया है. इस उदाहरण के लिए, मान लें कि प्रविष्टि में केवल एक लेखक हो सकता है और लक्ष्य संसाधन में पहले से ही लेखक के नाम और ईमेल पते के मान हैं.
<author>
एलिमेंट में दो चाइल्ड फ़ील्ड होते हैं, लेकिन दिए गए डेटा में सिर्फ़<name>
एलिमेंट मौजूद होता है. इस वजह से, सिर्फ़ उस फ़ील्ड की वैल्यू बदली जाती है. दिए गए डेटा में जो<email>
एलिमेंट मौजूद नहीं है, उसकी वैल्यू में कोई बदलाव नहीं हुआ है.PATCH /myfeed/1/1/ Content-Type: application/xml <entry xmlns='http://www.w3.org/2005/Atom' xmlns:gd='http://schemas.google.com/g/2005'> <author> <name>New Name</name> </author> </entry>
दोहराए जाने वाले फ़ील्ड जोड़ दिए जाते हैं. अगर रिसॉर्स डेटा पहले से ही बार-बार इस्तेमाल होने वाले एलिमेंट के लिए वैल्यू तय करता है, तो आपकी तरफ़ से जो नया एलिमेंट जोड़ा जाता है उसे वैल्यू के मौजूदा सेट में जोड़ दिया जाता है.
ध्यान दें कि ऐसा भी हो सकता है कि आप दोहराए जाने वाले एलिमेंट के नए इंस्टेंस को जोड़ने के अलावा कुछ और करना चाहें. उदाहरण के लिए, इनमें से कोई एक काम किया जा सकता है:
दोहराए जाने वाले एलिमेंट की पूरी सूची बदलें. आप
gd:fields
एट्रिब्यूट का इस्तेमाल करके, बार-बार आने वाले सभी फ़ील्ड मिटा सकते हैं. उदाहरण के लिए,gd:fields='ns:accessControl'
. साथ ही, आपके पास रीप्लेसमेंट फ़ील्ड का पूरा सेट देने का भी विकल्प है. सभी मौजूदा एलिमेंट पहले मिटा दिए जाते हैं. इसलिए, आपके दिए गए फ़ील्ड सेट को जोड़ने पर, किसी भी मौजूदा वैल्यू के साथ कोई टकराव नहीं होता.दोहराए जाने वाले एलिमेंट के लिए मौजूदा वैल्यू के सेट में से एक वैल्यू को बदलना. इस मामले में,
gd:fields
वैल्यू को सटीक तौर पर तय करके, सिंगल एलिमेंट को हटा दें. इससे, अन्य वैल्यू को मिटाने से बचा जा सकता है. उदाहरण के लिए,embed
के सिर्फ़action
के ऐक्सेस कंट्रोल को हटाने के लिए,gd:fields='ns:accessControl[@action="embed"]'
का इस्तेमाल करें. इसके बाद,<entry>
एलिमेंट के शीर्षक में एक फ़ील्ड डालें, ताकि उसे बदला जा सके:PATCH /myfeed/1/1/ Content-Type: application/xml <entry xmlns='http://www.w3.org/2005/Atom' xmlns:gd='http://schemas.google.com/g/2005' gd:fields='ns:accessControl[@action="embed"]> <ns:accessControl action="embed" permission="allowed" /> </entry>
कुछ अपडेट के जवाब को मैनेज करना
आंशिक अपडेट का मान्य अनुरोध प्रोसेस करने के बाद, एपीआई 200 OK
एचटीटीपी रिस्पॉन्स कोड दिखाता है. डिफ़ॉल्ट रूप से, जवाब का मुख्य हिस्सा वह पूरी एंट्री होती है जिसे आपने अपडेट किया है. जब PATCH
अनुरोध को प्रोसेस करता है, तो सर्वर ठीक उसी तरह ETag वैल्यू को अपडेट करता है जैसा कि PUT
के साथ करता है.
अगर PATCH
के अनुरोध के हिसाब से, कोई नया संसाधन जनरेट किया जाता है, तो सिंटैक्स या सिमेंटिक तरीके से अमान्य होने पर, सर्वर HTTP 400 Bad Request
या 422 Unprocessable Entity
एचटीटीपी स्टेटस कोड दिखाता है और रिसॉर्स की स्थिति में कोई बदलाव नहीं होता. उदाहरण के लिए, अगर किसी ज़रूरी फ़ील्ड को मिटाने की कोशिश करने पर भी, रीप्लेसमेंट नहीं किया जाता, तो सर्वर गड़बड़ी का मैसेज दिखाता है.
ध्यान दें: यह समझना ज़रूरी है कि अलग-अलग फ़ील्ड एक-दूसरे से कैसे जुड़े हुए हैं. आपसी पारस्परिक स्वतंत्र मानों के केवल हिस्से को अपडेट करके किसी संसाधन को असंगत स्थिति में रखा जा सकता है. उदाहरण के लिए, खत्म होने के समय के बजाय शुरू होने के समय को बाद के मान में अपडेट करना मुमकिन है. हालांकि, एपीआई को गड़बड़ी का कोड दिखाना चाहिए, लेकिन हमारा सुझाव है कि समानता बनाए रखने के लिए, आप इस तरह की शर्तों को पूरी तरह से आज़माएं.
PATCH के साथ काम न करने की स्थिति में वैकल्पिक नोटेशन
अगर आपका फ़ायरवॉल PATCH
को अनुमति नहीं देता है, तो एचटीटीपी POST
अनुरोध करें और ओवरराइड हेडर को PATCH
पर सेट करें, जैसा कि यहां दिखाया गया है:
POST /myfeed/1/1/ X-HTTP-Method-Override: PATCH Content-Type: application/xml ...
आंशिक अपडेट के साथ आंशिक जवाब का इस्तेमाल किया जा रहा है
आगे के किसी आंशिक अपडेट अनुरोध के आधार पर आप आंशिक जवाब का इस्तेमाल कर सकते हैं. ऐसा करने पर, fields
क्वेरी पैरामीटर के साथ-साथ @gd:*
में बदलाव करने के लिंक के बारे में भी बताएं. इससे पक्का होता है कि अधूरे जवाब में ETag और gd:fields
एट्रिब्यूट की वैल्यू शामिल होती हैं. ये वैल्यू बाद के अनुरोधों के लिए ज़रूरी हैं.
यहां उदाहरण के तौर पर, कुछ हिस्से का जवाब दिया गया है. आप इस जवाब को आने वाले समय में होने वाले अपडेट के आधार के तौर पर इस्तेमाल कर सकते हैं:
http://example.com/myFeed/1/1/?fields=@gd:*,link[@rel='edit'](@href),gd:who
सर्वर जवाब देता है:
<?xml version='1.0' encoding='utf-8'?> <entry xmlns='http://www.w3.org/2005/Atom' xmlns:gd='http://schemas.google.com/g/2005' gd:etag='"E0UKRAREeCp7IWA6WhJT"' gd:fields="@gd;*,link[@rel='edit'](@href),gd:who"> <link href='http://example.com/myFeed/1/1/'/> <gd:who email='liz@gmail.com'/> <gd:who email='jo@gmail.com'/> <gd:who email='jane@gmail.com'/> </entry>
मान लें कि आपको 'jane@gmail.com'
ईमेल वाले उपयोगकर्ता को हटाना है, 'will@gmail.com'
उपयोगकर्ता वाले उपयोगकर्ता को जोड़ना है, और 'jo@gmail.com'
के तौर पर सूची में रखे गए उपयोगकर्ता के ईमेल पते को 'josy@gmail.com'
में बदलना है.
पिछले जवाब के नतीजों से शुरू करके, सिर्फ़ अलग-अलग फ़ील्ड में बदलाव करके और PATCH
अनुरोध के मुख्य हिस्से के तौर पर बदले गए कुछ हिस्से की एंट्री सबमिट करके, ये बदलाव किए जा सकते हैं. इस उदाहरण के लिए, ये बदलाव ज़रूरी हैं:
- दिए गए एलिमेंट की सूची में से
<gd:who email='jane'/>
को मिटाएं. - दिए गए एलिमेंट की सूची में
<gd:who email='will@gmail.com'/>
जोड़ें. <gd:who email='jo@gmail.com'/>
को<gd:who email='josy@gmail.com'/>
से बदलें.
पेवियस आंशिक जवाब पर आधारित PATCH
अनुरोध नीचे दिखाया गया है:
PATCH /myFeed/1/1/ Content-Type: application/xml <entry gd:fields="@gd:*,link[@rel='edit'](@href),gd:who" gd:etag="FE8LQQJJeSp7IWA6WhVa"> <link href='http://example.com/myFeed/1/1'/> <gd:who email='liz@gmail.com'/> <gd:who email='josy@gmail.com'/> <gd:who email='will@gmail.com'/> </entry>
ध्यान दें: यह तरीका gd:fields
और gd:etag
(अगर काम करता है) एट्रिब्यूट पर निर्भर करता है. इन्हें एंट्री के लिए, कुछ जवाब में शामिल किया जाता है. आंशिक प्रविष्टि के मुख्य भाग में उन सभी फ़ील्ड और एट्रिब्यूट को बनाए रखा जाना चाहिए जो आंशिक जवाब में मौजूद थे — उन फ़ील्ड को छोड़कर जिन्हें आप साफ़ तौर से हटाना चाहते हैं. मुख्य भाग में किसी भी मौजूदा फ़ील्ड को नए मानों से अपडेट किया जा सकता है और आप ऐसे नए फ़ील्ड शामिल कर सकते हैं, जिन्हें आप जोड़ना चाहते हैं.
पुष्टि करना
जब कोई क्लाइंट किसी सेवा को ऐक्सेस करने की कोशिश करता है, तो उसे सेवा के लिए उपयोगकर्ता के क्रेडेंशियल देने पड़ सकते हैं, ताकि यह दिखाया जा सके कि उपयोगकर्ता के पास कार्रवाई करने का अधिकार है.
पुष्टि करने के लिए, क्लाइंट को यह तरीका अपनाना चाहिए:
- डेस्कटॉप ऐप्लिकेशन को Google-विशिष्ट प्रमाणीकरण सिस्टम का उपयोग करना चाहिए, जिसे इंस्टॉल किए गए ऐप्लिकेशन के लिए खाता प्रमाणीकरण कहते हैं (जिसे "ClientLogin" भी कहा जाता है). (वेब-आधारित क्लाइंट को इस सिस्टम का उपयोग नहीं करना चाहिए.)
- वेब आधारित क्लाइंट, जैसे Google सेवा पर तृतीय-पक्ष फ़्रंट एंड, वेब-आधारित ऐप्लिकेशन के लिए खाता प्रमाणीकरण प्रॉक्सी (जिसे "AuthSub" भी कहा जाता है) Google-विशिष्ट प्रमाणीकरण सिस्टम का उपयोग करना चाहिए.
ClientLogin सिस्टम में, डेस्कटॉप क्लाइंट उपयोगकर्ता से उनके क्रेडेंशियल मांगता है और फिर उन क्रेडेंशियल को Google प्रमाणीकरण सिस्टम पर भेजता है.
अगर पुष्टि हो जाती है, तो बाद में पुष्टि करने वाला सिस्टम एक टोकन दिखाता है. क्लाइंट इसका इस्तेमाल तब करता है, जब यह एचटीटीपी एपीआई अनुरोध भेजता है.
अगर पुष्टि नहीं हो पाती है, तो सर्वर 403 ऐक्सेस का स्टेटस कोड दिखाता है. साथ ही, WWW- Authenticator हेडर भी दिखाता है. इसमें पुष्टि करने के लिए एक चैलेंज होता है.
AuthSub सिस्टम इसी तरह काम करता है, लेकिन बस उपयोगकर्ता से उसके क्रेडेंशियल मांगने के बजाय उपयोगकर्ता को ऐसी Google सेवा से कनेक्ट करता है जो क्रेडेंशियल का अनुरोध करती है. इसके बाद, इस सेवा को एक टोकन मिलता है, जिसका इस्तेमाल वेब ऐप्लिकेशन कर सकता है. इस तरीके का फ़ायदा यह है कि Google, वेब फ़्रंट एंड की जगह उपयोगकर्ता के क्रेडेंशियल को सुरक्षित तरीके से हैंडल और स्टोर करता है.
पुष्टि करने वाले इन सिस्टम के बारे में जानने के लिए, Google Data API की पुष्टि करने की खास जानकारी या Google खाते की पुष्टि करना दस्तावेज़ देखें.
सेशन की स्थिति
कई कारोबारी नियम लागू करने के लिए सेशन को बनाए रखना ज़रूरी होता है—जैसे कि उपयोगकर्ता के सेशन की स्थिति को ट्रैक करना.
Google, सेशन की स्थिति को दो तरीकों से ट्रैक करता है: कुकी का इस्तेमाल करके और टोकन का इस्तेमाल करके, जिसे क्वेरी पैरामीटर के तौर पर भेजा जा सकता है. दोनों तरीकों से एक जैसा असर पड़ता है. हमारी सलाह है कि क्लाइंट इनमें से किसी एक सत्र-राज्य ट्रैकिंग पद्धति का समर्थन करें (या तो एक ही काफ़ी है). अगर कोई क्लाइंट इनमें से किसी भी तरीके का इस्तेमाल नहीं करता, तो वह क्लाइंट अब भी डेटा एपीआई के साथ काम करता है. हालांकि, क्लाइंट के इन तरीकों का समर्थन करने वाले क्लाइंट की तुलना में परफ़ॉर्मेंस पर असर पड़ सकता है. खास तौर पर, अगर कोई क्लाइंट इन तरीकों का इस्तेमाल नहीं करता, तो हर अनुरोध के साथ दूसरे वेबलिंक पर भेजा जाता है. इसलिए, हर अनुरोध (और उससे जुड़े डेटा) को सर्वर पर दो बार भेजा जाता है. इससे क्लाइंट और सर्वर की परफ़ॉर्मेंस पर असर पड़ता है.
Google क्लाइंट लाइब्रेरी आपके लिए सेशन की स्थिति हैंडल करती है. इसलिए, अगर आप हमारी लाइब्रेरी का इस्तेमाल करते हैं, तो सेशन की स्थिति के बारे में सहायता पाने के लिए आपको कुछ करने की ज़रूरत नहीं है.
अतिरिक्त रिसॉर्स
आपको तीसरे पक्ष के ये दस्तावेज़ उपयोगी लग सकते हैं:
- इंटरटेशन की मदद से, ऐटम और आरएसएस की तुलना
- IBM से ऐटम की खास जानकारी
- आरएसएस के लिए, डबलिन कोर एक्सटेंशन
- एचटीटीपी 1.1 तरीका की परिभाषाएं;
GET
,POST
,PUT
, औरDELETE
की जानकारी - एचटीटीपी 1.1 स्टेटस कोड की परिभाषाएं
- REST प्रोटोकॉल कैसे बनाएं
- वेब सेवाओं को बनाना बाकी बचे पैसे
- एक्सएमएल टेक्नोलॉजी का तकनीकी परिचय
- एक्सएमएल नेमस्पेस के उदाहरण
- एचटीटीपी की खास बातों का ईटैग सेक्शन