Chart Tools Datasource Protocol (V0.6) implementieren

Auf dieser Seite wird beschrieben, wie Sie einen Dienst implementieren, der das Datasource-Protokoll „Chart Tools“ unterstützt, um Daten mithilfe der Abfrageklasse in Diagrammen darzustellen.

Inhalt

  1. Zielgruppe
  2. Overview
  3. Sicherheitsaspekte
  4. Anfrageformat
  5. Antwortformat
    1. JSON-Antwortformat
    2. CSV-Antwortformat
    3. HTML-Antwortformat
  6. Beispiele
  7. Entwicklertools

Zielgruppe

Diese Seite ist in erster Linie für Entwickler gedacht, die eine eigene Datenquelle ohne die Datenquellenbibliothek für Diagrammtools erstellen. Wenn Sie diese oder eine andere Hilfsbibliothek verwenden, lesen Sie zuerst die Dokumentation Ihrer Bibliothek.

Diese Seite richtet sich auch an Leser, die sich für das Wire-Protokoll interessieren, das für die Kommunikation zwischen einer Clientvisualisierung und einer Datenquelle verwendet wird.

Wenn Sie eine Visualisierung erstellen oder verwenden, müssen Sie diese Seite nicht lesen.

Für das Lesen dieses Dokuments sollten Sie mit der grundlegenden JSON- und HTTP-Anfragesyntax vertraut sein. Außerdem sollten Sie verstehen, wie Diagramme aus der Perspektive der Nutzenden funktionieren.

Hinweis:Google befürwortet oder unterstützt keine externen Datenquellen, die das Chart Tools-Datenquellenprotokoll unterstützen.

Übersicht

Sie können das Datenquellenprotokoll von Chart Tools implementieren, um ein Datenquellenanbieter für Ihre eigenen Diagramme oder andere Diagramme zu werden. Eine Datenquelle für Diagrammtools enthält eine URL, die sogenannte Datenquellen-URL, an die ein Diagramm HTTP-GET-Anfragen senden kann. Die Datenquelle gibt daraufhin ordnungsgemäß formatierte Daten zurück, die im Diagramm zum Rendern der Grafik auf der Seite verwendet werden können. Dieses Anfrage-/Antwort-Protokoll wird als Wire-Protokoll der Google Visualization API bezeichnet.

Die von einer Datenquelle bereitgestellten Daten können aus verschiedenen Ressourcen wie einer Datei oder Datenbank extrahiert werden. Die einzige Einschränkung besteht darin, dass Sie die Daten als zweidimensionale Tabelle mit typisierten Spalten formatieren können.

Als Chart Tools-Datenquelle müssen Sie eine Anfrage in einem bestimmten Format parsen und eine Antwort in einem bestimmten Format zurückgeben. Dazu haben Sie im Allgemeinen zwei Möglichkeiten:

  • Verwenden Sie eine der folgenden Hilfsbibliotheken, um die Anfrage und die Antwort zu verarbeiten, und erstellen Sie die DataTable, die zurückgegeben werden soll. Wenn Sie eine dieser Bibliotheken verwenden, müssen Sie nur den Code schreiben, der erforderlich ist, um Ihre Daten der Bibliothek in Form einer Tabelle zur Verfügung zu stellen.
    • Java-Datenquellenbibliothek: verarbeitet die Anfrage und die Antwort, erstellt die Antworttabelle aus den von Ihnen bereitgestellten Daten und implementiert die SQL-Abfragesprache Google Chart Tools.
    • Python-Datenquellenbibliothek: Erstellt eine Antworttabelle und generiert die Antwortsyntax. Übernimmt nicht das Parsen der Anfrage oder Implementieren der SQL-Abfragesprache von Google Chart Tools.

      ODER

  • Schreiben Sie eine neue Datenquelle, indem Sie die Anfrage verarbeiten, eine DataTable erstellen und die Antwort senden.

So gehts:

  1. Die Datenquelle enthält eine URL, die als Datenquellen-URL bezeichnet wird und an die Diagramme eine HTTP-GET-Anfrage senden.
  2. Der Client stellt eine HTTP-GET-Anfrage mit Parametern, die das Format für zurückgegebene Daten angeben, einem optionalen Abfragestring und optionalen benutzerdefinierten Parametern.
  3. Die Datenquelle empfängt und parst die Anfrage, wie unter Anfrageformat beschrieben.
  4. Die Datenquelle bereitet die Daten im angeforderten Format vor. In der Regel ist dies eine JSON-Tabelle. Antwortformate werden im Abschnitt Antwortformat behandelt. Die Datenquelle kann optional die Abfragesprache der Visualization API unterstützen, mit der Filter, Sortierung und andere Datenmanipulationen festgelegt werden.
  5. Die Datenquelle erstellt eine HTTP-Antwort, die die serialisierten Daten und andere Antwortparameter enthält, und sendet sie wie unter Antwortformat beschrieben an den Client zurück

