В этом документе описывается протокол, используемый API данных Google, включая информацию о том, как выглядит запрос, как выглядят результаты и т. д.
Дополнительную информацию об API данных Google см. в документе «Руководство разработчика данных Google» и в Руководстве по протоколу .
Аудитория
Этот документ предназначен для всех, кто хочет разобраться в деталях формата и протокола XML, используемых API данных Google.
Если вы просто хотите написать код, который использует клиентские API данных Google, вам не нужно знать эти подробности; вместо этого вы можете использовать клиентские библиотеки для конкретного языка.
Но если вы хотите понять протокол, прочтите этот документ. Например, вы можете прочитать этот документ, чтобы помочь вам с любой из следующих задач:
- оценка архитектуры данных Google
- кодирование с использованием протокола без использования предоставленных клиентских библиотек Google Data
- написание клиентской библиотеки на новом языке
В этом документе предполагается, что вы понимаете основы XML, пространств имен, синдицированных каналов и запросов GET , POST , PUT и DELETE в HTTP, а также концепцию HTTP «ресурса». Дополнительные сведения об этих вещах см. в разделе «Дополнительные ресурсы» этого документа.
Этот документ не опирается на какой-либо конкретный язык программирования; вы можете отправлять и получать сообщения данных Google с помощью любого языка программирования, который позволяет отправлять HTTP-запросы и анализировать ответы на основе XML.
Детали протокола
В этом разделе описывается формат документа Google Data и синтаксис запроса.
Формат документа
Google Data, Atom и RSS 2.0 используют одну и ту же базовую модель данных: контейнер, который содержит как некоторые глобальные данные, так и любое количество записей. Для каждого протокола формат определяется базовой схемой, но его можно расширить с помощью внешних пространств имен.
API данных Google могут использовать формат синдикации Atom (как для чтения, так и для записи) или формат RSS (только для чтения).
Atom — это формат данных Google по умолчанию. Чтобы запросить ответ в формате RSS, используйте параметр /alt=rss/ ; дополнительные сведения см. в разделе Запросы запросов .
Когда вы запрашиваете данные в формате RSS, Google Data предоставляет фид (или другое представление ресурса) в формате RSS. Если для данного свойства данных Google нет эквивалентного свойства RSS, данные Google используют свойство Atom, помечая его соответствующим пространством имен, чтобы указать, что это расширение для RSS.
Примечание . В большинстве фидов данных Google в формате Atom пространство имен Atom используется в качестве пространства имен по умолчанию. Для этого в элементе фида указывается атрибут xmlns . см. раздел примеров, где приведены примеры того, как это сделать. Таким образом, примеры в этом документе явно не указывают atom: для элементов фида в формате Atom.
В следующих таблицах показаны представления элементов схемы в Atom и RSS. Все данные, не упомянутые в этих таблицах, обрабатываются как обычный XML и отображаются одинаково в обоих представлениях. Если не указано иное, элементы XML в данном столбце находятся в пространстве имен, соответствующем этому столбцу. В этой сводке используется стандартная нотация XPath: в частности, косая черта показывает иерархию элементов, а знак @ указывает на атрибут элемента.
В каждой из следующих таблиц выделенные элементы являются обязательными.
В следующей таблице показаны элементы фида данных Google:
| Элемент схемы фида | Представление атома | RSS-представительство |
|---|---|---|
| Название фида | /feed/title | /rss/channel/title |
| Идентификатор фида | /feed/id | /rss/channel/atom:id |
| HTML-ссылка канала | /feed/link[@rel="alternate"] \[@type="text/html"]/@href | /rss/channel/link |
| Описание фида | /feed/subtitle | /rss/channel/description |
| Язык канала | /feed/@xml:lang | /rss/channel/language |
| Фид Авторские права | /feed/rights | /rss/channel/copyright |
| Автор фида | (Требуется в некоторых случаях; см. спецификацию Atom.) | /rss/channel/managingEditor |
| Дата последнего обновления фида | /feed/updated(формат RFC 3339) | /rss/channel/lastBuildDate(формат RFC 822) |
| Категория фида | /feed/category/@term | /rss/channel/category |
| Схема категорий корма | /feed/category/@scheme | /rss/channel/category/@domain |
| Генератор каналов | /feed/generator/feed/generator/@uri | /rss/channel/generator |
| Значок ленты | /feed/icon | /rss/channel/image/url (если нет логотипа, в этом случае значок не включается в ленту) |
| Логотип канала | /feed/logo | /rss/channel/image/url |
В следующей таблице показаны элементы фида результатов поиска данных Google. Обратите внимание, что Google Data раскрывает некоторые элементы ответа OpenSearch 1.1 в фидах результатов поиска.
| Элемент схемы фида результатов поиска | Представление атома | Представительство RSS/OpenSearch |
|---|---|---|
| Количество результатов поиска | /feed/openSearch:totalResults | /rss/channel/openSearch:totalResults |
| Индекс начала результатов поиска | /feed/openSearch:startIndex | /rss/channel/openSearch:startIndex |
| Количество результатов поиска на странице | /feed/openSearch:itemsPerPage | /rss/channel/openSearch:itemsPerPage |
В следующей таблице показаны элементы записи данных Google:
| Элемент схемы входа | Представление атома | RSS-представительство |
|---|---|---|
| Идентификатор записи | /feed/entry/id | /rss/channel/item/guid |
| Идентификатор версии записи | Опционально встраивается в EditURI (см. раздел «Оптимистичный параллелизм» в этом документе). | — |
| Название записи | /feed/entry/title | /rss/channel/item/title |
| Входная ссылка | /feed/entry/link | /rss/channel/item/link/rss/channel/item/enclosure/rss/channel/item/comments |
| Резюме записи | (Требуется в некоторых случаях; см. спецификацию Atom.) | /rss/channel/item/atom:summary |
| Вход Содержание | (Если нет элемента содержимого, то запись должна содержать хотя бы один элемент | /rss/channel/item/description |
| Автор записи | (Требуется в некоторых случаях; см. спецификацию Atom.) | /rss/channel/item/author |
| Категория входа | /feed/entry/category/@term | /rss/channel/item/category |
| Схема категории входа | /feed/entry/category/@scheme | /rss/channel/item/category/@domain |
| Дата публикации записи | /feed/entry/published(RFC 3339) | /rss/channel/item/pubDate(RFC 822) |
| Дата обновления записи | /feed/entry/updated(RFC 3339) | /rss/channel/item/atom:updated(RFC 3339) |
Запросы
В этом разделе описывается, как использовать систему запросов.
Принципы проектирования модели запроса
Модель запроса намеренно очень проста. Основные постулаты:
- Запросы выражаются в виде URI HTTP, а не в виде заголовков HTTP или части полезной нагрузки. Одним из преимуществ этого подхода является то, что вы можете ссылаться на запрос.
- Предикаты привязаны к одному элементу. Таким образом, невозможно отправить корреляционный запрос, такой как «найти все электронные письма от людей, которые отправили мне не менее 10 электронных писем сегодня».
- Набор свойств, на которые могут основываться запросы, очень ограничен; большинство запросов представляют собой просто запросы полнотекстового поиска.
- Порядок результатов зависит от реализации.
- Протокол естественно расширяем. Если вы хотите предоставить дополнительные предикаты или сортировку в своем сервисе, вы можете легко сделать это, введя новые параметры.
Запросы запросов
Клиент запрашивает службу данных Google, отправляя HTTP-запрос GET . URI запроса состоит из URI ресурса (называемого FeedURI в Atom), за которым следуют параметры запроса. Большинство параметров запроса представлены в виде традиционных ?name=value[&...] параметров URL. Параметры категории обрабатываются по-разному; см. ниже.
Например, если FeedURI — http://www.example.com/feeds/jo , вы можете отправить запрос со следующим URI:
http://www.example.com/feeds/jo?q=Darcy&updated-min=2005-04-19T15:30:00Z
Службы данных Google поддерживают HTTP Conditional GET . Они устанавливают заголовок ответа Last-Modified на основе значения элемента <atom:updated> в возвращаемом фиде или записи. Клиент может отправить это значение обратно как значение заголовка запроса If-Modified-Since, чтобы избежать повторного получения содержимого, если оно не изменилось. Если содержимое не изменилось с момента If-Modified-Since, служба данных Google возвращает HTTP-ответ 304 (не изменено).
Служба данных Google должна поддерживать запросы категории и alt запросы; поддержка других параметров необязательна. Передача стандартного параметра, не понятого данной службой, приводит к ответу 403 Forbidden . Передача неподдерживаемого нестандартного параметра приводит к ответу 400 Bad Request . Информацию о других кодах состояния см. в разделе кодов состояния HTTP этого документа.
Стандартные параметры запроса приведены в следующей таблице. Все значения параметров должны быть закодированы в URL.
| Параметр | Значение | Примечания |
|---|---|---|
q | Полнотекстовая строка запроса |
|
/-/ category | Фильтр категорий |
|
category | Фильтр категорий |
|
author | Автор записи |
|
alt | Альтернативный тип представления |
|
updated-min , updated-max | Границы даты обновления записи |
|
published-min , published-max | Границы на дату публикации статьи |
|
start-index | Отсчитываемый от 1 индекс первого извлекаемого результата |
|
max-results | Максимальное количество результатов, которые необходимо получить | Для любой службы, которая имеет значение max-results по умолчанию (чтобы ограничить размер фида по умолчанию), вы можете указать очень большое число, если хотите получать весь фид. |
| идентификатор записи | ID конкретной записи, которую необходимо получить |
|
О запросах категории
Мы решили указать несколько необычный формат для категорийных запросов. Вместо такого запроса:
http://example.com/jo?category=Fritz&category=2006
мы используем:
http://example.com/jo/-/Fritz/2006
Этот подход идентифицирует ресурс без использования параметров запроса и создает более чистые URI. Мы выбрали этот подход для категорий, потому что считаем, что запросы категорий будут наиболее распространенными запросами.
Недостаток этого подхода заключается в том, что мы требуем, чтобы вы использовали /-/ в запросах категорий, чтобы службы данных Google могли отличать запросы категорий от URI других ресурсов, таких как http://example.com/jo/MyPost/comments .
Ответы на запросы
Запросы возвращают фид Atom, запись Atom или RSS-канал, в зависимости от параметров запроса.
Результаты запроса содержат следующие элементы OpenSearch непосредственно под элементом <feed> или элементом <channel> (в зависимости от того, являются ли результаты Atom или RSS):
-
openSearch:totalResults - Общее количество результатов поиска по запросу (не обязательно все они присутствуют в ленте результатов).
-
openSearch:startIndex - Отсчитываемый от 1 индекс первого результата.
-
openSearch:itemsPerPage - Максимальное количество элементов, отображаемых на одной странице. Это позволяет клиентам создавать прямые ссылки на любой набор последующих страниц. Однако о возможной ловушке при использовании этого номера см. примечание относительно
start-indexв таблице в разделе Запросы запросов .
Лента ответов и записи Atom также могут включать любые из следующих элементов данных Atom и Google (а также другие элементы, перечисленные в спецификации Atom):
-
<link rel="http://schemas.google.com/g/2005#feed" type="application/atom+xml" href="..."/> - Указывает URI, по которому можно получить полный фид Atom.
-
<link rel="http://schemas.google.com/g/2005#post" type="application/atom+xml" href="..."/> - Указывает PostURI фида Atom (куда могут публиковаться новые записи).
-
<link rel="self" type="..." href="..."/> - Содержит URI этого ресурса. Значение атрибута
typeзависит от запрошенного формата. Если за это время никакие данные не изменились, отправка другого запроса GET на этот URI возвращает тот же ответ. -
<link rel="previous" type="application/atom+xml" href="..."/> - Указывает URI предыдущего фрагмента этого набора результатов запроса, если он разбит на фрагменты.
-
<link rel="next" type="application/atom+xml" href="..."/> - Указывает URI следующего фрагмента этого набора результатов запроса, если он разбит на фрагменты.
-
<link rel="edit" type="application/atom+xml" href="..."/> - Указывает EditURI записи Atom (куда вы отправляете обновленную запись).
Вот образец тела ответа на поисковый запрос:
<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns:atom="http://www.w3.org/2005/Atom"
xmlns:openSearch="http://a9.com/-/spec/opensearchrss/1.0/">
<id>http://www.example.com/feed/1234.1/posts/full</id>
<updated>2005-09-16T00:42:06Z</updated>
<title type="text">Books and Romance with Jo and Liz</title>
<link rel="alternate" type="text/html" href="http://www.example.net/"/>
<link rel="http://schemas.google.com/g/2005#feed"
type="application/atom+xml"
href="http://www.example.com/feed/1234.1/posts/full"/>
<link rel="http://schemas.google.com/g/2005#post"
type="application/atom+xml"
href="http://www.example.com/feed/1234.1/posts/full"/>
<link rel="self" type="application/atom+xml"
href="http://www.example.com/feed/1234.1/posts/full"/>
<author>
<name>Elizabeth Bennet</name>
<email>liz@gmail.com</email>
</author>
<generator version="1.0"
uri="http://www.example.com">Example Generator Engine</generator>
<openSearch:totalResults>2</openSearch:totalResults>
<openSearch:startIndex>0</openSearch:startIndex>
<entry>
<id>http://www.example.com/feed/1234.1/posts/full/4521614025009481151</id>
<published>2005-01-09T08:00:00Z</published>
<updated>2005-01-09T08:00:00Z</updated>
<category scheme="http://www.example.com/type" term="blog.post"/>
<title type="text">This is the title of entry 1009</title>
<content type="xhtml">
<div
xmlns="http://www.w3.org/1999/xhtml">This is the entry body of entry 1009</div>
</content>
<link rel="alternate" type="text/html"
href="http://www.example.com/posturl"/>
<link rel="edit" type="application/atom+xml"
href="http://www.example.com/feed/1234.1/posts/full/4521614025009481151"/>
<author>
<name>Elizabeth Bennet</name>
<email>liz@gmail.com</email>
</author>
</entry>
<entry>
<id>http://www.example.com/feed/1234.1/posts/full/3067545004648931569</id>
<published>2005-01-07T08:00:00Z</published>
<updated>2005-01-07T08:02:00Z</updated>
<category scheme="http://www.example.com/type" term="blog.post"/>
<title type="text">This is the title of entry 1007</title>
<content type="xhtml">
<div
xmlns="http://www.w3.org/1999/xhtml">This is the entry body of entry 1007</div>
</content>
<link rel="alternate" type="text/html"
href="http://www.example.com/posturl"/>
<link rel="edit" type="application/atom+xml"
href="http://www.example.com/feed/1234.1/posts/full/3067545004648931569"/>
<author>
<name>Elizabeth Bennet</name>
<email>liz@gmail.com</email>
</author>
</entry>
</feed> Если запрошенный фид имеет формат Atom, параметры запроса не указаны и результат не содержит всех записей, в фид верхнего уровня вставляется следующий элемент: <link rel="next" type="application/atom+xml" href="..."/> . Он указывает на канал, содержащий следующий набор записей. Последующие наборы содержат соответствующий элемент <link rel="previous" type="application/atom+xml" href="..."/> . Перейдя по всем следующим ссылкам, клиент может получить все записи из фида.
Коды состояния HTTP
В следующей таблице описано, что означают различные коды состояния HTTP в контексте служб данных Google.
| Код | Объяснение |
|---|---|
| 200 ОК | Нет ошибки. |
| 201 СОЗДАН | Создание ресурса прошло успешно. |
| 304 НЕ ИЗМЕНЕНО | Ресурс не изменился с момента, указанного в заголовке запроса If-Modified-Since. |
| ОШИБКА 400, НЕВЕРНЫЙ ЗАПРОС | Неверный URI запроса или заголовок либо неподдерживаемый нестандартный параметр. |
| 401 НЕСАНКЦИОНИРОВАННЫЙ | Требуется Авторизация. |
| 403 ЗАПРЕЩЕНО | Неподдерживаемый стандартный параметр или сбой аутентификации или авторизации. |
| 404 НЕ НАЙДЕНО | Ресурс (например, фид или запись) не найден. |
| 409 КОНФЛИКТ | Указанный номер версии не соответствует последнему номеру версии ресурса. |
| 500 - ВНУТРЕННЯЯ ОШИБКА СЕРВЕРА | Внутренняя ошибка. Это код по умолчанию, который используется для всех нераспознанных ошибок. |
Оптимистичный параллелизм (управление версиями)
Иногда важно убедиться, что несколько клиентов случайно не перезаписывают изменения друг друга. Этого проще всего добиться, гарантируя, что текущая версия записи, которую модифицирует клиент, совпадает с версией, на которой клиент основывает свои модификации. Если второй клиент делает обновление до того, как это сделает первый клиент, то обновление первого клиента отклоняется, потому что первый клиент больше не основывает свои модификации на последней версии.
В фидах данных Google, которые поддерживают управление версиями, мы достигаем этой семантики, добавляя идентификатор версии к EditURI каждой записи. Обратите внимание, что затрагивается только EditURI, а не идентификатор записи. В этой схеме каждое обновление изменяет EditURI записи, тем самым гарантируя, что последующие обновления, основанные на исходной версии, не завершатся сбоем. Удаление, конечно, идентично обновлению в отношении этой функции; если вы отправляете удаление со старым номером версии, удаление завершается ошибкой.
Не все фиды данных Google поддерживают оптимистичный параллелизм. В фиде, который его поддерживает, если сервер обнаруживает конфликт версий при PUT или DELETE, сервер отвечает 409 Conflict . Тело ответа содержит текущее состояние записи (документ записи Atom). Клиенту рекомендуется разрешить конфликт и повторно отправить запрос, используя EditURI из ответа 409.
Мотивация и примечания к дизайну
Этот подход к оптимистичному параллелизму позволяет нам реализовать желаемую семантику, не требуя новой разметки для идентификаторов версий, что делает ответы Google Data совместимыми с конечными точками, отличными от Google Data Atom.
Вместо того, чтобы указывать идентификаторы версий, мы могли бы посмотреть метку времени обновления для каждой записи ( /atom:entry/atom:updated ). Однако есть две проблемы с использованием метки времени обновления:
- Он работает только для обновлений, а не для удаления.
- Это вынуждает приложения использовать значения даты и времени в качестве идентификаторов версий, что затруднит модернизацию данных Google поверх многих существующих хранилищ данных.
Аутентификация
Когда клиент пытается получить доступ к службе, ему может потребоваться предоставить службе учетные данные пользователя, чтобы продемонстрировать, что у пользователя есть полномочия для выполнения рассматриваемого действия.
Подход, который клиент должен использовать для аутентификации, зависит от типа клиента:
- Настольное приложение должно использовать специальную систему аутентификации Google, которая называется «Аутентификация учетной записи для установленных приложений» (также известная как «ClientLogin»). (Веб-клиенты не должны использовать эту систему.)
- Веб-клиент, например сторонний интерфейс службы данных Google, должен использовать специальную систему аутентификации Google, которая называется прокси- сервером аутентификации учетной записи для веб-приложений (также известной как AuthSub).
В системе ClientLogin настольный клиент запрашивает у пользователя его учетные данные, а затем отправляет эти учетные данные в систему аутентификации Google.
Если аутентификация проходит успешно, система аутентификации возвращает токен, который впоследствии использует клиент (в заголовке авторизации HTTP) при отправке запросов данных Google.
Если аутентификация не удалась, сервер возвращает код состояния 403 Forbidden вместе с заголовком WWW-Authenticate, содержащим запрос, применимый к аутентификации.
Система AuthSub работает аналогично, за исключением того, что вместо того, чтобы запрашивать у пользователя его учетные данные, она подключает пользователя к службе Google, которая запрашивает учетные данные. Затем служба возвращает токен, который может использовать веб-приложение; Преимущество этого подхода заключается в том, что Google (а не веб-интерфейс) безопасно обрабатывает и хранит учетные данные пользователя.
Подробнее об этих системах аутентификации см. в обзоре Google Data Authentication или в документации по аутентификации аккаунта Google .
Состояние сеанса
Многие реализации бизнес-логики требуют привязки сеанса — отслеживания состояния сеанса пользователя.
Google отслеживает состояние сеанса двумя способами: с помощью файлов cookie и с помощью токена, который можно отправить в качестве параметра запроса. Оба метода достигают одинакового эффекта. Мы рекомендуем клиентам поддерживать один из этих методов отслеживания состояния сеанса (достаточно любого из них). Если клиент не поддерживает ни один из этих методов, он по-прежнему будет работать со службами данных Google, но производительность может снизиться по сравнению с клиентами, поддерживающими эти методы. В частности, если клиент не поддерживает эти методы, каждый запрос приводит к перенаправлению, и поэтому каждый запрос (и любые связанные данные) отправляется на сервер дважды, что влияет на производительность как клиента, так и сервера.
Клиентские библиотеки Google обрабатывают состояние сеанса за вас, поэтому, если вы используете наши библиотеки, вам не нужно ничего делать, чтобы получить поддержку состояния сеанса.
Дополнительные ресурсы
Вам могут пригодиться следующие сторонние документы:
- Сравнение Atom и RSS от intertwingly
- Обзор Atom от IBM
- Расширения Dublin Core для RSS
- определения методов HTTP 1.1; спецификация для
GET,POST,PUTиDELETE - Определения кода состояния HTTP 1.1
- Как создать протокол REST
- Создание веб-сервисов в стиле REST
- Техническое введение в XML
- Пространства имен XML на примере