Menerapkan Chart Tools Datasource Protocol (V0.6)

Halaman ini menjelaskan cara menerapkan layanan yang mendukung protokol Sumber Data Chart Tools untuk mengekspos data ke diagram menggunakan class Kueri.

Daftar Isi

Audiens

Halaman ini ditujukan terutama bagi developer yang akan membuat sumber data mereka sendiri tanpa bantuan Library Sumber Data Chart Tools. Jika Anda menggunakannya atau library helper lainnya, baca dokumentasi library Anda terlebih dahulu.

Halaman ini juga ditujukan bagi pembaca yang tertarik untuk memahami protokol kabel yang digunakan untuk komunikasi antara visualisasi klien dan sumber data.

Jika Anda membuat atau menggunakan visualisasi, Anda tidak perlu membaca halaman ini.

Untuk membaca dokumen ini, Anda harus memahami sintaksis permintaan JSON dan HTTP dasar. Anda juga harus memahami bagaimana diagram bekerja dari sudut pandang pengguna.

Catatan: Google tidak secara resmi memberikan endorsement atau mendukung Sumber Data non-Google yang mendukung protokol Sumber Data Chart Tools.

Ringkasan

Anda dapat menerapkan protokol Sumber Data Chart Tools untuk menjadi penyedia sumber data untuk diagram Anda sendiri, atau diagram lainnya. Sumber Data Chart Tools mengekspos URL, yang disebut URL Sumber Data, yang dapat digunakan diagram untuk mengirim permintaan GET HTTP. Sebagai respons, sumber data menampilkan data yang diformat dengan benar yang dapat digunakan diagram untuk merender grafik pada halaman. Protokol permintaan-respons ini dikenal sebagai protokol kabel Google Visualization API.

Data yang disajikan oleh sumber data dapat diekstrak dari berbagai resource, seperti file atau database. Satu-satunya batasan adalah Anda dapat memformat data sebagai tabel dua dimensi dengan kolom yang memiliki jenis.

Sebagai Sumber Data Chart Tools, Anda harus mengurai permintaan dalam format tertentu, dan menampilkan respons dalam format tertentu. Anda dapat melakukannya dengan salah satu dari dua cara umum:

  • Gunakan salah satu library helper berikut untuk menangani permintaan dan respons, serta membuat DataTable yang akan ditampilkan. Jika menggunakan salah satu library ini, Anda hanya perlu menulis kode yang diperlukan untuk menyediakan data Anda ke library dalam bentuk tabel.
    • Library Sumber Data Java - Menangani permintaan dan respons, membuat tabel respons dari data yang Anda berikan, dan mengimplementasikan bahasa kueri SQL Google Chart Tools.
    • Library Python Datasource - Membuat tabel respons yang menghasilkan sintaksis respons. Tidak menangani penguraian permintaan atau penerapan bahasa kueri SQL Alat Diagram Google.

      ATAU

  • Tulis sumber data Anda sendiri dari awal dengan menangani permintaan, membuat DataTable, dan mengirimkan respons.

Cara kerjanya:

  1. Sumber data mengekspos URL, yang disebut URL sumber data, ke diagram yang mengirimkan permintaan HTTP GET.
  2. Klien membuat permintaan HTTP GET dengan parameter yang menjelaskan format yang akan digunakan untuk data yang ditampilkan, string kueri opsional, dan parameter kustom opsional.
  3. Datasource menerima dan mengurai permintaan, seperti yang dijelaskan dalam Format Permintaan.
  4. Sumber Data menyiapkan data dalam format yang diminta; biasanya, berupa tabel JSON. Format respons dibahas di bagian Format Respons. Sumber Data secara opsional dapat mendukung bahasa kueri Visualization API yang menentukan pemfilteran, pengurutan, dan manipulasi data lainnya.
  5. Datasource membuat respons HTTP yang mencakup data serial dan parameter respons lainnya, lalu mengirimkannya kembali ke klien seperti yang dijelaskan dalam Format Respons

