Implementacja protokołu źródeł danych wykresów (V0.6)

Z tego artykułu dowiesz się, jak wdrożyć usługę, która obsługuje protokół Źródło danych narzędzi narzędzi do wykresów, aby wyświetlać dane na wykresach przy użyciu klasy zapytania.

Spis treści

Odbiorcy

Ta strona jest przeznaczona przede wszystkim dla deweloperów, którzy będą tworzyć własne źródła danych bez pomocy Biblioteki źródła danych Chart. Jeśli używasz tej lub innych bibliotek pomocniczych, najpierw zapoznaj się z dokumentacją biblioteki.

Ta strona jest też przeznaczona dla czytelników zainteresowanych protokółem komunikacji używanym w komunikacji między klientem a źródłami danych.

Jeśli tworzysz lub używasz wizualizacji, nie musisz czytać tej strony.

Aby odczytać ten dokument, musisz znać podstawową składnię żądań JSON i HTTP. Musisz też zrozumieć, jak działają wykresy z perspektywy użytkownika.

Uwaga: Google nie oficjalnie promuje ani nie obsługuje żadnych źródeł danych innych niż Google, które obsługują protokół Chart Tools Datasource.

Omówienie

Aby uzyskać dostęp do źródła danych dla własnych wykresów lub innych wykresów, możesz wdrożyć protokół Chart Tools Datasource. Źródło danych narzędzi do wykresów ujawnia adres URL, nazywany adresem URL źródła danych, na który wykres może wysyłać żądania HTTP GET. W odpowiedzi źródło danych zwraca poprawnie sformatowane dane, których wykres może użyć do renderowania grafiki na stronie. Ten protokół odpowiedzi na żądanie jest nazywany protokołem przewodowym interfejsu GoogleVisual API.

Dane, które są udostępniane przez źródło danych, można wyodrębnić z różnych zasobów, takich jak plik lub baza danych. Jedynym ograniczeniem jest formatowanie danych w postaci dwuwymiarowej tabeli z kolumnami wpisywanymi.

Jako źródło danych narzędzia do wykresów musisz przeanalizować żądanie w określonym formacie i zwrócić odpowiedź w określonym formacie. Możesz to zrobić na 2 ogólne sposoby:

  • Użyj jednej z tych bibliotek pomocniczych do obsługi żądania i odpowiedzi oraz utwórz bazę danych, która ma zwracać dane. Jeśli używasz jednej z tych bibliotek, musisz napisać sam kod niezbędny do udostępnienia danych bibliotecznej w postaci tabeli.
    • Biblioteka źródeł danych Java – obsługuje żądania i odpowiedzi, tworzy tabelę odpowiedzi na podstawie przekazanych danych i implementuje język zapytań SQL w Wykresach Google.
    • Python Datasource Library – tworzy tabelę odpowiedzi, która generuje składnię odpowiedzi. Nie obsługuje analizy żądania ani implementowania języka zapytań SQL w Grafie Google.

      LUB

  • Utwórz własne źródło danych od zera, obsługując żądanie, tworząc tabelę danych i wysyłając odpowiedź.

Jak to działa:

  1. Źródło danych ujawnia adres URL nazywany adresem URL źródła, do którego wykresy wysyłają żądanie HTTP GET.
  2. Klient wysyła żądanie HTTP GET z parametrami opisującymi format, którego należy użyć w przypadku zwracanych danych, opcjonalny ciąg zapytania i opcjonalne parametry niestandardowe.
  3. Źródło danych otrzymuje i analizuje żądanie zgodnie z opisem w sekcji Format żądania.
  4. Źródło danych przygotowuje dane w wymaganym formacie. Zwykle jest to tabela JSON. Formaty odpowiedzi są opisane w sekcji Format odpowiedzi. Źródło danych może opcjonalnie obsługiwać język zapytań w Wizualizacja, który określa filtrowanie, sortowanie i inne manipulacje danymi.
  5. Źródło danych tworzy odpowiedź HTTP, która zawiera zserializowane dane i inne parametry odpowiedzi, i wysyła ją z powrotem do klienta zgodnie z opisem w formacie odpowiedzi.

