Implementowanie protokołu źródła danych Chart Tools (V0.6)

Na tej stronie opisujemy, jak wdrożyć usługę, która obsługuje protokół Datasource narzędzi wykresów, aby udostępniać dane na wykresach przy użyciu klasy zapytania.

Spis treści

Odbiorcy

Ta strona jest przeznaczona głównie dla deweloperów, którzy będą tworzyć własne źródła danych bez korzystania z biblioteki źródeł danych narzędzi do tworzenia wykresów. Jeśli używasz tej lub innych bibliotek pomocniczych, najpierw zapoznaj się z dokumentacją swojej biblioteki.

Ta strona jest też przeznaczona dla czytelników, którzy chcą się dowiedzieć, jaki protokół służy do komunikacji między wizualizacją klienta a źródłem danych.

Jeśli tworzysz wizualizację lub korzystasz z niej, nie musisz korzystać z tej strony.

Aby zapoznać się z tym dokumentem, musisz znać podstawową składnię żądań JSON i HTTP. Trzeba też wiedzieć, jak działają wykresy z perspektywy użytkownika.

Uwaga: Google nie promuje ani nie wspiera żadnych źródeł danych spoza Google, które obsługują protokół źródła danych Chart Tools.

Omówienie

Możesz wdrożyć protokół Datasource narzędzi Chart, aby zostać dostawcą źródeł danych dla własnych wykresów lub innych wykresów. Źródło danych w narzędziach do tworzenia wykresów udostępnia adres URL nazywany adresem URL źródła danych, do którego wykres może wysyłać żądania HTTP GET. W odpowiedzi źródło danych zwróci prawidłowo sformatowane dane, których wykres może użyć do wyrenderowania grafiki na stronie. Ten protokół żądania-odpowiedzi jest nazywany protokołem Wire interfejsu Google wizualizacji API.

Dane dostarczane przez źródło danych można wyodrębnić z różnych zasobów, takich jak plik lub baza danych. Jedynym ograniczeniem jest to, że możesz sformatować dane w postaci tabeli dwuwymiarowej z kolumnami z wpisanymi danymi.

Jako źródło danych narzędzi do tworzenia wykresów musisz przeanalizować żądanie w określonym formacie i zwrócić odpowiedź w określonym formacie. Możesz to zrobić na jeden z dwóch ogólnych sposobów:

  • Użyj jednej z tych bibliotek pomocniczych do obsługi żądań i odpowiedzi oraz utwórz zwracaną tabelę Data. Jeśli używasz jednej z tych bibliotek, musisz napisać tylko kod niezbędny do udostępnienia danych bibliotece w formie tabeli.
  • Zapisz własne źródło danych od zera, przetwarzając żądanie, tworząc tabelę DataTable i wysyłając odpowiedź.

Jak to działa:

  1. Źródło danych udostępnia adres URL (nazywany adresem URL źródła danych), do którego wykresy wysyłają żądanie HTTP GET.
  2. Klient tworzy żądanie HTTP GET z parametrami opisującymi format, który ma zostać użyty w przypadku zwracanych danych, opcjonalnym ciągiem zapytania i opcjonalnymi parametrami niestandardowymi.
  3. Źródło danych odbiera i analizuje żądanie zgodnie z opisem w sekcji Format żądania.
  4. Źródło danych przygotowuje dane w żądanym formacie. Zwykle jest to tabela JSON. Formaty odpowiedzi znajdziesz w sekcji Format odpowiedzi. Źródło danych może opcjonalnie obsługiwać język zapytań interfejsu API wizualizacji, który określa filtrowanie, sortowanie i inne operacje na danych.
  5. Źródło danych tworzy odpowiedź HTTP, która zawiera zserializowane dane i inne parametry odpowiedzi, oraz wysyła ją z powrotem do klienta zgodnie z opisem w sekcji Format odpowiedzi.

Uwaga: wszystkie parametry i wartości stałe ciągu znaków wymienione w tym dokumencie w przypadku żądań i odpowiedzi (np. responseHandler czy „ok”) są małe i jest w nich rozróżniana wielkość liter.

Wymagania minimalne