Catatan: Semua parameter dan nilai konstanta string yang tercantum dalam dokumen ini untuk permintaan dan respons (seperti responseHandler dan "ok") menggunakan huruf kecil, dan peka huruf besar/kecil.

Persyaratan Minimum

Berikut adalah persyaratan minimum untuk berfungsi sebagai Sumber Data Alat Diagram:

  • Sumber data harus menerima permintaan GET HTTP, dan harus tersedia untuk klien Anda.
  • Protokol dapat mengubah dan mendukung skema versi (versi saat ini adalah 0.6), sehingga sumber data Anda harus mendukung permintaan yang menggunakan versi sebelumnya serta versi saat ini. Anda harus mencoba mendukung versi baru segera setelah dirilis untuk menghindari merusak klien yang melakukan upgrade ke versi terbaru dengan cepat.
  • Jangan gagal jika properti yang tidak diketahui dikirim sebagai bagian dari permintaan. Hal ini karena versi baru dapat memperkenalkan properti baru yang tidak Anda ketahui.
  • Hanya uraikan properti yang Anda harapkan. Meskipun versi baru mungkin memperkenalkan properti baru, jangan menerima dan menggunakan seluruh string permintaan secara membabi buta. Untuk melindungi diri Anda dari serangan berbahaya, uraikan dengan hati-hati dan hanya gunakan properti yang Anda harapkan.
  • Dokumentasikan persyaratan sumber data Anda dengan hati-hati jika Anda tidak melakukan coding sendiri diagram klien. Hal ini termasuk mendokumentasikan informasi berikut:
    • Parameter khusus apa pun yang Anda terima,
    • Apakah Anda dapat mengurai bahasa kueri Google Visualization API atau tidak, dan
    • Jenis data yang Anda tampilkan, dan struktur data tersebut (apa yang diwakili oleh baris dan kolom, dan juga pelabelan).
  • Lakukan semua tindakan pencegahan keamanan standar untuk situs yang menerima permintaan dari klien yang tidak dikenal. Anda dapat mendukung MD5, hashing, dan mekanisme keamanan lainnya dalam parameter untuk mengautentikasi permintaan atau membantu mengamankan dari serangan berbahaya, serta mengharapkan klien mengetahui persyaratan Anda dan meresponsnya. Namun, pastikan untuk mendokumentasikan semua persyaratan Anda dengan baik, jika Anda tidak melakukan coding sendiri pada diagram. Lihat Pertimbangan Keamanan di bawah.
  • Semua string permintaan dan respons harus berenkode UTF-8.
  • Format respons yang paling penting adalah JSON. Pastikan untuk menerapkan JSON terlebih dahulu, karena ini adalah format yang digunakan oleh sebagian besar diagram. Tambahkan jenis respons lain setelahnya.
  • Anda tidak diwajibkan untuk mendukung bahasa kueri Visualization API, tetapi hal ini akan menjadikan sumber data Anda lebih berguna bagi pelanggan.
  • Anda tidak harus mendukung permintaan dari setiap dan semua jenis diagram, dan Anda dapat mendukung parameter kustom untuk diagram kustom. Namun, Anda harus menampilkan respons dalam format standar yang dijelaskan di bawah ini.

Pertimbangan Keamanan

Saat mendesain sumber data, Anda perlu mempertimbangkan seberapa aman data Anda. Anda dapat menggunakan berbagai skema keamanan untuk situs Anda, mulai dari akses sandi sederhana hingga autentikasi cookie yang aman.

Serangan XSSI (penyertaan skrip lintas situs) berisiko dengan diagram. Pengguna mungkin membuka halaman yang berisi skrip berbahaya yang kemudian mulai mencoba membuat kueri ke URL sumber data, menggunakan kredensial pengguna saat ini. Jika pengguna belum logout dari situs, skrip akan diautentikasi sebagai pengguna saat ini dan memiliki izin di situs tersebut. Dengan tag <script src>, skrip berbahaya dapat menyertakan sumber data, mirip dengan JSONP.