Hinweis: Alle in diesem Dokument aufgeführten Parameter und Stringkonstantenwerte für Anfragen und Antworten (z. B. responseHandler und "ok") werden kleingeschrieben und es wird zwischen Groß- und Kleinschreibung unterschieden.

Mindestvoraussetzungen für dich

Dies sind die Mindestanforderungen für die Verwendung als Datenquelle für Diagrammtools:

  • Die Datenquelle sollte HTTP-GET-Anfragen akzeptieren und für Ihre Clients verfügbar sein.
  • Das Protokoll kann sich ändern und unterstützt ein Versionsschema (die aktuelle Version ist 0.6). Ihre Datenquelle sollte daher Anfragen mit früheren und der aktuellen Version unterstützen. Sie sollten versuchen, neue Versionen unmittelbar nach ihrer Veröffentlichung zu unterstützen, um zu verhindern, dass Clients, die schnell auf die neueste Version aktualisieren, Probleme auftreten.
  • Schlagen Sie nicht fehl, wenn im Rahmen der Anfrage unbekannte Eigenschaften gesendet werden. Das liegt daran, dass mit neuen Versionen neue Attribute eingeführt werden können, die Sie nicht kennen.
  • Parse nur Properties, die du erwartet hast. Auch wenn neue Versionen möglicherweise neue Attribute enthalten, sollten Sie nicht unbeabsichtigt den gesamten Anfragestring akzeptieren und verwenden. Zum Schutz vor schädlichen Angriffen sollten Sie nur die erwarteten Attribute parsen und verwenden.
  • Dokumentieren Sie die Anforderungen an die Datenquelle sorgfältig, wenn Sie die Clientdiagramme nicht selbst programmieren. Dazu gehören folgende Informationen:
    • Alle benutzerdefinierten Parameter, die Sie akzeptieren,
    • Ob Sie die Abfragesprache der Google Visualization API parsen können
    • Welche Art von Daten zurückgegeben werden und wie diese Daten strukturiert sind (was die Zeilen und Spalten darstellen und welche Labels vorhanden sind)
  • Ergreifen Sie alle standardmäßigen Sicherheitsmaßnahmen für eine Website, die Anfragen von unbekannten Clients akzeptiert. Sie können in Ihren Parametern MD5, Hashing und andere Sicherheitsmechanismen angemessen unterstützen, um Anfragen zu authentifizieren oder sich vor schädlichen Angriffen zu schützen. Sie erwarten, dass die Clients Ihre Anforderungen kennen und darauf reagieren. Wenn Sie die Diagramme nicht selbst programmieren, sollten Sie jedoch unbedingt alle Ihre Anforderungen gut dokumentieren. Weitere Informationen finden Sie unter Sicherheitsaspekte weiter unten.
  • Alle Anfrage- und Antwortstrings sollten UTF-8-codiert sein.
  • Das wichtigste Antwortformat ist JSON. Achten Sie darauf, zuerst JSON zu implementieren, da dieses Format von den meisten Diagrammen verwendet wird. Fügen Sie anschließend weitere Antworttypen hinzu.
  • Sie müssen die Abfragesprache der Visualization API nicht erforderlich unterstützen, aber dadurch wird Ihre Datenquelle für Kunden nützlicher.
  • Es ist nicht erforderlich, Anfragen von allen Diagrammtypen zu unterstützen. Benutzerdefinierte Parameter können auch für benutzerdefinierte Diagramme unterstützt werden. Die Antworten sollten jedoch im unten beschriebenen Standardformat zurückgegeben werden.

Sicherheitsaspekte

Beim Entwerfen Ihrer Datenquelle müssen Sie berücksichtigen, wie sicher Ihre Daten sein müssen. Du kannst für deine Website verschiedene Sicherheitsschemas verwenden, vom einfachen Passwortzugriff bis hin zur sicheren Cookie-Authentifizierung.

