כאן מוסבר איך מטמיעים שירות שתומך בפרוטוקול Datasource של Chart Tools כדי לחשוף נתונים לתרשימים באמצעות סיווג השאילתה.
תוכן עניינים
קהל
הדף הזה מיועד בעיקר למפתחים שיצרו מקור נתונים משלהם בלי להיעזר בספריית מקורות הנתונים של Chart Tools. אם משתמשים בספרייה הזו או בכל ספריות עזר אחרות, צריך לקרוא קודם את מסמכי התיעוד של הספרייה.
הדף הזה מיועד גם לקוראים שרוצים להבין את פרוטוקול הכבלים שמשמש לתקשורת בין התצוגה החזותית של הלקוח לבין מקור הנתונים.
אם אתם יוצרים או משתמשים בהצגה חזותית, אין צורך לקרוא את הדף הזה.
כדי לקרוא את המסמך הזה, צריך להבין תחביר בסיסי של בקשות JSON ו-HTTP. חשוב גם להבין איך התרשימים פועלים מנקודת המבט של המשתמש.
סקירה כללית
תוכלו להטמיע את פרוטוקול Datasource של Chart Tools כדי להפוך לספק מקור נתונים לתרשימים או לתרשימים אחרים משלכם. מקור נתונים של כלי תרשים חושף כתובת URL, שנקראת כתובת URL של מקור נתונים, שאליה התרשים יכול לשלוח בקשות HTTP GET. בתגובה, מקור הנתונים מחזיר נתונים בפורמט תקין, שבהם התרשים יכול להשתמש כדי לעבד את הגרפיקה בדף. פרוטוקול הבקשה-תגובה הזה נקרא פרוטוקול העברה של GoogleVisual API.
אפשר לחלץ את הנתונים שמוצגים על ידי מקור נתונים מתוך משאבים שונים, כמו קובץ או מסד נתונים. ההגבלה היחידה היא שאפשר לעצב את הנתונים כטבלה דו-ממדית עם עמודות בפורמט מוקלד.
בתור מקור נתונים של Chart Tools, צריך לנתח בקשה בפורמט ספציפי ולהחזיר תשובה בפורמט ספציפי. אפשר לעשות זאת באחת משתי הדרכים הכלליות הבאות:
-
כדאי להשתמש באחת מספריות העזר הבאות כדי לטפל בבקשה ובתגובה, וליצור את ה-DataTable שיוחזר. אם משתמשים באחת מהספריות האלה, צריך לכתוב רק את הקוד שדרוש כדי שהנתונים יהיו זמינים לספרייה
בצורה של טבלה.
- Java Datasource Library – מטפל בבקשה ובתשובה, יוצר את טבלת התגובות מהנתונים שסיפקתם ומטמיע את שפת שאילתות ה-SQL של Google Chart Tools.
-
ספריית מקור הנתונים של Python –
יצירת טבלת תשובות יוצרת את התחביר של התשובה. לא מטפלים בניתוח הבקשה או בהטמעה של שפת שאילתות ה-SQL של Google Chart Tools.
או
- כתיבת מקור נתונים מאפס על ידי טיפול בבקשה, בניית DataTable ושליחת התגובה.
איך זה עובד:
- מקור הנתונים חושף כתובת URL שנקראת כתובת ה-URL של מקור הנתונים, שאליה התרשימים שולחים בקשת HTTP GET.
- הלקוח שולח בקשת HTTP GET עם פרמטרים שמתארים את הפורמט שבו צריך להשתמש לנתונים שהוחזרו, מחרוזת שאילתה אופציונלית ופרמטרים מותאמים אישית אופציונליים.
- מקור הנתונים מקבל ומנתח את הבקשה, כפי שמתואר במאמר פורמט הבקשה.
- מקור הנתונים מכין את הנתונים בפורמט המבוקש. בדרך כלל זו טבלת JSON. אפשר לקרוא על פורמטים של תשובות בקטע פורמט התגובה. באופן אופציונלי, מקור הנתונים יכול לתמוך ב שפת השאילתות שלVisual API שמציינת סינון, מיון ומניפולציה אחרת של נתונים.
- מקור הנתונים יוצר תגובת HTTP שכוללת את הנתונים הסידוריים ופרמטרים אחרים של תגובה, ושולחת אותה בחזרה ללקוח כפי שמתואר בפורמט התגובה.
הערה: כל הפרמטרים והערכים הקבועים של המחרוזת
שרשומים במסמך הזה לבקשות ולתשובות (כמו
responseHandler ו-'ok') הם באותיות קטנות ותלויי אותיות רישיות.
הדרישות המינימליות
כדי להשתמש בתור מקור נתונים של כלים לתרשימים, צריך לעמוד בדרישות המינימליות הבאות:
- מקור הנתונים צריך לקבל בקשות HTTP GET, והוא צריך להיות זמין ללקוחות שלכם.
- הפרוטוקול יכול להשתנות ותומך בסכמת גרסאות (הגרסה הנוכחית היא 0.6), ולכן מקור הנתונים צריך לתמוך בבקשות שמשתמשות בגרסאות קודמות וגם בגרסה הנוכחית. מומלץ לנסות לתמוך בגרסאות חדשות ברגע שהן מתפרסמות, כדי למנוע תקלות בלקוחות שמשדרגים לגרסה החדשה ביותר במהירות.
- העיבוד לא ייכשל אם שולחים מאפיינים לא מוכרים כחלק מהבקשה. הסיבה לכך היא שגרסאות חדשות יכולות לכלול נכסים חדשים שאתם לא מודעים להם.
- נתחו רק את הנכסים שאתם מצפים לקבל. למרות שגרסאות חדשות עשויות להוסיף מאפיינים חדשים, לא כדאי לאשר את כל מחרוזת הבקשה ולהשתמש בה באופן עיוור. כדי להגן על עצמך מפני מתקפות זדוניות, יש לנתח בקפידה את הנכסים שציפית להשתמש בהם.
- חשוב לתעד בקפידה את הדרישות לגבי מקורות הנתונים אם אתם לא מקודדים בעצמכם את התרשים של הלקוח. האיסור הזה כולל תיעוד של
המידע הבא:
- כל פרמטר מותאם אישית שאתם מקבלים.
- האם ניתן לנתח את שפת השאילתות של GoogleVisual API, וכן
- איזה סוג של נתונים מחזירים, והמבנה של הנתונים האלה (מה שהשורות והעמודות מייצגות, כולל תוויות אחרות).
- יש לנקוט את כל אמצעי הזהירות הרגילים להגנה על אתרים המקבלים בקשות מלקוחות לא ידועים. אפשר לתמוך בצורה סבירה ב-MD5, בגיבוב (hashing) ובמנגנוני אבטחה אחרים בפרמטרים שלכם כדי לאמת בקשות או לעזור לאבטח מפני התקפות זדוניות, ולצפות מהלקוחות להיות מודעים לדרישות שלכם ולהגיב להן. עם זאת, אם אתם לא מקודדים את התרשימים בעצמכם, חשוב לתעד את כל הדרישות. ראו את שיקולי האבטחה שבהמשך.
- כל מחרוזות הבקשה והתגובה צריכות להיות בקידוד UTF-8.
- פורמט התגובה החשוב ביותר הוא JSON. קודם חשוב להטמיע JSON, כי זה הפורמט שבו משתמשים רוב התרשימים. אחר כך אפשר להוסיף סוגי תשובות אחרים.
- אתם לא צריכים לתמוך בשפת השאילתות שלVisual API, אבל זה הופך את מקור הנתונים לשימושי יותר ללקוחות.
- אתם לא צריכים לתמוך בבקשות מכל סוגי התרשימים, ואתם יכולים גם לתמוך בפרמטרים מותאמים אישית בתרשימים בהתאמה אישית. עם זאת, עליך להחזיר תשובות בפורמט הרגיל שמתואר בהמשך.
שיקולי אבטחה
כשמעצבים את מקור הנתונים, חשוב להביא בחשבון את מידת האבטחה של הנתונים. תוכלו להשתמש במגוון תוכניות אבטחה לאתר, החל מגישה פשוטה באמצעות סיסמה ועד לאימות מאובטח של קובצי cookie.
מתקפות XSSI (הכללה של סקריפטים חוצי-אתרים) מהוות סיכון בעזרת תרשימים. משתמש עשוי לעבור לדף שמכיל סקריפט זדוני שמתחיל לאחר מכן בניסיון לשלוח שאילתות לכתובות URL של מקור הנתונים, באמצעות פרטי הכניסה של המשתמש הנוכחי. אם המשתמש לא התנתק מאתר, הסקריפט יאומת בתור המשתמש הנוכחי ויקבל הרשאות באתר הזה. אם משתמשים בתג <script src>, הסקריפט הזדוני יכול לכלול את מקור הנתונים, בדומה ל-JSONP.
כאמצעי אבטחה נוסף, מומלץ להגביל את הבקשות למשתמשים שמגיעים מאותו דומיין כמו מקור הנתונים. ההגדרה הזו תגביל באופן משמעותי את החשיפה של מקור הנתונים, אבל אם יש לך מידע אישי רגיש מאוד שלא צריך לגשת אליו מחוץ לדומיין, כדאי לשקול זאת. מקור נתונים שמאפשר בקשות מאותו דומיין בלבד נקרא מקור נתונים מוגבל, בניגוד למקור נתונים לא מוגבל, שמקבל שאילתות מכל דומיין. פרטים נוספים על אופן ההטמעה של מקור נתונים מוגבל:
כדי לוודא שהבקשה באמת מגיעה מתוך הדומיין, ולא מדומיין חיצוני (או מדפדפן בתוך הדומיין שנמצא תחת התקפת XSRF):
- מאמתים את הנוכחות של כותרת "X-DataSource-Auth" בבקשה. הכותרת הזו מוגדרת על ידי Google Vision API. אין צורך לבדוק את התוכן של הכותרת, אלא רק לוודא שהיא מופיעה שם. אם משתמשים בספריית מקור הנתונים של Google Chart Tools, אפשר להגדיר אותה כך שהספרייה לטפל בזה.
- משתמשים באימות באמצעות קובצי cookie כדי לאמת את הלקוח. אין דרך ידועה להחדיר כותרות מותאמות אישית לבקשה בכמה דומיינים ועדיין לשמור על קובצי ה-cookie לאימות.
- הגדרת מצב שבו לא סביר ש-JavaScript יופעל כשהוא כלול בתג <script src>. כדי לעשות את זה, צריך להוסיף את הקידומת ' }}' לתגובת ה-JSON ואחריה מופיעה שורה חדשה. בלקוח, מסירים את הקידומת מהתשובה. ב-XmlHttpRequest, הדבר אפשרי רק כאשר הבקשה הגיעה מאותו דומיין.
פורמט הבקשה
הלקוח שולח בקשת HTTP GET עם כמה פרמטרים, כולל רכיבים מותאמים אישית, מחרוזת שאילתה אופציונלית, חתימה ורכיבים אחרים. באחריותך רק לנתח את הפרמטרים שמתוארים בקטע הזה, ועליך להיזהר לא לטפל באחרים כדי להימנע מהתקפות זדוניות.
חשוב להגדיר ערכי ברירת מחדל לפרמטרים אופציונליים (רגילים וגם מותאמים אישית), ולתעד את כל ברירות המחדל במסמכי התיעוד של האתר.
הנה כמה בקשות לדוגמה (תוכלו לראות עוד דוגמאות של בקשות ותגובות בסוף המסמך בקטע דוגמאות):
הערה: לפני השליחה, צריך לסמן את מחרוזות הבקשה הבאות, ואת אלה שמוצגות בקטע Examples.
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 | לא |
לא |
שאילתה שנכתבת בשפת השאילתות של GoogleVisual API, ומציינים איך לסנן, למיין או לשנות את הנתונים המוחזרים בצורה אחרת. אין צורך להקיף את המחרוזת במירכאות. לדוגמה: |
| tqx | לא |
כן |
קבוצה של צמדי מפתח/ערך שמופרדים בנקודתיים לפרמטרים רגילים או מותאמים אישית. זוגות מופרדים באמצעות נקודה-פסיק. רשימה של הפרמטרים הרגילים שמוגדרים על ידי פרוטוקול הוויזואליזציה:
לדוגמה: |
| tqrt, tqrt | לא |
לא |
שמור: מתעלמים מהפרמטר הזה. השיטה ששימשה לשליחת השאילתה. |
פורמט התגובות
פורמט התשובה תלוי בפרמטר out של הבקשה, שמציין את סוג התגובה הצפויה. בקטעים הבאים מוסבר איך להגיב לכל סוג בקשה:
- JSON - החזרת תגובת JSON שכוללת את הנתונים באובייקט JavaScript, שניתן להעביר ישירות ל-constructor של
DataTableכדי לאכלס אותו. זהו, ללא ספק, סוג הבקשה הנפוץ ביותר והחשוב ביותר להטמעה נכונה. - CSV – הפונקציה מחזירה רשימה שטוחה של ערכים מופרדים בפסיקים שהדפדפן צריך לטפל בהם.
- TSV – הפונקציה מחזירה רשימה של ערכים מופרדים בטאבים שהדפדפן צריך לטפל בהם.
- HTML – הפונקציה מחזירה טבלת HTML שהדפדפן מעבד.
כדי ליצור את הפורמטים האלה, אפשר להשתמש בספריית מקורות הנתונים של Google להמחשת הנתונים (Java) או בספריית Python להצגה חזותית.
פורמט תגובה מסוג JSON
פורמט התשובה שמוגדר כברירת מחדל הוא JSON אם הבקשה כוללת כותרת "X-DataSource-Auth", ו-JSONP במקרים אחרים. הערה: לקוח התרשים של Google תומך למעשה בגרסה מתוקנת של JSON ו-JSONP. אם אתם משתמשים בספריות העזרה של Java או Python, הן יוציאו את הקוד המתאים בשבילכם. אם אתם מנתחים את התשובות באופן ידני, תוכלו לעיין בקטע שינויים בפורמט JSON שבהמשך.
כשאוכפים בקשות לאותו דומיין, צריך לאמת את הנוכחות של הכותרת "X-DataSource-Auth" בבקשה ולהשתמש בקובצי cookie להרשאות.
זהו פורמט התשובה היחיד שצוין על ידי ה-method google.visualization.Query.send() של GoogleVisual API.
בסוף הדף הזה אפשר לראות כמה בקשות ותגובות של 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 | כן* |
מספר מחרוזת שמציין את המזהה של הבקשה עבור הלקוח הזה. אם זה
היה בבקשה, מוחזר אותו הערך. לפרטים נוספים, אפשר לעיין בתיאור של reqId בקטע הבקשות. * אם הפרמטר הזה לא צוין בבקשה, אין צורך להגדיר אותו בתשובה. |
| status | כן |
מחרוזת שמתארת את ההצלחה או הכשל של הפעולה הזו. חייב להיות אחד מהערכים הבאים בלבד:
לדוגמה: |
| אזהרות | רק אם status=warning |
מערך של אובייקט אחד או יותר, כאשר כל אחד מהם מתאר בעיה לא חמורה.
חובה אם הוא
לדוגמה: |
| שגיאות | חובה אם status=error |
מערך של אובייקט אחד או יותר, כאשר כל אחד מהם מתאר שגיאה. חובה אם הוא
המערך מכיל את איברי המחרוזת הבאים (החזרת ערך אחד בלבד לכל איבר):
לדוגמה:
|
| sig | לא |
ערך מגובב (hashed) של אובייקט הטבלה. המדיניות הזו שימושית לאופטימיזציה של העברת הנתונים בין הלקוח למקור הנתונים. אפשר לבחור כל אלגוריתם גיבוב (hash) שרוצים. אם המאפיין הזה תומך בנכס הזה, צריך להחזיר את הערך שהועבר על ידי הלקוח אם לא מוחזרים נתונים, או להחזיר גיבוב חדש אם מוחזרים נתונים חדשים. לדוגמה: |
| טבלה | לא |
אובייקט {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 תומך בייצוג חוקי של תאריכים ב-JSON כמחרוזת בפורמט הבא: Date(year, month, day[,hour, minute, second[, millisecond]])
שבו כל מה שאחרי היום הוא אופציונלי, והחודשים מבוססים על אפס.
אופטימיזציה של תשובות JSON
אם לקוח שולח שתי בקשות, והנתונים לא השתנו בין הבקשות, כדאי לא לשלוח מחדש את הנתונים. פעולה זו תבזבז את רוחב הפס. כדי לייעל את הבקשות, הפרוטוקול תומך במטמון של הנתונים אצל הלקוח, ובשליחת אות בתשובה אם הנתונים לא השתנו מאז הבקשה האחרונה. כך זה עובד:
- הלקוח שולח בקשה למקור הנתונים.
- מקור הנתונים יוצר
DataTableוגם גיבוב של האובייקטDataTable, ומחזיר את שניהם (הגיבוב מוחזר בפרמטרtqx.sig). הלקוח של GoogleVisual API שומר במטמון את הערךDataTableואת הערךsig. - הלקוח שולח בקשה נוספת לנתונים, כולל הערך של
tqx.sigשנשמר במטמון. - מקור הנתונים יכול להגיב באחת משתי דרכים:
- אם הנתונים השתנו מהבקשה הקודמת, מקור הנתונים שולח חזרה את
הגיבוב (hash) החדש של
DataTableואת הערך החדשsig. - אם הנתונים לא השתנו מהבקשה הקודמת, מקור הנתונים שולח חזרה את
status=error,reason=not_modified,sig=old_sig_value.
- אם הנתונים השתנו מהבקשה הקודמת, מקור הנתונים שולח חזרה את
הגיבוב (hash) החדש של
- בכל מקרה, הדף שמארח את התרשים מקבל תגובה מוצלחת,
והוא יכול לאחזר את
DataTableעל ידי קריאה ל-QueryResponse.getDataTable(). אם הנתונים זהים, זו פשוט הגרסה השמורה במטמון של הטבלה.
הערה: האפשרות הזו פועלת רק בבקשות JSON מתרשימים שנוצרו ב-GoogleVisual API.
פורמט תגובה בקובץ 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.
אם הבקשה כוללת חבר 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>
דוגמאות
הנה מספר בקשות ותגובות לדוגמה. לתשומת ליבכם,
לא בוצע סימון של כתובת URL בתו בריחה (escape). הפעולה הזו מתבצעת בדרך כלל על ידי הדפדפן או על ידי האובייקט 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.
- ספריית מקור הנתונים של Python (מ-Google) – יצירת טבלת תשובות יוצרת את התחביר של התשובות. לא מטפלים בניתוח הבקשה או בהטמעה של שפת שאילתות ה-SQL של Google Chart Tools.
- MC-Google_Visualization (צד שלישי) – ספרייה בצד השרת של PHP שאפשר להשתמש בה כדי להטמיע מקור נתונים של Chart Tools עבור מנועי מסדי נתונים ב-MySQL, SQLite ו-PostgreSQL באמצעות PDO.
- bortosky-google-visualization (צד שלישי) – זו ספרייה שעוזרת ליצור טבלת נתונים של GoogleVisual API למשתמשי .NET.
- GV Streamer (צד שלישי) – GV Streamer הוא כלי בצד השרת שיכול להמיר נתונים ממקורות שונים לתגובות חוקיות לשאילתות של תרשימים של Google. ב-GV Streamer יש תמיכה בכמה שפות (למשל PHP, Java, .NET) ובכמה מקורות נתונים גולמיים (למשל MySql).
- TracGViz (צד שלישי) – TracGViz הוא כלי חינמי וקוד פתוח שמספק רכיבים, כדי ש-Trac
- vis-table (צד שלישי) - ספרייה שהטמיעה מקור נתונים של כלי התרשים של Google ב-PHP. הוא מורכב משלושה חלקים עיקריים. הטמעת טבלת הנתונים עצמה, המנתח של שפת השאילתה וכלי העיצוב.
- הטמעת מקורות נתונים של Google ב-Oracle PL/SQL (צד שלישי) - חבילת Oracle PL/SQL שמאפשרת ל-Oracle להעביר מקורות נתונים לשרת ישירות ממסד הנתונים. עכשיו אפשר להשתמש בכל שאילתה של Oracle בתור מקור נתונים של Google Chart Tools (החבילה תחזיר קובץ JSON עם הנתונים). יש בו תמיכה כמעט מלאה ב-Google Query Language.