Sebagai tingkat keamanan tambahan, Anda dapat mempertimbangkan untuk membatasi permintaan yang berasal dari domain yang sama dengan sumber data Anda. Tindakan ini akan sangat membatasi visibilitas sumber data Anda, tetapi jika Anda memiliki data yang sangat sensitif yang tidak boleh diakses dari luar domain, sebaiknya pertimbangkan hal tersebut. Sumber data yang hanya mengizinkan permintaan dari domain yang sama disebut sumber data yang dibatasi, bukan sumber data tidak dibatasi, yang akan menerima kueri dari domain mana pun. Berikut ini beberapa detail cara menerapkan sumber data yang dibatasi:

Untuk memastikan bahwa permintaan benar-benar berasal dari dalam domain Anda, dan bukan dari domain luar (atau browser di dalam domain yang berada di bawah serangan XSRF):

  • Verifikasi keberadaan header "X-DataSource-Auth" dalam permintaan. Header ini ditentukan oleh Google Visualization API; Anda tidak perlu memeriksa konten header ini, cukup verifikasi bahwa header tersebut ada di sana. Jika Anda menggunakan library Data source Google Chart Tools, Anda dapat meminta library tersebut menangani hal ini untuk Anda.
  • Gunakan autentikasi cookie untuk mengautentikasi klien. Tidak ada cara yang diketahui untuk memasukkan header kustom ke permintaan lintas-domain sambil tetap mempertahankan cookie autentikasi.
  • Buat JavaScript tidak dapat dijalankan saat disertakan dengan tag <script src>. Untuk melakukannya, awali respons JSON Anda dengan )]}' yang diikuti dengan baris baru. Di klien, hapus awalan dari respons. Untuk XmlHttpRequest, hal ini hanya dapat dilakukan jika permintaan berasal dari domain yang sama.

Format Permintaan

Klien mengirim permintaan GET HTTP dengan beberapa parameter, termasuk elemen kustom, string kueri opsional, tanda tangan, dan elemen lainnya. Anda hanya bertanggung jawab untuk menguraikan parameter yang dijelaskan di bagian ini, dan harus berhati-hati untuk tidak menangani parameter lain agar terhindar dari serangan berbahaya.

Pastikan Anda memiliki nilai default untuk parameter opsional (baik standar maupun kustom), dan dokumentasikan semua nilai default dalam dokumentasi situs Anda.

Berikut beberapa contoh permintaan (Anda bisa melihat lebih banyak contoh permintaan dan respons di bagian akhir dokumen ini di Contoh):

Catatan: String permintaan berikut dan yang ditampilkan di bagian Examples harus di-escape URL sebelum dikirim.

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

Berikut adalah daftar semua parameter standar dalam string permintaan. Perhatikan bahwa nama parameter (seperti "version") dan nilai string konstan (seperti "ok", "warning", dan "not_Modify") peka huruf besar/kecil. Tabel ini juga menjelaskan apakah parameter tersebut harus dikirim, dan jika dikirim, apakah Anda diwajibkan untuk menanganinya.

Parameter
Wajib diisi dalam Permintaan?
Sumber Data yang Harus Ditangani?
Deskripsi
tq
Tidak
Tidak

Kueri yang ditulis dalam bahasa kueri Google Visualization API, yang menentukan cara memfilter, mengurutkan, atau memanipulasi data yang ditampilkan. String tidak perlu diberi tanda kutip.

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

tqx
Tidak
Ya