Oto minimalne wymagania, które musisz spełnić, aby używać go jako źródła danych w narzędziach do tworzenia wykresów:

  • Źródło danych powinno akceptować żądania HTTP GET i powinno być dostępne dla klientów.
  • Protokół może się zmienić i obsługiwać schemat wersji (obecna wersja to 0.6), dlatego Twoje źródło danych powinno obsługiwać żądania korzystające z poprzednich oraz bieżącej wersji. Staraj się obsługiwać nowe wersje od razu po ich opublikowaniu, aby uniknąć uszkodzenia klientów, które szybko uaktualniają się do najnowszej wersji.
  • Nie kończ, jeśli wraz z żądaniem 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.
  • Analizuj tylko te właściwości, których oczekujesz. Mimo że nowe wersje mogą wprowadzać nowe właściwości, nie akceptuj na ślepo i nie używaj całego ciągu żądania. Aby uchronić się przed złośliwymi atakami, starannie przeanalizuj dane i używaj tylko oczekiwanych właściwości.
  • Jeśli nie kodujesz wykresów klienta samodzielnie, uważnie udokumentuj wymagania dotyczące źródeł danych. Obejmuje to dokumentowanie tych informacji:
    • Wszystkie zaakceptowane parametry niestandardowe
    • możliwość przeanalizowania języka zapytań interfejsu GoogleVisual API oraz
    • rodzaj zwracanych danych i ich struktura (czyli treść, jaką reprezentują wiersze i kolumny oraz ewentualne etykiety).
  • Zastosuj wszystkie standardowe środki ostrożności związane z bezpieczeństwem witryny, która akceptuje żądania od nieznanych klientów. Możesz w uzasadnionych przypadkach obsługiwać MD5, szyfrowanie i inne mechanizmy zabezpieczeń w parametrach, aby uwierzytelniać żądania lub zabezpieczać przed złośliwymi atakami. Możesz też oczekiwać, że klienci będą znać Twoje wymagania i reagować na nie. Pamiętaj jednak, aby dobrze udokumentować wszystkie wymagania, jeśli nie kodujesz wykresów samodzielnie. Zobacz Uwagi na temat bezpieczeństwa poniżej.
  • Wszystkie ciągi znaków żądania i odpowiedzi powinny być zakodowane w formacie UTF-8.
  • Najważniejszym formatem odpowiedzi jest JSON. Pamiętaj, aby najpierw zaimplementować format JSON, ponieważ jest to format używany na większości wykresów. Później dodaj inne typy odpowiedzi.
  • Nie nie musisz obsługiwać języka zapytań interfejsu API wizualizacji, ale dzięki temu Twoje źródło danych będzie bardziej przydatne dla klientów.
  • Nie musisz obsługiwać żądań pochodzących z żadnych lub wszystkich typów wykresów. Możesz też obsługiwać parametry niestandardowe w przypadku wykresów niestandardowych. Odpowiedzi powinny być jednak zwracane w standardowym formacie opisanym poniżej.

Uwagi na temat bezpieczeństwa

Podczas projektowania źródła danych musisz wziąć pod uwagę, jak bezpieczne muszą być dane. W swojej witrynie możesz stosować różne schematy zabezpieczeń, od prostego dostępu za pomocą hasła po bezpieczne uwierzytelnianie na podstawie plików cookie.

Dzięki wykresom istnieje ryzyko, że ataki XSSI (z uwzględnieniem skryptów między witrynami) wiążą się z ryzykiem. Użytkownik może przejść na stronę, która zawiera złośliwy skrypt, który następnie zaczyna próbować tworzyć zapytania do adresów URL źródeł danych, korzystając z 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ł do niej uprawnienia. Za pomocą tagu <script src> złośliwy skrypt może dołączyć źródło danych, podobnie jak w przypadku JSONP.

Aby zwiększyć bezpieczeństwo, możesz rozważyć ograniczenie żądań do tych pochodzących z tej samej domeny co Twoje źródło danych. Może to znacznie ograniczyć widoczność Twojego źródła danych, ale jeśli masz bardzo wrażliwe dane, do których nie należy uzyskiwać dostępu spoza Twojej domeny, weź pod uwagę te informacje. Źródło danych, które dopuszcza wyłącznie żądania z tej samej domeny, jest nazywane źródłem z ograniczonym dostępem w odróżnieniu od nieograniczonego źródła danych, które akceptuje zapytania z dowolnej domeny. Poniżej znajdziesz szczegółowe informacje o implementowaniu ograniczonego źródła danych:

