इंटिग्रेशन के बारे में खास जानकारी

Google.com पर एग्रीगेटर की लिस्टिंग (या सेवा देने वाली कंपनियों) को दिखाने के लिए, लोकल सर्विस विज्ञापन (एलएसए) का इस्तेमाल किया जाता है. इस गाइड में बताया गया है कि एग्रीगेटर, एलएसए को सेवा देने वाली कंपनियों का स्ट्रक्चर्ड डेटा कैसे दे सकते हैं. खास तौर पर, हम एपीआई एंडपॉइंट के उस सेट के बारे में बताते हैं जिसे एग्रीगेटर को एलएसए के साथ इंटिग्रेट करने के लिए लागू करना होगा.

शब्दावली

एग्रीगेटर (या पार्टनर): ये ऐसे पार्टनर होते हैं जो सेवा देने वाली कंपनियों को इकट्ठा करते हैं. ये उन्हें सेवाएं देते हैं और इनका डेटा LSA को दिया जा सकता है.

तीसरे पक्ष की सेवा देने वाली कंपनी (या लिस्टिंग): ये छोटे कारोबार होते हैं. जैसे, प्लंबर (जैसे, Joe’s plumbing) को भी शामिल किया जा सकता है. इन प्लंबर का एग्रीगेटर के साथ कारोबारी संबंध हो सकता है. एग्रीगेटर, Local Services को इन कारोबारों के बारे में जानकारी देते हैं.

खास जानकारी

एग्रीगेटर, फ़ीड का इस्तेमाल करके लोकल सर्विस को अपने सेवा देने वालों (कारोबारों) के बारे में डेटा देंगे. हर फ़ीड में, कई प्रोवाइडर का डेटा होता है. किसी फ़ीड में, किसी एक कंपनी का डेटा, फ़ीड आइटम में शामिल होता है. हर फ़ीड में एक टाइमस्टैंप भी होता है, जिससे पता चलता है कि फ़ीड कितना नया है. हर फ़ीड में, फ़ीड का टाइप भी बताया जाता है. यह डेटा, सेवा देने वाली कंपनी की प्रोफ़ाइल या सेवा देने वाली कंपनी की समीक्षाओं के बारे में हो सकता है. इसके बारे में यहां बताया गया है.

फ़ीड के टाइप

शुरुआती इंटिग्रेशन के लिए, हर फ़ीड इनमें से किसी भी तरह का हो सकता है:

• प्रोफ़ाइल फ़ीड: इस फ़ीड में, सेवा देने वाली कंपनियों की प्रोफ़ाइलों के बारे में जानकारी होती है. हर फ़ीड आइटम में, किसी खास प्रोवाइडर की प्रोफ़ाइल की जानकारी शामिल होती है. इसमें कारोबार का यूनीक आईडी, कारोबार का नाम, सेवा देने की जगहें, दी जाने वाली सेवाएं, काम के घंटे वगैरह शामिल हैं. फ़ीड आइटम में इस कारोबार के लिए, विज्ञापन दिखाने से जुड़ा मेटाडेटा भी शामिल होता है. जैसे, महीने के बजट की रकम, विज्ञापन की स्थिति वगैरह.

• समीक्षा फ़ीड: इस फ़ीड में, सेवा देने वाली कंपनी की समीक्षाओं के बारे में जानकारी होती है. हर फ़ीड आइटम में, किसी खास सेवा देने वाली कंपनी के बारे में उपभोक्ताओं की समीक्षाओं की पूरी जानकारी होती है. उपयोगकर्ता की हर समीक्षा में, उपयोगकर्ता का नाम, रेटिंग (1 से 5), समीक्षा का टेक्स्ट, समीक्षा का टाइमस्टैंप वगैरह शामिल होता है.

प्रोफ़ाइल फ़ीड और समीक्षा फ़ीड में मौजूद फ़ील्ड और उनके सिमैंटिक के बारे में ज़्यादा जानकारी.

फ़ीड का डेटा देना

फ़ीड डेटा को JSON के तौर पर क्रम से लगाया जाता है. डेटा सबमिट करने के लिए, एलएसए सिर्फ़ पुल करने की सुविधा के साथ काम करेगा. आने वाले समय में, पुश मेकेनिज़्म की सुविधा उपलब्ध कराने की योजना है.

डेटा फ़ेच करने का तरीका