Serangkaian key-value pair yang dipisahkan titik dua untuk parameter standar atau kustom. Pasangan dipisahkan dengan titik koma. Berikut adalah daftar parameter standar yang ditentukan oleh protokol Visualization:

  • reqId - [Wajib ada dalam permintaan; Sumber data harus menangani] ID numerik untuk permintaan ini. Hal ini digunakan agar jika klien mengirim beberapa permintaan sebelum menerima respons, sumber data dapat mengidentifikasi respons dengan permintaan yang tepat. Kirim nilai ini kembali dalam respons.
  • version - [Opsional dalam permintaan; Sumber data harus menangani] Nomor versi protokol Google Visualization. Versi saat ini adalah 0.6. Jika tidak terkirim, gunakan versi terbaru.
  • sig - [Opsional dalam permintaan; Opsional untuk sumber data yang akan ditangani] Hash DataTable yang dikirim ke klien ini dalam setiap permintaan sebelumnya ke sumber data ini. Ini adalah pengoptimalan untuk menghindari pengiriman data yang identik ke klien dua kali. Lihat Mengoptimalkan Permintaan di bawah untuk mengetahui informasi tentang cara menggunakan fitur ini.
  • out - [Opsional dalam permintaan; Sumber data harus menangani] String yang menjelaskan format untuk data yang ditampilkan. Nilainya dapat berupa salah satu dari nilai berikut:
    • json - [Nilai default] String respons JSON (dijelaskan di bawah).
    • html - Tabel HTML dasar dengan baris dan kolom. Jika ini digunakan, satu-satunya hal yang harus ditampilkan adalah tabel HTML dengan data; ini berguna untuk proses debug, seperti yang dijelaskan di bagian Format Respons di bawah.
    • csv - Nilai yang dipisahkan koma. Jika ini digunakan, satu-satunya hal yang ditampilkan adalah string data CSV. Anda dapat meminta nama kustom untuk file dalam header respons dengan menentukan parameter outFileName.
    • tsv-excel - Mirip dengan csv, tetapi menggunakan tab, bukan koma, dan semua data dienkode dengan utf-16.
    Perlu diketahui bahwa satu-satunya jenis data yang akan diminta oleh diagram yang dibuat di Google Visualization API adalah json. Lihat Format Respons di bawah untuk detail tentang setiap jenis.
  • responseHandler - [Opsional dalam permintaan; Sumber data harus menangani] Nama string fungsi penanganan JavaScript di halaman klien yang akan dipanggil dengan respons. Jika tidak disertakan dalam permintaan, nilainya adalah "google.visualization.Query.setResponse". Ini akan dikirim kembali sebagai bagian dari respons; lihat Format Respons di bawah untuk mempelajari caranya.
  • outFileName - [Opsional dalam permintaan; Opsional untuk ditangani sumber data] Jika menentukan out:csv atau out:tsv-excel, Anda dapat meminta nama file yang ditentukan di sini secara opsional. Contoh: outFileName=results.csv.

Contoh: tqx=version:0.6;reqId:1;sig:5277771;out:json; responseHandler:myQueryHandler

tqrt
Tidak
Tidak

Dicadangkan: abaikan parameter ini. Metode yang digunakan untuk mengirim kueri.

Format Respons

Format respons bergantung pada parameter out permintaan, yang menentukan jenis respons yang diharapkan. Lihat bagian berikut untuk mempelajari cara merespons setiap jenis permintaan:

  • JSON - Menampilkan respons JSON yang menyertakan data dalam objek JavaScript yang dapat diteruskan langsung ke konstruktor DataTable untuk mengisinya. Sejauh ini, jenis permintaan ini paling umum, dan paling penting untuk diterapkan dengan benar.
  • CSV - Menampilkan daftar nilai datar yang dipisahkan koma, yang akan ditangani oleh browser.
  • TSV - Menampilkan daftar nilai yang dipisahkan tab, yang akan ditangani oleh browser.
  • HTML - Menampilkan tabel HTML yang akan dirender oleh browser.

Anda dapat menggunakan Library Sumber Data Visualisasi Google (java) atau library Python visualisasi untuk membuat format output ini untuk Anda.

Format Respons JSON

