Chart Tools Datasource Protocol(V0.6)の実装

このページでは、クエリクラスを使用してグラフにデータを公開するグラフツール データソース プロトコルをサポートするサービスを実装する方法について説明します。

目次

視聴者

このページは主に、グラフツール データソース ライブラリを使用せずに独自のデータソースを作成するデベロッパーを対象としています。このライブラリまたはその他のヘルパー ライブラリを使用している場合は、まずそのライブラリのドキュメントをご覧ください。

このページは、クライアントの可視化とデータソース間の通信に使用されるワイヤ プロトコルを理解したいデベロッパーを対象としています。

ビジュアリゼーションを作成または使用している場合、このページを読む必要はありません。

このドキュメントを読むには、基本的な JSON および HTTP リクエスト構文を理解する必要があります。また、グラフがユーザーの視点からどのように機能しているかも理解しました。

注: Chart Tools データソース プロトコルをサポートしている Google 以外のデータソースは、Google が公式に推奨またはサポートしているわけではありません。

概要

Chart Tools Datasource プロトコルを実装すると、独自のグラフや他のグラフのデータソース プロバイダになります。グラフツールのデータソースは、データソースの URL という URL を公開します。この URL で、HTTP GET リクエストを送信できます。これを受けて、データソースは、ページにグラフィックをレンダリングするために使用できる適切な形式のデータを返します。このリクエストとレスポンスのプロトコルは、Google Visualization API のワイヤ プロトコルと呼ばれます。

データソースによって提供されるデータは、ファイルやデータベースなどのさまざまなリソースから抽出できます。唯一の制限は、データを型付き列のある 2 次元テーブルとしてフォーマットできることです。

グラフツールのデータソースとして、特定の形式でリクエストを解析し、特定の形式でレスポンスを返す必要があります。これは、次の 2 つの方法のいずれかで作成できます。

  • 次のいずれかのヘルパー ライブラリを使用してリクエストとレスポンスを処理し、返される DataTable を作成します。これらのライブラリのいずれかを使用する場合は、データをテーブル形式でライブラリで使用できるようにするために必要なコードのみを記述する必要があります。
  • 独自のデータソースをゼロから作成するには、リクエストを処理して DataTable を作成し、レスポンスを送信します。

仕組み:

  1. データソースは、データソースの URL という URL を公開します。この URL に HTTP GET リクエストを送信します。
  2. クライアントは、返されたデータに使用する形式、省略可能なクエリ文字列、オプションのカスタム パラメータを記述するパラメータを含む HTTP GET リクエストを行います。
  3. リクエスト形式で説明されているように、データソースはリクエストを受信して解析します。
  4. データソースはリクエストされた形式でデータを準備します。通常、これは JSON テーブルです。レスポンスの形式については、レスポンスの形式のセクションをご覧ください。データソースは、フィルタリング、並べ替え、その他のデータ操作を指定する Vision API クエリ言語をオプションでサポートできます。
  5. データソースは、シリアル化されたデータやその他のレスポンス パラメータを含む HTTP レスポンスを作成し、レスポンス形式の説明に従ってクライアントに送り返します。

注: リクエストとレスポンス(「responseHandler」や「ok」など)について、このドキュメントに記載されているパラメータと文字列定数の値はすべて小文字であり、大文字と小文字が区別されます。

最小要件

