Menerapkan Protokol Sumber Data Chart Tools (V0.6)

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

Daftar Isi

  1. Penonton
  2. Ringkasan
  3. Pertimbangan Keamanan
  4. Format Permintaan
  5. Format Respons
    1. Format Respons JSON
    2. Format Respons CSV
    3. Format Respons HTML
  6. Contoh
  7. Alat Pengembangan

Penonton

Halaman ini ditujukan terutama bagi developer yang akan membuat sumber datanya sendiri tanpa bantuan Library Sumber Data Diagram. Jika Anda menggunakan library tersebut atau library helper lainnya, baca dokumentasi library Anda terlebih dahulu.

Halaman ini juga ditujukan bagi pembaca yang tertarik untuk memahami protokol berkabel 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 telah memahami cara kerja diagram dari perspektif pengguna.

Catatan: Google tidak secara resmi mendukung atau mendukung sumber Data non-Google apa pun yang mendukung protokol Sumber Data Chart Tools.

Ringkasan

Anda dapat menerapkan protokol Sumber Data Chart Tools untuk menjadi penyedia sumber data bagi diagram Anda sendiri, atau diagram lainnya. Sumber Data Alat Diagram mengekspos URL, yang disebut URL Sumber Data, yang dapat digunakan diagram untuk mengirim permintaan HTTP GET. Sebagai respons, sumber data menampilkan data dengan format yang benar yang dapat digunakan diagram untuk merender grafis di halaman. Protokol respons permintaan 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 diketik.

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

  • Gunakan salah satu library helper berikut untuk menangani permintaan dan respons, serta buat DataTable untuk ditampilkan. Jika menggunakan salah satu library ini, Anda hanya perlu menulis kode yang diperlukan agar data tersedia untuk library dalam bentuk tabel.
  • Tulis sumber data Anda sendiri dari awal dengan menangani permintaan, membuat DataTable, dan mengirim respons.

Cara kerjanya:

  1. Sumber data mengekspos URL yang disebut URL sumber data, yang diagramnya 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. Sumber data menerima dan mengurai permintaan, seperti yang dijelaskan dalam Format Permintaan.
  4. Sumber Data menyiapkan data dalam format yang diminta; biasanya, ini adalah tabel JSON. Format respons dibahas di bagian Format Respons. Sumber data dapat secara opsional mendukung bahasa kueri Visualization API yang menentukan pemfilteran, pengurutan, dan manipulasi data lainnya.
  5. Sumber Data membuat respons HTTP yang menyertakan 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") peka 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 agar tidak terjadi error pada klien yang mengupgrade ke versi terbaru dengan cepat.
  • Jangan gagal jika properti yang tidak dikenal dikirim sebagai bagian dari permintaan. Hal ini karena versi baru dapat memperkenalkan properti baru yang tidak Anda ketahui.
  • Hanya mengurai properti yang Anda harapkan. Meskipun versi baru dapat memperkenalkan properti baru, jangan terima dan gunakan seluruh string permintaan. Untuk melindungi diri Anda dari serangan berbahaya, uraikan dan gunakan properti yang Anda harapkan dengan hati-hati.
  • Dokumentasikan persyaratan sumber data Anda dengan cermat jika Anda tidak membuat kode diagram klien sendiri. Hal ini mencakup dokumentasi informasi berikut:
    • Setiap parameter kustom yang Anda terima,
    • Bisa atau tidaknya Anda mengurai bahasa kueri Google Visualization API, dan
    • Jenis data yang ditampilkan, dan struktur data tersebut (apa yang diwakili oleh baris dan kolom, dan pelabelan apa pun).
  • Lakukan semua tindakan pencegahan keamanan standar untuk situs yang menerima permintaan dari klien tidak dikenal. Anda dapat secara wajar mendukung MD5, hashing, dan mekanisme keamanan lainnya dalam parameter Anda untuk mengautentikasi permintaan atau membantu mengamankan serangan berbahaya, dan mengharapkan klien mengetahui persyaratan Anda serta meresponsnya. Namun, pastikan untuk mendokumentasikan semua persyaratan Anda dengan baik, jika Anda tidak membuat kode diagram sendiri. 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 lainnya setelahnya.
  • Anda tidak wajib mendukung bahasa kueri Visualization API, tetapi hal ini akan membuat sumber data Anda lebih bermanfaat bagi pelanggan.
  • Anda tidak wajib mendukung permintaan dari salah satu 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.

