כאן מוסבר איך אפשר להטמיע שירות שתומך בפרוטוקול מקור הנתונים של הכלים לתרשימים, כדי לחשוף נתונים לתרשימים באמצעות מחלקת השאילתות.
תוכן עניינים
קהל
הדף הזה מיועד בעיקר למפתחים שיוצרים מקור נתונים משלהם ללא עזרה בספריית מקורות הנתונים של כלים לתרשימים. אם אתם משתמשים בה או בספריות סיוע אחרות, יש לקרוא תחילה את מסמכי התיעוד של הספרייה שלכם.
הדף הזה מיועד גם לקוראים שרוצים להבין את פרוטוקול ההעברה המשמש לתקשורת בין תצוגה חזותית של לקוח לבין מקור נתונים.
אם ברצונך ליצור תצוגה חזותית או להשתמש בה, אין צורך לקרוא את הדף הזה.
כדי לקרוא את המסמך הזה, עליך להבין את התחביר הבסיסי של בקשות מסוג JSON ו-HTTP. עליך גם להבין כיצד התרשימים פועלים מנקודת המבט של משתמש.
סקירה כללית
תוכלו להשתמש בפרוטוקול מקור הנתונים של כלי התרשימים כדי להיות ספק מקור נתונים לתרשימים משלכם, או לתרשימים אחרים. מקור נתונים לכלים לתרשימים חושף כתובת URL שנקראת כתובת URL של מקור נתונים, שאליה תרשים יכול לשלוח בקשות HTTP GET. בתגובה, מקור הנתונים מחזיר נתונים בפורמט תקין שבהם התרשים יכול לשמש לעיבוד הגרפיקה שבדף. פרוטוקול ה-Request-Response הזה נקרא Google Visualization API פרוטוקול חוטי.
אפשר לחלץ את הנתונים שמוצגים ממקור נתונים ממשאבים שונים, כמו קובץ או מסד נתונים. המגבלה היחידה היא שניתן לעצב את הנתונים כטבלה דו-מימדית עם עמודות שמוקלדות.
כמקור נתונים של כלים לתרשימים, עליכם לנתח בקשה בפורמט ספציפי ולהחזיר תשובה בפורמט ספציפי. יש שתי דרכים לעשות זאת:
-
ניתן להשתמש באחת מספריות העזרה הבאות כדי לטפל בבקשה ובתגובה וליצור את DataTable להחזרה. אם משתמשים באחת מהספריות האלה, צריך לכתוב רק את הקוד הדרוש כדי שהנתונים יהיו זמינים לספרייה בצורת טבלה.
- ספריית מקור נתונים של Java – מטפלת בבקשה ובתגובה, יוצרת את טבלת התגובות מהנתונים שנתתם לה ומטמיעה את שפת השאילתה של SQL Charts של Google.
-
ספריית מקור הנתונים של Python -
יצירת טבלת תגובות יוצרת את התחביר של התגובה. לא
מנתח את הבקשה או מיישם את שפת השאילתות של SQL ב-Google Charts.
או
- כתוב מקור נתונים משלך מההתחלה על ידי טיפול בבקשה, יצירת DataTable ושליחת התגובה.
איך זה עובד:
- מקור הנתונים חושף כתובת URL שנקראת כתובת URL של מקור נתונים, שאליה תרשימים שולחים בקשת HTTP GET.
- הלקוח שולח בקשת GET ב-HTTP עם פרמטרים שמתארים באיזה פורמט להשתמש עבור נתונים שהוחזרו, מחרוזת שאילתה אופציונלית ופרמטרים אופציונליים מותאמים אישית.
- מקור הנתונים מקבל ומנתח את הבקשה, כפי שמתואר ב פורמט הבקשה.
- מקור הנתונים מכין את הנתונים בפורמט המבוקש. לרוב, מדובר בטבלת JSON. הפורמטים של התגובות נכללים בקטע פורמט התגובות. מקור הנתונים יכול לתמוך בשפת השאילתה של Vision API, המציינת סינון, מיון ומניפולציות אחרות על נתונים.
- מקור הנתונים יוצר תגובת HTTP שכוללת את הנתונים הסידוריים ואת הפרמטרים האחרים של התגובה, ושולח אותם חזרה ללקוח כפי שמתואר בפורמט התגובה.
הערה: כל הפרמטרים והערכים הקבועים במחרוזת
שצוינו במסמך זה לבקשות ולתשובות (כגון
responseHandler ו-"אישור") הם אותיות קטנות ותלויות אותיות רישיות.
דרישות מינימליות
אלו הדרישות המינימליות שישמשו כמקור נתונים של כלי תרשים:
- מקור הנתונים צריך לקבל בקשות HTTP GET ולהיות זמין ללקוחות שלכם.
- הפרוטוקול יכול לשנות ולתמוך בסכימת גרסאות (הגרסה הנוכחית היא 0.6), כך שמקור הנתונים צריך לתמוך בבקשות באמצעות הגרסאות הקודמות וגם בגרסה הנוכחית. מומלץ לנסות לתמוך בגרסאות חדשות ברגע שהן מתפרסמות, כדי למנוע פריצה ללקוחות שמשדרגים לגרסה העדכנית ביותר במהירות.
- כישלון במקרה שנכסים לא ידועים נשלחים כחלק מהבקשה. הסיבה לכך היא שגרסאות חדשות יכולות להשיק נכסים חדשים שעדיין לא ידעת עליהם.
- נתחו רק נכסים שאתם מצפים לקבל. אומנם גרסאות חדשות עשויות לכלול נכסים חדשים, אבל אנחנו לא מאשרים את השימוש במחרוזת הבקשה במלואה. כדי להגן על עצמך מפני התקפות זדוניות, כדאי לנתח בקפידה את המאפיינים שציפית להשתמש בהם ולהשתמש בהם בלבד.
- הקפידו לתעד את הדרישות של מקור הנתונים אם אתם לא מקודדים את תרשימי הלקוחות בעצמכם. דוגמאות למסמכים כאלה:
- כל פרמטר מותאם אישית שאתם מקבלים,
- אם ניתן לנתח את שפת השאילתות של Google Visualization API, וגם
- מהו סוג הנתונים שמחזירים, והמבנה של הנתונים האלה (מה שהשורות והעמודות מייצגות ותוויות שמסומנות).
- יש לנקוט אמצעי זהירות רגילים בכל הנוגע לאתר שמקבל בקשות מלקוחות לא ידועים. ניתן לתמוך באופן סביר ב-MD5, ב-hash ובמנגנוני אבטחה אחרים בפרמטרים שלך כדי לאמת בקשות או לסייע באבטחה מפני מתקפות זדוניות, והלקוחות צריכים להיות מודעים לדרישות שלך ולהגיב להן. עם זאת, חשוב לתעד את כל הדרישות בצורה נכונה, אם לא מקודדים את התרשימים בעצמכם. אפשר לקרוא בהמשך על שיקולי אבטחה.
- כל מחרוזות הבקשה והתגובה צריכות להיות מקודדות בקידוד UTF-8.
- פורמט התגובה החשוב ביותר הוא JSON. חשוב להטמיע JSON, כי זהו הפורמט שבו משתמשים רוב התרשימים. אפשר להוסיף סוגים אחרים של תשובות בשלב מאוחר יותר.
- לא חייבים לתמוך בשפה של שאילתת ה-API להצגה חזותית, אבל היא הופכת את מקור הנתונים לשימושי יותר עבור הלקוחות.
- לא חובה לתמוך בבקשות מכל סוג ומכל תרשים, ואפשר גם לתמוך בפרמטרים מותאמים אישית בתרשימים בהתאמה אישית. אבל צריך להחזיר את התגובות בפורמט הרגיל שבהמשך.
שיקולי אבטחה
כשמתכננים את מקור הנתונים, צריך להביא בחשבון את מידת האבטחה של הנתונים. אפשר להשתמש במגוון תוכניות אבטחה לאתר, החל מגישה פשוטה לסיסמאות ועד אימות מאובטח של קובצי cookie.
מתקפות XSSI (הכללת סקריפטים חוצי אתרים) הן סיכון עם תרשימים. משתמש עשוי לנווט לדף שמכיל סקריפט זדוני, שלאחר מכן מתחיל לנסות לבצע שאילתות לכתובות של מקורות נתונים באמצעות פרטי הכניסה של המשתמש הנוכחי. אם המשתמש לא יצא מהאתר, הסקריפט יאומת כמשתמש הנוכחי ויש לו הרשאות באותו אתר. באמצעות תג <script src>, הסקריפט הזדוני יכול לכלול את מקור הנתונים, בדומה ל-JSONP.
כאמצעי אבטחה נוסף, מומלץ להגביל את הבקשות שנשלחות מאותו דומיין של מקור הנתונים. הפעולה הזו תגביל באופן משמעותי את החשיפה של מקור הנתונים, אבל אם יש לך נתונים רגישים מאוד שאין לגשת אליהם מחוץ לדומיין, עליך לשקול זאת. מקור נתונים שמאפשר רק בקשות מאותו דומיין נקרא מקור נתונים מוגבל, בניגוד למקור נתונים ללא הגבלה, שמקבל שאילתות מכל דומיין. כך מטמיעים מקור נתונים מוגבל:
כדי לוודא שבקשה מגיעה באמת מהדומיין שלך, ולא מדומיין חיצוני (או מדפדפן בתוך הדומיין שנמצא במתקפת XSRF):
- יש לאמת את הנוכחות של כותרת "X-DataSource-Auth" בבקשה. הכותרת מוגדרת על ידי Google Visualization API. אין צורך לבדוק את התוכן של הכותרת הזו רק לוודא שהיא קיימת. אם אתם משתמשים בספריית מקורות הנתונים של Google Chart , הספרייה יכולה להתאים לכם.
- משתמשים באימות קובצי cookie כדי לאמת את הלקוח. אין דרך ידועה להזרקת כותרות מותאמות אישית לבקשה בין דומיינים, תוך שמירה על קובצי cookie לאימות.
- יש לוודא שה-JavaScript לא יפעל כאשר הוא נכלל בתג <script src>. כדי לעשות זאת, מוסיפים את המחרוזת JSON לפני )]} ואז מוסיפים שורה חדשה. יש להסיר את הקידומת מהלקוח. ב-XmlHttpRequest, זה אפשרי רק כשהבקשה הגיעה מאותו דומיין.
פורמט הבקשה
לקוח שולח בקשת GET של HTTP עם מספר פרמטרים, כולל רכיבים מותאמים אישית, מחרוזת שאילתה אופציונלית, חתימה ורכיבים אחרים. האחריות היא רק לנתח את הפרמטרים שמתוארים בקטע הזה ולהיזהר לא לטפל בגורמים אחרים כדי להימנע מהתקפות זדוניות.
חשוב לוודא שיש לכם ערכי ברירת מחדל לפרמטרים אופציונליים (כמו פרמטרים רגילים או מותאמים אישית), וגם לתעד את כל ברירות המחדל במסמכי התיעוד של האתר.
כמה בקשות לדוגמה (אפשר לראות דוגמאות נוספות לבקשות ולתשובות בסוף המסמך הזה בקטע דוגמאות):
הערה: לפני שליחת מחרוזות ה-URL הבאות, יש לסמן אותן בתו בריחה (escape) אחרי המחרוזות הבאות בקטע דוגמאות.
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
זוהי הרשימה של כל הפרמטרים הרגילים במחרוזת הבקשה. חשוב לשים לב שגם שמות הפרמטרים (כמו "גרסה") וגם ערכי המחרוזת הקבועה (כמו "אישור", "אזהרה" ו"ללא_שינוי") הם תלויי אותיות רישיות. בטבלה מצוין גם אם יש צורך לשלוח את הפרמטר, ואם הוא נשלח, האם חובה לטפל בו.
| פרמטר | נדרש בבקשה? |
מהו מקור הנתונים? |
תיאור |
|---|---|---|---|
| tq, טק טי | לא |
לא |
שאילתה שכתובה בשפת השאילתות של Google Visualization API ומציינת איך לסנן, למיין או לשנות את הנתונים שהוחזרו. אין צורך לצטט את המחרוזת. דוגמה: |
| tqx, טקס | לא |
כן |
קבוצה של צמדי מפתח/ערך המופרדים בנקודתיים עבור פרמטרים סטנדרטיים או פרמטרים מותאמים אישית. הערכים מופרדים באמצעות נקודה-פסיק (;). לפניכם רשימה של הפרמטרים הרגילים שמוגדרים על ידי פרוטוקול ההמחשה:
דוגמה: |
| tqrt, טירקט | לא |
לא |
שמור: התעלמות מהפרמטר הזה. השיטה שבה נעשה שימוש לשליחת השאילתה. |
פורמט תגובה
פורמט התשובה תלוי בפרמטר out של הבקשה, שמציין את סוג התגובה הצפויה. בקטעים הבאים מוסבר איך לענות לכל סוג של בקשה:
- JSON – החזרת תגובת JSON שכוללת את הנתונים באובייקט JavaScript, שניתן להעביר ישירות לבנאי
DataTableכדי לאכלס אותו. זהו סוג הבקשה הנפוץ ביותר, והחשוב ביותר להטמיע אותו כראוי. - CSV – מחזירה רשימת ערכים שטוחה המופרדת בפסיקים, שיש לטפל בה בדפדפן.
- TSV – מחזירה רשימת ערכים מופרדים בטאבים, שיטופלו על ידי הדפדפן.
- HTML – מחזירה טבלת HTML שתוצג על ידי הדפדפן.
אפשר להשתמש בספריית מקור נתוני ההמחשה של Google (ג'אווה) או בספריית המילון החזותית כדי ליצור בשבילך את הפורמטים האלה.
פורמט של תגובת JSON
פורמט התגובה המוגדר כברירת מחדל הוא JSON אם הבקשה כוללת כותרת מסוג "X-DataSource-Auth", ואם לא, JSONP. חשוב לשים לב שהלקוח תרשים Google תומך בפועל בגרסה ששונתה של JSON ו-JSONP. אם משתמשים בספריות המסייעות של Java או Python, הם יפרסמו את הקוד המתאים בשבילך. אם מנתחים את התגובות באופן ידני, יש לעיין בשינויים ב-JSON בהמשך.
אם בחרת לאכוף בקשות באותו דומיין, עליך לאמת את הנוכחות של הכותרת 'X-DataSource-Auth' בבקשה ולהשתמש בקובצי cookie של הרשאה.
זהו פורמט התגובה היחיד שצוין על ידי השיטה של Google Visualization API
google.visualization.Query.send()
.
דוגמאות של בקשות ותגובות של JSON מוצגות בסוף הדף בקטע דוגמאות.
אפשר להשתמש בספריות העזרה של Java או של Python כדי ליצור בשבילך את מחרוזת התגובה הזו.
פורמט התגובה הזה הוא אובייקט JSON בקידוד UTF-8 (אובייקט שמוקף בסוגריים מסולסלים { } עם כל נכס מופרד באמצעות פסיק) שכולל את המאפיינים בטבלה שבהמשך (הנתונים מוקצים לנכס table). יש להקיף את אובייקט JSON בתוך ערך הפרמטר responseHandler בתוך הבקשה. כלומר, אם הערך responseHandler של הבקשה הוא
"myHandler", עליכם להחזיר מחרוזת כזאת (רק נכס אחד מוצג למטרות קיצור):
"myHandler({status:ok, ...})"
אם הבקשה לא כוללת ערך של responseHandler, ערך ברירת המחדל הוא "google.visualization.Query.setResponse", ולכן עליך להחזיר מחרוזת דומה לזו (רק נכס אחד מוצג לציון קיצור):
"google.visualization.Query.setResponse({status:ok, ...})"
אלו הם האנשים הנכללים באובייקטים של תגובות:
| מאפיין (property) | נדרש? |
תיאור |
|---|---|---|
| גרסה | לא |
מספר מחרוזת שמספק את מספר הגרסה של פרוטוקול ההמחשה של Google. אם לא תצוין, הלקוח יקבל את הגרסה העדכנית ביותר. דוגמה: |
| מזהה בקשה | כן* |
מספר מחרוזת שמציין את מזהה הבקשה עבור הלקוח. אם זו הייתה הבקשה, יש להחזיר את אותו הערך. לפרטים נוספים אפשר לעיין בreqIdקטע בקשת. * אם הפרמטר הזה לא צוין בבקשה, אין צורך להגדיר אותו בתשובה. |
| סטטוס | כן |
מחרוזת המתארת את ההצלחה או הכשל של הפעולה. חייב להיות רק אחד מהערכים הבאים:
דוגמה: |
| אזהרות | רק אם status=warning |
מערך של אובייקט אחד או יותר, שכל אחד מהם מתאר בעיה לא חמורה.
חובה אם
דוגמה: |
| שגיאות | חובה אם status=error |
מערך של אובייקט אחד או יותר, שמתארים כל שגיאה. חובה אם
במערך יש את מחרוזות המחרוזת הבאות (החזר ערך אחד בלבד לכל חבר):
דוגמה:
|
| Sig | לא |
ערך מגובב (hashed) של אובייקט הטבלה. שימושי באופטימיזציה של העברת נתונים בין הלקוח למקור הנתונים. אתם יכולים לבחור כל אלגוריתם גיבוב. אם הנכס הזה נתמך, יש להחזיר את הערך שהועבר על ידי הלקוח אם לא מוחזרים נתונים. לחלופין, אפשר להחזיר גיבוב חדש אם מוחזרים נתונים חדשים. דוגמה: |
| טבלה | לא |
אובייקט {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 לאובייקט JavaScript. הבדל אחד באופן העיבוד של JSON
על ידי ה-API הוא, שלמרות שה-JSON לא תומך בערכי תאריך JavaScript (לדוגמה,
"תאריך חדש(2008,1,28,0,31,26)";
ה-API כן תומך בייצוג חוקי של תאריכים במחרוזת כמחרוזת
בפורמט הבא:Date(year, month, day[,hour, minute, second[, millisecond]])
כאשר כל מה שמתרחש בסוף היום הוא אופציונלי, וגם החודשים מבוססים על אפס.
אופטימיזציה של תגובות JSON
אם לקוח שולח שתי בקשות, והנתונים לא השתנו בין בקשות, הגיוני לא לשלוח את הנתונים מחדש; הפעולה הזו תגרום לבזבוז רוחב פס. כדי לייעל את הבקשות, הפרוטוקול תומך במטמון הנתונים בלקוח ובשליחת אות בתגובה אם הנתונים לא השתנו מאז הבקשה האחרונה. כך זה עובד:
- הלקוח שולח בקשה למקור הנתונים.
- מקור הנתונים יוצר
DataTableוגם גיבוב (hash) של האובייקטDataTable, ומחזיר את שניהם בתגובה (הגיבוב מוחזר בפרמטרtqx.sig). לקוח Google Visualization API שומר במטמון את הערךDataTableואת הערךsig. - הלקוח שולח בקשה נוספת לנתונים, כולל הערך
tqx.sigהשמור במטמון. - מקור הנתונים יכול להגיב באחת משתי דרכים:
- אם הנתונים השתנו מהבקשה הקודמת, מקור הנתונים ישלח שוב את הגיבוב (hash) החדש של
DataTableואת הערך החדש שלsig. - אם הנתונים לא השתנו מהבקשה הקודמת, מקור הנתונים
ישלח חזרה את
status=error,reason=not_modified,sig=old_sig_value.
- אם הנתונים השתנו מהבקשה הקודמת, מקור הנתונים ישלח שוב את הגיבוב (hash) החדש של
- בכל מקרה, הדף שמארח את התרשים מקבל תגובה מוצלחת, ויכול לאחזר את ה-
DataTableעל ידי התקשרותQueryResponse.getDataTable(). אם הנתונים זהים, הם יהיו גרסת המטמון של הטבלה.
חשוב לשים לב שאפשרות זו פועלת רק בבקשות JSON מתרשימים שנוצרו ב-Google Visualization API.
פורמט תגובה ל-CSV
אם הבקשה מציינת out:csv, התגובה לא תכלול מטא-נתונים, אלא רק ייצוג CSV של הנתונים. טבלת CSV היא בדרך כלל
רשימה מופרדת בפסיקים, שבה כל שורת נתונים היא רשימת ערכים המופרדים בפסיקים,
שמסתיימת בתו חדש של UNIX (\n). הערכים של כל תא צריכים להיות זהים בכל עמודה. השורה הראשונה כוללת את תוויות העמודות. הנה דוגמה לטבלה עם שלוש עמודות
ב-3 שורות:
A, B, C 1.0, "yes", true 2.0, "no", false 3.0, "maybe", true
ה-CSV לא מצוין על ידי הפרוטוקול הזה. מקור הנתונים אחראי על ההגדרה של קובץ ה-CSV. עם זאת, פורמט נפוץ הוא קבוצה של ערכים המופרדים באמצעות פסיקים (ללא רווחים בין השורות), ושורה חדשה (\n) בסוף כל שורה. כשדפדפן מקבל תשובה לקובץ CSV, הוא עשוי לשאול את המשתמש באיזו אפליקציה להשתמש כדי לפתוח את המחרוזת, או פשוט לעבד אותה על המסך. ספריות הקוד הפתוח Java ו-Python מספקות שיטה להמרת DataTable למחרוזת CSV.
אם הבקשה כוללת חבר outFileName בפרמטר tqx , עליך לכלול את שם הקובץ שצוין בכותרות התגובה.
האובייקט google.visualization.Query לא תומך בבקשה לתגובת CSV. אם לקוח רוצה לבקש קובץ CSV, אפשר להטמיע גאדג'ט של סרגל הכלים להצגה חזותית בדף שלכם, או שהוא יכול להשתמש בקוד מותאם אישית כדי ליצור את הבקשה, או לספק קישור שמגדיר את המאפיין out:csv של tqx באופן מפורש, כמו בדוגמה הבאה בכתובת ה-URL של הבקשה:
בקשה
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 עם הנתונים. פעולה זו
שימושית לניפוי באגים בקוד, כי הדפדפן עשוי לעבד את התוצאה
ישירות בפורמט קריא. לא ניתן לשלוח שאילתה בתגובת HTML באמצעות האובייקט google.visualization.Query.
צריך ליצור שאילתה לתגובת HTML באמצעות קוד מותאם אישית, או להקליד כתובת URL דומה לזו בדפדפן.
בקשה
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'}]}]}});
בקשה פשוטה עם handler של תגובה: מחזירה טבלה של שלוש עמודות עם שלושה סוגי נתונים.
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) - מטפלת בבקשה ובתגובה, יוצרת את טבלת התגובות מהנתונים שאתם נותנים לה ומטמיעה את שפת השאילתות של SQL בכלי Google Chart.
- ספריית מקורות Python (מ-Google) – יוצרת טבלת תגובות שיוצרת את התחביר של התגובה. לא מטפלים בניתוח הבקשה או בהטמעה של שפת השאילתות של SQL בכלי Google Chart.
- MC-Google_Visualization (צד שלישי) – זו ספרייה בצד השרת בפרוטוקול PHP שאפשר להשתמש בה כדי להטמיע מקור נתונים למסדי נתונים של Chart עבור מנועי MySQL, SQLite ו-PostgreSQL באמצעות PDO.
- bortosky-google-visualization (צד שלישי) – זו ספרייה של משאבים שיעזרו לך ליצור טבלת נתונים של Google Visualization API למשתמשי .NET.
- GV Streamer (צד שלישי) – GV Streamer הוא כלי בצד השרת, שיכול להמיר נתונים ממקורות שונים לתגובות חוקיות של שאילתות בתרשימים של Google. סטרימר מסוג GV תומך בכמה שפות (לדוגמה, PHP, Java, .NET) ומספר מקורות גולמיים (לדוגמה, MySql).
- TracGViz (צד שלישי) – TracGViz הוא כלי חינמי בקוד פתוח, שמספק רכיבים כדי ש-Trac יוכל להשתמש בגאדג'טים של תרשים וגם להטמיע נתונים שמנוהלים על ידי Trac כמקור נתונים של Google Chart Tools.
- vis-table (צד שלישי) – ספרייה שמטמיעה מקור נתונים של Google Chart Tools ב-PHP. הוא כולל שלושה חלקים עיקריים. הטמעה של טבלת הנתונים עצמה, מנתח שפת השאילתות ורכיבי העיצוב.
- הטמעת מקור נתונים של Google ב-Oracle PL/SQL (צד שלישי) – חבילת Oracle PL/SQL שמאפשרת איסוף נתונים ממסד הנתונים של Oracle לשרת ישירות ממסד הנתונים. למעשה, ניתן להשתמש בכל שאילתה ב-Oracle כמקור נתונים של Google Chart Tools (החבילה תחזיר קובץ JSON עם הנתונים). הוא כולל תמיכה כמעט מלאה בשפת השאילתות של Google.