चार्ट टूल डेटा सोर्स प्रोटोकॉल (V0.6) को लागू करना

इस पेज में बताया गया है कि क्वेरी क्लास का इस्तेमाल करके, चार्ट में डेटा दिखाने के लिए ऐसी सेवा को कैसे लागू किया जा सकता है जो चार्ट टूल डेटा सोर्स प्रोटोकॉल के साथ काम करती हो.

विषय सूची

दर्शक

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

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

अगर विज़ुअलाइज़ेशन बनाया जा रहा है या उसका इस्तेमाल किया जा रहा है, तो आपको यह पेज पढ़ने की ज़रूरत नहीं है.

इस दस्तावेज़ को पढ़ने के लिए, आपको बेसिक JSON और एचटीटीपी अनुरोध सिंटैक्स को समझना होगा. आपको इस बात को भी समझना चाहिए कि उपयोगकर्ता के नज़रिये से चार्ट कैसे काम करते हैं.

खास जानकारी

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

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

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

• अनुरोध और रिस्पॉन्स को मैनेज करने के लिए, नीचे दी गई हेल्पर लाइब्रेरी में से किसी एक का इस्तेमाल करें और रिटर्न के लिए DataTable बनाएं. अगर इनमें से किसी एक लाइब्रेरी का इस्तेमाल किया जाता है, तो सिर्फ़ वह कोड लिखना होगा जिसकी ज़रूरत लाइब्रेरी में आपका डेटा टेबल के तौर पर उपलब्ध कराने के लिए होती है.
  • Java डेटा सोर्स लाइब्रेरी - यह अनुरोध और रिस्पॉन्स को मैनेज करती है और आपके दिए गए डेटा से रिस्पॉन्स टेबल बनाती है. साथ ही, यह Google Chart Tools की एसक्यूएल क्वेरी लैंग्वेज को लागू करती है.
  • Python डेटा सोर्स लाइब्रेरी - रिस्पॉन्स टेबल बनाने से, रिस्पॉन्स सिंटैक्स जनरेट होता है. यह अनुरोध पार्स नहीं करता या Google Chart टूल एसक्यूएल क्वेरी लैंग्वेज को लागू नहीं करता.
    
    या
    
    
• शुरुआत से अपना डेटा सोर्स लिखें. इसके लिए, अनुरोध को मैनेज करें, DataTable बनाएं, और जवाब भेजें.

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

1. डेटा सोर्स, डेटा सोर्स यूआरएल नाम का एक यूआरएल दिखाता है, जिस पर चार्ट एचटीटीपी जीईटी अनुरोध भेजते हैं.
2. क्लाइंट, कई पैरामीटर के साथ एचटीटीपी जीईटी अनुरोध करता है. इन पैरामीटर से पता चलता है कि दिए गए डेटा, वैकल्पिक क्वेरी स्ट्रिंग, और वैकल्पिक कस्टम पैरामीटर के लिए कौनसे फ़ॉर्मैट का इस्तेमाल करना है.
3. डेटा सोर्स, अनुरोध को रिसीव और पार्स करता है, जैसा कि अनुरोध के फ़ॉर्मैट में बताया गया है.
4. डेटा सोर्स, अनुरोध किए गए फ़ॉर्मैट में डेटा तैयार करता है. आम तौर पर, यह एक JSON टेबल होती है. रिस्पॉन्स के फ़ॉर्मैट, रिस्पॉन्स के फ़ॉर्मैट सेक्शन में दिए गए हैं. Datasource में विकल्प के तौर पर, विज़ुअलाइज़ेशन एपीआई क्वेरी की भाषा का इस्तेमाल किया जा सकता है. इस भाषा में डेटा को फ़िल्टर करने, क्रम से लगाने, और डेटा में बदलाव करने के अन्य तरीके शामिल होते हैं.
5. डेटा सोर्स ऐसा एचटीटीपी रिस्पॉन्स बनाता है जिसमें क्रम से लगाए गए डेटा और रिस्पॉन्स के अन्य पैरामीटर शामिल होते हैं. इसके बाद, इसे रिस्पॉन्स फ़ॉर्मैट में बताए गए तरीके से क्लाइंट को वापस भेजा जाता है