Aby upewnić się, że żądanie rzeczywiście pochodzi z Twojej domeny, a nie z domeny zewnętrznej (lub z przeglądarki w domenie, która jest zaatakowana przez atak XSRF):

  • Sprawdź, czy w żądaniu znajduje się nagłówek „X-DataSource-Auth”. Ten nagłówek jest definiowany przez interfejs GoogleVisual API. Nie musisz badać jego zawartości – sprawdź tylko, czy on się tam znajduje. Jeśli używasz biblioteki źródeł danych narzędzia Google Chart, może ona obsługiwać to za Ciebie.
  • Do uwierzytelniania klienta używaj uwierzytelniania za pomocą plików cookie. Nie jest znany sposób wstrzykiwania niestandardowych nagłówków do żądania międzydomenowego z zachowaniem plików cookie uwierzytelniania.
  • Zmniejsz prawdopodobieństwo wykonania kodu JavaScript po dodaniu tagu <script src>. Aby to zrobić, poprzedź odpowiedź JSON przedrostkiem )]}' i nowym wierszem. W kliencie usuń prefiks z 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 z elementami niestandardowymi, opcjonalnym ciągiem zapytania, podpisem i innymi elementami. Odpowiadasz wyłącznie za analizę parametrów opisanych w tej sekcji. Nie obchodź się z innymi, aby uniknąć złośliwych ataków.

Upewnij się, że masz określone wartości domyślne dla parametrów opcjonalnych (zarówno standardowych, jak i niestandardowych), a wszystkie wartości domyślne udokumentuj w dokumentacji witryny.

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

Uwaga: poniższe ciągi znaków żądania oraz te wymienione w sekcji Przykłady powinny mieć przed wysłaniem zmienione znaczenie adresu URL.

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. „wersja”), jak i wartości ciągów stałych (np. „ok”, „warning” i „not_modified”), wielkość liter ma znaczenie. W tabeli znajdziesz też informacje o tym, czy parametr musi zostać wysłany oraz czy musisz go obsłużyć.

Parametr
Wymagany w żądaniu?
Czy źródło danych musi obsługiwać?
Opis
TQ
Nie
Nie

Zapytanie napisane w języku zapytań interfejsu GoogleVisual API, które określa sposób filtrowania, sortowania i innych operacji na zwróconych danych. Ciągu nie trzeba cytować.

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

TQX
Nie
Tak

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

  • reqId – [wymagany w żądaniu; źródło danych musi obsługiwać] identyfikator numeryczny tego żądania. Dzięki temu jeśli klient wyśle wiele żądań przed otrzymaniem odpowiedzi, źródło danych będzie mogło zidentyfikować tę odpowiedź z odpowiednim żądaniem. Odeślij tę wartość w odpowiedzi.
  • version – [element opcjonalny w żądaniu; źródło danych musi obsługiwać] numer wersji protokołu Google wizualizacji. Obecna wersja to 0.6. Jeśli nie wyślesz, zakładaj najnowszą wersję.
  • sig – [opcjonalny w żądaniu; opcjonalny w przypadku źródła danych do obsłużenia] Skrót identyfikatora DataTable wysłanego do tego klienta we wszystkich poprzednich żądaniach kierowanych do tego źródła danych. Pozwala to uniknąć dwukrotnego wysyłania tych samych danych do klienta. Informacje o tym, jak korzystać z tej funkcji, znajdziesz poniżej w sekcji Optymalizacja żądania.
  • out – [opcjonalny w żądaniu; źródło danych musi obsługiwać] ciąg opisujący format zwracanych danych. Może to być dowolna z tych wartości:
    • json – [wartość domyślna] ciąg 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. Przydaje się ona podczas debugowania, co opisano w sekcji Format odpowiedzi poniżej.
    • csv – wartości rozdzielone przecinkami. W takim przypadku zwracany jest tylko ciąg danych w formacie CSV. Możesz zażądać niestandardowej nazwy pliku w nagłówkach odpowiedzi, określając parametr outFileName.
    • tsv-excel – podobne do csv, ale zamiast przecinków używa się tabulatorów, a wszystkie dane są zakodowane w formacie UTF-16.
    . Jedynym typem danych, do którego żądania może żądać wykres utworzony w interfejsie Google Visualization API, będzie kiedykolwiek żądano formatu JSON. Szczegółowe informacje o poszczególnych typach znajdziesz poniżej w sekcji Format odpowiedzi.
  • responseHandler – [opcjonalny w żądaniu; źródło danych musi obsługiwać] nazwa ciągu znaków funkcji obsługi JavaScript na stronie klienta, która zostanie wywołana z odpowiedzią. Jeśli żądanie nie zawiera jego wartości, przyjmuje wartość „google.visualization.Query.setResponse”. Ten kod zostanie odesłany w ramach odpowiedzi. Aby dowiedzieć się, jak to zrobić, zapoznaj się z sekcją Format odpowiedzi poniżej.
  • outFileName – [opcjonalny w żądaniu; opcjonalny w przypadku źródła danych do obsługi] Jeśli określisz out:csv lub out:tsv-excel, możesz opcjonalnie poprosić o podaną tutaj nazwę pliku. Przykład: outFileName=results.csv.

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

