Реализация протокола источника данных инструментов диаграмм (версия 0.6)

На этой странице описывается, как можно реализовать службу, поддерживающую протокол источника данных инструментов диаграмм, чтобы предоставлять данные диаграммам с помощью класса Query .

Содержание

Аудитория

Эта страница предназначена в первую очередь для разработчиков, которые будут создавать собственный источник данных без помощи библиотеки источников данных инструментов для работы с диаграммами . Если вы используете эту или любые другие вспомогательные библиотеки, сначала прочитайте документацию вашей библиотеки.

Эта страница также предназначена для читателей, интересующихся пониманием проводного протокола, используемого для связи между клиентской визуализацией и источником данных.

Если вы создаете или используете визуализацию, вам не нужно читать эту страницу.

Чтобы прочитать этот документ, вы должны понимать базовый синтаксис запросов JSON и HTTP. Вы также должны понимать, как работают диаграммы с точки зрения пользователя.

Примечание. Google официально не одобряет и не поддерживает источники данных, не принадлежащие Google, которые поддерживают протокол источника данных инструментов диаграмм.

Обзор

Вы можете реализовать протокол источника данных инструментов диаграмм, чтобы стать поставщиком источника данных для ваших собственных диаграмм или других диаграмм. Источник данных инструментов диаграммы предоставляет URL-адрес, называемый URL-адресом источника данных , на который диаграмма может отправлять HTTP-запросы GET. В ответ источник данных возвращает правильно отформатированные данные, которые диаграмма может использовать для отображения графики на странице. Этот протокол запроса-ответа известен как проводной протокол Google Visualization API.

Данные, предоставляемые источником данных, могут быть извлечены из различных ресурсов, таких как файл или база данных. Единственное ограничение заключается в том, что вы можете форматировать данные как двумерную таблицу с типизированными столбцами.

В качестве источника данных инструментов для работы с диаграммами вы должны анализировать запрос в определенном формате и возвращать ответ в определенном формате. Вы можете сделать это одним из двух основных способов:

  • Используйте одну из следующих вспомогательных библиотек для обработки запроса и ответа и создайте возвращаемый объект DataTable. Если вы используете одну из этих библиотек, вам нужно написать только код, необходимый для того, чтобы ваши данные были доступны библиотеке в виде таблицы.
  • Напишите свой собственный источник данных с нуля, обработав запрос, создав DataTable и отправив ответ.

Как это работает:

  1. Источник данных предоставляет URL-адрес, называемый URL-адресом источника данных , на который диаграммы отправляют запрос HTTP GET.
  2. Клиент отправляет HTTP-запрос GET с параметрами, которые описывают, какой формат использовать для возвращаемых данных, необязательной строкой запроса и необязательными настраиваемыми параметрами.
  3. Источник данных получает и анализирует запрос, как описано в разделе «Формат запроса» .
  4. Источник данных подготавливает данные в запрошенном формате; обычно это таблица JSON. Форматы ответов описаны в разделе «Формат ответа» . Источник данных может дополнительно поддерживать язык запросов API визуализации, который определяет фильтрацию, сортировку и другие манипуляции с данными.
  5. Источник данных создает ответ HTTP, который включает сериализованные данные и другие параметры ответа, и отправляет его обратно клиенту, как описано в разделе «Формат ответа».

Примечание. Все параметры и значения строковых констант, перечисленные в этом документе для запросов и ответов (например, responseHandler и «ok»), написаны строчными буквами и чувствительны к регистру.

Минимальные требования