XSSI-Angriffe (Cross-Site Script Inclusion) stellen ein Risiko bei Diagrammen dar. Ein Nutzer ruft möglicherweise eine Seite mit einem schädlichen Script auf, das dann versucht, mithilfe der Anmeldedaten des aktuellen Nutzers Abfragen an Datenquellen-URLs zu senden. Wenn sich der Nutzer nicht von einer Website abgemeldet hat, wird das Skript als aktueller Nutzer authentifiziert und hat Berechtigungen für diese Website. Mit einem <script src>-Tag kann das schädliche Skript die Datenquelle einschließen, ähnlich wie bei JSONP.

Als zusätzliche Sicherheitsstufe können Sie Anfragen auf solche beschränken, die von derselben Domain wie Ihre Datenquelle stammen. Dadurch wird die Sichtbarkeit Ihrer Datenquelle erheblich eingeschränkt. Wenn Sie jedoch sehr sensible Daten haben, auf die von außerhalb Ihrer Domain nicht zugegriffen werden sollte, sollten Sie dies in Betracht ziehen. Eine Datenquelle, für die nur Anfragen aus derselben Domain zulässig sind, wird als eingeschränkte Datenquelle bezeichnet – im Gegensatz zu einer uneingeschränkten Datenquelle, die Abfragen aus beliebigen Domains akzeptiert. Hier sind einige Details dazu, wie Sie eine eingeschränkte Datenquelle implementieren:

So stellen Sie sicher, dass eine Anfrage wirklich von innerhalb Ihrer Domain kommt und nicht von einer externen Domain (oder einem Browser innerhalb der Domain, die einem XSRF-Angriff unterzogen wird):

  • Prüfen Sie, ob der Header „X-DataSource-Auth“ in der Anfrage vorhanden ist. Dieser Header wird von der Google Visualization API definiert. Sie müssen den Inhalt des Headers nicht untersuchen, sondern nur prüfen, ob er vorhanden ist. Wenn Sie die Datenquellenbibliothek von Google Chart Tools verwenden, kann die Bibliothek dies für Sie übernehmen.
  • Verwenden Sie die Cookie-Authentifizierung, um den Client zu authentifizieren. Es gibt keine bekannte Möglichkeit, benutzerdefinierte Header in eine domainübergreifende Anfrage einzufügen und gleichzeitig Authentifizierungscookies beizubehalten.
  • Legen Sie fest, dass der JavaScript-Code wahrscheinlich nicht ausgeführt wird, wenn er in einem <script src> -Tag eingefügt ist. Stellen Sie dazu der JSON-Antwort )]}' voran, gefolgt von einem Zeilenumbruch. Entfernen Sie in Ihrem Client das Präfix aus der Antwort. Bei XmlHttpRequest ist dies nur möglich, wenn die Anfrage von derselben Domain stammt.

Anfrageformat

Ein Client sendet eine HTTP-GET-Anfrage mit mehreren Parametern, darunter benutzerdefinierte Elemente, ein optionaler Abfragestring, eine Signatur und andere Elemente. Sie sind nur für das Parsen der in diesem Abschnitt beschriebenen Parameter verantwortlich. Achten Sie darauf, nicht mit anderen zu umgehen, um bösartige Angriffe zu vermeiden.

Achten Sie darauf, Standardwerte für optionale Parameter (sowohl Standard- als auch benutzerdefinierte Parameter) festzulegen, und dokumentieren Sie alle Standardeinstellungen in Ihrer Websitedokumentation.

Hier einige Beispielanfragen. Weitere Anfrage- und Antwortbeispiele finden Sie am Ende dieses Dokuments in den Beispielen:

Hinweis: Die folgenden Anfragestrings sowie die im Abschnitt Beispiele aufgeführten Anfragestrings sollten vor dem Senden mit einer URL-Escapesequenz versehen werden.

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

Im Folgenden finden Sie eine Liste aller Standardparameter im Anfragestring. Bei beiden Parameternamen (z. B. „version“) und konstanten Stringwerten (z. B. „ok“, „warning“ und „not_modified“) wird zwischen Groß- und Kleinschreibung unterschieden. In der Tabelle wird auch beschrieben, ob der Parameter gesendet werden muss und ob Sie ihn, falls gesendet, verarbeiten müssen.

Parameter
In Anfrage erforderlich?
Muss die Datenquelle verarbeitet werden?
 Beschreibung
TQ
Nein
Nein

Eine in der Abfragesprache der Google Visualization API geschriebene Abfrage, die angibt, wie die zurückgegebenen Daten gefiltert, sortiert oder anderweitig bearbeitet werden. Der String muss nicht in Anführungszeichen gesetzt werden.

Beispiel: http://www.example.com/mydatasource?tq=select Col1
TQX
Nein
Ja

