Chart Tools データソース プロトコル（V0.6）の実装

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

目次

視聴者

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

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

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

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

概要

独自のグラフやその他のグラフのデータソース プロバイダにするために、グラフツールのデータソース プロトコルを実装できます。グラフツールのデータソースは、データソース URL と呼ばれる URL を公開します。この URL にグラフから HTTP GET リクエストを送信できます。これに対してデータソースは、ページ上にグラフィックをレンダリングするために使用できる、適切な形式のデータを返します。このリクエスト / レスポンス プロトコルは、Google ビジュアリゼーション API ワイヤ プロトコルと呼ばれています。

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

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

• 次のいずれかのヘルパー ライブラリを使用してリクエストとレスポンスを処理し、返される DataTable を作成します。これらのライブラリのいずれかを使用する場合は、ライブラリでデータをテーブル形式で利用できるようにするために必要なコードだけを書く必要があります。
  • Java データソース ライブラリ - リクエストとレスポンスを処理し、指定されたデータからレスポンス テーブルを作成して、Google グラフツールの SQL クエリ言語を実装します。
  • Python データソース ライブラリ - レスポンスの構文を生成するレスポンス テーブルを作成します。リクエストの解析や Google グラフツールの SQL クエリ言語の実装は行いません。
    
    または
    
    
• 独自のデータソースをゼロから作成します。具体的には、リクエストを処理し、DataTable を作成してレスポンスを送信します。

仕組み:

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

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

最小要件

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

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

セキュリティに関する考慮事項

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

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

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

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

• リクエストに「X-DataSource-Auth」ヘッダーが存在することを確認します。このヘッダーは GoogleVisualization API によって定義されます。このヘッダーの内容を調べる必要はありません。含まれていることのみ確認してください。Google グラフツール データソース ライブラリを使用している場合は、ライブラリに処理させることができます。
• 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」など）の両方で、大文字と小文字が区別されます。この表には、パラメータの送信が必要かどうか、送信した場合はその処理が必要かどうかも記載されています。

レスポンスの形式

レスポンスの形式は、リクエストの 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 ビジュアリゼーション 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, ...})"

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

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

JSON レスポンスの最適化

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

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

これは、GoogleVisualization 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 文字列の応答を受け取ると、文字列を開くためにどのアプリケーションを使用するかをユーザーに尋ねるか、または単純に画面にレンダリングします。Java と Python のオープンソース ライブラリには、DataTable を CSV 文字列に変換するメソッドが用意されています。

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

google.visualization.Query オブジェクトは、CSV レスポンスのリクエストをサポートしていません。クライアントが CSV をリクエストする場合は、ビジュアリゼーション ツールバー ガジェットをページに埋め込むか、カスタムコードを使用してリクエストを作成します。または、次のリクエスト URL に示すように、tqx の out: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 レスポンスのクエリを送信することはできません。カスタムコードを使用するか、ブラウザに次のような URL を入力して、HTML レスポンスのクエリを作成する必要があります。

リクエスト

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

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

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