Trang này được dịch bởi Cloud Translation API.

Triển khai Giao thức nguồn dữ liệu của công cụ biểu đồ (V0.6)

Trang này mô tả cách bạn có thể triển khai một dịch vụ hỗ trợ giao thức Nguồn dữ liệu của công cụ biểu đồ để hiển thị dữ liệu cho các biểu đồ bằng cách sử dụng lớp Truy vấn.

Nội dung

Đối tượng người xem
Tổng quan
Những điểm cần cân nhắc về bảo mật
Định dạng yêu cầu
Định dạng phản hồi
Ví dụ
Công cụ phát triển

Thẻ Đối tượng người xem

Trang này chủ yếu dành cho các nhà phát triển đang tạo nguồn dữ liệu của riêng họ mà không cần sự trợ giúp của Thư viện nguồn dữ liệu của công cụ biểu đồ. Nếu bạn đang dùng thư viện trợ giúp đó hoặc bất kỳ thư viện trợ giúp nào khác, trước tiên, hãy đọc tài liệu về thư viện đó.

Trang này cũng dành cho những độc giả muốn tìm hiểu giao thức dùng dây dùng để giao tiếp giữa hình ảnh ứng dụng và nguồn dữ liệu.

Nếu đang tạo hoặc sử dụng hình ảnh trực quan, bạn không cần phải đọc trang này.

Để đọc tài liệu này, bạn cần nắm được cú pháp cơ bản của yêu cầu JSON và HTTP. Bạn cũng nên nắm được cách hoạt động của biểu đồ từ góc độ của người dùng.

Lưu ý: Google không chính thức chứng thực hoặc hỗ trợ bất kỳ Nguồn dữ liệu nào không phải của Google có hỗ trợ giao thức Nguồn dữ liệu của công cụ biểu đồ.

Tổng quan

Bạn có thể triển khai giao thức Nguồn dữ liệu của công cụ biểu đồ để trở thành nhà cung cấp nguồn dữ liệu cho biểu đồ của riêng bạn hoặc các biểu đồ khác. Nguồn dữ liệu của công cụ biểu đồ hiển thị một URL, được gọi là URL nguồn dữ liệu, mà biểu đồ có thể gửi các yêu cầu HTTP GET đến đó. Để phản hồi, nguồn dữ liệu sẽ trả về dữ liệu được định dạng chính xác mà biểu đồ có thể sử dụng để kết xuất hình ảnh đồ hoạ trên trang. Giao thức phản hồi yêu cầu này được gọi là giao thức gửi tín dụng của Google Nghĩa của API Trực quan hoá.

Dữ liệu do nguồn dữ liệu phân phát có thể được trích xuất từ nhiều tài nguyên, chẳng hạn như một tệp hoặc cơ sở dữ liệu. Hạn chế duy nhất là bạn có thể định dạng dữ liệu dưới dạng bảng hai chiều với các cột đã nhập.

Là Nguồn dữ liệu của công cụ biểu đồ, bạn phải phân tích cú pháp một yêu cầu ở một định dạng cụ thể và trả về một phản hồi ở một định dạng cụ thể. Bạn có thể thực hiện điều này theo một trong hai cách chung:

Sử dụng một trong các thư viện trợ giúp sau để xử lý yêu cầu và phản hồi, đồng thời tạo DataTable để trả về. Nếu sử dụng một trong các thư viện này, bạn chỉ cần viết mã cần thiết để đưa dữ liệu của bạn vào thư viện dưới dạng bảng.
- Thư viện nguồn dữ liệu Java – Xử lý yêu cầu và phản hồi, tạo bảng phản hồi từ dữ liệu bạn cung cấp và triển khai ngôn ngữ truy vấn SQL của Công cụ biểu đồ của Google.
- Thư viện nguồn dữ liệu Python – Tạo bảng phản hồi sẽ tạo cú pháp phản hồi. Không xử lý phân tích cú pháp yêu cầu hoặc triển khai ngôn ngữ truy vấn SQL của Công cụ Google Biểu đồ.
  
  HOẶC
Viết nguồn dữ liệu của riêng bạn từ đầu bằng cách xử lý yêu cầu, tạo DataTable và gửi phản hồi.

Cách hoạt động:

Nguồn dữ liệu hiển thị một URL (được gọi là URL nguồn dữ liệu) mà các biểu đồ sẽ gửi yêu cầu HTTP GET đến đó.
Ứng dụng đưa ra yêu cầu HTTP GET với các tham số mô tả định dạng cần sử dụng cho dữ liệu được trả về, chuỗi truy vấn không bắt buộc và tham số tuỳ chỉnh không bắt buộc.
Nguồn dữ liệu nhận và phân tích cú pháp yêu cầu, như mô tả trong Định dạng yêu cầu.
Nguồn dữ liệu chuẩn bị dữ liệu theo định dạng được yêu cầu; thường là một bảng JSON. Các định dạng phản hồi được đề cập trong phần Định dạng phản hồi. Nguồn dữ liệu có thể tuỳ ý hỗ trợ ngôn ngữ truy vấn của API Hình ảnh hoá để chỉ định tính năng lọc, sắp xếp và các thao tác khác đối với dữ liệu.
Nguồn dữ liệu tạo phản hồi HTTP bao gồm dữ liệu được chuyển đổi tuần tự và các tham số phản hồi khác, rồi gửi lại ứng dụng khách theo mô tả trong phần Định dạng phản hồi

