این صفحه توضیح می دهد که چگونه می توانید سرویسی را پیاده سازی کنید که از پروتکل Chart Tools Datasource پشتیبانی می کند تا داده ها را با استفاده از کلاس Query در معرض نمودارها قرار دهد.
فهرست
حضار
این صفحه عمدتاً برای توسعه دهندگانی است که منبع داده خود را بدون کمک کتابخانه منبع داده ابزار نمودار ایجاد می کنند. اگر از آن یا هر کتابخانه کمکی دیگری استفاده می کنید، ابتدا اسناد کتابخانه خود را بخوانید.
این صفحه همچنین برای خوانندگان علاقه مند به درک پروتکل سیم مورد استفاده برای ارتباط بین تجسم مشتری و منبع داده در نظر گرفته شده است.
اگر در حال ایجاد یا استفاده از تصویرسازی هستید، نیازی به خواندن این صفحه ندارید.
برای خواندن این سند، باید دستور اولیه JSON و HTTP درخواست را بدانید. همچنین باید درک کنید که نمودارها از دیدگاه کاربر چگونه کار می کنند.
بررسی اجمالی
شما می توانید پروتکل Chart Tools Datasource را پیاده سازی کنید تا به یک ارائه دهنده منبع داده برای نمودارهای خود یا نمودارهای دیگر تبدیل شوید. یک منبع داده ابزار نمودار یک URL به نام URL منبع داده را نشان می دهد که نمودار می تواند درخواست های HTTP GET را به آن ارسال کند. در پاسخ، منبع داده، داده‌هایی با فرمت مناسب را برمی‌گرداند که نمودار می‌تواند از آن برای نمایش گرافیک در صفحه استفاده کند. این پروتکل درخواست-پاسخ به عنوان پروتکل سیمی Google Visualization API شناخته می شود.
داده هایی که توسط یک منبع داده ارائه می شود را می توان از منابع مختلفی مانند یک فایل یا پایگاه داده استخراج کرد. تنها محدودیت این است که می توانید داده ها را به صورت یک جدول دو بعدی با ستون های تایپ شده قالب بندی کنید.
به عنوان منبع داده ابزار نمودار، شما باید یک درخواست را در یک قالب خاص تجزیه و تحلیل کنید و یک پاسخ را در یک قالب خاص برگردانید. شما می توانید این کار را به یکی از دو روش کلی انجام دهید:
- از یکی از کتابخانه های کمکی زیر برای رسیدگی به درخواست و پاسخ استفاده کنید و DataTable را برای بازگشت بسازید. اگر از یکی از این کتابخانه ها استفاده می کنید، فقط باید کد مورد نیاز برای در دسترس قرار دادن داده های خود را در قالب یک جدول در کتابخانه بنویسید.
- کتابخانه منبع داده جاوا - درخواست و پاسخ را مدیریت می‌کند، جدول پاسخ را از داده‌هایی که به آن می‌دهید ایجاد می‌کند و زبان پرس و جو SQL ابزار نمودار Google را پیاده‌سازی می‌کند.
- کتابخانه منبع داده پایتون - یک جدول پاسخ ایجاد می کند و دستور پاسخ را ایجاد می کند. تجزیه درخواست یا پیاده سازی زبان پرس و جو SQL Google Chart Tools را انجام نمی دهد .
یا
- با مدیریت درخواست، ساخت DataTable و ارسال پاسخ ، منبع داده خود را از ابتدا بنویسید .
چگونه کار می کند:
- منبع داده یک URL به نام URL منبع داده را نشان می دهد که نمودارها یک درخواست HTTP GET را برای آن ارسال می کنند.
- کلاینت یک درخواست HTTP GET با پارامترهایی ایجاد می کند که توصیف می کند از چه قالبی برای داده های برگشتی استفاده شود، یک رشته پرس و جو اختیاری و پارامترهای سفارشی اختیاری.
- منبع داده همانطور که در فرمت درخواست توضیح داده شده است، درخواست را دریافت و تجزیه می کند.
- منبع داده داده ها را در قالب درخواستی آماده می کند. به طور معمول، این یک جدول JSON است. فرمت های پاسخ در بخش قالب پاسخ پوشش داده شده است. منبع داده می تواند به صورت اختیاری از زبان پرس و جو Visualization API پشتیبانی کند که فیلتر کردن، مرتب سازی و سایر دستکاری داده ها را مشخص می کند.
- منبع داده یک پاسخ HTTP ایجاد می کند که شامل داده های سریال و سایر پارامترهای پاسخ است و همانطور که در Response Format توضیح داده شده است آن را به مشتری ارسال می کند.
توجه: تمام پارامترها و مقادیر ثابت رشته‌ای که در این سند برای درخواست‌ها و پاسخ‌ها فهرست شده‌اند (مانند responseHandler و "ok") به حروف کوچک و حساس هستند.
حداقل الزامات
اینها حداقل شرایط لازم برای خدمت به عنوان منبع داده ابزار نمودار هستند:
- منبع داده باید درخواست های HTTP GET را بپذیرد و باید در دسترس مشتریان شما باشد.
- این پروتکل می تواند یک طرح نسخه را تغییر دهد و از آن پشتیبانی می کند (نسخه فعلی 0.6 است)، بنابراین منبع داده شما باید از درخواست هایی با استفاده از نسخه های قبلی و همچنین نسخه فعلی پشتیبانی کند. شما باید سعی کنید به محض انتشار نسخه های جدید را پشتیبانی کنید تا از شکستن کلاینت هایی که به سرعت به جدیدترین نسخه ارتقا می یابند جلوگیری کنید.
- اگر ویژگی های ناشناخته به عنوان بخشی از درخواست ارسال شود، شکست نخورید. این به این دلیل است که نسخه های جدید می توانند ویژگی های جدیدی را معرفی کنند که شما از آنها بی اطلاع هستید.
- تنها خواصی را که انتظار دارید تجزیه کنید. اگرچه نسخه‌های جدید ممکن است ویژگی‌های جدیدی را معرفی کنند، کورکورانه آن را قبول نکنید و از کل رشته درخواست استفاده نکنید. برای محافظت از خود در برابر حملات مخرب، به دقت تجزیه و تحلیل کنید و فقط از ویژگی هایی که انتظار دارید استفاده کنید.
- اگر خودتان نمودارهای مشتری را کدنویسی نمی کنید ، الزامات منبع داده خود را با دقت مستند کنید . این شامل مستندسازی اطلاعات زیر است:
- هر پارامتر سفارشی که قبول می کنید،
- اینکه آیا می توانید زبان پرس و جوی Google Visualization API را تجزیه کنید یا نه، و
- چه نوع داده‌هایی را برمی‌گردانید، و ساختار آن داده‌ها (آنچه سطرها و ستون‌ها نشان می‌دهند و هر برچسب‌گذاری).
- تمام اقدامات احتیاطی استاندارد امنیتی را برای سایتی که درخواست های مشتریان ناشناس را می پذیرد، انجام دهید . شما می توانید به طور منطقی از MD5، هش کردن و سایر مکانیسم های امنیتی در پارامترهای خود برای احراز هویت درخواست ها یا کمک به ایمن سازی در برابر حملات مخرب پشتیبانی کنید و از مشتریان انتظار داشته باشید که از نیازهای شما آگاه باشند و به آنها پاسخ دهند. با این حال، اگر خودتان نمودارها را کدنویسی نمی کنید، مطمئن شوید که تمام نیازهای خود را به خوبی مستند کنید. ملاحظات امنیتی را در زیر ببینید.
- تمام رشته های درخواست و پاسخ باید با کد UTF-8 باشند.
- مهمترین فرمت پاسخ JSON است. حتماً ابتدا JSON را پیاده سازی کنید، زیرا این فرمتی است که توسط اکثر نمودارها استفاده می شود. سپس انواع دیگر پاسخ را اضافه کنید.
- شما نیازی به پشتیبانی از زبان پرس و جو Visualization API ندارید، اما منبع داده شما را برای مشتریان مفیدتر می کند.
- شما نیازی به پشتیبانی از درخواست‌ها از هر نوع نموداری ندارید و می‌توانید از پارامترهای سفارشی برای نمودارهای سفارشی پشتیبانی کنید. اما شما باید پاسخ ها را در قالب استانداردی که در زیر توضیح داده شده است، برگردانید.
ملاحظات امنیتی
هنگام طراحی منبع داده خود، باید میزان امنیت داده های خود را در نظر بگیرید. شما می توانید از انواع طرح های امنیتی برای سایت خود استفاده کنید، از دسترسی ساده به رمز عبور تا احراز هویت امن کوکی.
حملات XSSI (شامل اسکریپت بین سایتی) خطری برای نمودارها هستند. یک کاربر ممکن است به صفحه‌ای بروید که دارای یک اسکریپت مخرب است و سپس با استفاده از اعتبار کاربر فعلی شروع به تلاش برای ایجاد پرس و جو در URLهای منبع داده می‌کند. اگر کاربر از سایتی خارج نشده باشد، اسکریپت به عنوان کاربر فعلی احراز هویت می شود و مجوزهایی در آن سایت دارد. با استفاده از تگ <script src>، اسکریپت مخرب می تواند منبع داده را، مشابه JSONP، شامل شود.
به عنوان یک سطح امنیتی اضافی، می‌توانید درخواست‌ها را به درخواست‌هایی که از همان دامنه منبع داده شما می‌آیند محدود کنید. این امر به طور قابل توجهی دید منبع داده شما را محدود می کند، اما اگر داده های بسیار حساسی دارید که نباید از خارج از دامنه خود به آنها دسترسی پیدا کنید، باید آن را در نظر بگیرید. منبع داده‌ای که فقط درخواست‌های یک دامنه را مجاز می‌کند ، منبع داده محدود نامیده می‌شود، برخلاف منبع داده نامحدود ، که درخواست‌های هر دامنه را می‌پذیرد. در اینجا جزئیاتی در مورد نحوه پیاده سازی منبع داده محدود آورده شده است:
برای اطمینان از اینکه یک درخواست واقعاً از داخل دامنه شما می‌آید و نه از یک دامنه خارجی (یا مرورگر داخل دامنه‌ای که تحت حمله XSRF است):
- وجود هدر «X-DataSource-Auth» در درخواست را تأیید کنید. این هدر توسط Google Visualization API تعریف شده است. شما نیازی به بررسی محتویات این هدر ندارید، فقط بررسی کنید که وجود دارد. اگر از کتابخانه Google Chart Tools Datasource استفاده می‌کنید، می‌توانید کتابخانه این کار را برای شما انجام دهد.
- از احراز هویت کوکی برای احراز هویت مشتری استفاده کنید. هیچ راه شناخته شده ای برای تزریق هدرهای سفارشی به یک درخواست متقابل دامنه وجود ندارد و در عین حال کوکی های احراز هویت را در جای خود نگه دارید.
- اجرای جاوا اسکریپت را زمانی که همراه با تگ <script src> باشد، غیرممکن کنید. برای انجام این کار، پیشوند پاسخ JSON خود را با )]} و سپس یک خط جدید قرار دهید. در مشتری خود، پیشوند را از پاسخ حذف کنید. برای XmlHttpRequest این تنها زمانی امکان پذیر است که درخواست از همان دامنه نشات گرفته باشد.
فرمت درخواست
یک سرویس گیرنده یک درخواست HTTP GET با چندین پارامتر، از جمله عناصر سفارشی، یک رشته درخواست اختیاری، امضا و سایر عناصر ارسال می کند. شما فقط مسئول تجزیه پارامترهای توضیح داده شده در این بخش هستید و باید مراقب باشید که برای جلوگیری از حملات مخرب دیگران را مدیریت نکنید.
حتماً مقادیر پیش‌فرض برای پارامترهای اختیاری (اعم از استاندارد و سفارشی) داشته باشید و همه پیش‌فرض‌های خود را در اسناد سایت خود ثبت کنید.
در اینجا چند نمونه درخواست آورده شده است (نمونه های درخواست و پاسخ بیشتر را می توانید در انتهای این سند در نمونه ها مشاهده کنید):
توجه : رشته‌های درخواست زیر و آن‌هایی که در بخش مثال‌ها نشان داده شده‌اند، باید قبل از ارسال، از URL خارج شوند.
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") به حروف بزرگ و کوچک حساس هستند. جدول همچنین توضیح می دهد که آیا پارامتر مورد نیاز برای ارسال است یا خیر و در صورت ارسال، آیا شما باید آن را مدیریت کنید یا خیر.
| پارامتر | در درخواست مورد نیاز است؟ | منبع داده باید مدیریت شود؟ | شرح |
|---|---|---|---|
| tq | خیر | خیر | درخواستی که به زبان پرس و جوی Google Visualization API نوشته شده است و نحوه فیلتر کردن، مرتب‌سازی یا دستکاری داده‌های برگشتی را مشخص می‌کند. رشته نیازی به نقل قول ندارد. مثال: |
| tqx | خیر | آره | مجموعه‌ای از جفت‌های کلید/مقدار محدود شده با کولون برای پارامترهای استاندارد یا سفارشی. جفت ها با نقطه ویرگول از هم جدا می شوند. در اینجا لیستی از پارامترهای استاندارد تعریف شده توسط پروتکل Visualization آمده است:
مثال: |
| tqrt | خیر | خیر | رزرو شده: این پارامتر را نادیده بگیرید. روشی که برای ارسال پرس و جو استفاده شد. |
فرمت پاسخ
قالب پاسخ به پارامتر out درخواست بستگی دارد که نوع پاسخ مورد انتظار را مشخص می کند. برای یادگیری نحوه پاسخگویی به هر نوع درخواست، بخش های زیر را ببینید:
- JSON - پاسخ JSON را برمی‌گرداند که شامل داده‌های موجود در یک شی جاوا اسکریپت است که می‌تواند مستقیماً به سازنده
DataTableارسال شود تا آن را پر کند. این تا حد زیادی رایج ترین نوع درخواست است و مهم ترین آن برای اجرای صحیح است. - CSV - یک لیست مقادیر مسطح جدا شده با کاما را برمی‌گرداند که باید توسط مرورگر مدیریت شود.
- TSV - فهرست مقادیر جدا شده از برگه را برمی‌گرداند که باید توسط مرورگر مدیریت شود.
- HTML - یک جدول HTML را برمی گرداند تا توسط مرورگر ارائه شود.
می توانید از کتابخانه منبع داده تجسم Google (جاوا) یا کتابخانه تجسم پایتون برای تولید این فرمت های خروجی برای شما استفاده کنید.
فرمت پاسخ JSON
اگر درخواست شامل سرصفحه "X-DataSource-Auth" باشد، فرمت پاسخ پیش فرض JSON است و در غیر این صورت JSONP است. توجه داشته باشید که کلاینت نمودار گوگل در واقع از نسخه اصلاح شده JSON و JSONP پشتیبانی می کند. اگر از کتابخانه های کمکی جاوا یا پایتون استفاده می کنید، آنها کد مناسب را برای شما قرار می دهند. اگر پاسخ‌ها را با دست تجزیه می‌کنید، به تغییرات JSON در زیر مراجعه کنید.
اگر درخواست‌های هم‌دامنه را اعمال می‌کنید، باید وجود هدر «X-DataSource-Auth» را در درخواست تأیید کنید و از کوکی‌های مجوز استفاده کنید.
این تنها قالب پاسخی است که توسط متد Google Visualization API google.visualization.Query.send() مشخص شده است. می‌توانید نمونه‌ای از درخواست‌ها و پاسخ‌های JSON را در انتهای این صفحه در Examples ببینید. می توانید از کتابخانه های کمکی جاوا یا پایتون برای ایجاد این رشته پاسخ برای شما استفاده کنید.
این فرمت پاسخ یک شی JSON با کد UTF-8 است (شئی که توسط پرانتزهای { } پیچیده شده و هر ویژگی با کاما از هم جدا شده است) که شامل ویژگی های جدول زیر است (داده ها به ویژگی table اختصاص داده می شوند). این شی JSON باید در داخل مقدار پارامتر responseHandler از درخواست پیچیده شود. بنابراین، اگر مقدار responseHandler درخواست «myHandler» بود، باید یک رشته مانند این را برگردانید (فقط یک ویژگی برای اختصار نشان داده شده است):
"myHandler({status:ok, ...})" اگر درخواست شامل مقدار responseHandler نبود، مقدار پیش‌فرض «google.visualization.Query.setResponse» است، بنابراین باید رشته‌ای مانند این را برگردانید (فقط یک ویژگی برای اختصار نشان داده شده است):
"google.visualization.Query.setResponse({status:ok, ...})"در اینجا اعضای شی پاسخ موجود هستند:
| ویژگی | ضروری؟ | شرح |
|---|---|---|
| نسخه | خیر | شماره رشته ای که شماره نسخه پروتکل سیم Google Visualization را می دهد. اگر مشخص نشده باشد، مشتری آخرین نسخه را فرض می کند. مثال: |
| reqId | آره* | شماره رشته ای که شناسه این درخواست را برای این مشتری نشان می دهد. اگر این در درخواست بود، همان مقدار را برگردانید. برای جزئیات بیشتر به توضیحات reqId در بخش درخواست مراجعه کنید.* اگر این پارامتر در درخواست مشخص نشده بود، لازم نیست آن را در پاسخ تنظیم کنید. |
| وضعیت | آره | رشته ای که موفقیت یا شکست این عملیات را توصیف می کند. باید یکی و تنها یکی از مقادیر زیر باشد:
مثال: |
| هشدارها | فقط اگر status=warning | آرایه ای از یک یا چند شی که هر کدام یک مشکل غیر کشنده را توصیف می کنند. اگر
مثال: |
| خطاها | اگر status=error الزامی است | آرایه ای از یک یا چند شی که هر کدام یک خطا را توصیف می کنند. اگر آرایه دارای اعضای رشته زیر است (فقط یک مقدار برای هر عضو برمی‌گرداند):
مثال: |
| علامت زدن | خیر | یک مقدار هش شده از شی جدول. برای بهینه سازی انتقال داده بین مشتری و منبع داده مفید است. شما می توانید هر الگوریتم هش را که می خواهید انتخاب کنید. اگر از این ویژگی پشتیبانی می‌کنید، اگر داده‌ای برگردانده نشد، باید مقدار ارسال شده توسط مشتری را برگردانید، یا اگر داده‌های جدید برگردانده شد، هش جدیدی را برگردانید. مثال: |
| جدول | خیر | یک شی {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'}]}
]
} ویژگی مثال: به مثال های زیر مراجعه کنید. |
کتابخانه‌های کمکی Google و تمام درخواست‌های ارسال شده به Google، JSON/JSONP سختگیرانه را برمی‌گردانند. اگر خودتان کد برگشتی را تجزیه نمی کنید، این برای شما مهم نیست. اگر هستید، می توانید از JSON.parse() برای تبدیل رشته JSON به یک شی جاوا اسکریپت استفاده کنید. یک تفاوت در نحوه پردازش JSON توسط API این است که، اگرچه JSON از مقادیر تاریخ جاوا اسکریپت پشتیبانی نمی کند (به عنوان مثال، "تاریخ جدید(2008,1,28,0,31,26)"؛ API از JSON معتبر پشتیبانی می کند. نمایش تاریخ ها به عنوان یک رشته در قالب زیر: Date(year, month, day[,hour, minute, second[, millisecond]]) که در آن همه چیز پس از روز اختیاری است، و ماه ها بر اساس صفر هستند .
بهینه سازی پاسخ های JSON
اگر یک کلاینت دو درخواست داشته باشد و داده ها بین درخواست ها تغییر نکرده باشد، منطقی است که داده ها را مجددا ارسال نکنید. انجام این کار باعث هدر رفتن پهنای باند می شود. برای کارآمدتر کردن درخواست‌ها، پروتکل از کش کردن داده‌ها روی کلاینت و ارسال سیگنال در پاسخ در صورتی که داده‌ها از آخرین درخواست تغییر نکرده است، پشتیبانی می‌کند. در اینجا نحوه کار این است:
- مشتری درخواستی را به منبع داده ارسال می کند.
- منبع داده یک
DataTableو همچنین یک هش از شیDataTableتولید می کند و هر دو را در پاسخ خود برمی گرداند (هش در پارامترtqx.sigبرگردانده می شود). سرویس گیرنده Google Visualization APIDataTableو مقدارsigدر حافظه پنهان ذخیره می کند. - مشتری درخواست دیگری برای داده ارسال می کند، از جمله مقدار کش شده
tqx.sig. - منبع داده می تواند به یکی از دو روش پاسخ دهد:
- اگر داده ها نسبت به درخواست قبلی تغییر کرده باشند، منبع داده
DataTableجدید و هش مقدارsigجدید را پس می فرستد. - اگر داده ها نسبت به درخواست قبلی تغییر نکرده باشند، منبع داده
status=error،reason=not_modified،sig= old_sig_valueرا ارسال می کند.
- اگر داده ها نسبت به درخواست قبلی تغییر کرده باشند، منبع داده
- در هر صورت، صفحه میزبان نمودار پاسخ موفقیت آمیزی دریافت می کند و می تواند
DataTableبا فراخوانیQueryResponse.getDataTable()بازیابی کند. اگر داده ها یکسان باشد، به سادگی نسخه ذخیره شده جدول خواهد بود.
توجه داشته باشید که این فقط برای درخواست‌های JSON از نمودارهای ساخته شده در Google Visualization API کار می‌کند.
فرمت پاسخ CSV
اگر در درخواست مشخص شود out:csv ، پاسخ شامل هیچ ابرداده ای نیست، بلکه صرفاً یک نمایش CSV از داده ها است. یک جدول CSV معمولاً یک لیست جدا شده با کاما است، که در آن هر ردیف از داده ها یک لیست از مقادیر جدا شده با کاما است که به یک کاراکتر خط جدید یونیکس (\n) ختم می شود. مقادیر سلول باید برای هر ستون یک نوع باشد. ردیف اول برچسب های ستون است. در اینجا نمونه ای از جدول سه ردیفی و سه ستونی آورده شده است:
A, B, C 1.0, "yes", true 2.0, "no", false 3.0, "maybe", true
فرمت CSV توسط این پروتکل مشخص نشده است. منبع داده مسئول تعریف قالب CSV آن است. با این حال، یک قالب رایج مجموعه‌ای از مقادیر است که با کاما (بدون فاصله میانی) و یک خط جدید (\n) در انتهای هر سطر از هم جدا شده‌اند. هنگامی که یک مرورگر یک پاسخ رشته CSV دریافت می کند، ممکن است از کاربر بپرسد که از چه برنامه ای برای باز کردن رشته استفاده کند، یا ممکن است به سادگی آن را روی صفحه نمایش دهد. کتابخانه های منبع باز جاوا و پایتون روشی را برای تبدیل DataTable به رشته CSV ارائه می کنند.
اگر درخواست شامل یک عضو outFileName از پارامتر tqx باشد، باید سعی کنید نام فایل مشخص شده را در سرصفحه‌های پاسخ قرار دهید.
شی google.visualization.Query از درخواست پاسخ CSV پشتیبانی نمی کند. اگر مشتری بخواهد CSV درخواست کند، می‌توانید یک ابزار Visualization Toolbar را در صفحه خود جاسازی کنید، یا می‌تواند از کد سفارشی برای ایجاد درخواست استفاده کند، یا می‌توانید پیوندی ارائه دهید که ویژگی out:csv tqx را به صراحت، همانطور که در نشان داده شده است، ارائه دهید. آدرس درخواست زیر:
درخواست
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 است . اگر درخواست شامل یک عضو outFileName از پارامتر tqx باشد، باید سعی کنید نام فایل مشخص شده را در سرصفحه‌های پاسخ قرار دهید.
فرمت پاسخ HTML
اگر درخواست out:html مشخص می کند، پاسخ باید یک صفحه HTML باشد که یک جدول HTML را با داده ها تعریف می کند. این برای اشکال زدایی کد شما مفید است، زیرا مرورگر می تواند نتیجه شما را مستقیماً در قالبی قابل خواندن ارائه دهد. شما نمی توانید با استفاده از شی google.visualization.Query درخواستی برای پاسخ HTML ارسال کنید. شما باید با استفاده از کد سفارشی یا با تایپ یک URL مشابه این در مرورگر خود، یک پرس و جو برای پاسخ HTML ایجاد کنید:
درخواست
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'}]}]}});
Query with a query string ساده: درخواست برای یک ستون، یک ستون منفرد با چهار ردیف را برمی گرداند.
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: مثالی از یک خطای 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.'}]});
ابزارهای توسعه
- کتابخانه منبع داده جاوا (از Google) - درخواست و پاسخ را مدیریت می‌کند، جدول پاسخ را از داده‌هایی که به آن می‌دهید ایجاد می‌کند، و زبان پرس‌وجو Google Chart Tools SQL را پیاده‌سازی می‌کند.
- کتابخانه منبع داده پایتون (از Google) - یک جدول پاسخ ایجاد می کند و نحو پاسخ را ایجاد می کند. تجزیه درخواست یا پیاده سازی زبان پرس و جو SQL Google Chart Tools را انجام نمی دهد .
- MC-Google_Visualization (شخص ثالث) - این یک کتابخانه سمت سرور PHP است که می توانید از آن برای پیاده سازی یک منبع داده نمودار نمودار برای موتورهای پایگاه داده MySQL، SQLite و PostgreSQL با استفاده از PDO استفاده کنید.
- bortosky-google-visualization (شخص ثالث) - این یک کتابخانه کمکی برای ایجاد یک Google Visualization API Datatable برای کاربران دات نت است.
- GV Streamer (شخص ثالث) - GV Streamer یک ابزار سمت سرور است که می تواند داده ها را از منابع مختلف به پاسخ های پرس و جو معتبر به نمودارهای گوگل تبدیل کند. GV Streamer از چندین زبان (به عنوان مثال، PHP، جاوا، دات نت) و چندین منبع داده خام (مثلاً MySql) پشتیبانی می کند.
- TracGViz (شخص ثالث) - TracGViz یک ابزار رایگان و متن باز است که اجزایی را فراهم می کند تا Trac بتواند از ابزارهای نمودار استفاده کند و همچنین داده های مدیریت شده توسط Trac را به عنوان منبع داده Google Chart Tools پیاده سازی کند.
- vis-table (شخص ثالث) - کتابخانه ای که منبع داده ابزار نمودار گوگل را در PHP پیاده سازی می کند. دارای سه بخش اصلی است. خود پیاده سازی جدول داده، تجزیه کننده زبان پرس و جو و فرمت کننده ها.
- پیاده‌سازی منبع داده Google در Oracle PL/SQL (شخص ثالث) - یک بسته Oracle PL/SQL که Oracle را قادر می‌سازد منابع داده را مستقیماً از پایگاه داده سرور سرور کند. بنابراین اساساً می توانید از هر پرس و جوی Oracle به عنوان منبع داده ابزار نمودار Google استفاده کنید (این بسته یک فایل JSON را همراه با داده ها برمی گرداند). تقریباً از زبان پرس و جو گوگل پشتیبانی کامل دارد.