グラフツールのデータソースとして使用するための最小要件は次のとおりです。

  • このデータソースは HTTP GET リクエストを受け入れ、クライアントが利用できるようにする必要があります。
  • プロトコルはバージョン スキームを変更してサポートできるため(現在のバージョンは 0.6)、データソースは以前のバージョンと現在のバージョンを使用するリクエストをサポートする必要があります。最新バージョンにすぐにアップグレードされるクライアントが破損しないように、新しいバージョンをリリース後すぐにサポートするようにしてください。
  • リクエストの一部として不明なプロパティが送信されても失敗しない。これは、新しいバージョンには気付かない新しいプロパティが導入される可能性があるためです。
  • 想定されるプロパティのみを解析する。新しいバージョンでは新しいプロパティが導入される可能性がありますが、そのままではリクエスト文字列全体を受け入れて使用しないでください。悪意のある攻撃から身を守るため、想定されるプロパティのみを慎重に解析して使用します。
  • クライアント チャートを自分でコーディングしていない場合は、データソースの要件を慎重に文書化してください。これには、次の情報が含まれます。
    • 任意のカスタム パラメータ
    • Google Visualization API のクエリ言語を解析できるかどうか
    • 返されるデータの種類、データの構造(行と列が表す内容、ラベル付け)。
  • 不明なクライアントからのリクエストを受け入れる場合は、サイトに対して標準的なセキュリティ対策をすべて行います。パラメータで MD5、ハッシュなどのセキュリティ メカニズムを合理的にサポートすることで、リクエストを認証したり、悪意のある攻撃から保護したりできます。また、クライアントが要件を認識し、それに応答することを期待できます。ただし、チャートをコーディングしていない場合は、すべての要件を十分に文書化してください。下記のセキュリティ上の考慮事項をご覧ください。
  • すべてのリクエスト文字列とレスポンス文字列は UTF-8 でエンコードされている必要があります。
  • 最も重要なレスポンス形式は JSON です。ほとんどのグラフで使用される形式であるため、最初に JSON を実装してください。その後、他のレスポンス タイプを追加します。
  • Visualization API のクエリ言語をサポートすることは必須ではありませんが、これにより、お客様にとってデータソースがさらに便利になります。
  • すべてのタイプのグラフからのリクエストをサポートする必要はなく、カスタムグラフのカスタム パラメータをサポートできます。ただし、下記の標準的な形式でレスポンスを返す必要があります。

セキュリティ上の考慮事項

データソースを設計する際は、データの安全性のセキュリティを考慮する必要があります。シンプルなパスワード アクセスから安全な Cookie 認証まで、さまざまなセキュリティ スキームをサイトに用意できます。

XSSI(クロスサイト スクリプト インクルード)攻撃は、チャートのリスクです。悪意のあるスクリプトがあるページに移動したユーザーは、現在のユーザーの認証情報を使用してデータソース URL に対してクエリを実行しようとします。ユーザーがサイトからログアウトしていない場合、スクリプトは現在のユーザーとして認証され、そのサイトに対する権限が付与されます。<script src> タグを使用すると、JSONP と同様に、悪意のあるスクリプトにデータソースを含めることができます。

セキュリティ レベルを高めるには、リクエストを同じドメインからのものに制限することをおすすめします。これにより、データソースの公開設定が大幅に制限されます。ただし、ドメイン外からアクセスする必要のない機密性の高いデータがある場合は、それを検討してください。すべてのドメインからのクエリを受け入れる無制限のデータソースとは対照的に、同じドメインからのリクエストのみを許可するデータソースは、制限付きデータソースと呼ばれます。制限付きデータソースの実装方法の詳細を以下に示します。

外部のドメイン(または XSRF 攻撃を受けているドメイン内のブラウザ)からではなく、実際にドメイン内から送信されたリクエストであることを確認するには:

  • リクエストに「X-DataSource-Auth」ヘッダーが含まれていることを確認します。このヘッダーは Google Visualization API によって定義されます。このヘッダーの内容を調べる必要はありません。ヘッダーが存在するかどうかを検証するだけです。Google Chart Tools Data Source Library を使用している場合は、ライブラリでこの処理を行うことができます。
  • Cookie 認証を使用してクライアントを認証します。認証 Cookie を維持したまま、クロスドメイン リクエストにカスタム ヘッダーを挿入する既知の方法はありません。
  • JavaScript を <script src> タグに含めても実行されないようにする。これを行うには、JSON レスポンスの前に ]]} を置き、その後に改行を付けます。クライアントで、レスポンスから接頭辞を削除します。XmlHttpRequest の場合、リクエストを同じドメインから発信した場合にのみ可能です。

リクエストの形式

クライアントは、カスタム要素、オプションのクエリ文字列、署名、その他の要素など、いくつかのパラメータを含む HTTP GET リクエストを送信します。このセクションで説明するパラメータの解析は、ご自身の責任で行ってください。悪意のある攻撃を避けるために、他のパラメータの処理に注意する必要があります。

省略可能なパラメータ(標準とカスタムの両方)にはデフォルト値を必ず指定し、デフォルト値はすべてサイトのドキュメントに記載してください。

リクエストの例をいくつか示します。その他のリクエストとレスポンスのサンプルは、このドキュメントの最後にあるで確認できます。

: 次のリクエスト文字列とのセクションに示されているリクエスト文字列は、送信前に 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

以下に、リクエスト文字列のすべての標準パラメータの一覧を示します。パラメータ名(「version」など)と定数文字列値(「ok」、「warning」、「not_modified」など)はどちらも大文字と小文字が区別されます。表には、パラメータの送信が必要かどうかと、送信する必要がある場合はその処理が必要かどうかも示されています。