Eine Reihe von durch Doppelpunkten getrennten Schlüssel/Wert-Paaren für Standard- oder benutzerdefinierte Parameter. Paare werden durch Semikolons getrennt. Hier ist eine Liste der Standardparameter, die vom Visualisierungsprotokoll definiert werden:

  • reqId – [Erforderlich in Anfrage; Datenquelle muss verarbeiten] Eine numerische Kennung für diese Anfrage. So kann die Datenquelle die Antwort mit der richtigen Anfrage identifizieren, wenn ein Client vor dem Empfang einer Antwort mehrere Anfragen sendet. Senden Sie diesen Wert in der Antwort zurück.
  • version – [Optional in Anfrage; Datenquelle muss verarbeitet] Die Versionsnummer des Google-Visualisierungsprotokolls. Die aktuelle Version ist 0.6. Wenn nicht gesendet, nehmen Sie die neueste Version an.
  • sig – [Optional in der Anfrage; optional für die Verarbeitung der Datenquelle] Ein Hash der DataTable, die in früheren Anfragen an diese Datenquelle an diesen Client gesendet wurde. Dadurch soll verhindert werden, dass identische Daten zweimal an einen Client gesendet werden. Informationen zur Verwendung finden Sie unten im Abschnitt Anfrage optimieren.
  • out: [Optional in Anfrage; Datenquelle muss verarbeitet werden] Ein String, der das Format der zurückgegebenen Daten beschreibt. Folgende Werte sind möglich:
    • json – [Standardwert] Ein JSON-Antwortstring (wie unten beschrieben).
    • html: Eine einfache HTML-Tabelle mit Zeilen und Spalten. Bei Verwendung dieser Methode muss einzig eine HTML-Tabelle mit den Daten zurückgegeben werden. Dies ist nützlich für die Fehlerbehebung, wie im Abschnitt Antwortformat unten beschrieben.
    • csv – Kommagetrennte Werte. Wird sie verwendet, wird einzige ein CSV-Datenstring zurückgegeben. Sie können in den Antwortheadern einen benutzerdefinierten Namen für die Datei anfordern, indem Sie einen outFileName-Parameter angeben.
    • tsv-excel: Ähnlich wie csv, verwendet aber Tabulatoren anstelle von Kommas und alle Daten sind utf-16-codiert.
    Hinweis: Der einzige Datentyp, den ein Diagramm auf der Google Visualization API anfordert, ist JSON. Weitere Informationen zu den einzelnen Typen finden Sie unten im Abschnitt Antwortformat.
  • responseHandler: [Optional in Anfrage; Datenquelle muss verarbeitet werden] Der Stringname der JavaScript-Verarbeitungsfunktion auf der Clientseite, die mit der Antwort aufgerufen wird. Wenn er nicht in der Anfrage enthalten ist, lautet der Wert „google.visualization.Query.setResponse“. Dieser wird als Teil der Antwort zurückgesendet. Weitere Informationen finden Sie unten unter Antwortformat.
  • outFileName: [Optional in der Anfrage; optional für die zu verarbeitende Datenquelle] Wenn Sie out:csv oder out:tsv-excel angeben, können Sie optional den hier angegebenen Dateinamen anfordern. Beispiel: outFileName=results.csv.

Beispiel: tqx=version:0.6;reqId:1;sig:5277771;out:json; responseHandler:myQueryHandler
TTRT
Nein
Nein

Reserviert: Diesen Parameter ignorieren. Die Methode, die zum Senden der Abfrage verwendet wurde.

Antwortformat

Das Format der Antwort hängt vom out-Parameter der Anfrage ab, der den erwarteten Antworttyp angibt. In den folgenden Abschnitten erfahren Sie, wie Sie auf die einzelnen Anfragetypen antworten:

  • JSON: Gibt eine JSON-Antwort zurück, die die Daten in einem JavaScript-Objekt enthält, das direkt an einen DataTable-Konstruktor übergeben werden kann, um das Objekt zu füllen. Dieser Anfragetyp ist bei Weitem der gängigste Anfragetyp und die korrekte Implementierung am wichtigsten.
  • CSV: gibt eine einfache, durch Kommas getrennte Werteliste zurück, die vom Browser verarbeitet wird.
  • TSV: gibt eine tabulatorgetrennte Werteliste zurück, die vom Browser verarbeitet wird.
  • HTML: gibt eine HTML-Tabelle zurück, die vom Browser gerendert werden soll.

Sie können die Datenquellenbibliothek für Visualisierungen von Google (Java) oder die Python-Visualisierungsbibliothek verwenden, um diese Ausgabeformate für Sie zu generieren.