Вот минимальные требования для использования в качестве источника данных инструментов диаграмм:

  • Источник данных должен принимать запросы HTTP GET и быть доступен вашим клиентам.
  • Протокол может меняться и поддерживает схему версий (текущая версия — 0,6), поэтому ваш источник данных должен поддерживать запросы, использующие как предыдущие версии, так и текущую версию. Вам следует стараться поддерживать новые версии сразу после их выпуска, чтобы избежать поломки клиентов, которые быстро обновляются до новейшей версии.
  • Не сбой, если неизвестные свойства отправляются как часть запроса. Это связано с тем, что в новых версиях могут появиться новые свойства, о которых вы не знаете.
  • Анализируйте только те свойства, которые вы ожидаете. Хотя в новых версиях могут появиться новые свойства, не принимайте слепо и не используйте всю строку запроса. Чтобы защитить себя от вредоносных атак, внимательно анализируйте и используйте только те свойства, которые вы ожидаете.
  • Тщательно документируйте требования к источникам данных, если вы не пишете клиентские диаграммы самостоятельно. Сюда входит документирование следующей информации:
    • Любые пользовательские параметры, которые вы принимаете,
    • Можете ли вы анализировать язык запросов API визуализации Google и
    • Какие данные вы возвращаете, и структуру этих данных (что представляют строки и столбцы, а также любые метки).
  • Примите все стандартные меры безопасности для сайта, принимающего запросы от неизвестных клиентов . Вы можете разумно поддерживать MD5, хеширование и другие механизмы безопасности в своих параметрах для аутентификации запросов или защиты от вредоносных атак и ожидать, что клиенты будут знать о ваших требованиях и отвечать на них. Однако обязательно тщательно задокументируйте все свои требования, если вы не пишете диаграммы самостоятельно. См. раздел «Вопросы безопасности» ниже.
  • Все строки запросов и ответов должны быть в кодировке UTF-8.
  • Самый важный формат ответа — JSON. Обязательно сначала реализуйте JSON, поскольку именно этот формат используется в большинстве диаграмм. Позже добавьте другие типы ответов.
  • От вас не требуется поддержка языка запросов Visualization API, но это делает ваш источник данных более полезным для клиентов.
  • Вам не обязательно поддерживать запросы от всех типов диаграмм, и вы можете поддерживать пользовательские параметры для пользовательских диаграмм. Но вам следует возвращать ответы в стандартном формате, описанном ниже.

Вопросы безопасности

При проектировании источника данных вам необходимо учитывать, насколько безопасными должны быть ваши данные. Вы можете использовать различные схемы безопасности для своего сайта: от простого доступа по паролю до безопасной аутентификации с помощью файлов cookie.

Атаки XSSI (межсайтовое включение скриптов) представляют собой риск для диаграмм. Пользователь может перейти на страницу, содержащую вредоносный сценарий, который затем начнет пытаться выполнять запросы к URL-адресам источников данных, используя учетные данные текущего пользователя. Если пользователь не вышел из сайта, сценарий будет аутентифицирован как текущий пользователь и получит разрешения на этом сайте. Используя тег <script src>, вредоносный скрипт может включить источник данных, аналогично JSONP.

В качестве дополнительного уровня безопасности вы можете рассмотреть возможность ограничения запросов теми, кто поступает из того же домена, что и ваш источник данных. Это значительно ограничит видимость вашего источника данных, но если у вас есть очень конфиденциальные данные, к которым нельзя получить доступ из-за пределов вашего домена, вам следует подумать об этом. Источник данных, который разрешает запросы только из одного и того же домена, называется ограниченным источником данных , в отличие от неограниченного источника данных , который принимает запросы из любого домена. Вот некоторые подробности о том, как реализовать ограниченный источник данных:

Чтобы убедиться, что запрос действительно поступает изнутри вашего домена , а не из внешнего домена (или браузера внутри домена, подвергшегося XSRF-атаке ):

  • Проверьте наличие заголовка «X-DataSource-Auth» в запросе. Этот заголовок определяется API визуализации Google; вам не нужно проверять содержимое этого заголовка, достаточно лишь убедиться в его наличии. Если вы используете библиотеку источников данных Google Chart Tools , библиотека может сделать это за вас.
  • Используйте аутентификацию с помощью файлов 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

Вот список всех стандартных параметров в строке запроса. Обратите внимание, что как имена параметров (например, «версия»), так и константные строковые значения (например, «ok», «предупреждение» и «not_modified») чувствительны к регистру. В таблице также указано, требуется ли отправлять параметр и, если он отправлен, необходимо ли вам его обрабатывать.

Параметр
Требуется в запросе?
Источник данных должен обрабатывать?
Описание
tq
Нет
Нет

Запрос, написанный на языке запросов Google Visualization API , определяющий, как фильтровать, сортировать или иным образом манипулировать возвращаемыми данными. Строку не нужно заключать в кавычки.

Пример: http://www.example.com/mydatasource?tq=select Col1

tqx
Нет
Да