パラメータ
リクエストでの必要性
データソースで処理する必要があるもの
説明
TQ
×
×

Google Visualization API のクエリ言語で記述されたクエリ。返されるデータをフィルタ、並べ替え、または操作する方法を指定します。文字列を引用符で囲む必要はありません。

例: http://www.example.com/mydatasource?tq=select Col1

TQX
×

標準パラメータまたはカスタム パラメータ用の Key-Value ペアをコロンで区切ったセット。ペアが複数ある場合はセミコロンで区切ります。以下に、Visualization プロトコルで定義された標準パラメータのリストを示します。

  • reqId - [リクエストで必須。データソースで処理する必要があります]。このリクエストの数値識別子。これを使用すると、クライアントがレスポンスを受信する前に複数のリクエストを送信した場合、データソースが適切なリクエストでレスポンスを識別できます。この値をレスポンスで送り返します。
  • version - [リクエストに応じて省略可。データソースで処理する必要があります] Google 可視化プロトコルのバージョン番号。現在のバージョンは 0.6 です。送信されていない場合は、最新バージョンと想定します。
  • sig - (省略可、リクエストでは省略可)このデータソースへの以前のリクエストで、このクライアントに送信される DataTable のハッシュです。これは、クライアントに同一のデータを 2 回送信しないようにする最適化です。使用方法について詳しくは、後述のリクエストを最適化するをご覧ください。
  • out - (省略可、リクエストで処理、データソースで処理)] 返されるデータの形式を示す文字列。値は次のいずれかになります。
    • json - [デフォルト値] 以下で説明する JSON レスポンス文字列です。
    • html - 行と列を含む基本的な HTML テーブル。これが使用されている場合、返される必要があるのはデータが含まれる HTML テーブルのみです。これは、以下のレスポンスの形式セクションで説明されているように、デバッグに役立ちます。
    • csv - カンマ区切り値。これを使用すると、CSV データ文字列だけが返されます。outFileName パラメータを指定すると、レスポンス ヘッダー内のファイルのカスタム名をリクエストできます。
    • tsv-excel - csv に似ていますが、カンマではなくタブを使用し、すべてのデータが utf-16 でエンコードされます。
    なお、Google Visualization API で作成されるグラフがリクエストするのは、json のみです。各タイプの詳細については、後述のレスポンスの形式をご覧ください。
  • responseHandler - (省略可。リクエストにはデータソースで処理する必要があります)レスポンス時に呼び出されるクライアント ページにある JavaScript 処理関数の文字列名。リクエストに含まれていない場合、値は google.visualization.Query.setResponse です。これはレスポンスの一部として返されます。方法については、以下のレスポンスの形式をご覧ください。
  • outFileName - [省略可。リクエストでは省略可。処理するデータソースの場合は省略可能]。[out:csv] または [out:tsv-excel] を指定した場合、ここで指定したファイル名をリクエストできます。例: outFileName=results.csv

例: tqx=version:0.6;reqId:1;sig:5277771;out:json; responseHandler:myQueryHandler

TQRT
×
×

予約済み: このパラメータを無視します。クエリの送信に使用されたメソッド。

レスポンスの形式

レスポンスの形式は、リクエストの out パラメータによって異なります。このパラメータには、想定されるレスポンスのタイプを指定します。各リクエスト タイプに対応する方法については、次のセクションをご覧ください。

  • JSON - JavaScript オブジェクトにデータを格納した JSON レスポンスを返します。このデータは、DataTable コンストラクタに直接渡して入力できます。これは最も一般的なリクエスト タイプであり、適切に実装することが特に重要です。
  • CSV - ブラウザが処理するフラットなカンマ区切り値のリストを返します。
  • TSV - ブラウザによって処理されるタブ区切りの値リストを返します。
  • HTML - ブラウザによってレンダリングされる HTML テーブルが返されます。

Google 可視化データソース ライブラリ(java)または可視化 Python ライブラリを使用して、これらの出力形式を生成できます。

JSON レスポンスの形式

リクエストに「X-DataSource-Auth」ヘッダーが含まれている場合、デフォルトのレスポンス形式は JSON であり、それ以外の場合は JSONP です。Google グラフ クライアントは JSON と JSONP の変更バージョンをサポートしています。Java または Python ヘルパー ライブラリを使用している場合は、適切なコードが出力されます。レスポンスを手動で解析する場合は、後述の JSON の変更をご覧ください。