JSON-Antwortformat

Das Standardantwortformat ist JSON, wenn die Anfrage den Header „X-DataSource-Auth“ enthält. Andernfalls ist JSONP das Format. Beachten Sie, dass der Google-Diagrammclient tatsächlich eine modifizierte Version von JSON und JSONP unterstützt. Wenn Sie die Hilfsbibliotheken von Java oder Python verwenden, wird der richtige Code dafür ausgegeben. Wenn Sie Antworten manuell parsen, lesen Sie weiter unten den Abschnitt JSON-Änderungen.

Wenn Sie Anfragen für dieselbe Domain erzwingen, sollten Sie das Vorhandensein des Headers „X-DataSource-Auth“ in der Anfrage prüfen und Autorisierungs-Cookies verwenden.

Dies ist das einzige Antwortformat, das durch die Methode google.visualization.Query.send() der Google Visualization API angegeben wird. Unter Beispiele finden Sie am Ende dieser Seite einige Beispiele für JSON-Anfragen und -Antworten. Sie können die Hilfsbibliotheken von Java oder Python verwenden, um diesen Antwortstring für Sie zu erstellen.

Dieses Antwortformat ist ein UTF-8-codiertes JSON-Objekt (ein von geschweiftes { } umschlossenes Objekt, wobei jedes Attribut durch ein Komma getrennt ist), das die Attribute in der folgenden Tabelle enthält (die Daten werden dem Attribut table zugewiesen). Dieses JSON-Objekt sollte in den Parameterwert responseHandler aus der Anfrage eingeschlossen sein. Wenn also der responseHandler-Wert der Anfrage "myHandler" lautet, sollten Sie einen String wie diesen zurückgeben (nur eine Property wird der Kürze halber angezeigt):

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

Wenn die Anfrage keinen responseHandler-Wert enthielt, ist der Standardwert "google.visualization.Query.setResponse". Sie sollten also einen String wie den folgenden zurückgeben (nur eine Property wird der Kürze halber angezeigt):

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

Dies sind die verfügbaren Antwortobjektmitglieder:

Attribut
Erforderlich?
 Beschreibung
Version
Nein

Eine Stringnummer, die die Versionsnummer des Protokolls des Google Visualization-Drahts angibt. Wenn keine Angabe erfolgt, verwendet der Client die neueste Version.

Beispiel: version=0.6
reqId
Ja*
 Eine Stringnummer, die die ID dieser Anfrage für diesen Client angibt. Wenn dies in der Anfrage enthalten war, geben Sie denselben Wert zurück. Weitere Informationen finden Sie in der reqId-Beschreibung im Anfrageabschnitt.

* Wenn dieser Parameter in der Anfrage nicht angegeben wurde, müssen Sie ihn nicht in der Antwort festlegen.
Status
Ja

Ein String, der den Erfolg oder Misserfolg dieses Vorgangs beschreibt. Darf nur einer der folgenden Werte sein:

  • ok – Erfolgreiche Anfrage. Das Attribut table muss eine Tabelle enthalten.
  • warning – Erfolgreich, aber mit Problemen. Das Attribut table muss eine Tabelle enthalten.
  • error - Ein Problem ist aufgetreten. Wenn Sie diesen Wert zurückgeben, sollten Sie nicht table zurückgeben, sondern müssen errors zurückgeben.

Beispiel: status:'warning'
Warnungen
Nur wenn status=warning

Ein Array mit einem oder mehreren -Objekten, die jeweils ein nicht schwerwiegendes Problem beschreiben. Erforderlich, wenn status=warning, sonst nicht zulässig. Jedes Objekt hat die folgenden String-Properties (für jedes Attribut wird nur ein Wert zurückgegeben):

  • reason - [Erforderlich] Eine aus einem Wort bestehende Stringbeschreibung der Warnung. Das Protokoll definiert die folgenden Werte, aber Sie können bei Bedarf auch eigene Werte definieren (der Client verarbeitet benutzerdefinierte Werte jedoch nicht auf spezielle Weise). Sie dürfen nur einen reason-Wert haben:
    • data_truncated: Beim zurückgegebenen DataTable wurden einige Zeilen entfernt, entweder weil der Nutzer einen Abfragestring eingefügt hat, durch den die Ergebnisliste gekürzt wurde, oder die Datenquelle wollte aus irgendeinem Grund keine vollständigen Ergebnisse zurückgeben.
    • other: Eine allgemeine nicht spezifizierte Warnung.
  • message: [optional] Ein kurzer String in Anführungszeichen zur Erläuterung des Problems, möglicherweise als Titel für ein Benachrichtigungsfeld verwendet. Dies kann dem Nutzer angezeigt werden. HTML wird nicht unterstützt.
  • detailed_message: [optional] Eine detaillierte Stringnachricht in Anführungszeichen, in der das Problem und mögliche Lösungen erläutert werden. Als einziger HTML-Code wird das <a>-Element mit einem einzelnen href-Attribut unterstützt. Unicode-Codierung wird unterstützt. Dies kann dem Nutzer angezeigt werden.