qrt
Nie
Nie

Zarezerwowany: zignoruj ten parametr. Metoda, która została użyta do wysłania zapytania.

Format odpowiedzi

Format odpowiedzi zależy od parametru out żądania, który określa oczekiwany typ odpowiedzi. W poniższych sekcjach znajdziesz informacje, jak odpowiadać na poszczególne typy żądań:

  • JSON – zwraca odpowiedź JSON zawierającą dane w obiekcie JavaScript, które można przekazać bezpośrednio do konstruktora DataTable w celu jej wypełnienia. Jest to najczęstszy typ żądania i najważniejsza z prawidłowej implementacji.
  • CSV – zwraca prostą listę wartości rozdzielonych przecinkami, którą obsługuje przeglądarka.
  • TSV – zwraca listę wartości rozdzielonych tabulatorami, która jest obsługiwana przez przeglądarkę.
  • HTML – zwraca tabelę HTML do renderowania przez przeglądarkę.

Aby wygenerować te formaty wyjściowe, możesz użyć biblioteki źródeł danych wizualizacji Google (w języku Java) lub biblioteki do wizualizacji w Pythonie.

Format odpowiedzi JSON

Domyślny format odpowiedzi to JSON, jeśli żądanie zawiera nagłówek „X-DataSource-Auth”, lub JSONP. Pamiętaj, że klient wykresów Google obsługuje zmodyfikowaną wersję JSON i JSONP. Jeśli używasz bibliotek pomocniczych Java lub Python, utworzy on odpowiedni kod. Jeśli analizujesz odpowiedzi ręcznie, zapoznaj się z sekcją Modyfikacje JSON poniżej.

Jeśli egzekwujesz żądania dotyczące tej samej domeny, sprawdź, czy w żądaniu znajduje się nagłówek „X-DataSource-Auth”, i użyj plików cookie autoryzacyjnych.

Jest to jedyny format odpowiedzi określony przez metodę Google Wizualizacja API google.visualization.Query.send() . Przykładowe żądania i odpowiedzi JSON znajdziesz na końcu tej strony w Przykłady. Aby utworzyć ten ciąg znaków odpowiedzi, możesz użyć bibliotek pomocniczych Java lub Pythona.

Ten format odpowiedzi to obiekt JSON zakodowany w UTF-8 (obiekt opakowany w nawiasy klamrowe { }, z których każdą właściwością oddzieloną przecinkami), który zawiera właściwości z tabeli poniżej (dane są przypisane do właściwości table). Ten obiekt JSON należy umieścić wewnątrz wartości parametru responseHandler z żądania. Jeśli więc żądanie responseHandler zawierało wartość „myHandler”, powinien zostać zwrócony ciąg znaków w takiej postaci (pokazana jest tylko 1 właściwość dla zachowania zwięzłości):

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