ध्यान दें: अनुरोधों और जवाबों (जैसे कि responseHandler और "ok") के लिए इस दस्तावेज़ में दिए गए सभी पैरामीटर और स्ट्रिंग की कॉन्सटेंट वैल्यू, लोअरकेस और केस-सेंसिटिव होती हैं.

ज़रूरी शर्तें

चार्ट टूल डेटा सोर्स के तौर पर इस्तेमाल करने के लिए ज़रूरी शर्तें:

• डेटा सोर्स को एचटीटीपी जीईटी अनुरोध स्वीकार करने चाहिए और यह आपके क्लाइंट के लिए उपलब्ध होना चाहिए.
• प्रोटोकॉल, वर्शन स्कीम (मौजूदा वर्शन 0.6 है) में बदलाव कर सकता है और उसके साथ काम कर सकता है. इसलिए, आपके डेटा सोर्स को पिछले वर्शन के साथ-साथ मौजूदा वर्शन का इस्तेमाल करने वाले अनुरोधों के साथ काम करना चाहिए. आपको नए वर्शन के रिलीज़ होते ही, उन्हें सपोर्ट करने की कोशिश करनी चाहिए, ताकि नए वर्शन में तेज़ी से अपग्रेड करने वाले क्लाइंट की परफ़ॉर्मेंस पर असर न पड़े.
• अगर अनुरोध के तौर पर अनजान प्रॉपर्टी भेजी जाती हैं, तो अनुरोध पूरा न करें. ऐसा इसलिए है, क्योंकि नए वर्शन में ऐसी नई प्रॉपर्टी शामिल हो सकती हैं जिनकी आपको जानकारी न हो.
• सिर्फ़ उन प्रॉपर्टी को पार्स करें जिनकी आपको उम्मीद है. नए वर्शन में नई प्रॉपर्टी हो सकती हैं, लेकिन बिना सोचे-समझे अनुरोध वाली स्ट्रिंग को स्वीकार न करें और उसका इस्तेमाल न करें. नुकसान पहुंचाने वाले हमलों से बचने के लिए, अपनी ज़रूरत के हिसाब से प्रॉपर्टी को पार्स करें और उनका इस्तेमाल करें.
• अगर क्लाइंट चार्ट को खुद कोड नहीं किया जा रहा है, तो अपने डेटा सोर्स की ज़रूरी शर्तों को ध्यान से दस्तावेज़ करें. इसमें नीचे दी गई जानकारी को दस्तावेज़ करना शामिल है:
  • कोई भी कस्टम पैरामीटर जिसे आप स्वीकार करते हैं,
  • Google विज़ुअलाइज़ेशन एपीआई क्वेरी की भाषा को पार्स किया जा सकता है या नहीं, और
  • आपको किस तरह का डेटा दिखाया जाता है और उस डेटा का स्ट्रक्चर कैसा है (पंक्तियों और कॉलम में क्या दिखाया जाता है और उस डेटा को कैसे लेबल किया जाता है).
• जो साइट अज्ञात क्लाइंट से अनुरोध स्वीकार करती है, उस पर सुरक्षा से जुड़ी सभी मानक सावधानियां रखें. अनुरोधों की पुष्टि करने या नुकसान पहुंचाने वाले हमलों से सुरक्षित रहने में मदद करने के लिए, अपने पैरामीटर में एमडी5, हैशिंग, और सुरक्षा के अन्य तरीकों का इस्तेमाल किया जा सकता है. साथ ही, यह उम्मीद की जा सकती है कि क्लाइंट को आपकी ज़रूरी शर्तों के बारे में पता होगा और वे उनका जवाब देंगे. हालांकि, अगर आपने चार्ट को खुद कोड करने का विकल्प नहीं चुना है, तो यह पक्का कर लें कि आपने सभी ज़रूरी शर्तों को अच्छी तरह से दस्तावेज़ में शामिल कर लिया हो. नीचे सुरक्षा से जुड़ी ज़रूरी बातें देखें.
• सभी अनुरोध और रिस्पॉन्स स्ट्रिंग, UTF-8 कोड में बदली जानी चाहिए.
• सबसे ज़रूरी रिस्पॉन्स फ़ॉर्मैट JSON है. पहले JSON को लागू करना न भूलें, क्योंकि ज़्यादातर चार्ट में इसी फ़ॉर्मैट का इस्तेमाल किया जाता है. बाद में दूसरी तरह के जवाब जोड़ें.
• आपके लिए विज़ुअलाइज़ेशन एपीआई क्वेरी की भाषा का इस्तेमाल करने की ज़रूरी नहीं है, लेकिन इससे आपका डेटा सोर्स ग्राहकों के लिए ज़्यादा काम का बन जाता है.
• आपको किसी भी तरह के चार्ट के अनुरोधों के लिए, ज़रूरी नहीं है. साथ ही, कस्टम चार्ट के लिए, कस्टम पैरामीटर इस्तेमाल किए जा सकते हैं. हालांकि, आपको नीचे बताए गए स्टैंडर्ड फ़ॉर्मैट में जवाब देने चाहिए.