Format respons default adalah JSON jika permintaan menyertakan header "X-DataSource-Auth", dan JSONP jika tidak. Perhatikan bahwa klien diagram Google sebenarnya mendukung versi JSON dan JSONP yang dimodifikasi; jika Anda menggunakan library helper Java atau Python, library tersebut akan memunculkan kode yang tepat untuk Anda; jika Anda mengurai respons secara manual, lihat Modifikasi JSON di bawah.

Jika Anda menerapkan permintaan domain yang sama, Anda harus memverifikasi keberadaan header "X-DataSource-Auth" pada permintaan dan menggunakan cookie otorisasi.

Ini adalah satu-satunya format respons yang ditentukan oleh metode Google Visualization API google.visualization.Query.send() . Anda dapat melihat beberapa contoh permintaan dan respons JSON di bagian akhir halaman ini dalam Contoh. Anda dapat menggunakan library helper Java atau Python untuk membuat string respons ini untuk Anda.

Format respons ini adalah objek JSON berenkode UTF-8 (objek yang diapit oleh tanda kurung kurawal { } dengan setiap properti dipisahkan oleh koma) yang menyertakan properti pada tabel di bawah (data ditetapkan ke properti table). Objek JSON ini harus digabungkan di dalam nilai parameter responseHandler dari permintaan. Jadi, jika nilai responseHandler permintaan adalah "myHandler", Anda harus menampilkan string seperti ini (hanya satu properti yang ditampilkan agar lebih singkat):

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

Jika permintaan tidak menyertakan nilai responseHandler, nilai defaultnya adalah "google.visualization.Query.setResponse", jadi Anda harus menampilkan string seperti ini (hanya satu properti yang ditampilkan agar lebih singkat):

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

Berikut adalah anggota objek respons yang tersedia:

Properti
Wajib?
Deskripsi
versi
Tidak

Nomor string yang memberikan nomor versi protokol kabel Visualisasi Google. Jika tidak ditentukan, klien akan menggunakan versi terbaru.

Contoh: version=0.6

reqId
Ya*
Nomor string yang menunjukkan ID permintaan ini untuk klien ini. Jika ini ada dalam permintaan, tampilkan nilai yang sama. Lihat deskripsi reqId di bagian permintaan untuk detail selengkapnya.

* Jika parameter ini tidak ditentukan dalam permintaan, Anda tidak perlu menetapkannya dalam respons.
status
Ya

String yang menjelaskan keberhasilan atau kegagalan operasi ini. Harus berupa satu dan hanya salah satu dari nilai berikut:

  • ok - Permintaan berhasil. Tabel harus disertakan dalam properti table.
  • warning - Berhasil, tetapi ada masalah. Tabel harus disertakan dalam properti table.
  • error - Terjadi masalah. Jika Anda mengembalikannya, Anda tidak boleh menampilkan table dan harus menampilkan errors.

Contoh: status:'warning'

peringatan
Hanya jika status=warning

Array berisi satu atau beberapa objek, masing-masing menjelaskan masalah non-fatal. Wajib jika status=warning, tidak diizinkan jika sebaliknya. Setiap objek memiliki properti string berikut (hanya menampilkan satu nilai untuk setiap properti):

  • reason - [Wajib] Deskripsi string satu kata peringatan. Protokol menetapkan nilai berikut, tetapi Anda dapat menentukan nilai Anda sendiri, jika perlu (tetapi, klien tidak akan memproses nilai kustom dengan cara khusus). Anda hanya dapat memiliki satu nilai reason:
    • data_truncated - Beberapa baris yang ditampilkan DataTable telah dihapus, baik karena pengguna menyertakan string kueri yang memangkas daftar hasil, atau sumber data tidak ingin menampilkan hasil lengkap karena alasan tertentu.
    • other - Peringatan umum yang tidak ditentukan.
  • message - [Opsional] String singkat yang dikutip yang menjelaskan masalah, yang mungkin digunakan sebagai judul untuk kotak pemberitahuan. Kolom ini mungkin ditampilkan kepada pengguna. HTML tidak didukung.
  • detailed_message - [Opsional] Pesan string dengan kutipan terperinci yang menjelaskan masalah, dan solusi yang memungkinkan. Satu-satunya HTML yang didukung adalah elemen <a> dengan satu atribut href. Encoding Unicode didukung. Kolom ini mungkin ditampilkan kepada pengguna.

