Google Visuaization API リファレンス

昨日の記事は尻切れトンボになってしまって申し訳ありませんでした。掲載できなかった Google Visualization API リファレンスをお届けします。これまでの記事ともども、ぜひご活用ください！

google.visualization.Query

データのリクエストを発行するためのクラスです。インスタンスの生成は、以下のように new を使って行います。

google.visualization.Query(データソースURL)

データソース URL については、前回の記事をご参照ください。以下は利用可能なメソッドです。

setRefreshInterval(秒数): 指定した秒数の間隔で自動的に send メソッドを実行し、新しいデータへの更新を行います。デフォルトの秒数は 0 で、この場合は自動更新を行いません。このメソッドは send よりも前に呼ぶ必要があります。
setTimeout(秒数): リクエストのタイムアウトまでの秒数を指定します。デフォルトは 30 秒です。このメソッドは send よりも前に呼ぶ必要があります。
setQuery(Query Language): 問い合わせをカスタマイズする Query Language を指定します。デフォルトは 30 秒です。このメソッドは send よりも前に呼ぶ必要があります。
send(コールバック関数): データの問い合わせを実行します。結果を受信すると、そのデータ（後述の QueryResponse オブジェクト）を引数にしてコールバック関数を呼び出します。

レスポンスデータを格納するクラスです。 Query.send メソッドに渡したコールバック関数が呼ばれる際に、その引数として渡されます。通常は明示的にインスタンスを生成することはありません。

getDataTable(): 取得したテーブルのデータを格納する、後述の DataTable オブジェクトを返します。エラーが発生した場合には null を返します。公式リファレンスでは "getData" という名前になっていますが、たぶん間違いです。
getDetailedMessage(): 開発者向けの詳細なエラーメッセージを返します。問い合わせが成功した場合は、空の文字列を返します。
getMessage(): エンドユーザー向けの簡易なエラーメッセージを返します。問い合わせが成功した場合は、空の文字列を返します。
getResponse(): リクエストの処理中に発生したエラーや警告などを示す文字列の配列を返します。各文字列の意味は下の表をご参照ください。
hasWarning(): 警告が発生したときに true を返します。その場合でも、エラーが発生していなければ getData メソッドは有効なテーブルを返します。
isError(): 問い合わせでエラーが発生したときに true を返します。その場合、 getData メソッドは null を返します。

getResopnse メソッドで返る配列に格納されている文字列には、以下のような意味があります。

文字列	意味
access_denied	アクセス権限がない。非公開のシートにログインしないでアクセスした場合など。
invalid_query	Query Language の文法違反。
data_truncated	limit 句やデータサイズの上限などで全データが取得できなかった。警告扱い。
timeout	タイムアウト時間内にレスポンスが返らなかった。

レスポンスに含まれるテーブル形式のデータを格納するクラスです。 QueryResponse.getDataTable メソッドで取得できます。通常は明示的にインスタンスを生成することはありません。

getNumberOfColumns(): テーブルのカラム数を返します。
getNumberOfRows(): テーブルの行数を返します。
getColumnId(カラムインデックス): 指定したカラムの ID を返します。 Google Spreadsheets の場合、カラムを表すアルファベットが ID になります。カラムインデックスは取得したテーブルの最も左のカラムを 0 としたインデックスです。
getColumnLabel(カラムインデックス): 指定したカラムのラベルを取得します。 Google Spreadsheets の場合、最初の行の内容がラベルになります（もしくは Query Language の LABEL 句で指定した文字列）。
getColumnPattern(カラムインデックス): Query Language の FORMAT 句で指定したパターンを返します。
getColumnType(カラムインデックス): 指定したカラムのデータ型を表す文字列を返します。返る可能性のある文字列は、 "string", "number", "boolean", "date", "timeofday", "datetime" です。
getValue(行インデックス, カラムインデックス): 指定した行・カラムの内容を返します。返り値のクラスはデータ型によって異なりますので、下の表を参照してください。
getFormattedValue(行インデックス, カラムインデックス): 指定した行、カラムの内容を適切にフォーマットした表示可能文字列で返します。

getValue で返る値のクラスはデータ型によって異なります。データ型と JavaScript クラスの対応は以下のようになります。

Gadget-in-Docs のコーディングに便利なヘルパー関数です。インスタンスの生成は以下のように new を使って行います。

google.visualization.GadgetHelper()

createQueryFromPrefs(prefs): prefs は iGoogle ガジェット API の _IG_Prefs クラスのオブジェクトです。ユーザー設定（データソース URL とリロード間隔）を反映した Query オブジェクトを生成します。
validateResponse(レスポンス): 問い合わせが成功していたら true を、失敗していたら false を返します。また、失敗の場合はエラーメッセージをガジェットの左上に表示します。

以上です。複雑な機能は Query Language のほうでサポートしているので、 API 自体はかなりシンプルですね。やっつけで書いたのでわかりにくい部分があるかもしれませんが、その際はコメントいただければ、できるだけお答えします。

参考

2008年03月28日 08:24 | Comments() | TrackBack() |

Recommendations

Books

「Closure Library」の入門書です。
詳しくはこちらの記事をどうぞ！