Работа с Bing API 2.0

С четвёртого февраля прошлого года поисковик Bing полностью перешёл на версию API 2.0. Работавший ранее поиск на сайте от Бинг через http://www.bing.com/siteowner, соответственно, перестал работать. Поэтому люди, которые используют функции майкрософтовского поисковика на своих сайтах были поставлены перед необходимостью перехода на новое API.

Некоторые шаги, например получение AppId, я уже рассматривал в статье «Перевод с помощью Bing Translation API«, теперь же я хочу остановится на описании API более подробно.

Bing API  2.0 позволяет вам встраивать гибкий и мощный поисковый движок как пользовательский поисковый компонент в ваши сайты и приложения. Эта версия включает в себя:

  • вызовы HTTP которые могут предоставлять результаты в XML или JSON форматах
  • Улучшенная поддержка SOAP
  • Полностью совместимый со спецификациями OpenSearch RSS-интерфейс, который даёт возможность доступа ко многим API информационных ресурсов

Bing API 2.0 облегчает работу с точками выхода в HTTP через вызовы GET-параметров протокола HTTP для отправки запросов.  Обычно работа из браузера с API включает в себя:

  • Получение AppID
  • Определение значения переменных для необходимых параметров
  • Работа с дополнительными параметрами
  • Выбор протокола
  • Отсылка запроса
  • Работа с результатом
  • Дополнительные образцы запросов
  • Парсинг результатов JSON

Определение значений для необходимых параметров.

Вместе с валидным AppID, запросы к любому интерфейсу API требуют два дополнительных параметра: Query и Sources.

Параметр Query это текст запроса, который вы хотите отправить на обработку через API. Для примера можно использовать текст «суши».

Параметр Sources представляет из себя одно или более значений, отображающих SourceType или SourceTypes откуда вы хотите запросить результаты. API включает в себя несколько различных SourceTypes, которые являются частью того, что  делает Bing  привлекательным  поисковым движком для ваших приложений. Для запроса из нескольких SourceTypes, разделяйте имена SourceType знаком «плюс» (+). Web SourceType возвращает набор результатов из Web SourceType. В добавок к типам Image и News, которые очень похожи на использование поиска Бинга онлайн. Есть еще некоторые типы, такие как  Spell и Related Search.

Сводная таблица типов:

Тип Описание Образец параметра запроса
Web Поиск веб-контента Суши
Image Поиск картинок в сети Суши
News Поиск новостей Суши
Spell Поиск по словарю Encarta для поисковых подсказок Кофе
Phonebook Поиск вхождений в телефонной книге Суши в Киеве
RelatedSearch Возвращает наиболее похожие запросы {Вкусное суши; суши ресторан; роллы}
Video Поиск видео в сети Суши

Для дальнейших примеров будет использоваться тип Web.

Для более подробной информации смотрите Working with SourceTypes в MSDN.

Дополнительные параметры

Вдобавок к параметрам из предыдущего раздела, каждый SourceType имеет опциональные параметры, которые можно использовать для уточнения вашего запроса. В процессе внедрения этих параметров рекомендую ознакомиться со всеми параметрами API на API Reference — MSDN.

Выбор протокола

Bing API 2.0 даёт вам возможность выбирать протокол, через поторый отправлять запросы. Здесь будут использоваться XML протокол вызовом через HTTP. Для более подробной информации посетите Choosing the Appropriate Protocol on MSDN.

Отправка запроса

Запрос через HTTP подразумевает работу через HTTP GET-запрос на определённые URI. Есть два URI, один для XML-результатов и второй для результатов JSON. Это http://api.bing.com/xml.aspx и http://api.bing.net/json.aspx, соответственно.

Пример запроса со словом «суши»:

http://api.bing.net/xml.aspx?Appid=<Ваш App ID !>&query=%D1%81%D1%83%D1%88%D0%B8&sources=web.

Разбор результатов

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

Образец результата

Образец результата

Тело результата следует за заголовком. Если использовался только один SourceType, будет только один дополнительный дочерний элемент SearchResponse после элемента Query, но их может быть больше, если использовалось несколько SourceTypes. Каждый тип имеет своё XML пространство имён URI (и, ко всесму прочему, свою схему), но все типы имеют общую структуру. На рисунке выше, из-за того что запрос был к Web SourceType, тело в элементе названо Web from
http://msdn.microsoft.com/en-us/library/dd250893.aspx

Работа с Total, Offset и Count

Элемент Web является родителем для двух элементов, которые классифицируются через пространство имён, но они общие для всех типов: Total и Offset. Элемент Total содержит конечное число результатов запроса в данном конкретном SourceType, пока Offset показывает как далеко зашла обработка результатов. Каждый SourceType имеет определённое количество результатов по-умолчанию, которое может быть изменено с помощью дополнительного параметра Count. Вы можете изменять Offset используя дополнительный параметр  Offset. В зависимости от того, насколько запрос популярен может изменяться и счётчик результатов. Не полагайтесь на это число в критичных вычислениях. Если вы будете использовать несколько SourceType, оба, Count и Offset должны быть определены в SourceType.