Contoh: warnings:[{reason:'data_truncated',message:'Retrieved data was truncated'}]

error
Wajib diisi jika status=error

Array berisi satu atau beberapa objek, masing-masing menjelaskan error. Wajib jika status=error, tidak diizinkan jika sebaliknya. Ini mirip dengan nilai warnings. Perlu diperhatikan bahwa error not_modified, meskipun merupakan error, sebenarnya bukan error untuk klien.

Array memiliki anggota string berikut (hanya menampilkan satu nilai untuk setiap anggota):

  • reason - [Wajib] Sama seperti warnings.reason, tetapi nilai berikut ditentukan:
    • not_modified - Data tidak berubah sejak permintaan terakhir. Jika ini adalah alasan errornya, Anda tidak boleh memiliki nilai untuk table.
    • user_not_authenticated - Jika sumber data memerlukan autentikasi dan belum dilakukan, tentukan nilai ini. Selanjutnya, klien akan menampilkan pemberitahuan dengan nilai message.
    • unknown_data_source_id
    • access_denied
    • unsupported_query_operation
    • invalid_query
    • invalid_request
    • internal_error
    • not_supported
    • illegal_formatting_patterns
    • other - Error umum yang tidak ditentukan.
  • message - [Opsional] Sama seperti warnings.message. Catatan: Ada kemungkinan bahwa pengguna berbahaya dapat menggunakan string data mendetail sebagai cara untuk mengakses data yang tidak sah, atau bahkan menggunakannya untuk menyerang data atau situs Anda. Jika Anda menyimpan data yang seharusnya aman, atau memproses kueri pengguna secara langsung, pertimbangkan untuk tidak menampilkan pesan error mendetail yang dapat memberikan informasi kepada penyerang; sebagai gantinya, berikan pesan umum, seperti "String kueri yang buruk".
  • detailed_message - [Opsional] Sama seperti warnings.detailed_message. Lihat peringatan untuk informasi message yang terlalu detail.

Contoh: status:'error',errors:[{reason:'not_modified',message:'Data not modified'}]

sig
Tidak

Nilai objek tabel yang di-hash. Berguna untuk mengoptimalkan transfer data antara klien dan sumber data. Anda dapat memilih algoritma {i>hash<i} yang Anda inginkan. Jika mendukung properti ini, Anda harus menampilkan nilai yang diteruskan oleh klien jika tidak ada data yang ditampilkan, atau menampilkan hash baru jika data baru ditampilkan.

Contoh: sig:'5982206968295329967'

meja
Tidak

Objek DataTable dalam notasi literal JavaScript, dengan data Anda. Lihat bagian referensi tertaut untuk mengetahui detail tentang format objek ini. Berikut adalah contoh tabel data sederhana:

{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'}]}
      ]
} 

Properti table hanya boleh ada jika status=ok atau status=warning. Jika Anda tidak menampilkan data, jangan sertakan properti ini (yaitu, jangan teruskan kembali properti dengan nilai string kosong).

Contoh: Lihat Contoh di bawah.

 

Perlu JSON ketat