पुल करने के तरीके में, एग्रीगेटर पहले से तय किए गए REST एंडपॉइंट (यूआरएल) के सेट के साथ काम करते हैं. ये JSON ऑब्जेक्ट भेजते और पाते हैं. यह वेब सर्वर पर एक या उससे ज़्यादा फ़ाइलों को होस्ट करने जैसा है. एलएसए, इन यूआरएल पर समय-समय पर एचटीटीपी GET अनुरोध भेजता रहेगा, ताकि डेटा फ़ेच किया जा सके. पहले से तय किए गए यूआरएल के बारे में जानकारी, एपीआई एंडपॉइंट के बारे में बताने वाले अगले सेक्शन में दी गई है.

पुश करने का तरीका

पुश मेकेनिज़्म में, LSA, एग्रीगेटर को कॉल करने और डेटा उपलब्ध कराने के लिए एक एंडपॉइंट देगा. सिमेंटिक तौर पर, यह पुल करने जैसा ही है. हालांकि, इससे उन मामलों में आसानी होती है जहां एग्रीगेटर, Local Services को खास डेटा पुश करना चाहते हैं. प्रोटोकॉल में बताए गए सभी सिमैंटिक, नियम या शर्तें, पुश और पुल, दोनों पर एक ही तरह से लागू होती हैं.

एपीआई एंडपॉइंट

एग्रीगेटर को इन एंडपॉइंट के साथ काम करना चाहिए: एक प्रोफ़ाइल फ़ीड के लिए और एक समीक्षा फ़ीड के लिए.

सुझाए गए एंडपॉइंट का पाथ

हमारा सुझाव है कि एंडपॉइंट में वर्शन की जानकारी शामिल हो. जैसे, यहां दी गई है. हम v1 से शुरू करते हैं.

एंडपॉइंट	पथ
प्रोफ़ाइल फ़ीड	/feeds/{version}/profile
समीक्षा वाला फ़ीड	/feeds/{version}/review

एंडपॉइंट पैरामीटर

Params	ब्यौरा
maxresults	यह सीमा तय करती है कि किसी पेज पर कितने फ़ीड आइटम का अनुरोध किया जा सकता है.
nextpagetoken	नतीजों का अगला पेज पाने के लिए पेज नंबर वाला टोकन

एंडपॉइंट की पुष्टि करना

पुष्टि करने के लिए, एचटीटीपी बेसिक ऐक्सेस ऑथेंटिकेशन का इस्तेमाल किया जाता है: base64 की मदद से कोड में बदला गया उपयोगकर्ता नाम और पुष्टि करने के लिए पासवर्ड. नीचे एक उदाहरण है.

• username “पुष्टि के लिए अस्थायी शुल्क” (सिर्फ़ उदाहरण के लिए)
• password J9adfdsafc3RfMjpVU1yif5XMw” (उदाहरण के लिए)

पुश के लिए एसएफ़टीपी ड्रॉपबॉक्स

Dropbox का पाथ: partnerupload.google.com:19321

चेतावनी: इस SFTP ड्रॉप बॉक्स में लोड की गई फ़ाइलें, 24 घंटे बाद अपने-आप मिट जाती हैं.

एंडपॉइंट की पुष्टि करना

• सार्वजनिक/निजी कुंजी का पेयर (सुझाया गया)

  • की पेयर जनरेट करने के लिए, यहां दिए गए ट्यूटोरियल का इस्तेमाल करें.
  • एलएसए को सार्वजनिक पासकोड भेजें और पुष्टि करने के लिए निजी पासकोड को अपने पास रखें
  • एलएसए, सार्वजनिक कुंजी का इस्तेमाल करके उपयोगकर्ता नाम जनरेट करेगा और उसे एग्रीगेटर को वापस भेज देगा

• पासवर्ड की मदद से पुष्टि करना

  • LSA, उपयोगकर्ता नाम और पासवर्ड जनरेट करेगा और उसे एग्रीगेटर को वापस भेज देगा

एसएफ़टीपी कमांड के बारे में खास जानकारी

1. लॉग इन करें. लॉग इन करने के लिए, इस कमांड का इस्तेमाल करें. (अगर आपको निजी पासकोड का इस्तेमाल नहीं करना है, तो -i को छोड़ दें).

   sftp -i <path_to_private_key> -P 19321 <username>@partnerupload.google.com

2. फ़ाइल कॉपी करें. फ़ाइल को रिमोट सिस्टम में कॉपी करें. फ़ाइल ढूंढने के लिए, अपने लोकल सिस्टम में lls/lcd का इस्तेमाल किया जा सकता है.ls/cd इसके बाद, फ़ाइल को इसके ज़रिए कॉपी करें:

   put <path_to_local_file>