सुरक्षा के लिए ध्यान देने वाली बातें

डेटा सोर्स डिज़ाइन करते समय, आपको यह ध्यान रखना होगा कि आपका डेटा कितना सुरक्षित होना चाहिए. अपनी साइट के लिए, सुरक्षा से जुड़ी कई तरह की स्कीम का इस्तेमाल किया जा सकता है. इनमें पासवर्ड को आसान तरीके से ऐक्सेस करने और कुकी की मदद से पुष्टि करने जैसी सुविधाएं शामिल हैं.

चार्ट की वजह से, एक्सएसएसआई (क्रॉस-साइट स्क्रिप्ट शामिल करने) के हमलों का खतरा बना रहता है. उपयोगकर्ता ऐसे पेज पर जा सकता है जिसमें नुकसान पहुंचाने वाली स्क्रिप्ट है. इसके बाद, वह मौजूदा उपयोगकर्ता के क्रेडेंशियल का इस्तेमाल करके, डेटा सोर्स के यूआरएल में क्वेरी करने की कोशिश करना शुरू कर देता है. अगर उपयोगकर्ता किसी साइट से लॉग आउट नहीं होता है, तो स्क्रिप्ट की पुष्टि मौजूदा उपयोगकर्ता के तौर पर की जाएगी और उसके पास उस साइट पर अनुमतियां होंगी. <script src> टैग का इस्तेमाल करके, नुकसान पहुंचाने वाली स्क्रिप्ट JSONP की तरह ही डेटा सोर्स शामिल कर सकती है.

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

यह पक्का करने के लिए कि अनुरोध वाकई आपके डोमेन से ही आ रहा है, न कि किसी बाहरी डोमेन से (या डोमेन के अंदर किसी ब्राउज़र से, जिस पर XSRF हमला किया गया है ):

• अनुरोध में "X-DataSource-Auth" हेडर के मौजूद होने की पुष्टि करें. यह हेडर, Google विज़ुअलाइज़ेशन एपीआई से तय होता है. आपको इस हेडर के कॉन्टेंट की जांच करने की ज़रूरत नहीं है. आपको सिर्फ़ इस बात की पुष्टि करनी है कि यह हेडर मौजूद है. Google चार्ट टूल की डेटा सोर्स लाइब्रेरी का इस्तेमाल करने पर, लाइब्रेरी से इसे अपने लिए मैनेज किया जा सकता है.
• क्लाइंट की पुष्टि करने के लिए, कुकी की पुष्टि करने की सुविधा का इस्तेमाल करें. किसी क्रॉस-डोमेन अनुरोध में कस्टम हेडर डालने का कोई तरीका उपलब्ध नहीं है. हालांकि, पुष्टि करने वाली कुकी मौजूद रहेंगी.
• <script src> टैग के साथ शामिल करने पर, JavaScript के चलने की संभावना न होना. ऐसा करने के लिए, JSON कोड की शुरुआत में )]}' लगाएं. इसके बाद, एक नई लाइन लिखें. अपने क्लाइंट के जवाब में से प्रीफ़िक्स को निकालें. XmlHttpRequest के लिए, ऐसा सिर्फ़ तब किया जा सकता है, जब अनुरोध उसी डोमेन से किया गया हो.

अनुरोध का फ़ॉर्मैट

क्लाइंट कई पैरामीटर के साथ एचटीटीपी जीईटी अनुरोध भेजता है. इनमें कस्टम एलिमेंट, वैकल्पिक क्वेरी स्ट्रिंग, हस्ताक्षर, और अन्य एलिमेंट शामिल हैं. इस सेक्शन में दिए गए पैरामीटर को पार्स करने की ज़िम्मेदारी आपकी है. साथ ही, आपको इस बात का ध्यान रखना चाहिए कि नुकसान पहुंचाने वाले हमलों से बचने के लिए, आप दूसरों की मदद न करें.

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

