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 cho 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
Thẻ Đối tượng người xem
Trang này chủ yếu dành cho những nhà phát triển sẽ tạo nguồn dữ liệu của riêng mình mà không có sự hỗ trợ của Thư viện nguồn dữ liệu cho 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, thì trước tiên, hãy đọc tài liệu về thư viện của bạn.
Trang này cũng dành cho những độc giả muốn biết giao thức lưới dùng để giao tiếp giữa hình ảnh máy khách và nguồn dữ liệu.
Nếu đang tạo hoặc sử dụng một hình ảnh trực quan, bạn không cần đọc trang này.
Để đọc đượ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 thức hoạt động của biểu đồ từ góc nhìn của người dùng.
Tổng quan
Bạn có thể triển khai giao thức Nguồn dữ liệu cho 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. Một Nguồn dữ liệu cho công cụ biểu đồ sẽ hiển thị một URL, được gọi là URL nguồn dữ liệu, theo đó biểu đồ có thể gửi yêu cầu HTTP GET. Để phản hồi, nguồn dữ liệu sẽ trả về dữ liệu được định dạng đúng cách mà biểu đồ có thể sử dụng để hiển thị nội dung đồ hoạ trên trang. Giao thức phản hồi yêu cầu này được gọi là giao thức dây API của Google Visual API.
Dữ liệu do một 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à một Nguồn dữ liệu cho 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 ở định dạng cụ thể. Bạn có thể thực hiện việc này bằng một trong hai cách chung:
-
Sử dụng một trong những thư viện trợ giúp sau để xử lý yêu cầu và phản hồi, đồng thời tạo Bảng dữ liệu để trả về. Nếu sử dụng một trong những thư viện này, bạn chỉ cần viết mã cần thiết để cung cấp dữ liệu cho 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 mà bạn cung cấp và triển khai ngôn ngữ truy vấn SQL trong 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 để tạo cú pháp phản hồi. Không xử lý phân tích cú pháp của yêu cầu hoặc triển khai ngôn ngữ truy vấn SQL của Công cụ biểu đồ Google.
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 một Bảng dữ liệu và gửi phản hồi.
Cách hoạt động:
- Nguồn dữ liệu sẽ hiển thị một URL, được gọi là URL nguồn dữ liệu, trong đó các biểu đồ sẽ gửi yêu cầu HTTP GET.
- Ứng dụng thực hiện một yêu cầu HTTP GET với các thông số mô tả định dạng cần sử dụng cho dữ liệu được trả về, một chuỗi truy vấn không bắt buộc và các thông số tuỳ chỉnh không bắt buộc.
- Nguồn dữ liệu sẽ nhận và phân tích cú pháp yêu cầu, như được mô tả trong phần Định dạng yêu cầu.
- Nguồn dữ liệu chuẩn bị dữ liệu ở định dạng được yêu cầu; thông thường, đây là một bảng JSON. Đị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 API Hình ảnh chỉ định việc 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 một phản hồi HTTP chứa dữ liệu được chuyển đổi tuần tự và các thông số phản hồi khác, sau đó gửi lại cho ứng dụng khách như mô tả trong phần Định dạng phản hồi
Lưu ý: Tất cả cá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
Sau đây là những yêu cầu tối thiểu để làm Nguồn dữ liệu cho công cụ biểu đồ:
- Nguồn dữ liệu của anh ấy nên 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 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 cũng như 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 chúng phát hành để tránh làm hỏng bất kỳ ứng dụng nào nâng cấp nhanh lên phiên bản mới nhất.
- Không gửi được nếu các thuộc tính không xác định được gửi trong yêu cầu. Điều này là do các phiên bản mới có thể đưa ra các thuộc tính mới mà bạn không biết.
- Chỉ phân tích cú pháp những cơ sở lưu trú mà bạn mong đợi. Mặc dù các phiên bản mới có thể đưa ra các thuộc tính mới, nhưng bạn không nên chấp nhận và sử dụng toàn bộ chuỗi yêu cầu. Để tự bảo vệ mình khỏi các cuộc tấn công độc hại, hãy phân tích cú pháp cẩn thận và chỉ sử dụng các thuộc tính mà bạn mong đợi.
- Hãy ghi lại cẩn thận các yêu cầu về nguồn dữ liệu nếu bạn không tự mã hóa biểu đồ khách hàng. bao gồm việc ghi lại
các thông tin sau:
- Mọi thông số tùy chỉnh mà bạn chấp nhận,
- Liệu bạn có thể phân tích cú pháp ngôn ngữ truy vấn của API Google Visual, và
- Loại dữ liệu bạn trả về và cấu trúc của dữ liệu đó (nội dung trong hàng và cột, cũng như mọi nhãn).
- Thực hiện tất cả các biện pháp phòng ngừa bảo mật tiêu chuẩn cho trang web chấp nhận các yêu cầu từ máy khách không xác định. Bạn có thể hỗ trợ một cách hợp lý MD5, băm và các cơ chế bảo mật khác trong tham số để xác thực các yêu cầu hoặc bảo vệ chống lại các cuộc tấn công độc hại. Đồng thời, bạn mong muốn khách hàng biết về các yêu cầu của bạn và phản hồi các cơ chế đó. 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 hiệu quả nếu bạn không tự lập trình biểu đồ. Hãy xem mục Cân nhắc 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á bằng phương thức 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 mà hầu hết các biểu đồ đề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 API Hình ảnh trực quan, nhưng điều này 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ỳ và tất cả các loại biểu đồ; và bạn có thể hỗ trợ các thông số tùy chỉnh cho biểu đồ tùy chỉnh. Tuy nhiên, bạn nên trả về các phản hồi ở định dạng chuẩn được mô tả dưới đây.
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 phải cân nhắc mức độ bảo mật của dữ liệu. Bạn có thể sử dụng nhiều lược đồ bảo mật cho trang web của mình, từ cách truy cập đơn giản bằng mật khẩu cho đến quy trình xác thực cookie bảo mật.
Các cuộc tấn công XSSI (bao gồm cả tập lệnh trên nhiều trang web) có nguy cơ xuất hiện trên các biểu đồ. Người dùng có thể chuyển đến một trang chứa tập lệnh độc hại mà sau đó bắt đầu cố gắng truy vấn các URL nguồn dữ liệu bằng thông tin xác thực 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ó quyền trên trang web đó. Việc 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.
Vì lý do bảo mật bổ sung, bạn có thể cân nhắc việc hạn chế các yêu cầu đến từ những người dùng có cùng miền với nguồn dữ liệu của bạn. Điều này sẽ hạn chế đáng kể khả năng hiển thị của nguồn dữ liệu, nhưng 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, bạn nên xem xét việc đó. Một 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ế, chứ không phải nguồn dữ liệu không bị hạn chế. Nguồn này sẽ chấp nhận các truy vấn từ mọi miền. Dưới đây là một số thông tin chi tiết về cách triển khai một 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ừ 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 có 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 API Hình ảnh của Google 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 sử 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 xử lý vấn đề này cho bạn.
- Hãy 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 yêu cầu trên nhiều miền mà vẫn giữ cookie xác thực.
- Làm cho JavaScript không thể thực thi khi được bao gồm với thẻ <script src>. Để thực hiện việc này, hãy thêm tiền tố phản hồi JSON bằng )]} vào trước một dòng mới. Trong máy khách, hãy bỏ tiền tố đó khỏi phản hồi. Đối với XmlHttpRequest, điều này chỉ có thể xảy ra 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 với một vài thông số, bao gồm cá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ỉ có trách nhiệm phân tích cú pháp những thông số được mô tả trong phần này và cần cẩn thận để không xử lý những người khác để tránh các cuộc tấn công ác ý.
Hãy nhớ có giá trị mặc định cho các thông số không bắt buộc (cả tiêu chuẩn và tuỳ chỉnh) cũng như ghi lại tất cả các giá trị mặc định trong tài liệu của trang web.
Sau đây là một số yêu cầu mẫu (bạn có thể xem thêm các yêu cầu và mẫu 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à các chuỗi hiển thị trong phần Ví dụ phải được thoát bằng 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ư "phiên bản") và giá trị chuỗi không đổi (chẳng hạn như "ok", "cảnh báo" và "not_Sửa đổi") đều phân biệt chữ hoa chữ thường. Bảng này cũng mô tả liệu bạn có cần gửi tham số 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ố | Bắt buộc trong Yêu cầu? |
Nguồn dữ liệu có thể xử lý? |
Mô tả |
|---|---|---|---|
| tq | Không |
Không |
Truy vấn được viết bằng ngôn ngữ truy vấn API Hình ảnh trực quan của Google, chỉ định cách lọc, sắp xếp hoặc thao tác dữ liệu được trả về. Chuỗi này không cần trích dẫn. Ví dụ: |
| 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 các tham số chuẩn hoặc 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ố tiêu chuẩn mà giao thức Hình ảnh xác định:
Ví dụ: |
| tqrt | Không |
Không |
Dành riêng: bỏ qua thông số này. Phương thức dùng để gửi truy vấn. |
Định dạng phản hồ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 sẽ chỉ định loại phản hồi dự kiến. Hãy xem các phần sau đây để 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 chứa dữ liệu trong đối tượng JavaScript, có thể truyền trực tiếp vào hàm khởi tạo
DataTableđể điền giá trị đó. Cho đến nay, đây là loại yêu cầu phổ biến nhất và là yếu tố quan trọng nhất để triển khai đúng cách. - CSV – Trả về danh sách giá trị được phân tách bằng dấu phẩy và sẽ do trình duyệt xử lý.
- TSV – Trả về danh sách giá trị được phân cách bằng ký tự tab để trình duyệt xử lý.
- HTML – Trả về một bảng HTML để trình duyệt hiển thị.
Bạn có thể dùng Thư viện nguồn dữ liệu trực quan của Google (java) hoặc thư viện Python trực quan để tạo các định dạng đầu ra này cho bạn.
Đị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 có tiêu đề "X-DataSource-Auth" và JSONP nếu không. 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 sử dụng thư viện trợ giúp Java hoặc Python, họ sẽ cung cấp mã thích hợp cho bạn. Nếu bạn đang phân tích cú pháp phản hồi bằng tay, hãy xem phần Sửa đổi JSON bên dưới.
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 do phương thức API Hình ảnh trực quan của Google chỉ định google.visualization.Query.send().
Bạn có thể xem một số yêu cầu và phản hồi mẫu JSON ở cuối trang này trong phần Ví dụ.
Bạn có thể dùng thư viện 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 (một đối tượng được bao bọc bởi dấu ngoặc nhọn { } với 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 gọn trong giá trị tham số responseHandler từ yêu cầu. Vì vậy, nếu giá trị responseHandler của yêu cầu là "myHandler", 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 bao gồm 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 cho thấy ngắn gọn):
"google.visualization.Query.setResponse({status:ok, ...})"
Dưới đây là các thành phần đối tượng phản hồi hiện có:
| Thuộc tính | Bắt buộc? |
Mô tả |
|---|---|---|
| phiên bản | Không |
Số chuỗi cung cấp số phiên bản của giao thức có dây của Google Visual. Nếu không được chỉ định, ứng dụng sẽ giả định phiên bản mới nhất. Ví dụ: |
| Mã yêu cầu | Có* |
Số chuỗi cho biết mã của yêu cầu này cho ứng dụng này. Nếu điều 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ả 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ố đó trong phản hồi. |
| trạng thái | Có |
Một chuỗi mô tả thành công hoặc không thành công của thao tác này. Phải là một và chỉ một trong các giá trị sau:
Ví dụ: |
| cảnh bá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
Ví dụ: |
| 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
Mảng đó có các thành phần chuỗi sau (chỉ trả về một giá trị cho mỗi thành viên):
Ví dụ:
|
| sig (sig) | Không |
Một giá trị đã băm của đối tượng bảng. Hữu ích khi tối ưu hoá việc chuyển dữ liệu giữa máy khách và nguồn dữ liệu. Bạn có thể chọn bất kỳ thuật toán băm nào mình muốn. Nếu hỗ trợ thuộc tính này, bạn nên trả về giá trị đã truyền vào bởi ứng dụng khách 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ụ: |
| bảng | Không |
Đối tượng {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 Ví dụ: Xem phần Ví dụ bên dưới. |
Thư viện trợ giúp của Google và mọi truy vấn được gửi tới Google sẽ 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ì việc này không quan trọng với bạn. Nếu có, bạn có thể dùng JSON.parse() để chuyển đổi chuỗi JSON thành đối tượng JavaScript. Một điểm khác biệt trong cách xử lý JSON qua API 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)"; API hỗ trợ việc biểu diễn JSON hợp lệ dưới dạng một chuỗi ở đị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 là 0.
Tối ưu hoá phản hồi JSON
Nếu một ứng dụng khách đưa ra hai 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àm lãng phí băng thông. Để yêu cầu trở nên hiệu quả hơn, giao thức sẽ hỗ trợ 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ừ lần yêu cầu cuối cùng. Dưới đây là cách hoạt động:
- Máy khách gửi một yêu cầu đến nguồn dữ liệu.
- Nguồn dữ liệu sẽ tạo
DataTablecũng như hàm băm của đối tượngDataTablevà trả về cả hai trong phản hồi (băm được trả về trong tham sốtqx.sig). Ứng dụng API Hình ảnh trực quan của Google sẽ lưu giá trịDataTablevàsigvà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được lưu vào bộ nhớ đệm. - Nguồn dữ liệu có thể phản hồi theo một trong hai cách:
- Nếu dữ liệu đã thay đổi so với yêu cầu trước đó, nguồn dữ liệu sẽ gửi lại
hàm băm mới
DataTablevà giá trịsigmới. - Nếu dữ liệu chưa thay đổi so với yêu cầu trước đó, nguồn dữ liệu
sẽ gửi lại
status=error,reason=not_modified,sig=old_sig_value.
- Nếu dữ liệu đã thay đổi so với yêu cầu trước đó, nguồn dữ liệu sẽ gửi lại
hàm băm mới
- 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
DataTablebằng cách gọiQueryResponse.getDataTable(). Nếu dữ liệu giống nhau, nó sẽ chỉ là phiên bản được lưu vào bộ nhớ đệm của bảng.
Xin lưu ý rằng tính năng này chỉ hoạt động đối với các yêu cầu JSON từ các biểu đồ được tạo trên API Hình ảnh của Google.
Đị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ỉ là biểu diễn 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 là một danh sách các giá trị được phân tách bằng dấu phẩy, kết thúc bằng một ký tự UNIX mới (\n). Các giá trị ô phải có cùng loại
cho mỗi cột. Hàng đầu tiên là nhãn cột. Dưới đây là ví dụ về bảng ba hàng, ba cột:
A, B, C 1.0, "yes", true 2.0, "no", false 3.0, "maybe", true
Giao thức này không chỉ định định dạng CSV; nguồn dữ liệu chịu trách nhiệm xác định định dạng CSV của giao thức. Tuy nhiên, đị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 can thiệp) và dòng mới (\n) ở cuối mỗi hàng. Khi nhận được phản hồi chuỗi CSV, trình duyệt có thể hỏi người dùng nên sử dụng ứng dụng nào để mở chuỗi hoặc chỉ cần 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 sang chuỗi CSV.
Nếu yêu cầu này có chứa một thành viên outFileName của tham số tqx , bạn nên cố gắng đưa tên tệp được 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 một khách hàng muốn yêu cầu CSV, bạn có thể nhúng một tiện ích Thanh công cụ trực quan vào trang của bạn 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ư 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 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ỉ là một bản trình bày dữ liệu được phân tách bằng ký tự tab, mã hóa utf-16. Nếu yêu cầu này có chứa một thành viên outFileName của tham số tqx , bạn nên cố gắng đưa tên tệp được chỉ định vào tiêu đề phản hồi.
Định dạng phản hồi HTML
Nếu yêu cầu này chỉ định out:html, thì phản hồi phải là trang HTML xác định bảng HTML chứa dữ liệu. Cách này hữu ích cho việc gỡ lỗi mã của bạn vì trình duyệt có thể trực tiếp hiển thị kết quả của bạn ở định dạng dễ đọc. Bạn không thể gửi truy vấn cho phản hồi HTML bằng cách sử dụng đối tượng google.visualization.Query.
Bạn phải thực hiện một truy vấn cho phản hồi HTML bằng mã tùy chỉnh hoặc bằng cách nhập một URL tương tự như URL vào trình duyệt của bạn:
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ố yêu cầu và phản hồi mẫu. Xin lưu ý rằng các yêu cầu chưa thoát URL; việc này 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 cột gồm 3 cột và 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 với trình xử lý phản hồi: Trả về bảng ba cột, ba hàng với các loại dữ liệu khác nhau.
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'}]}]}});
Cụm từ tìm kiếm có một chuỗi truy vấn đơn giản: Yêu cầu cho một cột duy nhất, trả về một cột có bốn 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 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à thông báo 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 (từ 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 trong 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 để tạo cú pháp phản hồi. Không xử lý việc phân tích cú pháp của yêu cầu hoặc triển khai ngôn ngữ truy vấn SQL của Công cụ biểu đồ của Google.
- MC-Google_Visualization (Bên thứ ba) – Đây là thư viện phía máy chủ PHP mà bạn có thể sử dụng để triển khai Nguồn dữ liệu cho 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à thư viện trợ giúp để tạo Google Hình ảnh API Dữ liệu trực quan 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ừ các nguồn khác nhau 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ở 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ý làm nguồn Dữ liệu của Công cụ biểu đồ của Google.
- vis-table (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. Phần này có ba phần chính. Bản thân phương thức triển khai dữ liệu, trình phân tích cú pháp ngôn ngữ truy vấn và trình định dạng.
- Triển khai nguồn dữ liệu của Google trong Oracle PL/SQL (Bên thứ ba) – Một gói Oracle PL/SQL cho phép Oracle lưu trữ các Nguồn dữ liệu ngay từ cơ sở dữ liệu. Vì vậy, về cơ bản bạn có thể sử dụng bất kỳ truy vấn Oracle nào làm Nguồn dữ liệu công cụ biểu đồ của Google (gói sẽ trả về tệp JSON với dữ liệu này). Công cụ này hỗ trợ gần như đầy đủ cho Ngôn ngữ truy vấn của Google.