3. पुष्टि करें पर क्लिक करें. एसएफ़टीपी डायरेक्ट्री में फ़ोल्डर और फ़ाइलों की सूची देखने के लिए, ls का इस्तेमाल करें. साथ ही, पुष्टि करें कि आपकी फ़ाइल को रिमोट सिस्टम पर कॉपी कर दिया गया है

फ़ीड की कैटगरी

जैसा कि पहले बताया गया है, हर फ़ीड एक फ़ाइल की तरह होता है और इसमें कई फ़ीड आइटम शामिल होते हैं. हर फ़ीड आइटम में, किसी खास प्रोवाइडर (यूनीक कारोबार आईडी) के बारे में डेटा शामिल होता है. हर फ़ीड में एक टाइमस्टैंप भी होता है, जिससे पता चलता है कि फ़ीड कितना नया है. फ़ीड कैटगरी से पता चलता है कि एलएसए, दिए गए फ़ीड को कैसे समझता है. फ़ीड दो कैटगरी में होते हैं. इनके बारे में यहां बताया गया है.

स्नैपशॉट फ़ीड में, किसी एग्रीगेटर के तहत आने वाली कंपनियों की पूरी सूची होती है. यह सूची, किसी खास टाइमस्टैंप पर उपलब्ध होती है. स्नैपशॉट फ़ीड को प्रोसेस करने के बाद, ये सिमैंटिक लागू होते हैं:

• फ़ीड में मौजूद किसी भी सेवा देने वाली कंपनी के लिए, सिस्टम LSA डेटाबेस में इस कंपनी का डेटा अपडेट करेगा.उदाहरण के लिए, अगर कोई कंपनी पहली बार मिली है, तो उसके लिए नया डेटाबेस बनाया जाएगा. अगर कंपनी को पहले किसी फ़ीड में प्रोसेस किया गया था, तो उसके डेटा को अपडेट किया जाएगा.

• अगर एग्रीगेटर के तहत आने वाली कोई कंपनी, एलएसए डेटाबेस में मौजूद है, लेकिन फ़ीड में मौजूद नहीं है, तो उसे हटा दिया जाएगा.

अपडेट (या इंक्रीमेंटल) फ़ीड में, किसी खास टाइमस्टैंप पर एग्रीगेटर के तहत आने वाले कुछ ही प्रोवाइडर की सूची होती है. इंक्रीमेंटल फ़ीड को प्रोसेस करने के बाद, ये सिमैंटिक लागू होंगे:

• अगर फ़ीड में मौजूद किसी भी सेवा देने वाली कंपनी को स्नैपशॉट फ़ीड में पहले बनाया गया था, तो सिस्टम LSA डेटाबेस में इस कंपनी के डेटा को अपडेट करेगा. (उदाहरण के लिए, अगर किसी सेवा देने वाली कंपनी का सामना पहली बार हुआ है, तो यह कोई कार्रवाई नहीं होगी)

• अगर कोई सेवा देने वाली कंपनी, एलएसए डेटाबेस में मौजूद है, लेकिन फ़ीड में मौजूद नहीं है, तो इस कार्रवाई का कोई असर नहीं होगा. इसका मतलब है कि इस कंपनी में कोई बदलाव नहीं होगा.

प्रोफ़ाइल और समीक्षाओं के फ़ीड के सिमैंटिक में थोड़ा अंतर होता है. प्रोसेसिंग की जानकारी के लिए, हर फ़ीड के सिमैंटिक देखें.

प्रोफ़ाइल फ़ीड: * पुल-आधारित स्नैपशॉट फ़ीड * पुश-आधारित स्नैपशॉट फ़ीड * पुश-आधारित अपडेट फ़ीड समीक्षा फ़ीड: * पुल-आधारित स्नैपशॉट फ़ीड * पुश-आधारित स्नैपशॉट फ़ीड

इनके लिए अलग-अलग प्रोफ़ाइल फ़ीड ज़रूरी हैं:

1. ऐसी कंपनियां जो Google की गारंटी के साथ या Google ने जांच की है बैज पाने की ज़रूरी शर्तें पूरी करती हैं.

2. ऐसी कंपनियां जो बैज पाने की ज़रूरी शर्तें पूरी नहीं करती हैं.

उदाहरण

स्नैपशॉट फ़ीड