Uwaga: wszystkie parametry i stałe wartości ciągów wymienione w tym dokumencie dotyczące żądań i odpowiedzi (np. responseHandler i „OK”) uwzględniają wielkość liter i wielkość liter ma znaczenie.

Wymagania minimalne

Oto minimalne wymagania, których można użyć jako źródła danych narzędzi do tworzenia wykresów:

  • Źródło danych powinno akceptować żądania HTTP GET i być dostępne dla Twoich klientów.
  • Protokół może się zmieniać i obsługiwać schemat wersji (obecna wersja 0.6), więc źródło danych powinno obsługiwać żądania z użyciem zarówno poprzednich, jak i bieżącej wersji. Spróbuj obsługiwać nowe wersje od razu po ich wydaniu, aby uniknąć uszkodzenia klientów, którzy szybko przechodzą na najnowszą wersję.
  • Nie ulegaj awarii, jeśli w ramach żądania wysyłane są nieznane właściwości. Dzieje się tak, ponieważ nowe wersje mogą wprowadzać nowe właściwości, których nie znasz.
  • Przeanalizuj dokładnie te właściwości, których oczekujesz. Chociaż w nowych wersjach mogą pojawiać się nowe właściwości, nie zapominaj o pełnym ciągu znaków żądania. Aby się przed nim uchronić, rozważ analizowanie i używanie tylko tych właściwości, których oczekujesz.
  • Jeśli wymagania dotyczące kodu klienta nie są kodowane przez Ciebie, uważnie udokumentuj wymagania dotyczące źródła danych. Obejmuje to dokumentowanie tych informacji:
    • wszystkie zaakceptowane parametry niestandardowe,
    • możliwość analizowania języka zapytań Google Indexing API,
    • jakiego rodzaju dane zwracasz oraz jaka jest ich struktura (co reprezentują wiersze i kolumny oraz etykiety).
  • Zastosuj wszystkie standardowe środki bezpieczeństwa w witrynie, która akceptuje żądania od nieznanych klientów. Możesz rozsądnie obsługiwać MD5, haszowanie i inne mechanizmy zabezpieczeń w parametrach, aby uwierzytelniać żądania lub chronić się przed złośliwymi atakami. Od klientów oczekujemy, że będą znać Twoje wymagania i na nie reagować. Jeśli jednak nie kodujesz wykresów samodzielnie, pamiętaj, aby dokładnie udokumentować wszystkie swoje wymagania. Zobacz Uwagi na temat zabezpieczeń poniżej.
  • Wszystkie ciągi żądań i odpowiedzi powinny być zakodowane w formacie UTF-8.
  • Najważniejszym formatem odpowiedzi jest JSON. Zacznij od wdrożenia kodu JSON, ponieważ jest to format używany przez większość wykresów. Następnie dodaj inne typy odpowiedzi.
  • Nie musisz obsługiwać interfejsu języka wizualizacji interfejsu API, ale dzięki temu źródło danych będzie bardziej przydatne dla klientów.
  • Nie musisz obsługiwać żądań z jakiegokolwiek typu wykresu i możesz obsługiwać parametry niestandardowe wykresów niestandardowych. Należy jednak zwracać odpowiedzi w standardowym formacie opisanym poniżej.

Bezpieczeństwo

Projektując źródło danych, musisz wziąć pod uwagę to, jak bezpieczne są Twoje dane. W swojej witrynie możesz korzystać z różnych schematów zabezpieczeń, od prostego dostępu do hasła po bezpieczne uwierzytelnianie plików cookie.

Ataki XSSI (skrypty między witrynami) stwarzają ryzyko dla wykresów. Użytkownik może przejść na stronę, która zawiera złośliwy skrypt, który następnie próbuje wysyłać zapytania do adresów URL źródeł danych przy użyciu danych logowania bieżącego użytkownika. Jeśli użytkownik nie wylogował się z witryny, skrypt zostanie uwierzytelniony jako bieżący użytkownik i będzie miał odpowiednie uprawnienia w tej witrynie. W tagu <script src> złośliwy skrypt może uwzględnić źródło danych podobne do kodu JSONP.