Jeśli żądanie nie zawierało wartości responseHandler, domyślną wartością jest „google.visualization.Query.setResponse”, dlatego należy zwrócić ciąg znaków podobny do tego (pokazana jest tylko jedna właściwość dla zachowania zwięzłości):

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

Oto dostępne składowe obiektu odpowiedzi:

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

Liczba ciągu znaków będąca numerem wersji protokołu przewodu Google Wizualizacja. Jeśli go nie podasz, klient przyjmie najnowszą wersję.

Przykład: version=0.6

reqId
Tak*
Liczba ciągu znaków wskazujący identyfikator tego żądania dla tego klienta. Jeśli to żądanie było zawarte w żądaniu, zwróć tę samą wartość. Więcej informacji znajdziesz w opisie reqId w sekcji prośby.

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

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

  • ok – Żądanie zakończone pomyślnie. We właściwości table musi być uwzględniona tabela.
  • warning – sukces, ale wystąpiły problemy. We właściwości table musi być uwzględniona tabela.
  • error – wystąpił problem. Jeśli zwracasz ten zwrot, nie zwracaj wartości table, a musisz zwrócić wartość errors.

Przykład: status:'warning'

ostrzeżenia
Tylko jeśli status=warning

Tablica z 1 lub większą liczbą obiektów, z których każdy opisuje problem niekrytyczny. Wymagany, jeśli status=warning. W innym przypadku niedozwolone. Każdy obiekt ma te właściwości ciągu znaków (zwraca tylko 1 wartość na każdą właściwość):

  • reason – [wymagany] – jednowyrazowy opis ostrzeżenia. Protokół definiuje poniższe wartości, ale w razie potrzeby możesz zdefiniować własne wartości (jednak klient nie będzie przetwarzać wartości niestandardowych w żaden specjalny sposób). Możesz mieć tylko jedną wartość reason:
    • data_truncated – w zwracanym obiekcie DataTable zostały usunięte niektóre wiersze, ponieważ użytkownik uwzględnił ciąg zapytania, który skrócił listę wyników, lub źródło danych z jakiegoś powodu nie chciało zwracać pełnych wyników.
    • other – ogólne, nieokreślone ostrzeżenie.
  • message – [opcjonalny] cytowany tekst wyjaśniający problem, który może być używany jako tytuł pola alertu. Ta informacja może być widoczna dla użytkownika. HTML nie jest obsługiwany.
  • detailed_message – [opcjonalny] szczegółowy komunikat w cudzysłowie objaśniający problem i możliwe rozwiązania. Jedynym obsługiwanym kodem HTML jest element <a> z pojedynczym atrybutem href. Obsługuje kodowanie Unicode. Ta informacja może być wyświetlana użytkownikowi.

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

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

Tablica z jednym lub większą liczbą obiektów, z których każdy opisuje błąd. Wymagany, jeśli status=error. W innym przypadku nie jest dozwolone. Jest ona podobna do wartości warnings. Pamiętaj, że błąd not_modified jest błędem, ale nie jest błędem po stronie klienta.

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

  • reason – [wymagany] – taki sam jak warnings.reason, ale dodatkowo zdefiniowane są te wartości:
    • not_modified – dane nie zmieniły się od czasu ostatniego żądania. Jeśli to jest przyczyną błędu, pole table powinno nie zawierać wartości.
    • user_not_authenticated – jeśli źródło danych wymaga uwierzytelnienia, które nie zostało przeprowadzone, 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] – tak samo jak warnings.message. Uwaga: szkodliwy użytkownik może wykorzystać szczegółowy ciąg danych, by uzyskać dostęp do nieautoryzowanych danych. Może nawet wykorzystać go do ataku na Twoje dane lub witrynę. Jeśli przechowujesz dane, które powinny być bezpieczne, lub przetwarzasz zapytania użytkowników bezpośrednio, rozważ niezwracanie szczegółowego komunikatu o błędzie, który może dostarczyć informacji osobie przeprowadzającej atak. Zamiast tego wyświetlaj ogólny komunikat, na przykład „Nieprawidłowy ciąg zapytania”.
  • detailed_message – [opcjonalny] – tak samo jak warnings.detailed_message. Wyświetl ostrzeżenie, aby uzyskać zbyt szczegółowe informacje dotyczące właściwości 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 szyfrowania. Jeśli obsługujesz tę właściwość, w przypadku braku danych musisz zwrócić wartość przekazaną przez klienta lub w przypadku zwrócenia nowych danych nowy hasz.