Для примера, если вы хотите запросить 40 результатов из Web SourceType, вам необходимо включить web.count=40 как часть строки запроса. Если вам необходимы следующие 40 результатов вам необходимо задать web.offset=41. Полный URI будет выглядеть так:

http://api.bing.net/xml.aspx?Appid=<AppID>&query=sushi&sources=web&web.count=40&web.offset=41.

Следующий рисунок показывает возвращаемый результат:

Обработка результатов из нескольких типов

Помните, что префиксы параметров Count и Offset необязательны, так как вы можете указать несколько SourceType. URL для формирования запроса по типам Web и Image будет выглядеть так:

http://api.bing.net/xml.aspx?Appid=<AppID>&query= %D1%81%D1%83%D1%88%D0%B8 &sources=web+image.

Следующий рисунок показывает возвращаемый результат:

Помните, что элемент Image имеет собственное пространство имён в URI. Оно также включает в себя дочерние элементы Total и Offset, но ограничено mms-префиксом (multimedia) пространства имён. Третий дочерний элемент любого XML-результата задаёт локальное имя результата  – снова ограничено пространством имён URI родителя.

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

Элемент результата является родителем для нескольких дочерних элементов, каждый из которых представляет определённый результат из определённого типа источника. Все эти дочерние элементы имеют заданные имена типов источника, таких как WebResult и ImageResult. Мы можете парсить эти результаты через  XML-процессинг API по вышему выбору, который определяется вышим языком программирования и предпочтениям.

Еще примеры запросов:

Здесь вы можете поэкспериментировать с различными источниками типов. Вам только необходимо заменить  <AppID> на ваш AppID.

http://api.bing.net/xml.aspx?Appid=<AppID>&query=sushi&sources=web

http://api.bing.net/xml.aspx?Appid=<AppID>&query=sushi&sources=image

http://api.bing.net/xml.aspx?Appid=<AppID>&query=sushi&sources=news

http://api.bing.net/xml.aspx?Appid=<AppID>&sources=spell&query=cofee

http://api.bing.net/xml.aspx?Appid=<AppID>&sources=phonebook&query=sushi in los angeles

http://api.bing.net/xml.aspx?Appid=<AppID>&sources=relatedqueries&query=sushi

Все приведённые запросы можно воспроизвести через браузер с поддержкой  XML API. Но лучше всего использовать программируемую среду разработки для непосредственного разбора результатов.

Всё просто: формируете запрос, посылаете его и обрабатываете результат.

Парсинг результатов JSON

Как было упомянуто выше, Bing API 2.0 может возвращать результаты в разных типах. Кроме XML, другой возможный тип, который возможно запросить через приложение — application/json — JavaScript Object Notation (JSON).

JSON это формат серализации который стал популярным по двум причинам:

  • У JSON меньший размер сериализации чем у XML (сбережение трафика, уменьшение процессорного времени на сериализацию\десерализацию).
  • Более натуральный, чем у XML формат, который позволяет строить AJAX-приложения с помощью JavaScript. (Это всё потому что XML-процессинг в большинстве реализаций JavaScript довольно сложен).

Принципы отправки JSON запроса примерно такие же как и при отправке XML-запроса. Но обработка результатов довольно-таки сильно отличается.

Используя запрос из предыдущего раздела, но отсылая JSON-запрос, мы получим следующий результат:

"SearchResponse":{ "Version":"2.0","Query":{"SearchTerms":"sushi"},"Web":{ "Total":15000000,"Offset":0,"Results":[{ "Title":"Sushi - Wikipedia, the free encyclopedia","Description":"In Japanese cuisine, sushi (寿司, 鮨, 鮓, sushi?) is vinegared rice, usually topped with other ingredients, including fish (cooked or uncooked) and vegetables.","Url":"http:\/\/en.wikipedia.org\/wiki\/Sushi","DisplayUrl":"http:\/\/en.wikipedia.org\/wiki\/Sushi","DateTime":"2008-06-09T06:42:34Z"}]}} /*pageview_candidate */}

URL для такого запроса будет

http://api.bing.net/json.aspx?Appid=<AppID>&query=sushi&sources=web.

Этот ответ можно разобрать как с помощью серверных языков программирования (PHP, Ruby), так и с помошью AJAX-приложения в браузере.

Великолепно для динамического разбора и встраивания подходит библиотека JavaScript jQuery. Не забывайте, что при динамическом разборе необходимо встроить тело ответа в DOM-дерево страницы. Можно использовать JSONP.

JSONP это техника встраивания JavaScript с другого веб-сайта в браузер. В следующем примере будет показан разбор JSON с помощью JavaScript:

Код JSONP Callback

if(typeof searchDone == 'function') searchDone({ "SearchResponse":{"Version":"2.0","Query":{ "SearchTerms":"sushi"},"Web":{"Total":15000000,"Offset":0,"Results":[ { "Title":"Sushi - Wikipedia, the free encyclopedia","Description":"In Japanese cuisine, sushi (寿司, 鮨, 鮓, sushi?) is vinegared rice, usually topped with other ingredients, including fish (cooked or uncooked) and vegetables.","Url":"http:\/\/en.wikipedia.org\/wiki\/Sushi","DisplayUrl":"http:\/\/en.wikipedia.org\/wiki\/Sushi","DateTime":"2008-06-09T06:42:34Z"}]}} /* pageview_candidate */});

Далее представлен полный HTML-код страницы

<html xmlns="http://www.w3.org/1999/xhtml" >
<head>
<link href="styles.css" rel="stylesheet" type="text/css" />
<title>Using Bing and JSON</title>
<script type="text/javascript">
function search() {
var search = "&query=" + document.getElementById("searchText").value;
var fullUri = serviceURI + AppId + search;
var head = document.getElementsByTagName('head');
var script = document.createElement('script');
script.type = "text/javascript";
script.src = fullUri;
head[0].appendChild(script);
}
function searchDone(results) {
var result = null;
var parent = document.getElementById('resultList');
parent.innerHTML = '';
var child = null;
for (var i = 0; i < results.SearchResponse.Image.Results.length; i++) {
result = results.SearchResponse.Image.Results[i];
child = document.createElement('li');
child.className = "resultlistitem";
child.innerHTML = '<a href="' + result.Url +'"><img src="' +
result.Thumbnail.Url +'" alt="' + result.Title +'" /></a>';
parent.appendChild(child);
}
}
var AppId = "&Appid=<YOUR APPID HERE!>";
var serviceURI =
"http://api.bing.net/json.aspx?JsonType=callback&JsonCallback=searchDone&sourc
es=image";
</script>
</head>
<body>
Type in a search:<input type="text" id="searchText" value="sushi"/>
<input type="button" value="Search!" id="searchButton" onclick="search()" />
<ul ID="resultList">
</ul>
</body>
</html>

Использование API с PHP

У PHP есть мощный механизм парсинга JSON, который из-за динамичности PHP, позволяет PHP-разработчикам удобно обращаться напрямую к JSON-объекту. Слудеющий пример показывает запрос, отсылаемый через  file_get_contents API  и возврат результатов JSON, которые превращаются в HTML-код

<html>
<head>
<link href="styles.css" rel="stylesheet" type="text/css" />
<title>PHP Bing</title>
</head>
<body><form method="post" action="<?php echo $PHP_SELF;?>">
Type in a search:<input type="text" id="searchText" name="searchText"
value="<?php
if (isset($_POST['searchText'])){
echo($_POST['searchText']); }
else { echo('sushi');}
?>"/>
<input type="submit" value="Search!" name="submit"
id="searchButton" />
<?php
if (isset($_POST['submit'])) {
$request =
'http://api.bing.net/json.aspx?Appid=<YourAppIDHere>&sources=image&query=' . urlencode( $_POST["searchText"]);
$response = file_get_contents($request);
$jsonobj = json_decode($response);
echo('<ul ID="resultList">');
foreach($jsonobj->SearchResponse->Image->Results as $value)
{
echo('<li><a href="' . $value->Url . '">');
echo('<img src="' . $value->Thumbnail->Url. '"></li>');
}
echo("</ul>");
} ?>
</form>
</body>
</html>

Доступ к Search через RSS

Вдобавок к  XML, JSON и SOAP интерфейсам, Bing API 2.0 позволяет обратиться к SourceType через механизм Web Feed в формате Really Simple Syndication (RSS). Вызов RSS полностью анонимен, он не требует AppID.

Для примера, вы можете послать запросить такой URI:

http://api.bing.com/rss.aspx?source=web&query=sushi+los%20angeles

Примечание: В этом формате вызов SourceType может осуществляться только в единественном числе («source»), а не  «sources» как в остальных случаях.

Данные возвращаются в RSS-формате, который понимает любой RSS-ридер.

Пример выполнения этого запроса в браузерах Opera и Internet Explorer

Помните, что RSS-формат Bing полностью совместим со стандартом Open Search 1.1

На этом пока всё, в этой статья я еще не привёл примеры использования .Net, Silverlight и многого другого. Если будет интересно — добро пожаловать в комментарии. :)

AD: Беспокоитесь о безопасности ребёнка в автомобиле? Avtobaby поможет вам в этом. Любите своего ребенка? Дорожите его здоровьем? Купите ему детское автокресло!

Постоянный адрес статьи Пинги запрещены.