Pertimbangan Keamanan

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

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

Sebagai tingkat keamanan tambahan, Anda dapat mempertimbangkan untuk membatasi permintaan ke permintaan yang berasal dari domain yang sama dengan sumber data Anda. Hal ini akan sangat membatasi visibilitas sumber data, tetapi jika Anda memiliki data yang sangat sensitif dan tidak boleh diakses dari luar domain, Anda harus mempertimbangkannya. Sumber data yang hanya mengizinkan permintaan dari domain yang sama disebut sumber data yang dibatasi, bukan sumber data yang tidak dibatasi, yang akan menerima kueri dari domain apa pun. Berikut adalah beberapa detail tentang 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 dalam serangan XSRF):

  • Memverifikasi 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 menggunakan library Sumber Data Google Chart Tools, Anda dapat meminta library 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 mungkin dijalankan ketika disertakan dengan tag <script src>. Untuk melakukannya, awali respons JSON Anda dengan )]}' yang diikuti dengan baris baru. Dalam klien Anda, hapus awalan dari respons. Untuk XmlHttpRequest, ini hanya dapat dilakukan jika permintaan berasal dari domain yang sama.

Format Permintaan

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

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

Berikut adalah beberapa contoh permintaan (Anda dapat melihat contoh permintaan dan respons lainnya di akhir dokumen ini di Contoh):

Catatan: String permintaan berikut, dan string yang ditampilkan di bagian Contoh, 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. Perlu diperhatikan bahwa kedua nama parameter (seperti "version") dan nilai string konstan (seperti "ok", "warning", dan "not_Modified") peka terhadap huruf besar dan kecil. Tabel ini juga menjelaskan apakah parameter diperlukan untuk dikirim dan, jika dikirim, apakah Anda harus menanganinya.

Parameter
Diperlukan di Permintaan?
Sumber Data Harus Menangani?
 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 dikutip.

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

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

  • reqId - [Wajib dalam permintaan; Sumber data harus menangani] ID numerik untuk permintaan ini. Cara ini digunakan sehingga jika klien mengirim beberapa permintaan sebelum menerima respons, sumber data dapat mengidentifikasi respons dengan permintaan yang tepat. Kirimkan kembali nilai ini dalam respons.
  • version - [Opsional dalam permintaan; Sumber data harus menangani] Nomor versi protokol Visualisasi Google. Versi saat ini adalah 0.6. Jika tidak dikirim, anggaplah versi terbaru.
  • sig - [Opsional dalam permintaan; Opsional untuk sumber data yang ditangani] Hash DataTable yang dikirim ke klien ini dalam permintaan sebelumnya ke sumber data ini. Ini adalah pengoptimalan untuk menghindari pengiriman data identik ke klien dua kali. Lihat Mengoptimalkan Permintaan Anda di bawah ini untuk informasi cara menggunakannya.
  • out - [Opsional dalam permintaan; Sumber data harus menangani] String yang menjelaskan format untuk data yang ditampilkan. Koordinat ini bisa berupa salah satu nilai berikut:
    • json - [Nilai default] String respons JSON (dijelaskan di bawah).
    • html - Tabel HTML dasar dengan baris dan kolom. Jika digunakan, satu-satunya hal yang harus ditampilkan adalah tabel HTML dengan data; hal 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 dikembalikan adalah string data CSV. Anda dapat meminta nama kustom untuk file di header respons dengan menentukan parameter outFileName.
    • tsv-excel - Mirip dengan csv, tetapi menggunakan tab, bukan koma, dan semua data dienkode dengan utf-16.
    Perhatikan bahwa satu-satunya jenis data yang dibuat oleh diagram yang dibuat di Google Visualization API adalah json. Lihat Format Respons di bawah untuk mengetahui 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 sumber data yang akan ditangani] Jika Anda menentukan out:csv atau out:tsv-excel, Anda dapat secara opsional meminta nama file yang ditentukan di sini. 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. Ini adalah jenis permintaan yang paling umum, dan yang 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-nya 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, mereka akan memberikan kode yang tepat untuk Anda; jika Anda mengurai respons secara manual, lihat Modifikasi JSON di bawah.