Beispiel: warnings:[{reason:'data_truncated',message:'Retrieved data was truncated'}]
Fehler
Erforderlich, wenn status=error

Ein Array mit einem oder mehreren Objekten, die jeweils einen Fehler beschreiben. Erforderlich, wenn status=error, sonst nicht zulässig. Dies entspricht in etwa dem Wert warnings. Beachten Sie, dass der Fehler not_modified zwar ein Fehler, aber kein Fehler für den Client ist.

Das Array enthält die folgenden String-Mitglieder (für jedes Mitglied wird nur ein Wert zurückgegeben):

  • reason - [Erforderlich] Entspricht warnings.reason, es sind jedoch die folgenden Werte definiert:
    • not_modified: Die Daten haben sich seit der letzten Anfrage nicht geändert. Wenn dies der Grund für den Fehler ist, sollten Sie keinen Wert für table haben.
    • user_not_authenticated – Geben Sie diesen Wert an, wenn die Datenquelle eine Authentifizierung erfordert und dies nicht erfolgt ist. Der Client zeigt dann eine Benachrichtigung mit dem Wert von message an.
    • unknown_data_source_id
    • access_denied
    • unsupported_query_operation
    • invalid_query
    • invalid_request
    • internal_error
    • not_supported
    • illegal_formatting_patterns
    • other: Ein allgemeiner, nicht spezifizierter Fehler.
  • message - [Optional] Wie warnings.message. Hinweis: Es besteht die Möglichkeit, dass böswillige Nutzer einen detaillierten Datenstring verwenden, um nicht autorisierte Daten abzurufen oder damit Ihre Daten oder Ihre Website anzugreifen. Wenn Sie Daten speichern, die sicher sein sollten, oder Nutzerabfragen direkt verarbeiten, sollten Sie keine detaillierte Fehlermeldung zurückgeben, die Informationen für einen Angreifer liefern könnte. Geben Sie stattdessen eine allgemeine Meldung wie „Fehlerhafter Abfragestring“ ein.
  • detailed_message - [Optional] Wie warnings.detailed_message. In der Warnung finden Sie übermäßig detaillierte Informationen zu message.

Beispiel: status:'error',errors:[{reason:'not_modified',message:'Data not modified'}]
sig
Nein

Ein Hash-Wert des Tabellenobjekts. Nützlich zur Optimierung der Datenübertragung zwischen dem Client und der Datenquelle. Sie können einen beliebigen Hash-Algorithmus auswählen. Wenn Sie dieses Attribut unterstützen, sollten Sie den vom Client übergebenen Wert zurückgeben, wenn keine Daten zurückgegeben werden, oder einen neuen Hashwert, wenn neue Daten zurückgegeben werden.

Beispiel: sig:'5982206968295329967'
table
Nein

Ein DataTable-Objekt in JavaScript-Literalschreibweise mit Ihren Daten. Weitere Informationen zum Format dieses Objekts finden Sie im verlinkten Referenzabschnitt. Hier ist ein Beispiel für eine einfache Datentabelle:

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

Das Attribut table sollte nur vorhanden sein, wenn status=ok oder status=warning vorhanden ist. Wenn Sie keine Daten zurückgeben, lassen Sie dieses Attribut weg. Das Attribut darf also nicht mit einem leeren Stringwert zurückgegeben werden.

Beispiel:Siehe Beispiele unten.

 

Striktes JSON erforderlich

Die Hilfsbibliotheken von Google und alle an Google gesendeten Abfragen geben den strikten JSON-/JSONP-Wert zurück. Wenn Sie den zurückgegebenen Code nicht selbst parsen, spielt dies keine Rolle. Falls ja, können Sie den JSON-String mit JSON.parse() in ein JavaScript-Objekt konvertieren. Ein Unterschied bei der Verarbeitung von JSON-Daten durch die API besteht darin, dass JSON keine JavaScript-Datumswerte (z. B. „new Date(2008,1,28,0,31,26“)) unterstützt. Die API unterstützt jedoch eine gültige JSON-Darstellung von Datumsangaben als String im folgenden Format: Date(year, month, day[,hour, minute, second[, millisecond]]), wobei alles nach dem Tag optional ist und Monate nullbasiert sind.

 