Lưu ý: Tất cả tham số và giá trị hằng số chuỗi được liệt kê trong tài liệu này cho các yêu cầu và phản hồi (chẳng hạn như responseHandler và "ok") đều là chữ thường và phân biệt chữ hoa chữ thường.

Yêu cầu tối thiểu

Đây là những yêu cầu tối thiểu để phân phát dưới dạng Nguồn dữ liệu của công cụ biểu đồ:

Nguồn dữ liệu này phải chấp nhận các yêu cầu HTTP GET và phải được cung cấp cho khách hàng của bạn.
Giao thức này có thể thay đổi và hỗ trợ lược đồ phiên bản (phiên bản hiện tại là 0.6), vì vậy, nguồn dữ liệu của bạn phải hỗ trợ các yêu cầu sử dụng phiên bản trước và phiên bản hiện tại. Bạn nên cố gắng hỗ trợ các phiên bản mới ngay khi phiên bản đó được phát hành để tránh làm hỏng bất kỳ ứng dụng nào nâng cấp lên phiên bản mới nhất một cách nhanh chóng.
Đừng thất bại nếu các thuộc tính không xác định được gửi trong yêu cầu. Lý do là các phiên bản mới có thể giới thiệu những thuộc tính mới mà bạn chưa biết.
Chỉ phân tích cú pháp các thuộc tính mà bạn dự kiến. Mặc dù các phiên bản mới có thể giới thiệu các thuộc tính mới, nhưng đừng chấp nhận và sử dụng toàn bộ chuỗi yêu cầu một cách mù quáng. Để tự bảo vệ mình khỏi các cuộc tấn công độc hại, hãy cẩn thận phân tích cú pháp và chỉ sử dụng các thuộc tính mà bạn muốn.
Ghi lại kỹ các yêu cầu về nguồn dữ liệu của bạn nếu bạn không tự lập trình biểu đồ khách hàng. Điều này bao gồm việc ghi nhận những thông tin sau:
- Bất kỳ thông số tùy chỉnh nào mà bạn chấp nhận,
- Bạn có thể phân tích cú pháp ngôn ngữ truy vấn của API Google Hình ảnh trực quan hay không, và
- Loại dữ liệu bạn trả về và cấu trúc của dữ liệu đó (nội dung mà hàng và cột biểu thị và mọi nhãn).
Thực hiện tất cả các biện pháp bảo mật tiêu chuẩn đối với một trang web chấp nhận yêu cầu của những ứng dụng không xác định. Bạn có thể hỗ trợ hợp lý cho MD5, hàm băm và các cơ chế bảo mật khác trong các tham số của mình để xác thực yêu cầu hoặc giúp bảo mật trước các cuộc tấn công độc hại, đồng thời mong muốn ứng dụng biết về các yêu cầu của bạn và phản hồi các yêu cầu đó. Tuy nhiên, hãy nhớ ghi lại tất cả các yêu cầu của bạn một cách chi tiết, nếu bạn không tự lập trình biểu đồ. Hãy xem Các cân nhắc về bảo mật bên dưới.
Tất cả chuỗi yêu cầu và phản hồi phải được mã hoá UTF-8.
Định dạng phản hồi quan trọng nhất là JSON. Trước tiên, hãy nhớ triển khai JSON vì đây là định dạng được hầu hết các biểu đồ sử dụng. Sau đó, hãy thêm các loại phản hồi khác.
Bạn không bắt buộc phải hỗ trợ ngôn ngữ truy vấn của API Hình ảnh hoá. Tuy nhiên, ngôn ngữ này sẽ giúp nguồn dữ liệu của bạn hữu ích hơn cho khách hàng.
Bạn không bắt buộc phải hỗ trợ các yêu cầu từ bất kỳ loại biểu đồ nào và có thể hỗ trợ các thông số tuỳ chỉnh cho biểu đồ tuỳ chỉnh. Tuy nhiên, bạn nên trả về câu trả lời ở định dạng chuẩn được mô tả bên dưới.

Những điều cần cân nhắc về bảo mật

Khi thiết kế nguồn dữ liệu, bạn cần cân nhắc mức độ bảo mật của dữ liệu. Bạn có thể sử dụng nhiều phương thức bảo mật cho trang web của mình, từ phương thức truy cập đơn giản bằng mật khẩu cho đến phương thức xác thực cookie an toàn.

Việc tấn công XSSI (đưa vào tập lệnh trên nhiều trang web) là một rủi ro kèm theo biểu đồ. Người dùng có thể chuyển đến một trang chứa tập lệnh độc hại. Sau đó, trang này sẽ bắt đầu tìm cách truy vấn các URL nguồn dữ liệu bằng thông tin đăng nhập của người dùng hiện tại. Nếu người dùng chưa đăng xuất khỏi một trang web, thì tập lệnh sẽ được xác thực là người dùng hiện tại và có các quyền trên trang web đó. Khi sử dụng thẻ <script src>, tập lệnh độc hại có thể bao gồm nguồn dữ liệu, tương tự như JSONP.

Để tăng cường bảo mật, bạn có thể cân nhắc việc hạn chế yêu cầu ở những người đến từ cùng miền với nguồn dữ liệu của bạn. Thao tác này sẽ hạn chế đáng kể khả năng hiển thị của nguồn dữ liệu, nhưng bạn nên cân nhắc việc này nếu có dữ liệu rất nhạy cảm không nên truy cập từ bên ngoài miền của bạn. Nguồn dữ liệu chỉ cho phép các yêu cầu từ cùng một miền được gọi là nguồn dữ liệu bị hạn chế, còn với nguồn dữ liệu không bị hạn chế chấp nhận truy vấn từ bất kỳ miền nào. Dưới đây là một số thông tin chi tiết về cách triển khai nguồn dữ liệu bị hạn chế:

Để đảm bảo rằng một yêu cầu thực sự đến từ bên trong miền của bạn chứ không phải từ một miền bên ngoài (hoặc một trình duyệt bên trong miền đang bị tấn công XSRF):

Xác minh sự hiện diện của tiêu đề "X-DataSource-Auth" trong yêu cầu. Tiêu đề này do GoogleVisual API xác định. Bạn không cần kiểm tra nội dung của tiêu đề này mà chỉ cần xác minh rằng tiêu đề đó có ở đó. Nếu đang dùng thư viện Nguồn dữ liệu của Công cụ biểu đồ của Google, bạn có thể yêu cầu thư viện này xử lý việc này cho bạn.
Sử dụng tính năng xác thực cookie để xác thực ứng dụng. Không có cách nào để chèn tiêu đề tuỳ chỉnh vào một yêu cầu trên nhiều miền trong khi vẫn giữ nguyên cookie xác thực.
Làm cho JavaScript không có khả năng thực thi khi được đi kèm với thẻ <script src>. Để thực hiện việc này, hãy thêm )]}' vào trước phản hồi JSON của bạn, theo sau là một dòng mới. Trong ứng dụng của bạn, hãy xoá tiền tố khỏi phản hồi. Đối với XmlHttpRequest, bạn chỉ có thể thực hiện việc này khi yêu cầu bắt nguồn từ cùng một miền.

Định dạng yêu cầu

Ứng dụng gửi yêu cầu HTTP GET kèm theo một số tham số, trong đó có phần tử tuỳ chỉnh, chuỗi truy vấn không bắt buộc, chữ ký và các phần tử khác. Bạn chỉ chịu trách nhiệm phân tích cú pháp các tham số được mô tả trong phần này và nên cẩn thận không xử lý các tham số khác để tránh các cuộc tấn công độc hại.

Hãy đảm bảo bạn cung cấp giá trị mặc định cho các thông số không bắt buộc (cả chuẩn và tuỳ chỉnh) và ghi lại tất cả các giá trị mặc định trong tài liệu về trang web của bạn.

Dưới đây là một số yêu cầu mẫu (bạn có thể xem thêm các mẫu yêu cầu và phản hồi ở cuối tài liệu này trong phần Ví dụ):

Lưu ý: Các chuỗi yêu cầu sau đây và những chuỗi xuất hiện trong phần Ví dụ phải dùng ký tự thoát URL trước khi gửi.

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

Dưới đây là danh sách tất cả các tham số chuẩn trong chuỗi yêu cầu. Xin lưu ý rằng cả tên thông số (chẳng hạn như "version") và giá trị chuỗi không đổi (chẳng hạn như "ok", "warning" và "not_modify") đều phân biệt chữ hoa chữ thường. Bảng này cũng cho biết liệu tham số có bắt buộc phải được gửi hay không và nếu được gửi thì bạn có phải xử lý tham số đó hay không.

Thông số