यहां अनुरोधों के कुछ सैंपल दिए गए हैं. इस दस्तावेज़ के आखिर में, अनुरोधों और रिस्पॉन्स के और सैंपल उदाहरण में देखे जा सकते हैं:

ध्यान दें: नीचे दी गई अनुरोध स्ट्रिंग और उदाहरण सेक्शन में दिखाई गई स्ट्रिंग को भेजने से पहले, उनका यूआरएल एस्केप होना चाहिए.

Basic request, no parameters:
http://www.example.com/mydatasource

Request with the tqx parameter that contains two properties:
http://www.example.com/mydatasource?tqx=reqId:0;sig:4641982796834063168

Request with a query string:
http://www.example.com/mydatasource?tq=limit 1

यहां अनुरोध स्ट्रिंग में मौजूद सभी स्टैंडर्ड पैरामीटर की सूची दी गई है. ध्यान रखें कि दोनों पैरामीटर के नाम (जैसे कि "वर्शन") और कॉन्स्टेंट स्ट्रिंग वैल्यू (जैसे कि "ok", "warning", और "not_modified") केस-सेंसिटिव (बड़े और छोटे अक्षरों में अंतर) होते हैं. टेबल में यह भी बताया जाता है कि पैरामीटर को भेजना ज़रूरी है या नहीं. साथ ही, अगर भेजा जाता है, तो उसे मैनेज करना आपके लिए ज़रूरी है या नहीं.

जवाब का फ़ॉर्मैट

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

• JSON - यह JSON रिस्पॉन्स दिखाता है कि इसमें JavaScript ऑब्जेक्ट का डेटा शामिल होता है. इस डेटा को पॉप्युलेट करने के लिए, सीधे DataTable कंस्ट्रक्टर में पास किया जा सकता है. यह अब तक का सबसे सामान्य अनुरोध है. साथ ही, उसे ठीक से लागू करना सबसे ज़रूरी भी है.
• CSV - यह कॉमा लगाकर अलग की गई, वैल्यू की सूची दिखाता है, जिसे ब्राउज़र मैनेज करता है.
• TSV - ब्राउज़र की ओर से हैंडल की जाने वाली, टैब से अलग की गई वैल्यू की सूची दिखाता है.
• एचटीएमएल - ब्राउज़र में रेंडर की जाने वाली एचटीएमएल टेबल दिखाता है.

ये आउटपुट फ़ॉर्मैट जनरेट करने के लिए, Google विज़ुअलाइज़ेशन डेटा सोर्स लाइब्रेरी (JavaScript) या विज़ुअलाइज़ेशन Python लाइब्रेरी का इस्तेमाल किया जा सकता है.

JSON रिस्पॉन्स फ़ॉर्मैट

अगर अनुरोध में "X-DataSource-Auth" हेडर शामिल किया जाता है, तो रिस्पॉन्स का डिफ़ॉल्ट फ़ॉर्मैट JSON होता है. अगर ऐसा नहीं है, तो JSONP शामिल होता है. ध्यान दें कि Google चार्ट क्लाइंट, दरअसल JSON और JSONP के बदले गए वर्शन के साथ काम करता है. अगर Java या Python हेल्पर लाइब्रेरी का इस्तेमाल किया जा रहा है, तो वे आपको सही कोड देंगे. अगर आपने मैन्युअल तरीके से जवाबों को पार्स किया है, तो नीचे JSON में बदलाव देखें.

एक जैसे डोमेन वाले अनुरोधों को लागू करने पर, आपको अनुरोध में "X-DataSource-Auth" हेडर की मौजूदगी की पुष्टि करनी चाहिए और अनुमति देने वाली कुकी का इस्तेमाल करना चाहिए.

जवाब के लिए सिर्फ़ यही एक ऐसा फ़ॉर्मैट है जिसे Google विज़ुअलाइज़ेशन एपीआई तरीके google.visualization.Query.send() से तय किया जाता है. JSON के अनुरोधों और रिस्पॉन्स के कुछ उदाहरण, इस पेज के आखिर में उदाहरण में देखे जा सकते हैं. आपके लिए यह रिस्पॉन्स स्ट्रिंग बनाने के लिए, Java या Python हेल्पर लाइब्रेरी का इस्तेमाल किया जा सकता है.