JSON-Antworten optimieren

Wenn ein Client zwei Anfragen stellt und sich die Daten zwischen den Anfragen nicht geändert haben, ist es sinnvoll, die Daten nicht noch einmal zu senden. Dies würde Bandbreite verschwenden. Um Anfragen effizienter zu gestalten, unterstützt das Protokoll das Caching der Daten auf dem Client und das Senden eines Signals in der Antwort, wenn sich die Daten seit der letzten Anfrage nicht geändert haben. Dies funktioniert folgendermaßen:

  1. Der Client sendet eine Anfrage an die Datenquelle.
  2. Die Datenquelle generiert ein DataTable sowie einen Hash des DataTable-Objekts und gibt beides in der Antwort zurück (der Hash wird im tqx.-Parameter sig zurückgegeben). Der Client der Google Visualization API speichert die Werte DataTable und sig im Cache.
  3. Der Client sendet eine weitere Datenanfrage, einschließlich des im Cache gespeicherten Werts tqx.sig.
  4. Die Datenquelle kann auf zwei Arten antworten:
    • Wenn sich die Daten im Vergleich zur vorherigen Anfrage geändert haben, sendet die Datenquelle den neuen Wert-Hash DataTable und den neuen sig-Wert zurück.
    • Wenn die Daten gegenüber der vorherigen Anfrage nicht geändert wurden, sendet die Datenquelle status=error, reason=not_modified, sig=old_sig_value zurück.
  5. In beiden Fällen erhält die Seite, auf der das Diagramm gehostet wird, eine erfolgreiche Antwort und kann das DataTable durch Aufrufen von QueryResponse.getDataTable() abrufen. Bei identischen Daten handelt es sich lediglich um die im Cache gespeicherte Version der Tabelle.

Dies funktioniert nur für JSON-Anfragen von Diagrammen, die auf der Google Visualization API basieren.

CSV-Antwortformat

Wenn in der Anfrage out:csv angegeben ist, enthält die Antwort keine Metadaten, sondern einfach eine CSV-Darstellung der Daten. Eine CSV-Tabelle ist normalerweise eine durch Kommas getrennte Liste, wobei jede Datenzeile eine durch Kommas getrennte Liste von Werten ist und mit einem UNIX-Zeilenumbruchzeichen (\n) endet. Die Zellenwerte sollten für jede Spalte denselben Typ haben. Die erste Zeile enthält die Spaltenbeschriftungen. Hier ist ein Beispiel für eine dreizeilige, dreispaltige Tabelle:

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

Das CSV-Format wird durch dieses Protokoll nicht angegeben. Die Datenquelle ist für die Definition des CSV-Formats verantwortlich. Ein gängiges Format ist jedoch ein Satz von Werten, die durch Kommas (ohne Leerzeichen) getrennt sind, und ein Zeilenumbruch (\n) am Ende jeder Zeile. Wenn ein Browser eine Antwort auf einen CSV-String erhält, wird der Nutzer möglicherweise gefragt, mit welcher Anwendung der String geöffnet werden soll, oder er wird einfach auf dem Bildschirm dargestellt. Die Open-Source-Bibliotheken Java und Python bieten eine Methode zum Konvertieren einer DataTable in einen CSV-String.

Wenn die Anfrage ein outFileName-Mitglied des Parameters tqx enthält, sollten Sie versuchen, den angegebenen Dateinamen in den Antwortheadern aufzunehmen.

Das Objekt google.visualization.Query unterstützt keine Anfrage für eine CSV-Antwort. Wenn ein Kunde eine CSV-Datei anfordern möchte, können Sie ein Visualisierungssymbolleiste-Gadget auf Ihrer Seite einbetten. Der Kunde kann zum Erstellen der Anfrage benutzerdefinierten Code verwenden oder Sie können einen Link bereitstellen, der die out:csv-Eigenschaft von tqx explizit festlegt, wie in der folgenden Anfrage-URL gezeigt:

Anfrage

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

Antwort

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

TSV-Antwortformat

Wenn in der Anfrage out:tsv-excel angegeben ist, enthält die Antwort keine Metadaten, sondern einfach eine tabulatorgetrennte Darstellung der Daten, die utf-16-codiert ist. Wenn die Anfrage ein outFileName-Mitglied des Parameters tqx enthält, sollten Sie versuchen, den angegebenen Dateinamen in den Antwortheadern aufzunehmen.