Jika menerapkan permintaan domain yang sama, Anda harus memverifikasi keberadaan header "X-DataSource-Auth" dalam 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 akhir halaman ini dalam Contoh. Anda dapat menggunakan library helper Java atau Python untuk membuat string respons ini.

Format respons ini adalah objek JSON berenkode UTF-8 (objek yang digabungkan dengan tanda kurung kurawal { } dengan setiap properti dipisahkan dengan koma) yang mencakup properti dalam tabel di bawah (data ditetapkan ke properti table). Objek JSON ini harus digabungkan 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 Google Visualization. Jika tidak ditentukan, klien mengasumsikan versi terbaru.

Contoh: version=0.6
ID kebutuhan
Ya*
 Nomor string yang menunjukkan ID permintaan untuk klien ini. Jika ini ada dalam permintaan, tampilkan nilai yang sama. Lihat deskripsi reqId di bagian permintaan untuk mengetahui 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 salah satu dari nilai berikut:

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

Contoh: status:'warning'
peringatan
Hanya jika status=warning

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

  • reason - [Wajib] Deskripsi string satu kata dari peringatan. Protokol menentukan nilai berikut, tetapi Anda dapat menentukan nilai Anda sendiri, jika perlu (tetapi klien tidak akan memproses nilai khusus dengan cara khusus apa pun). Anda hanya dapat memiliki satu nilai reason:
    • data_truncated - DataTable yang ditampilkan memiliki beberapa baris yang dihapus, entah karena pengguna menyertakan string kueri yang memangkas daftar hasil, atau sumber data tidak ingin menampilkan hasil lengkap karena beberapa alasan.
    • other - Peringatan umum yang belum ditetapkan.
  • message - [Opsional] String dengan tanda kutip singkat yang menjelaskan masalah, mungkin digunakan sebagai judul untuk kotak peringatan. Nama ini mungkin ditampilkan kepada pengguna. HTML tidak didukung.
  • detailed_message - [Opsional] Pesan string dengan detail yang menjelaskan masalah, dan solusi yang memungkinkan. Satu-satunya HTML yang didukung adalah elemen <a> dengan satu atribut href. Encoding Unicode didukung. Nama ini mungkin ditampilkan kepada pengguna.

Contoh: warnings:[{reason:'data_truncated',message:'Retrieved data was truncated'}]
error
Wajib jika status=error

Array dari satu atau beberapa objek, masing-masing menjelaskan error. Wajib jika status=error, tidak diizinkan jika tidak. Hal ini serupa dengan nilai warnings. Ingat 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 belum berubah sejak permintaan terakhir. Jika ini adalah alasan error, Anda tidak boleh memiliki nilai untuk table.
    • user_not_authenticated - Jika sumber data memerlukan autentikasi dan belum dilakukan, tentukan nilai ini. Klien kemudian akan menampilkan peringatan 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 generik dan belum ditentukan.
  • message - [Opsional] Sama seperti warnings.message. Catatan: Ada kemungkinan pengguna berbahaya dapat menggunakan string data mendetail sebagai sarana untuk mengakses data yang tidak diizinkan, 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 algoritme hash yang diinginkan. 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'
tabel
Tidak

Objek DataTable dalam notasi literal JavaScript, dengan data Anda. Lihat bagian referensi yang 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.

 

JSON yang ketat diperlukan