रिस्पॉन्स का यह फ़ॉर्मैट, UTF-8 में एन्कोड किया गया JSON ऑब्जेक्ट है. यह एक ऐसा ऑब्जेक्ट है जिसे ब्रैकेट { } के साथ रैप किया जाता है और हर प्रॉपर्टी को कॉमा लगाकर अलग किया जाता है. इसमें, यहां दी गई टेबल में मौजूद प्रॉपर्टी शामिल होती हैं (डेटा table प्रॉपर्टी को असाइन किया जाता है). इस JSON ऑब्जेक्ट को अनुरोध से, responseHandler पैरामीटर वैल्यू के अंदर रैप किया जाना चाहिए. इसलिए, अगर अनुरोध की responseHandler वैल्यू "myHandler" थी, तो आपको इस तरह की स्ट्रिंग दिखानी चाहिए (छोटी चीज़ों के लिए सिर्फ़ एक प्रॉपर्टी दिखती है):

"myHandler({status:ok, ...})"

अगर अनुरोध में responseHandler वैल्यू शामिल नहीं है, तो डिफ़ॉल्ट वैल्यू "google.Visualization.Query.setResponse" होती है. इसलिए, आपको इस तरह की स्ट्रिंग दिखानी चाहिए (छोटा करने के लिए सिर्फ़ एक प्रॉपर्टी दिखाई जाती है):

"google.visualization.Query.setResponse({status:ok, ...})"

यहां रिस्पॉन्स ऑब्जेक्ट में मौजूद सदस्यों की जानकारी दी गई है:

{cols:[{id:'Col1',label:'',type:'number'}],
 rows:[{c:[{v:1.0,f:'1'}]},
       {c:[{v:2.0,f:'2'}]},
       {c:[{v:3.0,f:'3'}]},
       {c:[{v:1.0,f:'1'}]}
      ]
} 

JSON से मिले जवाबों को ऑप्टिमाइज़ करना

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

1. क्लाइंट, डेटा सोर्स को एक अनुरोध भेजता है.
2. डेटा सोर्स, DataTable के साथ-साथ DataTable ऑब्जेक्ट का हैश जनरेट करता है. साथ ही, रिस्पॉन्स में दोनों को दिखाता है (हैश tqx.sig पैरामीटर में दिखाया जाता है). Google विज़ुअलाइज़ेशन API क्लाइंट, DataTable और sig वैल्यू को कैश मेमोरी में सेव करता है.
3. क्लाइंट, डेटा के लिए एक और अनुरोध भेजता है. इसमें कैश मेमोरी में सेव tqx.sig वैल्यू भी शामिल होती है.
4. डेटा सोर्स इनमें से किसी एक तरीके से जवाब दे सकता है:
   • अगर पिछले अनुरोध से डेटा में बदलाव हुआ है, तो डेटा सोर्स नया DataTable और sig वैल्यू हैश वापस भेजता है.
   • अगर डेटा में पिछले अनुरोध के मुकाबले बदलाव नहीं हुआ है, तो डेटा सोर्स status=error, reason=not_modified, sig=old_sig_value वापस भेज देता है.
5. दोनों ही मामलों में, चार्ट को होस्ट करने वाले पेज को सही रिस्पॉन्स मिलता है. साथ ही, वह QueryResponse.getDataTable() पर कॉल करके, DataTable को वापस पा सकता है. अगर डेटा एक जैसा है, तो वह सिर्फ़ टेबल का कैश मेमोरी में सेव किया गया वर्शन होगा.

ध्यान दें कि यह सिर्फ़ Google विज़ुअलाइज़ेशन एपीआई पर बनाए गए चार्ट से JSON अनुरोधों के लिए काम करता है.

CSV वाला रिस्पॉन्स फ़ॉर्मैट

अगर अनुरोध में out:csv का इस्तेमाल किया जाता है, तो रिस्पॉन्स में कोई मेटाडेटा शामिल नहीं होता. इसके बजाय, इसमें डेटा को सिर्फ़ CSV फ़ॉर्मैट में दिखाया जाता है. आम तौर पर, CSV टेबल एक कॉमा लगाकर अलग की गई सूची होती है, जहां डेटा की हर पंक्ति, वैल्यू की कॉमा-सेपरेटेड लिस्ट होती है. इसके आखिर में, एक UNIX न्यूलाइन वर्ण (\n) होता है. हर कॉलम के लिए, सेल की वैल्यू एक ही तरह होनी चाहिए. पहली पंक्ति कॉलम लेबल है. यहां तीन पंक्ति वाली, तीन कॉलम वाली टेबल का एक उदाहरण दिया गया है:

A, B, C
1.0, "yes", true
2.0, "no", false
3.0, "maybe", true

इस प्रोटोकॉल में CSV फ़ाइल फ़ॉर्मैट नहीं बताया गया है. अपना CSV फ़ॉर्मैट तय करने की ज़िम्मेदारी डेटा सोर्स की है. हालांकि, सामान्य फ़ॉर्मैट, वैल्यू का एक ऐसा सेट होता है जिसे कॉमा लगाकर अलग किया जाता है (इसमें बीच में स्पेस नहीं होता). साथ ही, हर लाइन के आखिर में एक नई लाइन (\n) होती है. जब किसी ब्राउज़र को CSV स्ट्रिंग वाला जवाब मिलता है, तो वह उपयोगकर्ता से पूछ सकता है कि स्ट्रिंग को खोलने के लिए कौनसे ऐप्लिकेशन का इस्तेमाल करना है. इसके अलावा, वह उसे स्क्रीन पर रेंडर भी कर सकता है. Java और Python की ओपन सोर्स लाइब्रेरी, DataTable को CSV स्ट्रिंग में बदलने का तरीका उपलब्ध कराती हैं.

अगर अनुरोध में tqx पैरामीटर में शामिल outFileName सदस्य शामिल है, तो आपको रिस्पॉन्स हेडर में फ़ाइल का नाम शामिल करने की कोशिश करनी चाहिए.

google.visualization.Query ऑब्जेक्ट, CSV रिस्पॉन्स के लिए अनुरोध करने की सुविधा नहीं देता. अगर कोई क्लाइंट CSV का अनुरोध करना चाहता है, तो अपने पेज पर विज़ुअलाइज़ेशन टूलबार गैजेट एम्बेड किया जा सकता है या अनुरोध करने के लिए कस्टम कोड का इस्तेमाल किया जा सकता है. इसके अलावा, ऐसा लिंक दिया जा सकता है जो tqx की out:csv प्रॉपर्टी को साफ़ तौर पर सेट करता हो, जैसा कि यहां दिए गए अनुरोध यूआरएल में दिखाया गया है:

अनुरोध करें

http://www.example.com/mydatasource?tqx=reqId:1;out:csv

जवाब

Label 1,Label2\n1,a\n2,b\n3,c\n4,d

TSV रिस्पॉन्स फ़ॉर्मैट

अगर अनुरोध में out:tsv-excel के बारे में बताया गया है, तो रिस्पॉन्स में कोई मेटाडेटा शामिल नहीं होता. इसके बजाय, डेटा को टैब से अलग करके दिखाया जाता है, जिसे utf-16 कोड में बदला गया होता है. अगर अनुरोध में tqx पैरामीटर में शामिल outFileName सदस्य शामिल है, तो आपको रिस्पॉन्स हेडर में फ़ाइल का नाम शामिल करने की कोशिश करनी चाहिए.

एचटीएमएल रिस्पॉन्स फ़ॉर्मैट

अगर अनुरोध में out:html के बारे में बताया गया है, तो रिस्पॉन्स एक एचटीएमएल पेज होना चाहिए, जिसमें डेटा के साथ एचटीएमएल टेबल परिभाषित हो. इससे आपके कोड को डीबग करने में मदद मिलती है, क्योंकि ब्राउज़र आपके नतीजे को सीधे पढ़ने लायक फ़ॉर्मैट में रेंडर कर सकता है. google.visualization.Query ऑब्जेक्ट का इस्तेमाल करके, एचटीएमएल रिस्पॉन्स के लिए क्वेरी नहीं भेजी जा सकती. आपको कस्टम कोड का इस्तेमाल करके या इससे मिलता-जुलता यूआरएल अपने ब्राउज़र में लिखकर, एचटीएमएल रिस्पॉन्स के लिए क्वेरी करनी होगी:

अनुरोध करें

http://www.example.com/mydatasource?tqx=reqId:1;out:html

जवाब