Przykład: sig:'5982206968295329967'

stół
Nie

Obiekt DataTable z Twoimi danymi w notacji literału JavaScript. Szczegółowe informacje o formacie tego obiektu znajdziesz w powiązanej sekcji referencyjnej. 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 być obecna tylko wtedy, gdy status=ok lub status=warning. Jeśli nie zwracasz danych, nie uwzględniaj tej właściwości (tzn. nie przekazuj jej z pustą wartością ciągu znaków).

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

 

Wymagany jest rygorystyczny format JSON

Biblioteki pomocnicze Google i wszystkie zapytania wysyłane do Google zwracają rygorystyczny format JSON/JSONP. Jeśli nie analizujesz zwróconego kodu samodzielnie, nie powinno to mieć dla Ciebie znaczenia. Jeśli tak, możesz użyć funkcji JSON.parse(), aby przekonwertować ciąg znaków JSON na obiekt JavaScript. Jedna z różnic w sposobie przetwarzania danych JSON przez interfejs API polega na tym, że chociaż JSON nie obsługuje wartości dat w JavaScripcie (np. „new Date(2008,1,28,0,31,26)”; interfejs API obsługuje prawidłową reprezentację dat w formacie JSON jako ciąg znaków w tym formacie: Date(year, month, day[,hour, minute, second[, millisecond]]),gdzie wszystko po dniu jest opcjonalne, a miesiące są liczone od zera.

 

Optymalizowanie odpowiedzi JSON

Jeśli klient wysyła 2 żądania, a dane nie zmieniają się między kolejnymi żądaniami, warto nie wysyłać danych ponownie, ponieważ spowodowałoby to stratę przepustowości. Aby zwiększyć efektywność żądań, protokół obsługuje buforowanie danych po stronie klienta i wysyłanie sygnału w odpowiedzi, 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 hasz obiektu DataTable i zwraca w odpowiedzi obie te wartości (hasz jest zwracany w parametrze tqx.sig). Klient interfejsu GoogleVisual API zapisuje w pamięci podręcznej wartości DataTable i sig.
  3. Klient wysyła kolejne żądanie danych, w tym wartości tqx.sig zapisanej w pamięci podręcznej.
  4. Źródło danych może odpowiadać na 2 sposoby:
    • Jeśli dane uległy zmianie w porównaniu z poprzednim żądaniem, źródło danych odeśle nowy hasz wartości DataTable i nową wartość sig.
    • Jeśli dane nie zmieniły się w porównaniu z poprzednim żądaniem, źródło danych odeśle status=error, reason=not_modified i sig=old_sig_value.
  5. W obu przypadkach strona, na której jest przechowywany wykres, otrzyma pomyślną odpowiedź i będzie mogła pobrać DataTable, wywołując funkcję QueryResponse.getDataTable(). Jeśli dane są takie same, jest to tylko wersja tabeli zapisana w pamięci podręcznej.

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

Format odpowiedzi CSV

Jeśli żądanie zawiera właściwość out:csv, odpowiedź nie zawiera metadanych, a jedynie plik CSV. Tabela CSV ma zazwyczaj postać listy rozdzielanej przecinkami, w której każdy wiersz danych to rozdzielana przecinkami lista wartości zakończona znakiem nowego wiersza systemu UNIX (\n). Wartości komórek powinny mieć ten sam typ dla każdej kolumny. Pierwszy wiersz to etykiety kolumn. Oto przykład tabeli z 3 wierszami i 3 kolumnami:

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

Ten protokół nie określa formatu CSV. Za zdefiniowanie jego formatu odpowiada źródło danych. Popularnym formatem jest jednak zbiór wartości rozdzielonych przecinkami (bez spacji między nimi) i znakiem nowego wiersza (\n) na końcu każdego wiersza. Gdy przeglądarka otrzyma odpowiedź w postaci ciągu CSV, może zapytać użytkownika, jakiej aplikacji użyć do otwarcia ciągu znaków, lub może po prostu wyświetlić ją na ekranie. Biblioteki open source Java i Pythona zapewniają metodę konwersji tabeli DataTable na ciąg znaków w formacie CSV.

Jeśli żądanie zawiera element outFileName parametru tqx , spróbuj umieścić w nagłówkach odpowiedzi podaną nazwę pliku.

Obiekt google.visualization.Query nie obsługuje żądania odpowiedzi w formacie CSV. Jeśli klient chce wysłać żądanie pliku CSV, możesz umieścić na swojej stronie gadżet paska narzędzi wizualizacji, użyć niestandardowego kodu do utworzenia żądania lub podać link jednoznacznie ustawiający właściwość out:csv tqx, 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 zawiera właściwość out:tsv-excel, odpowiedź nie zawiera metadanych, a tylko rozdzielaną tabulatorami reprezentację danych zakodowaną w formacie utf-16. Jeśli żądanie zawiera element outFileName parametru tqx , spróbuj umieścić w nagłówkach odpowiedzi podaną nazwę pliku.

Format odpowiedzi HTML

Jeśli żądanie określa out:html, odpowiedzią powinna być strona HTML definiująca tabelę HTML z danymi. Przydaje się to podczas debugowania kodu, ponieważ przeglądarka może bezpośrednio renderować wynik w czytelnym formacie. Nie możesz wysłać zapytania o odpowiedź HTML za pomocą obiektu google.visualization.Query. Musisz utworzyć zapytanie dla odpowiedzi HTML, korzystając z niestandardowego kodu lub wpisując w przeglądarce 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 próśb i odpowiedzi. Pamiętaj, że w żądaniach nie zastosowano zmiany znaczenia w adresie URL. Zazwyczaj robi to przeglądarka lub obiekt google.visualization.Query.

Proste żądanie: zwraca podstawowe informacje za pomocą tabeli w trzech i czterech wierszach.

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 dotyczące jednej kolumny zwraca pojedynczą 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: nie zmodyfikowano 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 obcięciu 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 zapytania. Pamiętaj, że szczegółowy komunikat ma charakter ogólny, a nie rzeczywisty.

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 danych Java (od Google) – obsługuje żądania i odpowiedzi, tworzy tabelę odpowiedzi na podstawie przekazanych przez Ciebie danych i implementuje język zapytań SQL narzędzi Google Chart.
  • Biblioteka źródeł danych w Pythonie (od Google) – tworzy tabelę odpowiedzi, która generuje składnię odpowiedzi. Nie obsługuje analizowania żądania ani implementacji języka zapytań SQL w narzędziach Google Charters.
  • MC-Google_Visualization (firma zewnętrzna) – to biblioteka PHP po stronie serwera, której możesz użyć do wdrożenia silników baz danych Chart Tools dla MySQL, SQLite i PostgreSQL za pomocą PDO.
  • bortosky-google-visualization (usługa innej firmy) – to biblioteka pomocnicza do tworzenia tabeli danych interfejsu Google wizualizacji API dla użytkowników .NET.
  • 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. Streamer GV obsługuje kilka języków (np. PHP, Java, .NET) i kilka nieprzetworzonych źródeł danych (np. MySql).
  • TracGViz (firma zewnętrzna) – TracGViz to bezpłatne narzędzie typu open source, które udostępnia komponenty, dzięki którym Trac może korzystać z gadżetów wykresów, a także implementuje dane zarządzane przez Trac jako źródło danych narzędzi do wykresów Google.
  • vis-table (firma zewnętrzna) – biblioteka implementująca źródło danych narzędzi wykresów Google w języku PHP. Składa się z 3 głównych części. Sama implementacja tabeli danych, parser języka zapytań i narzędzia do formatowania.
  • Implementacja źródła danych Google w Oracle PL/SQL (innej firmy) – pakiet Oracle PL/SQL, który umożliwia Oracle serwerowanie źródeł danych bezpośrednio z bazy danych. Zasadniczo możesz użyć dowolnego zapytania Oracle jako źródła danych w narzędziach wykresów Google (pakiet zwróci plik JSON z danymi). Oferuje niemal pełną obsługę języka Google Query Language.