Набор пар ключ/значение, разделенных двоеточиями, для стандартных или пользовательских параметров. Пары разделяются точкой с запятой. Вот список стандартных параметров, определенных протоколом визуализации:

  • reqId - [ Обязателен в запросе; Источник данных должен обрабатывать ] Числовой идентификатор этого запроса. Это используется для того, чтобы, если клиент отправляет несколько запросов до получения ответа, источник данных может идентифицировать ответ как правильный запрос. Отправьте это значение обратно в ответ.
  • version - [ Необязательно по запросу; Источник данных должен обрабатывать ] Номер версии протокола визуализации Google. Текущая версия 0.6. Если не отправлено, предположим, что установлена ​​последняя версия.
  • sig - [ Необязательно в запросе; Необязательно для обработки источника данных ] Хэш DataTable , отправленный этому клиенту во всех предыдущих запросах к этому источнику данных. Это оптимизация, позволяющая избежать повторной отправки идентичных данных клиенту. Информацию о том, как это использовать, см. ниже в разделе «Оптимизация вашего запроса» .
  • out - [ Необязательно в запросе; Источник данных должен обрабатывать ] Строка, описывающая формат возвращаемых данных. Это может быть любое из следующих значений:
    • json — [ Значение по умолчанию ] Строка ответа JSON (описана ниже).
    • html — базовая таблица HTML со строками и столбцами. Если это используется, единственное , что должно быть возвращено, — это HTML-таблица с данными; это полезно для отладки, как описано в разделе «Формат ответа» ниже.
    • csv — значения, разделенные запятыми. Если это используется, единственное , что возвращается, — это строка данных CSV. Вы можете запросить собственное имя для файла в заголовках ответа, указав параметр outFileName .
    • tsv-excel — аналогично csv , но вместо запятых используются табуляции, а все данные закодированы в формате utf-16.
    Обратите внимание, что единственный тип данных, который когда-либо будет запрашивать диаграмма, построенная на API визуализации Google, — это 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 — возвращает ответ JSON, содержащий данные в объекте JavaScript, который можно передать непосредственно в конструктор DataTable для его заполнения. Это, безусловно, самый распространенный тип запроса, и его наиболее важно правильно реализовать.
  • CSV — возвращает плоский список значений, разделенных запятыми, который будет обрабатываться браузером.
  • TSV — возвращает список значений, разделенных табуляцией, который будет обрабатываться браузером.
  • HTML — возвращает таблицу HTML, которая будет отображаться браузером.

Вы можете использовать библиотеку источников данных визуализации Google (java) или библиотеку Python для визуализации , чтобы сгенерировать эти выходные форматы.

Формат ответа JSON

Формат ответа по умолчанию — JSON, если запрос включает заголовок «X-DataSource-Auth», в противном случае — JSONP . Обратите внимание, что клиент диаграмм Google фактически поддерживает модифицированную версию JSON и JSONP; если вы используете вспомогательные библиотеки Java или Python , они предоставят вам подходящий код; если вы анализируете ответы вручную, см. раздел «Модификации JSON» ниже.

Если вы выполняете запросы того же домена, вам следует проверить наличие заголовка «X-DataSource-Auth» в запросе и использовать файлы cookie авторизации.

Это единственный формат ответа, указанный методом Google Visualization API google.visualization.Query.send() . Вы можете увидеть некоторые примеры запросов и ответов JSON в конце этой страницы в разделе «Примеры» . Вы можете использовать вспомогательные библиотеки Java или Python , чтобы создать эту строку ответа.

Этот формат ответа представляет собой объект JSON в кодировке UTF-8 (объект, заключенный в фигурные скобки { }, где каждое свойство отделено запятой), который включает свойства из таблицы ниже (данные присваиваются свойству table ). Этот объект JSON должен быть заключен в значение параметра responseHandler из запроса. Итак, если значение responseHandler запроса было «myHandler», вы должны вернуть такую ​​строку (для краткости показано только одно свойство):

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

Если запрос не включал значение responseHandler , значением по умолчанию является «google.visualization.Query.setResponse», поэтому вам следует вернуть такую ​​строку (для краткости показано только одно свойство):

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

Вот доступные члены объекта ответа:

Свойство
Необходимый?
Описание
версия
Нет

Номер строки, указывающий номер версии проводного протокола визуализации Google. Если не указано, клиент предполагает последнюю версию.

Пример: version=0.6