<html><body><table border='1' cellpadding='2' cellspacing='0'><tr style='font-weight: bold; background-color: #aaa;'><td>label 1</td><td>label 2</td></tr><tr bgcolor='#f0f0f0'><td align='right'>1</td><td>a</td></tr><tr bgcolor='#ffffff'><td align='right'>2</td><td>b</td></tr><tr bgcolor='#f0f0f0'><td align='right'>3</td><td>c</td></tr><tr bgcolor='#ffffff'><td align='right'>4</td><td>d</td></tr></table></body></html>

उदाहरण

यहां अनुरोधों और जवाबों के कुछ उदाहरण दिए गए हैं. ध्यान दें कि अनुरोध, यूआरएल-एस्केप नहीं किए गए हैं. आम तौर पर, ऐसा ब्राउज़र या google.visualization.Query ऑब्जेक्ट से किया जाता है.

सरल अनुरोध: तीन कॉलम, चार पंक्ति वाली टेबल के साथ बुनियादी जानकारी देता है.

Request:
http://www.example.com/mydatasource

Response
google.visualization.Query.setResponse({version:'0.6',reqId:'0',status:'ok',sig:'5982206968295329967',table:{cols:[{id:'Col1',label:'',type:'number'},{id:'Col2',label:'',type:'number'},{id:'Col3',label:'',type:'number'}],rows:[{c:[{v:1.0,f:'1'},{v:2.0,f:'2'},{v:3.0,f:'3'}]},{c:[{v:2.0,f:'2'},{v:3.0,f:'3'},{v:4.0,f:'4'}]},{c:[{v:3.0,f:'3'},{v:4.0,f:'4'},{v:5.0,f:'5'}]},{c:[{v:1.0,f:'1'},{v:2.0,f:'2'},{v:3.0,f:'3'}]}]}});

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

Request:
http://www.example.com/mydatasource?tqx=responseHandler:myHandlerFunction

Response
myHandlerFunction({version:'0.6',reqId:'0',status:'ok',sig:'4641982796834063168',table:{cols:[{id:'A',label:'NEW A',type:'string'},{id:'B',label:'B-label',type:'number'},{id:'C',label:'C-label',type:'datetime'}],rows:[{c:[{v:'a'},{v:1.0,f:'1'},{v:new Date(2008,1,28,0,31,26),f:'2/28/08 12:31 AM'}]},{c:[{v:'b'},{v:2.0,f:'2'},{v:new Date(2008,2,30,0,31,26),f:'3/30/08 12:31 AM'}]},{c:[{v:'c'},{v:3.0,f:'3'},{v:new Date(2008,3,30,0,31,26),f:'4/30/08 12:31 AM'}]}]}});

सरल क्वेरी स्ट्रिंग वाली क्वेरी: किसी एक कॉलम के लिए अनुरोध करने पर, चार पंक्तियों वाला एक कॉलम दिखाता है.

Request:
http://www.example.com/mydatasource?tq=select Col1

Response:
google.visualization.Query.setResponse({version:'0.6',reqId:'0',status:'ok',sig:'6099996038638149313',table:{cols:[{id:'Col1',label:'',type:'number'}],rows:[{c:[{v:1.0,f:'1'}]},{c:[{v:2.0,f:'2'}]},{c:[{v:3.0,f:'3'}]},{c:[{v:1.0,f:'1'}]}]}});

डेटा में बदलाव नहीं होने की गड़बड़ी: not_modified गड़बड़ी का उदाहरण.

Request:
http://www.example.com/mydatasource?tqx=reqId:0;sig:4641982796834063168

Response:
google.visualization.Query.setResponse({version:'0.6',reqId:'0',status:'error',errors:[{reason:'not_modified',message:'Data not modified'}]});

डेटा में काट-छांट की चेतावनी: data_truncated चेतावनी का उदाहरण. ध्यान दें कि अनुरोध अब भी डेटा दिखाता है.

Request:
http://www.example.com/mydatasource?tq=limit 1

Response:
google.visualization.Query.setResponse({version:'0.6',reqId:'0',status:'warning',warnings:[{reason:'data_truncated',message:'Retrieved data was truncated'}],sig:'1928724788649668508',table:{cols:[{id:'A',label:'NEW A',type:'string'},{id:'B',label:'B-label',type:'number'},{id:'C',label:'C-label',type:'datetime'}],rows:[{c:[{v:'a'},{v:1.0,f:'1'},{v:new Date(2008,1,28,0,31,26),f:'2/28/08 12:31 AM'}]}]}});