HTML-Antwortformat

Wenn in der Anfrage out:html angegeben ist, sollte die Antwort eine HTML-Seite sein, auf der eine HTML-Tabelle mit den Daten definiert wird. Dies ist nützlich, um Fehler in Ihrem Code zu beheben, da der Browser das Ergebnis direkt in ein lesbares Format rendern kann. Sie können mit dem Objekt google.visualization.Query keine Abfrage für eine HTML-Antwort senden. Sie müssen eine HTML-Antwort mit benutzerdefiniertem Code abfragen oder in Ihrem Browser eine URL wie diese eingeben:

Anfrage

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

Antwort

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

Beispiele

Hier sind einige Beispiele für Anfragen und Antworten. Beachten Sie, dass Anfragen nicht mit URL-Escape-Zeichen versehen wurden. Dies wird normalerweise entweder vom Browser oder vom google.visualization.Query-Objekt ausgeführt.

Einfache Anfrage: Gibt die grundlegenden Informationen in einer Tabelle mit drei Spalten und vier Zeilen zurück.

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

Einfache Anfrage mit einem Antwort-Handler:Gibt eine Tabelle mit drei Spalten und drei Zeilen mit unterschiedlichen Datentypen zurück.

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

Abfrage mit einem einfachen Abfragestring: Bei der Anfrage für eine einzelne Spalte wird eine einzelne Spalte mit vier Zeilen zurückgegeben.

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

Fehler „Daten nicht geändert“:Beispiel für den Fehler 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'}]});

Warnung Daten abgeschnitten:Beispiel für eine data_truncated-Warnung. Beachten Sie, dass die Anfrage weiterhin Daten zurückgibt.

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

Fehler „Zugriff verweigert“: Beispiel für den Fehler 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'}]});

Ungültiger Abfragestring:Beispiel für eine Anfrage mit einem ungültigen Abfragestring. Bei der detaillierten Meldung handelt es sich um eine allgemeine Meldung und nicht um die eigentliche Fehlermeldung.

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

Entwicklungstools

  • Java-Datenquellenbibliothek (von Google) – verarbeitet die Anfrage und die Antwort, erstellt die Antworttabelle aus den von Ihnen bereitgestellten Daten und implementiert die SQL-Abfragesprache für Google Chart Tools.
  • Python-Datenquellenbibliothek (von Google): Erstellt eine Antworttabelle und generiert die Antwortsyntax. Übernimmt weder das Parsen der Anfrage noch die Implementierung der SQL-Abfragesprache für Google Chart Tools.
  • MC-Google_Visualization (Drittanbieter): Dies ist eine serverseitige PHP-Bibliothek, mit der Sie mithilfe von PDO eine Chart Tools-Datenquelle für MySQL-, SQLite- und PostgreSQL-Datenbankmodule implementieren können.
  • bortosky-google-visualization (Drittanbieter): Dies ist eine Hilfsbibliothek zum Erstellen einer Datentabelle für die Google Visualization API für .NET-Nutzer.
  • GV Streamer (Drittanbieter): GV Streamer ist ein serverseitiges Tool, mit dem Daten aus verschiedenen Quellen in gültige Abfrageantworten in Google-Diagramme konvertiert werden können. GV Streamer unterstützt verschiedene Sprachen (z. B. PHP, Java und .NET) und mehrere Rohdatenquellen (z. B. MySql).
  • TracGViz (Drittanbieter): TracGViz ist ein kostenloses Open-Source-Tool, das Komponenten bereitstellt, mit denen Trac Diagramm-Gadgets verwenden kann und von Trac verwaltete Daten als Datenquelle für Google-Diagrammtools implementiert.
  • vis-table (Drittanbieter) – Bibliothek, die eine Google Chart Tools-Datenquelle in PHP implementiert Sie besteht aus drei Hauptteilen. Die Implementierung der Datentabelle selbst, der Abfragesprache-Parser und die Formatierer.
  • Google Datenquellen-Implementierung in Oracle PL/SQL (Drittanbieter): Ein Oracle-PL/SQL-Paket, mit dem Oracle Datenquellen direkt aus der Datenbank bereitstellen kann. Sie können also im Grunde eine beliebige Oracle-Abfrage als Google Chart Tools-Datenquelle verwenden (das Paket gibt eine JSON-Datei mit den Daten zurück). Die Google Query Language wird fast vollständig unterstützt.