Aby zwiększyć poziom zabezpieczeń, możesz ograniczyć żądania do żądań z tej samej domeny co Twoje źródło danych. Znacznie ograniczy to widoczność źródła danych, ale jeśli masz bardzo poufne dane, do których nie należy uzyskiwać dostępu spoza Twojej domeny, rozważ to. Źródło danych, które zezwala na żądania tylko z tej samej domeny, jest nazywane ograniczonym źródłem danych, a nie ograniczonym źródłem danych, które akceptuje zapytania z dowolnej domeny. Oto kilka informacji o tym, jak wdrożyć ograniczone źródło danych:

Aby upewnić się, że żądanie naprawdę pochodzi z Twojej domeny, a nie z domeny zewnętrznej (lub przeglądarki w domenie objętej atakiem XSRF):

  • Sprawdź, czy w żądaniu znajduje się nagłówek „X-DataSource-Auth”. Ten nagłówek jest określany przez interfejs Google wizualizacji API. Nie musisz badać jego zawartości, a jedynie sprawdzać, czy się w nim znajduje. Jeśli używasz biblioteki źródeł danych Google Chart Tools, możesz pozwolić tej bibliotece za Ciebie.
  • Użyj uwierzytelniania plików cookie, aby uwierzytelnić klienta. Nie można wstrzyknąć niestandardowych nagłówków do żądania z innej domeny przy jednoczesnym zachowaniu plików cookie uwierzytelniania.
  • Dopilnuj, aby kod JavaScript był niewykonany w tagu <script src>. Aby to zrobić, poprzedź odpowiedź JSON ciągiem )]}, po czym dodaj nowy wiersz. W kliencie usuń przedrostek odpowiedzi. W przypadku XmlHttpRequest jest to możliwe tylko wtedy, gdy żądanie pochodzi z tej samej domeny.

Format żądania

Klient wysyła żądanie HTTP GET z kilkoma parametrami, w tym elementami niestandardowymi, opcjonalnym ciągiem zapytania, podpisem i innymi. Użytkownik jest odpowiedzialny wyłącznie za przeanalizowanie parametrów opisanych w tej sekcji. Należy uważać, aby nie podejmować żadnych działań w celu uniknięcia złośliwych ataków.

Sprawdź, czy w dokumentacji witryny znajdują się wartości domyślne parametrów opcjonalnych (standardowych i niestandardowych) oraz udokumentuj je w dokumentacji.

Oto kilka przykładowych żądań (więcej przykładów i odpowiedzi znajdziesz na końcu tego dokumentu w przykładach):

Uwaga: poniższe ciągi żądań i te wyświetlane w sekcji Przykłady powinny zawierać przedrostek adresu URL ze zmianą znaczenia.

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

Oto lista wszystkich parametrów standardowych w ciągu żądania. Pamiętaj, że w nazwach parametrów (np. „version”) i ciągłych ciągach znaków (np. „OK”, „warning” i „not_modified”) wielkość liter jest rozróżniana. Tabela zawiera też informacje o tym, czy parametr jest wymagany i czy trzeba go obsługiwać.

Parametr
Wymagane w żądaniu?
Źródło danych musi obsługiwać?
Opis
tq
Nie
Nie

Zapytanie napisane w języku zapytań interfejsu GoogleWizualizacja API określające, jak filtrować, sortować lub w inny sposób przetwarzać zwrócone dane. Nie trzeba cytować ciągu.

Przykład: http://www.example.com/mydatasource?tq=select Col1.

TQX
Nie
Tak