Library helper Google dan semua kueri yang dikirim ke Google menampilkan JSON/JSONP yang ketat. Jika Anda tidak mengurai kode yang dikembalikan sendiri, hal ini seharusnya tidak menjadi masalah. Jika ya, Anda dapat menggunakan JSON.parse() untuk mengonversi string JSON menjadi objek JavaScript. Satu perbedaan dalam cara JSON diproses oleh API adalah bahwa, meskipun JSON tidak mendukung nilai Tanggal JavaScript (misalnya, "Tanggal baru(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]]) yang semuanya setelahnya bersifat opsional, dan bulan berbasis nol.

 

Mengoptimalkan Respons JSON

Jika klien membuat dua permintaan dan data tidak berubah di antara permintaan, wajar untuk tidak mengirim ulang data karena akan membuang bandwidth. Untuk membuat permintaan lebih efisien, protokol mendukung caching data pada klien, dan mengirimkan sinyal dalam respons jika data tidak berubah sejak permintaan terakhir. Berikut ini cara kerjanya:

  1. Klien mengirimkan permintaan ke sumber data.
  2. Sumber data menghasilkan DataTable serta hash objek DataTable, dan menampilkan keduanya dalam responsnya (hash tersebut ditampilkan dalam parameter tqx. sig). Klien Google Visualization API menyimpan nilai DataTable dan sig ke dalam cache.
  3. Klien mengirimkan permintaan data lain, 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 baru.
    • Jika data tidak berubah dari permintaan sebelumnya, sumber data akan mengirim ulang status=error, reason=not_modified, sig=old_sig_value.
  5. Dalam kedua kasus tersebut, halaman yang menghosting diagram mendapatkan respons yang berhasil, dan dapat mengambil DataTable dengan memanggil QueryResponse.getDataTable(). Jika data sama, itu hanya akan menjadi versi tabel yang di-cache.

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

Format Respons CSV

Jika permintaan tersebut menentukan out:csv, respons tidak akan menyertakan metadata, tetapi hanya representasi CSV dari data. Tabel CSV biasanya merupakan daftar yang dipisahkan koma, dengan setiap baris data adalah 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 yang memiliki tiga baris:

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 umum adalah kumpulan nilai yang dipisahkan oleh koma (tanpa spasi intervensi), dan baris baru (\n) di akhir setiap baris. Saat menerima balasan string CSV, browser mungkin menanyakan aplikasi apa yang digunakan untuk membuka string tersebut, atau mungkin merendernya di layar. Library open source Java dan Python menyediakan metode untuk mengonversi DataTable menjadi string CSV.

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

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

Kirim 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 tersebut menyertakan anggota outFileName dari parameter tqx , Anda harus mencoba menyertakan nama file yang ditentukan dalam header respons.

Format Respons HTML

Jika permintaan tersebut menentukan out:html, responsnya harus berupa halaman HTML yang menentukan tabel HTML dengan data. Hal ini berguna untuk men-debug kode Anda, karena browser dapat merender hasil 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 yang ini di browser:

Kirim 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 belum di-escape URL; yang biasanya dilakukan oleh browser, atau objek google.visualization.Query.

Permintaan sederhana: Menampilkan informasi dasar dengan tabel tiga kolom, 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 jenis data berbeda.

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, akan menampilkan kolom tunggal 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 terpotongnya data: Contoh peringatan data_truncated. Perhatikan bahwa permintaan masih mengembalikan 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 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.'}]});

Alat Pengembangan

  • Java Datasource Library (dari Google) - Menangani permintaan dan respons, membuat tabel respons dari data yang Anda berikan, dan menerapkan bahasa kueri SQL Google Chart Tools.
  • Python Library Sumber Data (dari Google) - Membuat tabel respons menghasilkan sintaksis respons. Tidak menangani penguraian permintaan atau menerapkan bahasa kueri SQL Google Chart Tools.
  • MC-Google_Visualization (Pihak ketiga) - Ini adalah library sisi server PHP yang dapat Anda gunakan untuk menerapkan sumber Data Chart Tools untuk mesin database MySQL, SQLite, dan PostgreSQL menggunakan PDO.
  • bortosky-google-visualization (Pihak ketiga) - Ini adalah library helper untuk membuat Tabel Data Google Visualization API 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 untuk diagram Google. GV Streamer mendukung beberapa bahasa (misalnya, PHP, Java, .NET) dan beberapa sumber data mentah (misalnya, MySql).
  • TracGViz (Pihak ketiga) - TracGViz adalah alat open source gratis yang menyediakan komponen sehingga Trac dapat menggunakan gadget diagram serta mengimplementasikan data yang dikelola oleh Trac sebagai sumber Sumber Data Google Chart Tools.
  • vis-table (Pihak ketiga) - Library yang mengimplementasikan Sumber Data Google Chart Tools di PHP. Kode ini memiliki tiga bagian utama. Implementasi tabel data itu sendiri, parser bahasa kueri, dan formatter.
  • Implementasi Sumber Data Google di Oracle PL/SQL (Pihak ketiga) - Paket PL/SQL Oracle yang memungkinkan Oracle mem-server Sumber Data secara langsung dari database. Jadi pada dasarnya Anda dapat menggunakan kueri Oracle sebagai Sumber Data Google Chart Tools (paket tersebut akan menampilkan file JSON beserta datanya). Ini memiliki dukungan hampir penuh untuk Bahasa Kueri Google.