требуемый идентификатор
Да*
Строковый номер, указывающий идентификатор этого запроса для этого клиента. Если это было в запросе, верните то же значение. Дополнительную информацию см. в описании reqId в разделе запроса .

* Если этот параметр не был указан в запросе, его не обязательно задавать в ответе.
положение дел
Да

Строка, описывающая успех или неудачу этой операции. Должно быть одно и только одно из следующих значений:

  • ok – успешный запрос. Таблица должна быть включена в свойство table .
  • warning — успех, но с проблемами. Таблица должна быть включена в свойство table .
  • error - возникла проблема. Если вы вернете это, вы не должны возвращать table и должны возвращать errors .

Пример: status:'warning'

предупреждения
Только если status=warning

Массив из одного или нескольких объектов, каждый из которых описывает некритическую проблему. Требуется, если status=warning , в противном случае не допускается. Каждый объект имеет следующие строковые свойства (для каждого свойства возвращается только одно значение):

  • reason — [ Обязательно ] Строковое описание предупреждения, состоящее из одного слова. Протокол определяет следующие значения, но при необходимости вы можете определить свои собственные значения (однако клиент не будет обрабатывать пользовательские значения каким-либо особым образом). У вас может быть только одно значение reason :
    • data_truncated — из возвращенного DataTable были удалены некоторые строки, либо потому, что пользователь включил строку запроса, которая обрезала список результатов, либо источник данных по какой-то причине не хотел возвращать полные результаты.
    • other — общее неопределенное предупреждение.
  • message — [ необязательно ] Короткая строка в кавычках, объясняющая проблему, возможно, используемая в качестве заголовка окна предупреждения. Это может быть показано пользователю. HTML не поддерживается.
  • detailed_message — [ Необязательно ] Подробное строковое сообщение в кавычках, объясняющее проблему и возможные решения. Единственный поддерживаемый HTML — это элемент <a> с одним атрибутом href . Поддерживается кодировка Unicode. Это может быть показано пользователю.

Пример: warnings:[{reason:'data_truncated',message:'Retrieved data was truncated'}]

ошибки
Требуется, если status=error

Массив из одного или нескольких объектов, каждый из которых описывает ошибку. Требуется, если status=error , в противном случае не допускается. Это похоже на значение warnings . Обратите внимание, что ошибка not_modified , хотя и является ошибкой, на самом деле не является ошибкой для клиента.

Массив имеет следующие строковые элементы (возвращает только одно значение для каждого элемента):

  • 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:'5982206968295329967'

стол
Нет

Объект DataTable в литеральной нотации JavaScript с вашими данными. Подробную информацию о формате этого объекта см. в связанном справочном разделе. Вот пример простой таблицы данных:

{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. Единственное отличие в том, как JSON обрабатывается API, заключается в том, что, хотя JSON не поддерживает значения даты JavaScript (например, «новая дата (2008,1,28,0,31,26)»), API поддерживает действительный JSON. представление дат в виде строки в следующем формате: Date(year, month, day[,hour, minute, second[, millisecond]]) где все после дня является необязательным, а месяцы отсчитываются от нуля .

Оптимизация ответов JSON

Если клиент делает два запроса, и данные между запросами не изменились, имеет смысл не отправлять данные повторно; это приведет к потере пропускной способности. Чтобы сделать запросы более эффективными, протокол поддерживает кэширование данных на клиенте и отправку сигнала в ответе, если данные не изменились с момента последнего запроса. Вот как это работает:

  1. Клиент отправляет запрос источнику данных.
  2. Источник данных генерирует DataTable , а также хеш объекта DataTable и возвращает оба в своем ответе (хэш возвращается в параметре tqx. sig ). Клиент Google Visualization API кэширует DataTable и значение sig .
  3. Клиент отправляет еще один запрос данных, включая кэшированное значение tqx.sig .
  4. Источник данных может ответить одним из двух способов:
    • Если данные изменились по сравнению с предыдущим запросом, источник данных отправляет обратно новый DataTable и новый хеш значения sig .
    • Если данные не изменились по сравнению с предыдущим запросом, источник данных отправляет обратно status=error , reason=not_modified , sig= old_sig_value .
  5. В любом случае страница, на которой размещена диаграмма, получает успешный ответ и может получить DataTable , вызвав QueryResponse.getDataTable() . Если данные одинаковы, это будет просто кэшированная версия таблицы.

Обратите внимание, что это работает только для запросов JSON из диаграмм, созданных на основе API визуализации Google.

Формат ответа CSV

Если в запросе указан out:csv , ответ не содержит метаданных, а просто представляет данные в формате CSV. Таблица CSV обычно представляет собой список, разделенный запятыми, где каждая строка данных представляет собой список значений, разделенных запятыми, заканчивающийся символом новой строки UNIX (\n). Значения ячеек должны иметь один и тот же тип для каждого столбца. Первая строка — это метки столбцов. Вот пример таблицы из трех строк и трех столбцов:

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

Формат CSV не указан в этом протоколе; источник данных отвечает за определение формата CSV. Однако общий формат — это набор значений, разделенных запятыми (без промежуточных пробелов), и символ новой строки (\n) в конце каждой строки. Когда браузер получает ответ в виде строки CSV, он может спросить пользователя, какое приложение использовать, чтобы открыть строку, или может просто отобразить ее на экране. Библиотеки с открытым исходным кодом Java и Python предоставляют метод преобразования DataTable в строку CSV.

Если запрос включает элемент outFileName параметра tqx , вам следует попытаться включить указанное имя файла в заголовки ответа.

Объект google.visualization.Query не поддерживает запрос ответа в формате CSV. Если клиент хочет запросить CSV, вы можете встроить гаджет панели инструментов визуализации на свою страницу, или он может использовать собственный код для создания запроса, или вы можете предоставить ссылку, которая явно устанавливает свойство out:csv tqx , как показано на рис. следующий URL-адрес запроса:

Запрос

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 . Если запрос включает элемент outFileName параметра tqx , вам следует попытаться включить указанное имя файла в заголовки ответа.

Формат ответа HTML

Если в запросе указан out:html , ответом должна быть HTML-страница, определяющая HTML-таблицу с данными. Это полезно для отладки вашего кода, поскольку браузер может напрямую отображать ваш результат в читаемом формате. Вы не можете отправить запрос на ответ HTML с помощью объекта google.visualization.Query . Вы должны выполнить запрос на ответ 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 .

Простой запрос : возвращает основную информацию в виде таблицы из трех столбцов и четырех строк.

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

Простой запрос с обработчиком ответа: возвращает таблицу из трех столбцов и трех строк с разными типами данных.

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

Запрос с простой строкой запроса. Запрос одного столбца возвращает один столбец с четырьмя строками.

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). Обрабатывает запросы и ответы, создает таблицу ответов на основе предоставленных вами данных и реализует язык запросов SQL Google Chart Tools.
  • Библиотека источников данных Python (от Google) — создает таблицу ответов и генерирует синтаксис ответа. Не обрабатывает синтаксический анализ запроса или реализацию языка SQL-запросов Google Chart Tools .
  • MC-Google_Visualization (сторонняя) — это серверная библиотека PHP, которую можно использовать для реализации источника данных инструментов диаграмм для механизмов баз данных MySQL, SQLite и PostgreSQL с использованием PDO.
  • bortosky-google-visualization (сторонняя) — это вспомогательная библиотека для создания таблицы данных API визуализации Google для пользователей .NET.
  • GV Streamer (сторонний) — GV Streamer — это серверный инструмент, который может преобразовывать данные из разных источников в действительные ответы на запросы к диаграммам Google. GV Streamer поддерживает несколько языков (например, PHP, Java, .NET) и несколько источников необработанных данных (например, MySql).
  • TracGViz (сторонний) — TracGViz — это бесплатный инструмент с открытым исходным кодом, который предоставляет компоненты, позволяющие Trac использовать гаджеты диаграмм, а также реализует данные, управляемые Trac, в качестве источника данных Google Chart Tools.
  • vis-table (сторонняя) — библиотека, реализующая источник данных Google Chart Tools на PHP. Он состоит из трех основных частей. Сама реализация данных, анализатор языка запросов и форматировщики.
  • Реализация источника данных Google в Oracle PL/SQL (сторонняя сторона) — пакет Oracle PL/SQL, который позволяет Oracle серверировать источники данных непосредственно из базы данных. Таким образом, в основном вы можете использовать любой запрос Oracle в качестве источника данных Google Chart Tools (пакет вернет файл JSON с данными). Он имеет почти полную поддержку языка запросов Google.