ऐक्सेस अस्वीकार होने की गड़बड़ी: access_denied गड़बड़ी का उदाहरण.

Request:
http://www.example.com/mydatasource

Response:
google.visualization.Query.setResponse({version:'0.6',reqId:'0',status:'error',errors:[{reason:'access_denied',message:'Access denied',detailed_message:'Access Denied'}]});

अमान्य क्वेरी स्ट्रिंग: अमान्य क्वेरी स्ट्रिंग वाले अनुरोध का उदाहरण. ध्यान दें कि ज़्यादा जानकारी वाला मैसेज, गड़बड़ी के असल मैसेज के बजाय एक सामान्य मैसेज है.

Request:
http://www.example.com/mydatasource?tq=select A

Response:
google.visualization.Query.setResponse({version:'0.6',reqId:'0',status:'error',errors:[{reason:'invalid_query',message:'Invalid query',detailed_message:'Bad query string.'}]});

विकास डिवाइस

• Java डेटा सोर्स लाइब्रेरी (Google की ओर से) - अनुरोध और रिस्पॉन्स को मैनेज करती है, आपके दिए गए डेटा से रिस्पॉन्स टेबल बनाती है, और Google Chart Tools की एसक्यूएल क्वेरी लैंग्वेज को लागू करती है.
• Python डेटा सोर्स लाइब्रेरी (Google की ओर से) - रिस्पॉन्स टेबल बनाने से रिस्पॉन्स सिंटैक्स जनरेट होता है. यह अनुरोध को पार्स करने या Google Chart टूल की एसक्यूएल क्वेरी लैंग्वेज को लागू करने की प्रोसेस को मैनेज नहीं करता.
• MC-Google_विज़ुअलाइज़ेशन (तीसरा पक्ष) - यह PHP सर्वर-साइड की लाइब्रेरी है. पीडीओ का इस्तेमाल करके, MySQL, SQLite, और PostgreSQL डेटाबेस इंजन के लिए Chart Tools Datasource लागू किया जा सकता है.
• bortosky-google-विज़ुअलाइज़ेशन (तीसरे पक्ष) - यह .NET उपयोगकर्ताओं के लिए Google विज़ुअलाइज़ेशन API Datatable बनाने में मदद करने वाली लाइब्रेरी है.
• जीवी स्ट्रीमर (तीसरा पक्ष) - जीवी स्ट्रीमर एक सर्वर साइड टूल है. यह अलग-अलग सोर्स से मिले डेटा को Google चार्ट में, क्वेरी के मान्य रिस्पॉन्स में बदल सकता है. GV Streamer कई भाषाओं (उदाहरण के लिए, PHP, Java, .NET) और कई रॉ डेटा सोर्स (उदाहरण के लिए, MySql) के साथ काम करता है.
• TracGViz (तीसरा पक्ष) - TracGViz एक मुफ़्त और ओपन सोर्स टूल है, जो कॉम्पोनेंट उपलब्ध कराता है. इसकी मदद से, Trac, चार्ट में मौजूद गैजेट का इस्तेमाल कर सकता है. साथ ही, Trac से मैनेज किए जाने वाले डेटा को, Google के चार्ट में मौजूद टूल के डेटा सोर्स के तौर पर इस्तेमाल करता है.
• vis-table (तीसरा पक्ष) - PHP में Google Chart टूल डेटा सोर्स को लागू करने वाली लाइब्रेरी. इसके तीन मुख्य हिस्से हैं. डेटा टेबल को लागू करने का तरीका, क्वेरी लैंग्वेज पार्सर, और फ़ॉर्मैटर.
• Oracle PL/SQL में Google का डेटा सोर्स लागू करना (तीसरा पक्ष) - ऐसा Oracle PL/SQL पैकेज, जो Oracle को डेटाबेस से सीधे डेटा सोर्स से सर्वर पर ले जाने की सुविधा देता है. इसलिए, किसी भी Oracle क्वेरी को Google Chart टूल डेटा सोर्स के तौर पर इस्तेमाल किया जा सकता है (पैकेज, डेटा के साथ JSON फ़ाइल देगा). यह Google क्वेरी लैंग्वेज के लिए करीब-करीब पूरी तरह से काम करता है.