Library bantuan Google, dan semua kueri yang dikirim ke Google, menampilkan JSON/JSONP yang ketat. Jika Anda tidak mengurai sendiri kode yang ditampilkan, hal ini seharusnya tidak menjadi masalah bagi Anda. Jika ya, Anda dapat menggunakan JSON.parse() untuk mengonversi string JSON menjadi objek JavaScript. Satu perbedaan dalam cara JSON diproses oleh API adalah, meskipun JSON tidak mendukung nilai Tanggal JavaScript (misalnya, "new Date(2008,1,28,0,31,26)"; API mendukung representasi tanggal JSON yang valid sebagai string dalam format berikut: Date(year, month, day[,hour, minute, second[, millisecond]]) dengan semua setelah hari bersifat opsional, dan bulan berbasis nol.

 

Mengoptimalkan Respons JSON

Jika klien membuat dua permintaan, dan data tidak berubah di antara permintaan, sebaiknya jangan mengirim ulang data; tindakan ini akan membuang-buang bandwidth. Agar permintaan lebih efisien, protokol mendukung caching data pada klien, dan mengirim sinyal dalam respons jika data belum berubah sejak permintaan terakhir. Berikut ini cara kerjanya:

  1. Klien mengirim permintaan ke sumber data.
  2. Sumber data menghasilkan DataTable serta hash objek DataTable, dan menampilkan keduanya dalam responsnya (hash ditampilkan dalam parameter tqx.sig). Klien Google Visualization API meng-cache nilai DataTable dan sig.
  3. Klien mengirimkan permintaan lain untuk data, termasuk nilai tqx.sig yang di-cache.
  4. Sumber data dapat merespons dengan salah satu dari dua cara berikut:
    • Jika data telah berubah dari permintaan sebelumnya, sumber data akan mengirimkan kembali hash nilai DataTable dan sig yang baru.
    • Jika data tidak berubah dari permintaan sebelumnya, sumber data akan mengirim kembali status=error, reason=not_modified, sig=old_sig_value.
  5. Dalam kedua kasus tersebut, halaman yang menghosting diagram akan mendapatkan respons yang berhasil, dan dapat mengambil DataTable dengan memanggil QueryResponse.getDataTable(). Jika datanya sama, maka hanya versi tabel yang di-cache.

Perhatikan bahwa ini hanya berfungsi untuk permintaan JSON dari diagram yang dibuat di Google Visualization API.

Format Respons CSV

Jika permintaan menentukan out:csv, respons tidak menyertakan metadata, tetapi hanya representasi CSV dari data. Tabel CSV biasanya merupakan daftar yang dipisahkan koma, dengan setiap baris data berupa daftar nilai yang dipisahkan koma, yang diakhiri dengan karakter baris baru UNIX (\n). Nilai sel harus memiliki jenis yang sama untuk setiap kolom. Baris pertama adalah label kolom. Berikut adalah contoh tabel tiga baris dengan tiga kolom:

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

Format CSV tidak ditentukan oleh protokol ini; sumber data bertanggung jawab untuk menentukan format CSV-nya. Namun, format yang umum adalah kumpulan nilai yang dipisahkan koma (tanpa spasi intervensi), dan baris baru (\n) di akhir setiap baris. Saat menerima balasan string CSV, browser mungkin menanyakan kepada pengguna aplikasi apa yang akan digunakan untuk membuka string tersebut, atau mungkin cukup merendernya di layar. Library open source Java dan Python menyediakan metode untuk mengonversi DataTable menjadi string CSV.

Jika permintaan menyertakan anggota outFileName dari parameter tqx , Anda harus mencoba menyertakan nama file yang ditentukan di header respons.

Objek google.visualization.Query tidak mendukung permintaan respons CSV. Jika klien ingin meminta CSV, Anda dapat menyematkan gadget Toolbar Visualisasi di halaman, atau mereka dapat menggunakan kode khusus untuk membuat permintaan, atau Anda dapat memberikan link yang menetapkan properti out:csv dari tqx secara eksplisit, seperti yang ditunjukkan pada URL permintaan berikut:

Permintaan

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

Respons

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

Format Respons TSV

Jika permintaan menentukan out:tsv-excel, respons tidak menyertakan metadata, tetapi hanya representasi data yang dipisahkan tab, dienkode utf-16. Jika permintaan menyertakan anggota outFileName dari parameter tqx , Anda harus mencoba menyertakan nama file yang ditentukan di header respons.

Format Respons HTML

Jika permintaan menentukan out:html, respons harus berupa halaman HTML yang menentukan tabel HTML dengan data. Ini berguna untuk men-debug kode, karena browser dapat merender hasil Anda dalam format yang dapat dibaca secara langsung. Anda tidak dapat mengirim kueri untuk respons HTML menggunakan objek google.visualization.Query. Anda harus membuat kueri untuk respons HTML menggunakan kode kustom, atau dengan mengetik URL yang mirip dengan URL ini di browser Anda:

Permintaan

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

Respons

<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>

Contoh

Berikut beberapa contoh permintaan dan respons. Perhatikan bahwa permintaan tidak di-escape URL; yang biasanya dilakukan oleh browser, atau objek google.visualization.Query.

Permintaan sederhana: Menampilkan informasi dasar dengan tabel tiga kolom dan empat baris.

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'}]}]}});

Permintaan sederhana dengan pengendali respons: Menampilkan tabel tiga kolom, tiga baris dengan berbagai jenis data.

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'}]}]}});

Kueri dengan string kueri sederhana: Permintaan untuk satu kolom, menampilkan satu kolom dengan empat baris.

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'}]}]}});

Error data tidak diubah: Contoh error 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'}]});

Peringatan data terpotong: Contoh peringatan data_truncated. Perhatikan bahwa permintaan masih menampilkan data.

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'}]}]}});

Error akses ditolak: Contoh error 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'}]});

String kueri tidak valid: Contoh permintaan dengan string kueri yang tidak valid. Perlu diperhatikan bahwa pesan mendetail adalah pesan umum, bukan pesan error yang sebenarnya.

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.'}]});

Fitur Pengembangan

  • Library Sumber Data Java (dari Google) - Menangani permintaan dan respons, membuat tabel respons dari data yang Anda berikan, dan menerapkan bahasa kueri SQL Google Chart Tools.
  • Library Sumber Data Python (dari Google) - Membuat tabel respons yang menghasilkan sintaksis respons. Tidak menangani penguraian permintaan atau penerapan bahasa kueri SQL Alat Diagram Google.
  • MC-Google_Visualization (Pihak ketiga) - Ini adalah library sisi server PHP yang dapat Anda gunakan untuk menerapkan Sumber Data Fitur Diagram untuk mesin database MySQL, SQLite, dan PostgreSQL menggunakan PDO.
  • bortosky-google-visualization (Pihak ketiga) - Ini adalah library helper untuk membuat Google Visualization API Datatable bagi pengguna .NET.
  • GV Streamer (Pihak ketiga) - GV Streamer adalah alat sisi server yang dapat mengonversi data dari berbagai sumber menjadi respons kueri yang valid terhadap diagram Google. GV Streamer mendukung beberapa bahasa (misalnya PHP, Java, .NET) dan beberapa sumber data mentah (misalnya MySql).
  • TracGViz (Pihak ketiga) - TracGViz adalah alat gratis dan open source yang menyediakan komponen sehingga Trac dapat menggunakan gadget diagram serta menerapkan data yang dikelola oleh Trac sebagai sumber Data Alat Google Chart.
  • vis-table (Pihak ketiga) - Library yang menerapkan Sumber Data Alat Diagram Google di PHP. Bagian ini memiliki tiga bagian utama. Implementasi tabel data itu sendiri, parser bahasa kueri, dan pemformat.
  • Implementasi Sumber Data Google di Oracle PL/SQL (Pihak ketiga) - Paket PL/SQL Oracle yang memungkinkan Oracle me-server Sumber Data langsung dari database. Jadi pada dasarnya, Anda dapat menggunakan kueri Oracle sebagai Datasource Google Chart Tools (paket ini akan menampilkan file JSON beserta data). Alat ini memiliki dukungan yang hampir penuh untuk Bahasa Kueri Google.