同じドメインのリクエストを適用する場合は、リクエストに「X-DataSource-Auth」ヘッダーが存在することを確認し、認可 Cookie を使用する必要があります。

これは、Google Visualization API のメソッド google.visualization.Query.send() で指定される、唯一のレスポンス形式です。JSON リクエストとレスポンスの例は、このページの最後にあるで確認できます。この応答文字列は、Java または Python のヘルパー ライブラリを使用して作成できます。

このレスポンス形式は、下の表に示すプロパティを含む、UTF-8 でエンコードされた JSON オブジェクト(各プロパティはカンマで区切って、中かっこ { で囲む)です。オブジェクトには、以下の表のプロパティが含まれています(データは table プロパティに割り当てられます)。この JSON オブジェクトは、リクエストの responseHandler パラメータ値でラップする必要があります。そのため、リクエストの responseHandler 値が「myHandler」の場合、次のような文字列を返す必要があります(簡潔にするために 1 つのプロパティのみが返されます)。

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

リクエストに responseHandler 値が含まれていない場合、デフォルト値は「google.visualization.Query.setResponse」です。したがって、次のような文字列を返す必要があります(簡潔にするために 1 つのプロパティのみ表示されます)。

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

使用できるレスポンス オブジェクト メンバーは次のとおりです。

プロパティ
必須かどうか
説明
version
×

Google 可視化ワイヤ プロトコルのバージョン番号を示す文字列番号。指定しない場合、クライアントは最新バージョンを想定します。

例: version=0.6

reqId
○*
このクライアントに対するリクエストの ID を示す文字列番号です。リクエストに含まれる場合は、同じ値を返します。詳しくは、リクエスト セクションreqId の説明をご覧ください。

* このパラメータがリクエストで指定されていない場合は、レスポンスで設定する必要はありません。
status

このオペレーションの成功または失敗を示す文字列。次のいずれかの値を指定する必要があります。

  • ok - リクエストが成功したとき。テーブルは table プロパティに含める必要があります
  • warning - 完了しましたが、問題が発生しています。テーブルは table プロパティに含める必要があります
  • error - 問題が発生しました。これを返す場合は、table返さずerrors を返す必要があります。

例: status:'warning'

警告
status=warning の場合のみ

非致命的な問題を表す 1 つ以上のオブジェクトの配列。 status=warning の場合は必須、それ以外の場合は許可されません。各オブジェクトには次の文字列プロパティがあります(プロパティごとに 1 つの値のみが返されます)。

  • reason - [必須] 警告の 1 単語の文字列の説明。プロトコルは次の値を定義しますが、必要に応じて独自の値を定義できます(ただし、クライアントは特別な方法でカスタム値を処理しません)。 指定できる reason 値は 1 つだけです。
    • data_truncated - 返された DataTable では、ユーザーが結果リストをトリミングしたクエリ文字列、またはなんらかの理由で完全な結果を返すことを望まないという理由で、一部の行が削除されました。
    • other - 一般的な指定されていない警告。
  • message - (省略可)問題を説明する短い引用符付きの文字列。アラート ボックスのタイトルとして使用されます。これはユーザーに表示されます。HTML はサポートされていません。
  • detailed_message - (省略可)問題の詳しい説明と考えられる解決策を説明する文字列メッセージ。サポートされている HTML は、単一の href 属性を含む <a> 要素のみです。Unicode エンコードがサポートされています。これはユーザーに表示されます。

例: warnings:[{reason:'data_truncated',message:'Retrieved data was truncated'}]

エラー
status=error の場合は必須

1 つ以上のオブジェクトの配列。それぞれがエラーを表します。status=error の場合は必須、それ以外の場合は許可されません。これは warnings 値に似ています。not_modified エラーはエラーですが、実際にはクライアントへのエラーではありません。

配列には次の文字列メンバーがあります(メンバーごとに 1 つの値のみが返されます)。

  • reason - [必須] warnings.reason と同じですが、次の値が定義されています。
    • not_modified - データは前回のリクエスト以降変更されていません。これがエラーの理由である場合は、table の値を指定しないでください。
    • user_not_authenticated - データソースで認証が必要で、まだ行われていない場合は、この値を指定します。すると、クライアントは message という値を持つアラートを表示します。
    • unknown_data_source_id
    • access_denied
    • unsupported_query_operation
    • invalid_query
    • invalid_request
    • internal_error
    • not_supported
    • illegal_formatting_patterns
    • other - 一般的な指定されていないエラー。
  • message - 省略可: warnings.message と同じです。注: 悪意のあるユーザーが詳細なデータ文字列を使用して、不正なデータにアクセスすることや、それを使ってあなたのデータやサイトを攻撃する可能性もあります。セキュリティを確保する必要があるデータを保存する場合、またはユーザークエリを直接処理する場合は、攻撃者に情報を提供する可能性のある詳細なエラー メッセージを返すのではなく、「不正なクエリ文字列」などの一般的なメッセージを表示することを検討してください。
  • detailed_message - [省略可] warnings.detailed_message と同じ。message の情報が詳細すぎる場合は、警告を確認してください。

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

Sig
×

テーブル オブジェクトのハッシュ値。クライアントとデータソース間のデータ転送を最適化するのに役立ちます。任意のハッシュ アルゴリズムを選択できます。 このプロパティがサポートされている場合は、データが返されない場合はクライアントによって渡された値を返し、新しいデータが返される場合は新しいハッシュを返す必要があります。

例: sig:'5982206968295329967'

table
×

データを含む JavaScript のリテラル表記の DataTable オブジェクト。このオブジェクトの形式について詳しくは、リンク先のリファレンス セクションをご覧ください。シンプルなデータテーブルの例を以下に示します。

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

table プロパティは、status=ok または status=warning の場合にのみ指定します。データを返さない場合は、このプロパティを指定しないでください(つまり、空の文字列値でプロパティを戻さないでください)。

例: 下記のをご覧ください。

 

厳密な JSON が必要

Google のヘルパー ライブラリと、Google に送信されるすべてのクエリは、厳格な JSON/JSONP を返します。返されたコードをご自身で解析していない場合、これは問題にはなりません。その場合は、JSON.parse() を使用して JSON 文字列を JavaScript オブジェクトに変換できます。API による JSON の処理の違いの 1 つとして、JSON は JavaScript の日付値("new Date(2008,1,28,0,31,26 など)" など)をサポートしていません。ただし、API は Date(year, month, day[,hour, minute, second[, millisecond]]) という形式の文字列の有効な JSON 表現をサポートしています。この場合、日付はすべて省略可能で、月はゼロベースです。

 

JSON レスポンスの最適化

クライアントが 2 つのリクエストを行い、リクエスト間でデータが変更されていない場合は、データを再送信しないのは理にかなっています。そうすると、帯域幅が無駄になります。リクエストを効率的に行うため、プロトコルでは、クライアント上のデータのキャッシュと、最後のリクエストからデータが変更されていなければレスポンスでのシグナルの送信がサポートされています。具体的には次のように算出します。

  1. クライアントがデータソースにリクエストを送信します。
  2. データソースは DataTable オブジェクトと DataTable オブジェクトのハッシュを生成し、両方をレスポンスで返します(ハッシュは tqx.sig パラメータで返されます)。Google Visualization API のクライアントは、DataTablesig の値をキャッシュに保存します。
  3. クライアントは、キャッシュに保存された tqx.sig 値など、別のデータ リクエストを送信します。
  4. データソースは、次の 2 つの方法のいずれかで応答できます。
    • 前のリクエストからデータが変更された場合、データソースは新しい DataTable と新しい sig の値のハッシュを返します。
    • 前のリクエストからデータが変更されていない場合、データソースは status=errorreason=not_modifiedsig=old_sig_value を返します。
  5. いずれの場合も、グラフをホストするページはレスポンスを正常に取得し、QueryResponse.getDataTable() を呼び出して DataTable を取得できます。データが同じであれば、単にキャッシュされたテーブルになります。

これは、Google Visualization API で作成されたグラフからの JSON リクエストでのみ機能します。

CSV レスポンス形式

リクエストで out:csv を指定すると、レスポンスにメタデータは含まれませんが、データの CSV 表現が返されます。CSV テーブルは通常、カンマ区切りのリストであり、データの各行はカンマ区切りのリストで、末尾が UNIX の改行文字(\n)です。セルの値は、各列のデータ型が同じである必要があります。最初の行は列のラベルです。3 行 3 列テーブルの例を次に示します。

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

CSV 形式はこのプロトコルで指定されていません。データソースで CSV 形式を定義する必要があります。ただし、一般的な形式としては、カンマで区切られた値のセット(スペースなし)と、すべての行の末尾に改行(\n)があります。ブラウザが CSV 文字列の応答を受け取ると、文字列を開くために使用するアプリをユーザーに尋ねるか、画面でレンダリングします。JavaPython のオープンソース ライブラリには、DataTable を CSV 文字列に変換するメソッドが用意されています。

リクエストに tqx パラメータの outFileName メンバーが含まれている場合は、指定したヘッダーをレスポンス ヘッダーに含める必要があります。

google.visualization.Query オブジェクトは、CSV レスポンスのリクエストをサポートしていません。クライアントが CSV をリクエストする場合は、可視化ツールバー ガジェットをページに埋め込むか、カスタムコードを使用してリクエストを作成するか、次のリクエスト URL に示すように、tqxout:csv プロパティを明示的に設定するリンクを指定できます。

リクエスト

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

レスポンス

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

TSV レスポンス フォーマット

リクエストで out:tsv-excel を指定すると、レスポンスにメタデータは含まれませんが、データのタブ区切り表記(utf-16 エンコード)のみとなります。リクエストに tqx パラメータの outFileName メンバーが含まれている場合は、指定したヘッダーをレスポンス ヘッダーに含める必要があります。

HTML レスポンスの形式

リクエストで out:html が指定されている場合、レスポンスでデータを含む HTML テーブルを定義する HTML ページが返されます。これは、ブラウザが結果を読み取り可能な形式で直接レンダリングできるため、コードのデバッグに役立ちます。google.visualization.Query オブジェクトを使用して HTML レスポンスのクエリを送信することはできません。HTML レスポンスのクエリを実行するには、カスタムコードを使用するか、ブラウザに次のような URL を入力します。

リクエスト

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

レスポンス

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

以下に、リクエストとレスポンスの例を示します。リクエストに URL エスケープが使用されていません。通常は、ブラウザまたは google.visualization.Query オブジェクトでリクエストします。

シンプルなリクエスト: 3 列 4 行のテーブルで基本情報を返します。

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

レスポンス ハンドラを使用したシンプルなリクエスト: 異なるデータ型の 3 列、3 行の表を返します。

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

単純なクエリ文字列を使用したクエリ: 1 つの列をリクエストすると、4 つの行を含む単一の列が返されます。

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

データ変更なしエラー: 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'}]});

データ切り捨ての警告: data_truncated 警告の例。このリクエストではまだデータが返されます。

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

アクセス拒否エラー: 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'}]});

無効なクエリ文字列: 無効なクエリ文字列を含むリクエストの例。詳細メッセージは実際のエラー メッセージではなく、一般的なメッセージです。

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

開発ツール

  • Java データソース ライブラリ(提供元: Google) - リクエストとレスポンスを処理し、受信したデータからレスポンス テーブルを作成して、Google Chart Tools SQL クエリ言語を実装します。
  • Python Datasource Library(Google 提供)- レスポンス テーブルを作成し、レスポンス構文を生成します。処理ではリクエストを解析せず、Google Chart Tools SQL クエリ言語を実装しません。
  • MC-Google_Visualization(サードパーティ)- PHP サーバー側ライブラリであり、PDO を使用して MySQL、SQLite、PostgreSQL データベース エンジンのグラフツール データソースを実装できます。
  • bortosky-google-visualization(サードパーティ)- .NET ユーザー用の Google Visualization API Datatable を作成するためのヘルパー ライブラリです。
  • GV Streamer(サードパーティ)- GV Streamer は、さまざまなソースのデータを Google グラフへの有効なクエリ レスポンスに変換できるサーバー側ツールです。GV Streamer は、複数の言語(PHP、Java、.NET など)と複数の未加工のデータソース(MySql など)をサポートしています。
  • TracGViz(サードパーティ) - TracGViz はコンポーネントを提供する無料のオープンソース ツールです。Trac はグラフ ガジェットを使用し、Trac によって管理されるデータを Google グラフツールのデータソースとして実装できます。
  • vis-table(第三者)- PHP で Google グラフツール データソースを実装するライブラリ。これには 3 つの主要な部分があります。データテーブルの実装自体、クエリ言語パーサー、フォーマッタ。
  • Oracle PL/SQL で Google がデータソースを実装(サードパーティ) - Oracle PL/SQL パッケージ。データベースから直接データソースを Oracle で処理できます。つまり、任意の Oracle クエリを Google Chart Tools データソースとして使用できます(パッケージはデータを含む JSON ファイルを返します)。Google クエリ言語はほぼ完全にサポートされています。