Thông số	Bắt buộc trong Yêu cầu?	Nguồn dữ liệu phải xử lý?	Nội dung mô tả
bàn thắng	Không	Không	Một truy vấn được viết bằng ngôn ngữ truy vấn của API Trực quan hoá của Google, chỉ định cách lọc, sắp xếp hoặc thao tác với dữ liệu được trả về. Chuỗi này không cần phải nằm trong cặp dấu ngoặc kép/dấu ngoặc đơn. Ví dụ: `http://www.example.com/mydatasource?tq=select Col1`
ghi điểm tqx	Không	Có	Một tập hợp các cặp khoá/giá trị được phân tách bằng dấu hai chấm cho thông số chuẩn hoặc thông số tuỳ chỉnh. Các cặp được phân tách bằng dấu chấm phẩy. Dưới đây là danh sách các thông số chuẩn do Giao thức trực quan hoá xác định: `reqId` – [Bắt buộc trong yêu cầu; Nguồn dữ liệu phải xử lý] Giá trị nhận dạng dạng số cho yêu cầu này. API này được dùng để nếu ứng dụng gửi nhiều yêu cầu trước khi nhận được phản hồi, thì nguồn dữ liệu có thể xác định phản hồi bằng yêu cầu phù hợp. Hãy gửi lại giá trị này trong câu trả lời. `version` - [Không bắt buộc trong yêu cầu; Nguồn dữ liệu phải xử lý] Số phiên bản của giao thức Google Hình ảnh hóa. Phiên bản hiện tại là 0.6. Nếu không được gửi, hãy giả định phiên bản mới nhất. `sig` – [Không bắt buộc trong yêu cầu; Không bắt buộc để xử lý nguồn dữ liệu] Hàm băm của `DataTable` được gửi tới ứng dụng này trong mọi yêu cầu trước đó đối với nguồn dữ liệu này. Đây là phương pháp tối ưu hoá để tránh gửi cùng một dữ liệu cho ứng dụng hai lần. Hãy xem phần Tối ưu hoá yêu cầu của bạn ở bên dưới để biết thông tin về cách sử dụng phương thức này. `out` – [Không bắt buộc trong yêu cầu; Nguồn dữ liệu phải xử lý] Một chuỗi mô tả định dạng cho dữ liệu được trả về. Giá trị này có thể là bất kỳ giá trị nào sau đây: json – [Giá trị mặc định] Chuỗi phản hồi JSON (mô tả bên dưới). html – Bảng HTML cơ bản có các hàng và cột. Nếu sử dụng thuộc tính này, thì duy nhất dữ liệu sẽ được trả về là bảng HTML có dữ liệu. Thao tác này rất hữu ích khi gỡ lỗi, như mô tả trong phần Định dạng phản hồi bên dưới. csv – Giá trị được phân tách bằng dấu phẩy. Nếu sử dụng thuộc tính này, duy nhất trả về sẽ là chuỗi dữ liệu CSV. Bạn có thể yêu cầu tên tuỳ chỉnh cho tệp trong các tiêu đề phản hồi bằng cách chỉ định tham số `outFileName`. tsv-excel – Tương tự như `csv`, nhưng sử dụng thẻ thay vì dấu phẩy và tất cả dữ liệu được mã hoá theo chuẩn utf-16. Xin lưu ý rằng loại dữ liệu duy nhất mà biểu đồ tạo trên API Hình ảnh của Google sẽ yêu cầu là json. Hãy xem phần Định dạng phản hồi bên dưới để biết thông tin chi tiết về từng loại. `responseHandler` – [Không bắt buộc trong yêu cầu; Nguồn dữ liệu phải xử lý] Tên chuỗi của hàm xử lý JavaScript trên trang ứng dụng sẽ được gọi cùng với phản hồi. Nếu không được đưa vào yêu cầu, thì giá trị sẽ là "google.Visualization.Query.setResponse". Nội dung này sẽ được gửi lại trong phản hồi. Hãy xem phần Định dạng phản hồi bên dưới để tìm hiểu cách thực hiện. `outFileName` – [Không bắt buộc trong yêu cầu; Không bắt buộc để xử lý nguồn dữ liệu] Nếu chỉ định `out:csv` hoặc `out:tsv-excel`, bạn có thể yêu cầu tên tệp được chỉ định tại đây. Ví dụ: `outFileName=results.csv`. Ví dụ: `tqx=version:0.6;reqId:1;sig:5277771;out:json`; `responseHandler:myQueryHandler`
tấn công mục tiêu	Không	Không	Đặt trước: bỏ qua thông số này. Phương thức dùng để gửi truy vấn.

Bắt buộc trong Yêu cầu?

Nguồn dữ liệu phải xử lý?

Nội dung mô tả

bàn thắng

Không

Một truy vấn được viết bằng ngôn ngữ truy vấn của API Trực quan hoá của Google, chỉ định cách lọc, sắp xếp hoặc thao tác với dữ liệu được trả về. Chuỗi này không cần phải nằm trong cặp dấu ngoặc kép/dấu ngoặc đơn.

Ví dụ: http://www.example.com/mydatasource?tq=select Col1

ghi điểm tqx

Không

Có

Một tập hợp các cặp khoá/giá trị được phân tách bằng dấu hai chấm cho thông số chuẩn hoặc thông số tuỳ chỉnh. Các cặp được phân tách bằng dấu chấm phẩy. Dưới đây là danh sách các thông số chuẩn do Giao thức trực quan hoá xác định:

reqId – [Bắt buộc trong yêu cầu; Nguồn dữ liệu phải xử lý] Giá trị nhận dạng dạng số cho yêu cầu này. API này được dùng để nếu ứng dụng gửi nhiều yêu cầu trước khi nhận được phản hồi, thì nguồn dữ liệu có thể xác định phản hồi bằng yêu cầu phù hợp. Hãy gửi lại giá trị này trong câu trả lời.
version - [Không bắt buộc trong yêu cầu; Nguồn dữ liệu phải xử lý] Số phiên bản của giao thức Google Hình ảnh hóa. Phiên bản hiện tại là 0.6. Nếu không được gửi, hãy giả định phiên bản mới nhất.
sig – [Không bắt buộc trong yêu cầu; Không bắt buộc để xử lý nguồn dữ liệu] Hàm băm của DataTable được gửi tới ứng dụng này trong mọi yêu cầu trước đó đối với nguồn dữ liệu này. Đây là phương pháp tối ưu hoá để tránh gửi cùng một dữ liệu cho ứng dụng hai lần. Hãy xem phần Tối ưu hoá yêu cầu của bạn ở bên dưới để biết thông tin về cách sử dụng phương thức này.
out – [Không bắt buộc trong yêu cầu; Nguồn dữ liệu phải xử lý] Một chuỗi mô tả định dạng cho dữ liệu được trả về. Giá trị này có thể là bất kỳ giá trị nào sau đây:
- json – [Giá trị mặc định] Chuỗi phản hồi JSON (mô tả bên dưới).
- html – Bảng HTML cơ bản có các hàng và cột. Nếu sử dụng thuộc tính này, thì duy nhất dữ liệu sẽ được trả về là bảng HTML có dữ liệu. Thao tác này rất hữu ích khi gỡ lỗi, như mô tả trong phần Định dạng phản hồi bên dưới.
- csv – Giá trị được phân tách bằng dấu phẩy. Nếu sử dụng thuộc tính này, duy nhất trả về sẽ là chuỗi dữ liệu CSV. Bạn có thể yêu cầu tên tuỳ chỉnh cho tệp trong các tiêu đề phản hồi bằng cách chỉ định tham số outFileName.
- tsv-excel – Tương tự như csv, nhưng sử dụng thẻ thay vì dấu phẩy và tất cả dữ liệu được mã hoá theo chuẩn utf-16.
Xin lưu ý rằng loại dữ liệu duy nhất mà biểu đồ tạo trên API Hình ảnh của Google sẽ yêu cầu là json. Hãy xem phần Định dạng phản hồi bên dưới để biết thông tin chi tiết về từng loại.
responseHandler – [Không bắt buộc trong yêu cầu; Nguồn dữ liệu phải xử lý] Tên chuỗi của hàm xử lý JavaScript trên trang ứng dụng sẽ được gọi cùng với phản hồi. Nếu không được đưa vào yêu cầu, thì giá trị sẽ là "google.Visualization.Query.setResponse". Nội dung này sẽ được gửi lại trong phản hồi. Hãy xem phần Định dạng phản hồi bên dưới để tìm hiểu cách thực hiện.
outFileName – [Không bắt buộc trong yêu cầu; Không bắt buộc để xử lý nguồn dữ liệu] Nếu chỉ định out:csv hoặc out:tsv-excel, bạn có thể yêu cầu tên tệp được chỉ định tại đây. Ví dụ: outFileName=results.csv.