याद रखें कि स्नैपशॉट फ़ीड में, सेवा देने वाली कंपनियों की पूरी सूची शामिल होगी. उदाहरण के लिए, अगर किसी एग्रीगेटर को LSA में 100 सेवा देने वाली कंपनियों को शामिल करना है, तो स्नैपशॉट फ़ीड में उन सभी 100 कंपनियों की मौजूदा स्थिति होनी चाहिए.

यह सुविधा कैसे काम करती है

यहां एक सामान्य उदाहरण दिया गया है, जिसमें बताया गया है कि प्रोफ़ाइल फ़ीड की स्नैपशॉट कैटगरी कैसे काम करती है.

• स्नैपशॉट 1 में Pro 1 और Pro 2 हैं
• स्नैपशॉट 2 में Pro 1 और Pro 3 हैं

स्नैपशॉट 1 को प्रोसेस करने के बाद, एलएसए डेटाबेस में Pro 1 और Pro 2 मौजूद होंगे. स्नैपशॉट 2 को प्रोसेस करने के दौरान, LSA, Pro 1 को अपडेट करेगा, Pro 3 बनाएगा, और Pro 2 को मिटा देगा. इसका मतलब है कि स्नैपशॉट 2 को प्रोसेस करने के बाद, एलएसए डेटाबेस में Pro 1 और Pro 3 होगा.

फ़ीड अपडेट करना (इंक्रीमेंटल)

याद रखें कि अपडेट फ़ीड में, एग्रीगेटर के तहत आने वाली कंपनियों की सूची का कुछ हिस्सा होता है. उदाहरण के लिए, अगर किसी एग्रीगेटर को सिर्फ़ उन 5 कारोबारियों या कंपनियों की जानकारी अपडेट करनी है जिनकी जानकारी उसने पहले दी थी, तो अपडेट फ़ीड में सिर्फ़ इन 5 कारोबारियों या कंपनियों की नई जानकारी होनी चाहिए.

यह सुविधा कैसे काम करती है

यहां एक सामान्य उदाहरण दिया गया है, जिसमें बताया गया है कि “प्रोफ़ाइल फ़ीड” की अपडेट कैटगरी कैसे काम करती है.

• पहला अपडेट: Pro 1, Pro 2
• दूसरा अपडेट: Pro 1, Pro 3

पहले अपडेट को प्रोसेस करने के बाद, एलएसए डेटाबेस में Pro 1 और Pro 2 मौजूद होंगे. अपडेट 2 को प्रोसेस करने के दौरान, एलएसए, Pro 1 को अपडेट करेगा और Pro 3 बनाएगा. ध्यान दें कि Pro 2 में कोई बदलाव नहीं किया गया है. इसका मतलब है कि अपडेट 2 को प्रोसेस करने के बाद, एलएसए डेटाबेस में Pro1, Pro2, और Pro 3 मौजूद होंगे.

स्नैपशॉट और पुल के असर

स्नैपशॉट फ़ीड + पुल मेकेनिज़्म पर ये पाबंदियां लागू होती हैं:

• पार्टनर को, विज्ञापन देने वाले लोगों या कंपनियों को जोड़ने या हटाने, प्रोफ़ाइल की जानकारी अपडेट करने, विज्ञापनों को रोकने या बजट में बदलाव करने में कुछ घंटे लग सकते हैं. पुल के अनुरोधों की फ़्रीक्वेंसी का सीधा असर, प्रोसेस में लगने वाले समय पर पड़ता है.
• डेटा को तुरंत अपडेट करने के लिए, हमें एक बार/तदर्थ पुल को मैन्युअल तरीके से सपोर्ट करने की ज़रूरत पड़ सकती है.

इंक्रीमेंटल और पुश सपोर्ट के असर

अपडेट फ़ीड + पुश करें सुविधा चालू करने का मतलब है कि ये सुधार किए गए हैं:

• पार्टनर, स्नैपशॉट फ़ीड को पुश या पुल, दोनों में से किसी भी तरीके से डिलीवर कर सकते हैं. जिन पार्टनर को पुल करने के लिए एंडपॉइंट बनाए रखने की ज़रूरत नहीं है वे एंडपॉइंट बनाए रखने की लागत को कम करने के लिए, पुश का इस्तेमाल कर सकते हैं. अगर पार्टनर पहले से ही पुल मोड में स्नैपशॉट फ़ीड उपलब्ध करा रहा है, तो वह पुल मोड में स्नैपशॉट फ़ीड उपलब्ध कराना जारी रख सकता है.
• पार्टनर, इंक्रीमेंटल का इस्तेमाल करके, सिर्फ़ कुछ प्रोवाइडर की प्रोफ़ाइल में बदलाव कर सकते हैं. इससे प्रोफ़ाइल का डेटा जल्दी अपडेट होता है.
• स्नैपशॉट बनाम इंक्रीमेंटल, पुश बनाम पुल में से किसी एक को चुनने के बारे में जानने के लिए, इंटिग्रेशन के सुझाए गए तरीके के बारे में जानने के लिए यह सेक्शन देखें.

इंटिग्रेशन का सुझाया गया तरीका

पार्टनर को समय-समय पर स्नैपशॉट फ़ीड उपलब्ध कराने होंगे. ये फ़ीड, पुश या पुल के ज़रिए उपलब्ध कराए जा सकते हैं. इससे LSA को अपडेट न होने की वजह से, रोलबैक और सिस्टम रिकवरी जैसी आपातकालीन स्थितियों को मैनेज करने में मदद मिलती है.

• पुश मेकेनिज़्म की मदद से, पार्टनर को हर दो घंटे में स्नैपशॉट प्रोफ़ाइल फ़ीड और हर छह घंटे में समीक्षा फ़ीड पुश करने चाहिए. इससे यह पक्का किया जा सकेगा कि डेटा अपडेट है.
• पुल करने की सुविधा की मदद से, एलएसए हर दो घंटे में स्नैपशॉट प्रोफ़ाइल फ़ीड और हर छह घंटे में समीक्षा फ़ीड को पुल करेगा. इससे यह पक्का किया जा सकेगा कि डेटा अपडेट है.
• स्नैपशॉट फ़ीड डिलीवर करने के लिए, पार्टनर को सिर्फ़ एक तरीके (पुश या पुल) की ज़रूरत होती है. दोनों की ज़रूरत नहीं होती.

वैकल्पिक रूप से, जिन पार्टनर को डेटा जल्दी अपडेट होने की सुविधा को बेहतर बनाना है वे पुश के ज़रिए अपडेट फ़ीड भेज सकते हैं. LSA, अपडेट किए गए फ़ीड को पुल नहीं करेगा.

• अपडेट फ़ीड का इस्तेमाल, पिछले स्नैपशॉट के बाद बदले गए आइटम को अपडेट करने के लिए किया जाता है. इसके लिए, अगले स्नैपशॉट का इंतज़ार नहीं करना पड़ता.
• एलएसए, सेवा देने वाली कंपनियों को यह सुझाव देता है कि वे दो पुश के बीच पांच मिनट से ज़्यादा का अंतराल रखें.
• हमारा सुझाव है कि अपडेट फ़ीड में फ़ीड आइटम को सही तरीके से बंडल करें. पांच सेवा देने वाली कंपनियों की जानकारी अपडेट करने के लिए, एलएसए यह सुझाव देता है कि सेवा देने वाली कंपनियां, पांच फ़ीड आइटम वाला एक अपडेट फ़ीड भेजें. इसके बजाय, वे एक फ़ीड आइटम वाला पांच अपडेट फ़ीड न भेजें.
• एलएसए, सिर्फ़ प्रोफ़ाइल फ़ीड के लिए इंक्रीमेंटल फ़ीड का इस्तेमाल करता है. यह सुविधा, समीक्षा फ़ीड के लिए उपलब्ध नहीं है.

डेटा में एकरूपता बनाए रखने के लिए, LSA मेटाडेटा में मौजूद feedTimestampMicros फ़ील्ड का इस्तेमाल करेगा. अगर किसी प्रॉडक्ट के लिए नया फ़ीड आइटम उपलब्ध है, तो पुराने टाइमस्टैंप वाले फ़ीड आइटम को छोड़ दिया जाएगा. इससे, प्रॉडक्ट के लिए पुराना डेटा इस्तेमाल नहीं होगा. स्नैपशॉट और अपडेट फ़ीड, दोनों में feedTimestampMicros का इस्तेमाल करके, डेटा अपडेट होने की फ़्रीक्वेंसी की सही जानकारी देना पार्टनर की ज़िम्मेदारी है.

पार्टनर को हर सेवा देने वाली कंपनी के हिसाब से लीड और शुल्क की जानकारी पाने के लिए, Reporting API का इस्तेमाल करना चाहिए.