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

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

Содержание

Аудитория

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

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

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

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

Обзор

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

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

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

• Используйте одну из следующих вспомогательных библиотек для обработки запроса и ответа и создайте возвращаемый объект DataTable. Если вы используете одну из этих библиотек, вам нужно написать только код, необходимый для того, чтобы ваши данные были доступны библиотеке в виде таблицы.
  • Библиотека источников данных Java — обрабатывает запросы и ответы, создает таблицу ответов на основе предоставленных вами данных и реализует язык запросов SQL Google Chart Tools.
  • Библиотека источников данных Python — создает таблицу ответов и генерирует синтаксис ответа. Не обрабатывает синтаксический анализ запроса или реализацию языка SQL-запросов Google Chart Tools .
    
    ИЛИ
    
    
• Напишите свой собственный источник данных с нуля, обработав запрос, создав 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») чувствительны к регистру. В таблице также указано, требуется ли отправлять параметр и, если он отправлен, необходимо ли вам его обрабатывать.

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

Формат ответа зависит от параметра 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, ...})"

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

{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

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

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.