Ví dụ: tqx=version:0.6;reqId:1;sig:5277771;out:json; responseHandler:myQueryHandler

tấn công mục tiêu

Không

Đặt trước: bỏ qua thông số này. Phương thức dùng để gửi truy vấn.

Định dạng câu trả lời

Định dạng của phản hồi phụ thuộc vào tham số out của yêu cầu. Tham số này chỉ định loại phản hồi dự kiến. Hãy xem các phần sau để tìm hiểu cách phản hồi từng loại yêu cầu:

JSON – Trả về phản hồi JSON bao gồm dữ liệu trong một đối tượng JavaScript có thể được truyền trực tiếp vào hàm khởi tạo DataTable để điền dữ liệu đó. Cho đến nay, đây là loại yêu cầu phổ biến nhất và là loại yêu cầu quan trọng nhất để triển khai đúng cách.
CSV – Trả về danh sách giá trị phẳng được phân tách bằng dấu phẩy do trình duyệt xử lý.
TSV – Trả về danh sách giá trị được phân tách bằng ký tự tab, do trình duyệt xử lý.
HTML – Trả về một bảng HTML do trình duyệt kết xuất.

Bạn có thể sử dụng Thư viện nguồn dữ liệu trực quan hoá của Google (java) hoặc thư viện Python trực quan hoá để tạo các định dạng đầu ra này cho mình.

Định dạng phản hồi JSON

Định dạng phản hồi mặc định là JSON nếu yêu cầu bao gồm tiêu đề "X-DataSource-Auth" và JSONP nếu không yêu cầu. Hãy lưu ý rằng ứng dụng biểu đồ của Google thực sự hỗ trợ phiên bản JSON và JSONP đã sửa đổi. Nếu bạn đang dùng thư viện trình trợ giúp Java hoặc Python, họ sẽ đưa ra mã phù hợp cho bạn. Nếu bạn đang phân tích cú pháp các phản hồi theo cách thủ công, hãy xem phần Sửa đổi JSON dưới đây.

Nếu đang thực thi các yêu cầu cùng miền, bạn nên xác minh sự hiện diện của tiêu đề "X-DataSource-Auth" trong yêu cầu và sử dụng cookie uỷ quyền.

Đây là định dạng phản hồi duy nhất được chỉ định theo phương thức API Google Hình ảnh hoá google.visualization.Query.send() . Bạn có thể xem một số ví dụ về yêu cầu và phản hồi JSON ở cuối trang này trong phần Ví dụ. Bạn có thể sử dụng thư viện trình trợ giúp Java hoặc Python để tạo chuỗi phản hồi này cho bạn.

Định dạng phản hồi này là một đối tượng JSON được mã hoá UTF-8 (đối tượng được gói bằng dấu ngoặc nhọn { }, trong đó mỗi thuộc tính được phân tách bằng dấu phẩy) bao gồm các thuộc tính trong bảng bên dưới (dữ liệu được gán cho thuộc tính table). Đối tượng JSON này phải được gói bên trong giá trị tham số responseHandler của yêu cầu. Vì vậy, nếu giá trị responseHandler của yêu cầu là "myHandler", thì bạn nên trả về một chuỗi như thế này (chỉ một thuộc tính được hiển thị cho ngắn gọn):

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

Nếu yêu cầu không chứa giá trị responseHandler, thì giá trị mặc định sẽ là "google.Visualization.Query.setResponse", vì vậy, bạn nên trả về một chuỗi như thế này (chỉ một thuộc tính được hiển thị ngắn gọn):

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

Dưới đây là các thành phần hiện có của đối tượng phản hồi:

Tài sản	Bắt buộc?	Nội dung mô tả
version	Không	Số chuỗi cho biết số phiên bản của giao thức truyền tin của Google Hình ảnh trực quan. Nếu không được chỉ định, ứng dụng sẽ dùng phiên bản mới nhất. Ví dụ: `version=0.6`
reqId	Có*	Số chuỗi cho biết mã của yêu cầu này đối với ứng dụng này. Nếu giá trị này nằm trong yêu cầu, hãy trả về cùng một giá trị. Hãy xem nội dung mô tả về `reqId` trong phần yêu cầu để biết thêm thông tin. * Nếu tham số này không được chỉ định trong yêu cầu, thì bạn không cần phải đặt tham số này trong phản hồi.
status	Có	Một chuỗi mô tả sự thành công hay thất bại của thao tác này. Phải là một và chỉ một trong các giá trị sau: `ok` – Yêu cầu thành công. Thuộc tính `table` phải có một bảng. `warning` - Thành công nhưng có một số vấn đề. Thuộc tính `table` phải có một bảng. `error` – Đã xảy ra sự cố. Nếu trả về giá trị này, bạn không nên trả về `table` và phải trả về `errors`. Ví dụ: `status:'warning'`
các cảnh báo	Chỉ khi `status=warning`	Một mảng gồm một hoặc nhiều đối tượng, mỗi đối tượng mô tả một vấn đề không nghiêm trọng. Bắt buộc nếu là `status=warning`, không được phép nếu không có giá trị này. Mỗi đối tượng có các thuộc tính chuỗi sau (chỉ trả về một giá trị cho mỗi thuộc tính): `reason` – [Bắt buộc] Nội dung mô tả về cảnh báo bằng một chuỗi gồm một từ. Giao thức xác định các giá trị sau, nhưng bạn có thể xác định các giá trị của riêng mình nếu cần (tuy nhiên, ứng dụng sẽ không xử lý các giá trị tuỳ chỉnh theo bất kỳ cách đặc biệt nào). Bạn chỉ có thể có một giá trị `reason`: `data_truncated` – Một số hàng trong `DataTable` được trả về đã bị xoá vì người dùng chứa một chuỗi truy vấn cắt bớt danh sách kết quả, hoặc nguồn dữ liệu không muốn trả về kết quả đầy đủ vì lý do nào đó. `other` – Cảnh báo chung không xác định. `message` - [Không bắt buộc] Một chuỗi ngắn được trích dẫn giải thích sự cố, có thể dùng làm tiêu đề cho hộp cảnh báo. Người dùng có thể thấy thông tin này. Không hỗ trợ HTML. `detailed_message` - [Không bắt buộc] Một thông báo dạng chuỗi được trích dẫn chi tiết giải thích vấn đề và mọi giải pháp khả thi. HTML duy nhất được hỗ trợ là phần tử `<a>` có một thuộc tính `href`. Hỗ trợ mã hoá Unicode. Người dùng có thể thấy thông tin này. Ví dụ: `warnings:[{reason:'data_truncated',message:'Retrieved data was truncated'}]`
các lỗi	Bắt buộc nếu `status=error`	Một mảng gồm một hoặc nhiều đối tượng, mỗi đối tượng mô tả một lỗi. Bắt buộc nếu là `status=error`, nếu không thì không được phép. Giá trị này tương tự như giá trị `warnings`. Xin lưu ý rằng lỗi `not_modified`, mặc dù là lỗi nhưng thực sự không phải là lỗi đối với ứng dụng. Mảng này có các thành phần chuỗi sau (chỉ trả về một giá trị cho mỗi thành phần): `reason` - [Bắt buộc] Giống như `warnings.reason`, nhưng các giá trị sau được xác định: `not_modified` – Dữ liệu không thay đổi kể từ yêu cầu gần đây nhất. Nếu đây là nguyên nhân gây ra lỗi, bạn không nên đặt giá trị cho `table`. `user_not_authenticated` – Nếu nguồn dữ liệu yêu cầu xác thực và việc đó chưa được thực hiện, hãy chỉ định giá trị này. Sau đó, ứng dụng sẽ cho thấy một cảnh báo có giá trị là `message`. `unknown_data_source_id` `access_denied` `unsupported_query_operation` `invalid_query` `invalid_request` `internal_error` `not_supported` `illegal_formatting_patterns` `other` – Lỗi chung chung, không xác định. `message` - [Không bắt buộc] Tương tự như `warnings.message`. Lưu ý: Người dùng độc hại vẫn có thể sử dụng một chuỗi dữ liệu chi tiết làm phương tiện để truy cập vào dữ liệu trái phép hoặc thậm chí sử dụng chuỗi đó để tấn công dữ liệu hoặc trang web của bạn. Nếu bạn lưu trữ dữ liệu cần được bảo mật hoặc xử lý trực tiếp các truy vấn của người dùng, hãy cân nhắc không trả về thông báo lỗi chi tiết có thể cung cấp thông tin cho kẻ tấn công. Thay vào đó, hãy đưa ra một thông báo chung chung, chẳng hạn như "Chuỗi truy vấn không hợp lệ". `detailed_message` - [Không bắt buộc] Tương tự như `warnings.detailed_message`. Hãy xem phần cảnh báo để biết thông tin `message` quá chi tiết. Ví dụ: `status:'error',errors:[{reason:'not_modified',message:'Data not modified'}]`
sig	Không	Một giá trị đã băm của đối tượng bảng. Được dùng để tối ưu hoá quá trình chuyển dữ liệu giữa ứng dụng và nguồn dữ liệu. Bạn có thể chọn bất kỳ thuật toán băm nào mà mình muốn. Nếu hỗ trợ thuộc tính này, bạn nên trả về giá trị được ứng dụng chuyển vào nếu không có dữ liệu nào được trả về hoặc trả về một hàm băm mới nếu dữ liệu mới được trả về. Ví dụ: `sig:'5982206968295329967'`
bàn	Không	Đối tượng `DataTable` trong ký hiệu cố định JavaScript, cùng với dữ liệu của bạn. Hãy xem phần tài liệu tham khảo được liên kết để biết thông tin chi tiết về định dạng của đối tượng này. Dưới đây là ví dụ về một bảng dữ liệu đơn giản: {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'}]} ] } Thuộc tính `table` chỉ nên xuất hiện nếu `status=ok` hoặc `status=warning`. Nếu bạn không trả về dữ liệu, đừng đưa thuộc tính này vào (tức là đừng trả về thuộc tính bằng một giá trị chuỗi trống). Ví dụ: Hãy xem phần Ví dụ bên dưới.

Yêu cầu JSON nghiêm ngặt

Các thư viện trợ giúp của Google và tất cả truy vấn gửi đến Google đều trả về JSON/JSONP nghiêm ngặt. Nếu bạn không tự phân tích cú pháp mã được trả về, thì điều này không quan trọng với bạn. Nếu đúng như vậy, bạn có thể sử dụng JSON.parse() để chuyển đổi chuỗi JSON thành đối tượng JavaScript. Một điểm khác biệt về cách API xử lý JSON là mặc dù JSON không hỗ trợ các giá trị Ngày của JavaScript (ví dụ: "Ngày mới(2008,1,28,0,31,26)"; nhưng API này hỗ trợ biểu diễn JSON hợp lệ dưới dạng chuỗi theo định dạng sau: Date(year, month, day[,hour, minute, second[, millisecond]]), trong đó mọi thứ sau ngày là không bắt buộc và tháng được tạo dựa trên số 0.

Tối ưu hoá phản hồi JSON

Nếu máy khách đưa ra 2 yêu cầu và dữ liệu không thay đổi giữa các yêu cầu, thì bạn không nên gửi lại dữ liệu. Việc này sẽ lãng phí băng thông. Để giúp các yêu cầu hiệu quả hơn, giao thức hỗ trợ việc lưu dữ liệu vào bộ nhớ đệm trên máy khách và gửi tín hiệu trong phản hồi nếu dữ liệu không thay đổi kể từ yêu cầu gần nhất. Dưới đây là cách hoạt động:

Ứng dụng gửi yêu cầu đến nguồn dữ liệu.
Nguồn dữ liệu tạo ra một DataTable cũng như một hàm băm của đối tượng DataTable, đồng thời trả về cả hai trong phản hồi của nó (hàm băm được trả về trong tham số tqx.sig). Ứng dụng GoogleVisual API sẽ lưu giá trị DataTable và sig vào bộ nhớ đệm.
Ứng dụng gửi một yêu cầu khác về dữ liệu, bao gồm cả giá trị tqx.sig đã lưu vào bộ nhớ đệm.
Nguồn dữ liệu có thể phản hồi theo một trong 2 cách:
- Nếu dữ liệu đã thay đổi so với yêu cầu trước đó, thì nguồn dữ liệu sẽ gửi lại hàm băm DataTable và hàm băm giá trị sig mới.
- Nếu dữ liệu chưa thay đổi so với yêu cầu trước đó, thì nguồn dữ liệu sẽ gửi lại status=error, reason=not_modified, sig=old_sig_value.
Trong cả hai trường hợp, trang lưu trữ biểu đồ sẽ nhận được phản hồi thành công và có thể truy xuất DataTable bằng cách gọi QueryResponse.getDataTable(). Nếu dữ liệu giống nhau, đó chỉ đơn giản là phiên bản được lưu trong bộ nhớ đệm của bảng.

Xin lưu ý rằng cách này chỉ áp dụng cho các yêu cầu JSON của những biểu đồ được tạo trên API Google Hình ảnh hoá.

Định dạng phản hồi CSV

Nếu yêu cầu chỉ định out:csv, thì phản hồi sẽ không bao gồm siêu dữ liệu mà chỉ chứa bản trình bày dữ liệu ở định dạng CSV. Bảng CSV thường là một danh sách được phân tách bằng dấu phẩy, trong đó mỗi hàng dữ liệu là một danh sách giá trị được phân tách bằng dấu phẩy, kết thúc bằng một ký tự dòng mới UNIX (\n). Các giá trị ô phải có cùng loại cho mỗi cột. Hàng đầu tiên là các nhãn cột. Dưới đây là ví dụ về bảng gồm 3 hàng, 3 cột:

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

Định dạng CSV không được giao thức này chỉ định; nguồn dữ liệu chịu trách nhiệm xác định định dạng CSV. Tuy nhiên, một định dạng phổ biến là một tập hợp các giá trị được phân tách bằng dấu phẩy (không có dấu cách xen kẽ) và một dòng mới (\n) ở cuối mỗi hàng. Khi nhận được một chuỗi phản hồi CSV, trình duyệt có thể hỏi người dùng xem nên dùng ứng dụng nào để mở chuỗi đó hoặc có thể chỉ hiển thị chuỗi đó trên màn hình. Thư viện nguồn mở Java và Python cung cấp một phương thức để chuyển đổi DataTable thành chuỗi CSV.

Nếu yêu cầu bao gồm một thành phần outFileName của tham số tqx , bạn nên cố gắng đưa tên tệp đã chỉ định vào tiêu đề phản hồi.

Đối tượng google.visualization.Query không hỗ trợ yêu cầu phản hồi CSV. Nếu khách hàng muốn yêu cầu CSV, bạn có thể nhúng tiện ích Thanh công cụ trực quan hoá vào trang của mình, hoặc họ có thể sử dụng mã tuỳ chỉnh để tạo yêu cầu, hoặc bạn có thể cung cấp một đường liên kết để đặt thuộc tính out:csv của tqx một cách rõ ràng, như được hiển thị trong URL yêu cầu sau:

Yêu cầu

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

Đáp

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

Định dạng phản hồi của TSV

Nếu yêu cầu chỉ định out:tsv-excel, thì phản hồi sẽ không bao gồm siêu dữ liệu mà chỉ chứa bản trình bày dữ liệu được phân tách bằng ký tự tab, utf-16 được mã hoá. Nếu yêu cầu bao gồm một thành phần outFileName của tham số tqx , bạn nên cố gắng đưa tên tệp đã chỉ định vào tiêu đề phản hồi.

Định dạng phản hồi HTML

Nếu yêu cầu chỉ định out:html, thì phản hồi phải là một trang HTML xác định bảng HTML có dữ liệu. Việc này rất hữu ích khi bạn gỡ lỗi mã vì trình duyệt có thể trực tiếp hiển thị kết quả ở định dạng dễ đọc. Bạn không thể gửi truy vấn về phản hồi HTML bằng đối tượng google.visualization.Query. Bạn phải tạo truy vấn cho phản hồi HTML bằng mã tuỳ chỉnh hoặc bằng cách nhập một URL tương tự như URL này vào trình duyệt:

Yêu cầu

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

Đáp

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

Ví dụ

Dưới đây là một số ví dụ về yêu cầu và phản hồi. Hãy lưu ý rằng các yêu cầu không có ký tự thoát URL mà thường do trình duyệt hoặc đối tượng google.visualization.Query thực hiện.

Yêu cầu đơn giản: Trả về thông tin cơ bản bằng một bảng gồm 3 cột, 4 hàng.

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

Yêu cầu đơn giản bằng trình xử lý phản hồi: Trả về một bảng gồm 3 cột gồm 3 hàng với nhiều loại dữ liệu.

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

Truy vấn có chuỗi truy vấn đơn giản: Yêu cầu về một cột duy nhất, trả về một cột duy nhất có 4 hàng.

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

Lỗi dữ liệu không được sửa đổi: Ví dụ về lỗi 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'}]});

Cảnh báo bị cắt bớt dữ liệu: Ví dụ về cảnh báo data_truncated. Xin lưu ý rằng yêu cầu này vẫn trả về dữ liệu.

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

Lỗi quyền truy cập bị từ chối: Ví dụ về lỗi 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'}]});

Chuỗi truy vấn không hợp lệ: Ví dụ về yêu cầu có chuỗi truy vấn không hợp lệ. Xin lưu ý rằng thông báo chi tiết là một thông báo chung chung chứ không phải là thông báo lỗi thực tế.

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

Công cụ Phát triển

Thư viện nguồn dữ liệu Java (của Google) – Xử lý yêu cầu và phản hồi, tạo bảng phản hồi từ dữ liệu mà bạn cung cấp và triển khai ngôn ngữ truy vấn SQL của Công cụ biểu đồ của Google.
Thư viện nguồn dữ liệu Python (từ Google) – Tạo bảng phản hồi sẽ tạo cú pháp phản hồi. Không xử lý việc phân tích cú pháp yêu cầu hoặc triển khai ngôn ngữ truy vấn SQL của Công cụ Google Biểu đồ.
MC-Google_Visualization (Bên thứ ba) – Đây là một thư viện phía máy chủ PHP mà bạn có thể dùng để triển khai Nguồn dữ liệu của Công cụ biểu đồ cho các công cụ cơ sở dữ liệu MySQL, SQLite và PostgreSQL bằng PDO.
bortosky-google-Visualization (Bên thứ ba) – Đây là một thư viện trợ giúp để tạo Bảng dữ liệu API Google trực quan hoá cho người dùng .NET.
GV Streamer (Bên thứ ba) – GV Streamer là một công cụ phía máy chủ có thể chuyển đổi dữ liệu từ nhiều nguồn thành phản hồi truy vấn hợp lệ cho các biểu đồ của Google. GV Streamer hỗ trợ một số ngôn ngữ (ví dụ: PHP, Java, .NET) và một số nguồn dữ liệu thô (ví dụ: MySql).
TracGViz (Bên thứ ba) – TracGViz là một công cụ nguồn mở và miễn phí cung cấp các thành phần để Trac có thể sử dụng các tiện ích biểu đồ cũng như triển khai dữ liệu do Trac quản lý dưới dạng Nguồn dữ liệu của công cụ biểu đồ của Google.
bảng hiển thị (Bên thứ ba) - Thư viện triển khai Nguồn dữ liệu của công cụ biểu đồ của Google bằng PHP. Ứng dụng này có 3 phần chính. Chính việc triển khai bảng dữ liệu, trình phân tích cú pháp ngôn ngữ truy vấn và trình định dạng.
Quy trình triển khai nguồn dữ liệu của Google trong Oracle PL/SQL (Bên thứ ba) – Gói PL/SQL giúp Oracle trực tiếp lưu trữ Nguồn dữ liệu từ cơ sở dữ liệu. Về cơ bản, bạn có thể sử dụng bất kỳ truy vấn Oracle nào dưới dạng Nguồn dữ liệu của Công cụ biểu đồ của Google (gói này sẽ trả về một tệp JSON chứa dữ liệu). Công cụ này hỗ trợ gần như đầy đủ cho Ngôn ngữ truy vấn của Google.