Zestaw par klucz-wartość rozdzielonych dwukropkiem dla parametrów standardowych lub niestandardowych. Pary są rozdzielone średnikami. Oto lista parametrów standardowych zdefiniowanych przez protokół wizualizacji:

  • reqId – [w żądaniu wymagany; źródło danych musi obsługiwać] numeryczny identyfikator tego żądania. Jest tak używany, jeśli klient przed wysłaniem odpowiedzi otrzyma wiele żądań, źródło danych może zidentyfikować odpowiedź przy użyciu odpowiedniego żądania. Odeślij tę wartość w odpowiedzi.
  • version – [w żądaniu wymagany; źródło danych musi obsługiwać] numer wersji protokołu Google wizualizacji. Bieżąca wersja to 0.6. . Jeśli nie, wyślij najnowszą wersję.
  • sig – [w żądaniu żądanym; opcjonalny w przypadku źródła danych do obsługi] hasz DataTable wysłany do tego klienta w poprzednim żądaniu wysłanym do tego źródła danych. Jest to optymalizacja, która pozwala uniknąć podwójnego wysyłania identycznych danych do klienta. Poniżej dowiesz się, jak zoptymalizować żądanie.
  • out – [w żądaniu wymagany; źródło danych musi obsługiwać] ciąg znaków opisujący format zwracanych danych. Może to być dowolna z tych wartości:
    • json – [wartość domyślna] ciąg znaków odpowiedzi JSON (opisany poniżej).
    • html – podstawowa tabela HTML z wierszami i kolumnami. W takim przypadku jedyną rzeczą, która powinna zostać zwrócona, jest tabela HTML z danymi. Jest to przydatne w przypadku debugowania, zgodnie z opisem w sekcji Format odpowiedzi poniżej.
    • csv – wartości rozdzielone przecinkami. W takim przypadku zwracany jest jedyny ciąg znaków pliku CSV. Możesz zażądać niestandardowej nazwy pliku w nagłówkach odpowiedzi, określając parametr outFileName.
    • tsv-excel – podobni do csv, ale korzysta z kart zamiast przecinków, a wszystkie dane są kodowane w formacie utf-16.
    Uwaga: jedyny typ danych, którego wykres zależy, aby uzyskać żądanie, to wykres json. Szczegółowe informacje o poszczególnych typach znajdziesz w sekcji Format odpowiedzi poniżej.
  • responseHandler – [w żądaniu wymagany; źródło danych musi obsługiwać] nazwa ciągu znaków funkcji JavaScript na stronie klienta, która zostanie wywołana w odpowiedzi. Jeśli żądanie nie zawiera tej wartości, wartość to „google.visualization.Query.setResponse”. Ta odpowiedź zostanie wysłana w ramach odpowiedzi. Zobacz Format odpowiedzi poniżej, aby dowiedzieć się, jak to zrobić.
  • outFileName – [w żądaniu wysłanym; opcjonalny w przypadku źródła danych – jeśli podasz out:csv lub out:tsv-excel, możesz opcjonalnie podać tutaj nazwę pliku. Przykład: outFileName=results.csv.

Przykład: tqx=version:0.6;reqId:1;sig:5277771;out:json; responseHandler:myQueryHandler

tqrt,
Nie
Nie

Zarezerwowane: zignoruj ten parametr Metoda użyta do wysłania zapytania.

Format odpowiedzi

Format odpowiedzi zależy od parametru out żądania, który określa oczekiwany typ odpowiedzi. Aby dowiedzieć się, jak odpowiadać na żądania poszczególnych typów, zapoznaj się z tymi sekcjami:

  • JSON – zwraca odpowiedź JSON zawierającą dane z obiektu JavaScript, które mogą zostać przekazane bezpośrednio do konstruktora DataTable. To zdecydowanie najpowszechniejszy rodzaj żądania, który jest najważniejszy.
  • CSV – zwraca stałą listę wartości rozdzielonych przecinkami, która będzie obsługiwana przez przeglądarkę.
  • TSV – zwraca listę wartości rozdzielonych tabulatorami, którą ma obsługiwać przeglądarka.
  • HTML – zwraca tabelę HTML, która ma być renderowana przez przeglądarkę.

Aby wygenerować te formaty wyjściowe, możesz użyć biblioteki źródła danych Google wizualizacji (java) lub biblioteki Pythona dla wizualizacji.

Format odpowiedzi JSON

Domyślny format odpowiedzi to JSON, jeśli żądanie zawiera nagłówek „X-DataSource-Auth” lub JSONP. Pamiętaj, że klient wykresu Google w rzeczywistości obsługuje zmodyfikowaną wersję JSON i JSONP. Jeśli używasz bibliotek pomocniczych Java lub Pythona, właściwy kod wyświetli się za Ciebie. Jeśli ręcznie analizujesz odpowiedzi, przeczytaj modyfikacje JSON poniżej.

Jeśli stosujesz żądania dotyczące tej samej domeny, zweryfikuj obecność w nagłówku nagłówka „X-DataSource-Auth” i użyj plików cookie autoryzacji.

To jedyny format odpowiedzi określany za pomocą metody google.visualization.Query.send() interfejsu GoogleVisual API. Przykładowe żądania i odpowiedzi JSON znajdziesz na końcu tej strony w Przykłady. Aby utworzyć ten ciąg odpowiedzi, możesz skorzystać z bibliotek pomocniczych Java lub Pythona.

Ten format odpowiedzi to obiekt JSON zakodowany w UTF-8 (obiekt otoczony nawiasami { }, a każda usługa oddzielona przecinkiem) zawierająca właściwości z tabeli poniżej (dane są przypisane do właściwości table). Ten obiekt JSON powinien być zawarty w wartości parametru responseHandler z żądania. Jeśli więc wartość żądania responseHandler to „myHandler”, musisz zwrócić ten ciąg znaków (w celu zachowania zwięzłości wyświetlana jest tylko jedna właściwość):

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

Jeśli żądanie nie zawierało wartości responseHandler, domyślną wartością jest „google.visualization.Query.setResponse”, więc musisz zwrócić ciąg znaków w ten sposób (tylko 1 usługa jest widoczna dla zwięzłości):

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

Oto dostępne elementy obiektów odpowiedzi:

Właściwość
Element wymagany?
Opis
Wersja
Nie

Numer ciągu znaków określający numer wersji protokołu przewodowego Google wizualizacji. Jeśli zasada nie zostanie określona, klient przyjmie najnowszą wersję.

Przykład: version=0.6.

identyfikator żądania
Tak*
Numer ciągu znaków wskazujący identyfikator tego żądania dla tego klienta. Jeśli żądanie było dostępne, ustaw taką samą wartość. Więcej informacji znajdziesz w opisie reqId w sekcji żądania.

* Jeśli ten parametr nie został określony w żądaniu, nie musisz go ustawiać w odpowiedzi.
stan
Tak

Ciąg opisujący sukces lub błąd tej operacji. Musi to być jedna z tych wartości:

  • ok – udana prośba. Tabela musi zawierać się we właściwości table.
  • warning – sukces, ale problemy. Tabela musi zawierać się we właściwości table.
  • error – wystąpił problem. Jeśli zwrócisz ten wynik, nie musisz zwracać wartości table i musisz zwracać errors.

Przykład: status:'warning'.

ostrzeżenia
Tylko jeśli status=warning

Tablica z co najmniej 1 obiektem, z których każdy opisuje problem niekrytyczny. Wymagany, jeśli status=warning, w przeciwnym razie jest niedozwolony. Każdy obiekt ma te właściwości ciągu znaków (zwróć tylko jedną wartość na każdą usługę):

  • reason – [wymagany] – jednowyrazowy opis ostrzeżenia. Protokół określa poniższe wartości, ale w razie potrzeby możesz zdefiniować własne. Wartości klientów niestandardowych nie będą jednak w żaden sposób przetwarzane. Możesz mieć tylko 1 wartość reason:
    • data_truncated – zwrócone wiersze DataTable zostały usunięte, ponieważ użytkownik dodał ciąg zapytania, który przyciął listę wyników, lub źródło danych z jakiegoś powodu nie chce zwrócić pełnych wyników.
    • other – ogólne nieokreślone ostrzeżenie.
  • message[opcjonalny] Krótki cudzysłów wyjaśniający problem, który może być używany jako tytuł pola alertu. Ten komunikat może być wyświetlany użytkownikowi. HTML nie jest obsługiwany.
  • detailed_message – [opcjonalnie] szczegółowy komunikat z cytowaniem wyjaśniający problem i możliwe rozwiązania. Jedynym obsługiwanym kodem HTML jest element <a> z pojedynczym atrybutem href. Obsługiwane jest kodowanie Unicode. Może to być widoczne dla użytkownika.

Przykład: warnings:[{reason:'data_truncated',message:'Retrieved data was truncated'}].

błędy
Wymagany, jeśli status=error

Tablica z co najmniej jednym obiektem, z których każdy opisuje błąd. Wymagany, jeśli status=error. W przeciwnym razie jest niedozwolony. Jest ona podobna do wartości warnings. Pamiętaj, że błąd not_modified nie jest błędem klienta.

Tablica zawiera te ciągi znaków (zwraca tylko jedną wartość dla każdego użytkownika):

  • reason – [wymagany] – jest taki sam jak warnings.reason, ale zdefiniowane są te wartości:
    • not_modified – dane nie uległy zmianie od ostatniego żądania. Jeśli to jest przyczyną błędu, wartość table nie powinna być określona.
    • user_not_authenticated – jeśli źródło danych wymaga uwierzytelniania, ale nie zostało to zrobione, podaj tę wartość. Klient wyświetli alert o wartości message.
    • unknown_data_source_id
    • access_denied
    • unsupported_query_operation
    • invalid_query
    • invalid_request
    • internal_error
    • not_supported
    • illegal_formatting_patterns
    • other – ogólny, nieokreślony błąd.
  • message[opcjonalny] to samo co warnings.message. Uwaga: złośliwy użytkownik może wykorzystać szczegółowy ciąg danych, aby uzyskać dostęp do nieautoryzowanych danych, a nawet wykorzystać go do ataku na dane lub witrynę. Jeśli przechowujesz dane, które powinny być bezpieczne, lub przetwarzasz zapytania użytkowników bezpośrednio, rozważ zwracanie szczegółowego komunikatu o błędzie, który może dostarczyć informacje atakującemu. Zamiast tego dodaj ogólny komunikat, np. „Nieprawidłowy ciąg zapytania”.
  • detailed_message[opcjonalny] to samo co warnings.detailed_message. Wyświetl ostrzeżenie, aby dowiedzieć się więcej o message.

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

Sig
Nie

Zaszyfrowana wartość obiektu tabeli. Ta opcja jest przydatna przy optymalizacji przenoszenia danych między klientem a źródłem danych. Możesz wybrać dowolny algorytm haszowy. Jeśli obsługujesz tę właściwość, musisz zwrócić wartość przekazana przez klienta, jeśli żadne dane nie zostaną zwrócone, lub zwrócić nowy hasz, jeśli zostaną zwrócone nowe dane.

Przykład: sig:'5982206968295329967'.

tabela
Nie

Obiekt DataTable w notacji literału JavaScript z Twoimi danymi. Szczegółowe informacje o formacie tego obiektu znajdziesz w sekcji z linkami. Oto przykład prostej tabeli danych:

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

Właściwość table powinna występować tylko wtedy, gdy status=ok lub status=warning. Jeśli nie zwracasz danych, nie uwzględniaj tej właściwości (czyli nie przekazuj jej z pustą wartością ciągu znaków).

Przykład: zobacz Przykłady poniżej.

 

Wymagany jest ścisły tryb JSON

Biblioteki pomocnicze Google i wszystkie zapytania wysyłane do Google zwracają ścisły format JSON/JSONP. Jeśli nie analizujesz zwróconego kodu samodzielnie, nie powinno to być dla Ciebie istotne. Jeśli tak, możesz użyć funkcji JSON.parse(), by przekonwertować ciąg JSON na obiekt JavaScript. Jedną z różnic w przetwarzaniu JSON przez interfejs API jest to, że chociaż JSON nie obsługuje wartości daty JavaScriptu (np. „new Date(2008,1,28,0,31,26)”, interfejs API obsługuje prawidłowe reprezentowanie dat w formacie JSON w formacie Date(year, month, day[,hour, minute, second[, millisecond]]), w którym wszystkie dni po konfiguracji są opcjonalne, a miesiące są oparte na zerowej wartości.

 

Optymalizacja odpowiedzi JSON

Jeśli klient wysyła 2 żądania, a dane nie zmieniają się między żądaniami, nie ma potrzeby wysyłania ponownie danych. Spowoduje to niepotrzebne wykorzystanie przepustowości. Aby zwiększyć efektywność żądań, protokół obsługuje przechowywanie danych w pamięci podręcznej klienta i wysyłanie sygnału, jeśli dane nie uległy zmianie od ostatniego żądania. Jak to działa:

  1. Klient wysyła żądanie do źródła danych.
  2. Źródło danych generuje DataTable oraz skrót obiektu DataTable i zwraca oba w odpowiedzi (hasz jest zwracany w parametrze tqx.sig). Klient Google Migration API przechowuje wartości DataTable i sig w pamięci podręcznej.
  3. Klient wysyła kolejne żądanie danych, w tym wartość tqx.sig w pamięci podręcznej.
  4. Źródło danych może odpowiedzieć na 2 sposoby:
    • Jeśli dane uległy zmianie od poprzedniego żądania, źródło danych wysyła nowy hasz wartości DataTable i nowy sig.
    • Jeśli dane nie zmieniły się w porównaniu z poprzednim żądaniem, źródło danych odsyła status=error, reason=not_modified i sig=old_sig_value.
  5. W obu przypadkach strona, na której znajduje się wykres, otrzyma prawidłową odpowiedź i może pobrać DataTable z wywołania QueryResponse.getDataTable(). Jeśli dane są takie same, jest to po prostu wersja tabeli z pamięci podręcznej.

Pamiętaj, że działa to tylko w przypadku żądań JSON z wykresów utworzonych przy użyciu interfejsu GoogleVisual API.

Format odpowiedzi CSV

Jeśli żądanie zawiera wartość out:csv, odpowiedź nie zawiera metadanych, a jedynie reprezentuje plik danych. Tabela CSV zazwyczaj zawiera listę wartości oddzielonych przecinkami, gdzie każdy wiersz danych to rozdzielona przecinkami lista wartości, która kończy się znakiem UNIX nowego wiersza (\n). Wartości w komórkach powinny mieć ten sam typ każdej kolumny. Pierwszy wiersz to etykiety kolumn. Oto przykład trzywierszowej tabeli z 3 kolumnami:

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

Format CSV nie jest określany przez ten protokół. To źródło danych odpowiada za zdefiniowanie formatu CSV. Typowy format to jednak zbiór wartości rozdzielonych przecinkami (bez znaków odstępu) i nowy wiersz (\n) na końcu każdego wiersza. Gdy przeglądarka otrzyma odpowiedź w formie ciągu CSV, może zapytać użytkownika, której aplikacji użyć do otwarcia ciągu tekstowego, lub może wyświetlić ją po prostu na ekranie. Biblioteki open source w językach Java i Python udostępniają metodę przekształcania DataTable w ciąg znaków CSV.

Jeśli żądanie zawiera parametr outFileName z parametrem tqx , staraj się uwzględnić podaną nazwę pliku w nagłówkach odpowiedzi.

Obiekt google.visualization.Query nie obsługuje żądania odpowiedzi CSV. Jeśli klient chce poprosić o dostęp do pliku CSV, możesz umieścić na stronie gadżet Wizualizacja lub użyć niestandardowego kodu do utworzenia żądania lub podać link, który wyraźnie określa właściwość out:csv w tqx, tak jak w tym adresie URL żądania:

Wyślij prośbę

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

Odpowiedź

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

Format odpowiedzi TSV

Jeśli żądanie wskazuje out:tsv-excel, odpowiedź nie zawiera metadanych, a jedynie rozdzielanych tabulatorami danych jest zakodowane w standardzie UTF-16. Jeśli żądanie zawiera parametr outFileName z parametrem tqx , staraj się uwzględnić podaną nazwę pliku w nagłówkach odpowiedzi.

Format odpowiedzi HTML

Jeśli żądanie wskazuje out:html, odpowiedzią powinna być strona HTML definiująca tabelę HTML z danymi. Ta funkcja przydaje się do debugowania kodu, ponieważ przeglądarka może renderować wynik bezpośrednio w czytelnym formacie. Nie można wysyłać zapytań dotyczących odpowiedzi HTML za pomocą obiektu google.visualization.Query. Zapytanie o odpowiedź HTML musisz utworzyć, wpisując kod niestandardowy albo wpisując w przeglądarce adres URL podobny do tego:

Wyślij prośbę

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

Odpowiedź

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

Przykłady

Oto kilka przykładowych żądań i odpowiedzi. Pamiętaj, że w przypadku żądań nie zmienia się znaczenie adresu URL. Jest to zwykle wykonywane przez przeglądarkę lub obiekt google.visualization.Query.

Proste żądanie: zwraca podstawowe informacje, korzystając z tabeli w 3 kolumnach i 4 wierszy.

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

Proste żądanie z modułem obsługi odpowiedzi: zwraca tabelę z 3 kolumnami i 3 wierszami z różnymi typami danych.

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

Zapytanie z prostym ciągiem zapytania: żądanie pojedynczej kolumny zwraca jedną kolumnę z 4 wierszami.

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

Błąd dotyczący niezmodyfikowanych danych: przykład błędu 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'}]});

Ostrzeżenie o skróconym danych: przykład ostrzeżenia (data_truncated). Zwróć uwagę, że żądanie nadal zwraca dane.

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

Błąd odmowy dostępu: przykład błędu 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'}]});

Nieprawidłowy ciąg zapytania: przykład żądania z nieprawidłowym ciągiem zapytań. Pamiętaj, że komunikat szczegółowe to komunikat ogólny, a nie rzeczywisty komunikat o błędzie.

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

Narzędzia dla programistów

  • Biblioteka Java Datasource (od Google) – obsługuje żądania i odpowiedzi, tworzy tabelę odpowiedzi na podstawie przekazanych danych i implementuje język zapytań SQL w Wykresach Google.
  • Python Datasource Library (od Google) – tworzy tabelę odpowiedzi, która generuje składnię odpowiedzi. Nie obsługuje analizy żądania ani implementowania języka zapytań SQL w Grafie Google.
  • MC-Google_Visualization (firma zewnętrzna) – biblioteka PHP odpowiedzi na serwerze po stronie serwera, którą możesz wykorzystać do wdrożenia silników danych Chart Tools w MySQL, SQLite i PostgreSQL za pomocą PDO.
  • bortosky-google-visualization (inna firma) – biblioteka pomocnicza dla użytkowników .NET, tworząc bazę danych interfejsu GoogleWizualizacj API.
  • Streamer GV (zewnętrzny) – narzędzie po stronie serwera, które może konwertować dane z różnych źródeł na prawidłowe odpowiedzi na zapytania na wykresach Google. GV Streamer obsługuje kilka języków (np. PHP, Java, .NET) i kilka źródeł nieprzetworzonych danych (np. MySql).
  • TracGViz (firma zewnętrzna) – TracGViz to bezpłatne narzędzie typu open source, które udostępnia komponenty, dzięki czemu Trac będzie mógł korzystać z gadżetów wykresów, a także implementować dane zarządzane przez Trac jako źródło danych narzędzi Wykresów Google.
  • vis-table (zewnętrzna) – biblioteka wdrażająca źródło danych z narzędzia Google Chart Tools w języku PHP. Składa się z 3 głównych części. Sama implementacja bazy danych, parser języka zapytania i formatery.
  • Implementacja źródła danych Google w Oracle PL/SQL (firma zewnętrzna) – pakiet Oracle PL/SQL, który umożliwia serwerom Oracle korzystanie ze źródeł danych bezpośrednio z bazy danych. Zasadniczo można więc użyć dowolnego zapytania Oracle jako źródła danych narzędzi Google Charts (pakiet zwróci plik JSON z danymi). Język Google Query Language jest prawie w pełni obsługiwany.