Справочник по протоколу

Предупреждение . Эта страница посвящена старым API Google, API данных Google; это относится только к API, которые перечислены в каталоге API данных Google , многие из которых были заменены более новыми API. Для получения информации о конкретном новом API см. документацию по новому API. Информацию об авторизации запросов с помощью более нового API см. в разделе Аутентификация и авторизация учетных записей Google .

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

Дополнительные сведения о протоколе данных Google см. на странице обзора Руководства разработчика и в документе Основы протокола .

Аудитория

Этот документ предназначен для всех, кто хочет разобраться в деталях формата и протокола XML, используемых API-интерфейсами, реализующими протокол данных Google.

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

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

• оценка архитектуры протокола данных Google
• кодирование по протоколу без использования предоставленных клиентских библиотек
• написание клиентской библиотеки на новом языке

В этом документе предполагается, что вы понимаете основы XML, пространств имен, синдицированных каналов и запросов GET , POST , PUT и DELETE в HTTP, а также концепцию HTTP «ресурса». Дополнительные сведения об этих вещах см. в разделе «Дополнительные ресурсы» этого документа.

Этот документ не опирается на какой-либо конкретный язык программирования; вы можете отправлять и получать сообщения Google Data Protocol с помощью любого языка программирования, который позволяет отправлять HTTP-запросы и анализировать ответы на основе XML.

Детали протокола

В этом разделе описывается формат документа Google Data Protocol и синтаксис запроса.

Формат документа

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

Atom — это формат по умолчанию для протокола данных Google. Чтобы запросить ответ в другом формате, используйте параметр запроса alt ; дополнительные сведения см. в разделе Запросы запросов .

Примечание . Большинство фидов Google Data Protocol в формате Atom используют пространство имен Atom в качестве пространства имен по умолчанию, указав атрибут xmlns в элементе фида, как показано в примерах, приведенных в разделе Основы протокола . Таким образом, примеры в этом документе явно не указывают atom: для элементов фида в формате Atom.

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

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

В каждой из следующих таблиц выделенные элементы являются обязательными.

В следующей таблице показаны элементы фида протокола данных Google:

В следующей таблице показаны элементы фида результатов поиска Google Data Protocol. Обратите внимание, что протокол предоставляет некоторые элементы ответа OpenSearch 1.1 в каналах результатов поиска.

В следующей таблице показаны элементы записи протокола данных Google:

Запросы

В этом разделе описывается, как использовать систему запросов.

Принципы проектирования модели запроса

Модель запроса намеренно очень проста. Основные постулаты:

• Запросы выражаются в виде 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 . API-интерфейсы, реализующие протокол, устанавливают заголовок ответа Last-Modified на основе значения элемента <atom:updated> в возвращаемом веб-канале или записи. Клиент может отправить это значение обратно как значение заголовка запроса If-Modified-Since, чтобы избежать повторного получения содержимого, если оно не изменилось. Если содержимое не изменилось с момента If-Modified-Since, служба возвращает HTTP-ответ 304 (не изменено).

API-интерфейсы, реализующие протокол данных Google, должны поддерживать alt запросы; поддержка других параметров необязательна. Передача стандартного параметра, не понятого данной службой, приводит к ответу 403 Forbidden . Передача неподдерживаемого нестандартного параметра приводит к ответу 400 Bad Request . Информацию о других кодах состояния см. в разделе кодов состояния HTTP этого документа.

Стандартные параметры запроса приведены в следующей таблице. Все значения параметров должны быть закодированы в URL.

О запросах категории

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

http://example.com/jo?category=Fritz&category=2006

мы сделали возможным использование:

http://example.com/jo/-/Fritz/2006

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

Недостаток этого подхода заключается в том, что мы требуем от вас использования /-/ в запросах категорий этого типа, чтобы службы могли отличать запросы категорий от 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 и Data API (а также другие элементы, перечисленные в спецификации 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="http://www.w3.org/2005/Atom"
        xmlns:openSearch="http://a9.com/-/spec/opensearch/1.1/"
        xmlns:gd='http://schemas.google.com/g/2005'
        gd:etag='W/"C0QBRXcycSp7ImA9WxRVFUk."'>
  <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 gd:etag='W/"C0QBRXcycSp7ImA9WxRVGUo."'>
    <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 gd:etag='W/"C0QBRXrurSp7ImA9WxRVGUo."'>
    <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 в контексте API данных.

Управление версиями ресурсов (ETags)

Иногда вам нужно иметь возможность ссылаться на конкретную версию конкретной записи.

Это особенно важно в двух случаях:

• Выполнение «условного поиска», при котором ваш клиент запрашивает запись, а сервер отправляет запись, только если она изменилась с момента последнего запроса клиента.
• Обеспечение того, чтобы несколько клиентов случайно не перезаписали изменения друг друга. API данных делают это, делая обновления и удаления неудачными, если клиент указывает идентификатор старой версии для записи.

API данных Google обрабатывают оба этих случая с помощью ETags , стандартной части HTTP.

ETag — это идентификатор, указывающий конкретную версию конкретной записи. Сервер прикрепляет ETag к элементам входа и канала, которые он отправляет клиентам. Когда запись или фид изменяются, их ETag также меняется.

API данных Google предоставляют ETag в двух местах: в HTTP-заголовке ETag и в атрибуте gd:etag элементов <feed> и <entry> .

В API данных Google ETag обычно представляет собой строку букв и цифр, иногда также включающую дефисы и точки; строка обычно заключается в кавычки. (Кавычки являются частью ETag.) Например, вот ETag из записи API данных: "S0wCTlpIIip7ImA0X0QI" .

Есть два типа ETag: сильные и слабые. Строгие ETag идентифицируют конкретную версию конкретной записи и могут использоваться для предотвращения перезаписи изменений других клиентов. Слабые ETag в контексте API данных Google используются только для условного поиска. Слабый ETag всегда начинается с W/ . Например: W/"D08FQn8-eil7ImA9WxZbFEw."

Не все API данных Google поддерживают надежные ETag. Для тех, кто это делает, сильные ETag используются только для записей; ETag в фидах всегда слабые.

Вот пример фида (включая некоторые заголовки HTTP), полученного от службы, которая поддерживает надежные ETags:

GData-Version: 2.0
ETag: W/"C0QBRXcycSp7ImA9WxRVFUk."
...
<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='W/"C0QBRXcycSp7ImA9WxRVFUk."'>
  ...
  <entry gd:etag='"CUUEQX47eCp7ImA9WxRVEkQ."'>
    ...
  </entry>
</feed>

Клиентские библиотеки, поддерживающие API данных версии 2, прозрачно обрабатывают ETag за вас. Следующая информация предназначена для клиентов, не использующих клиентские библиотеки, и для читателей, интересующихся тем, как управление версиями обрабатывается на уровне протокола.

Примечание . Сведения о системе управления версиями ресурсов, используемой в API данных версии 1.0, см. в справочном руководстве по версии 1.0 .

Условный поиск

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

Чтобы выполнить такого рода условный поиск, отправьте HTTP-запрос GET , который включает HTTP-заголовок If-None-Match . В заголовке укажите ETag записи.

Вот пример заголовка If-None-Match :

If-None-Match: W/"D08FQn8-eil7ImA9WxZbFEw."

Когда сервер получает этот запрос, он проверяет, имеет ли запрошенная вами запись тот же ETag, что и указанный вами ETag. Если ETags совпадают, то запись не изменилась, и сервер возвращает код состояния HTTP 304 Not Modified .

Если ETag не совпадают, то запись была изменена с момента последнего запроса, и сервер возвращает запись.

Обновление записей

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

Когда ваш клиент извлекает данные из службы, которая поддерживает сильные ETag, каждая запись имеет ETag, который действует как уникальный идентификатор версии для этой версии этой записи.

Примечание . Обновление с использованием ETag работает только с надежными ETag. Для служб, предоставляющих слабые ETag, все обновления выполняются успешно, независимо от того, обновлял ли запись кто-то еще с момента ее получения; самое новое обновление всегда перезаписывает любые другие предыдущие обновления. Поэтому не отправляйте слабые ETag при обновлении или удалении; вы получите сообщение об ошибке, если вы это сделаете.

Поэтому, когда ваш клиент отправляет обновление в службу сильных ETags, ему необходимо указать, какую версию записи он обновляет. Есть два способа сделать это:

• Используйте HTTP-заголовок If-Match .
• Используйте атрибут gd:etag в элементе <atom:entry> .

Мы рекомендуем подход If-Match где это возможно.

Чтобы обновить запись с помощью If-Match , начните с получения записи, которую вы обновляете. Внесите необходимые изменения в запись, затем создайте новый запрос PUT , содержащий измененную запись. (Подробнее об используемых URL-адресах см. в документации по конкретной службе.)

Перед отправкой PUT добавьте заголовок HTTP If-Match , содержащий ETag из исходной записи:

If-Match: "S0wCTlpIIip7ImA0X0QI"

Затем отправьте запрос PUT .

Если обновление прошло успешно, сервер возвращает код состояния HTTP 200 OK и копию обновленной записи.

Если обновление завершается сбоем из-за того, что указанный вами ETag не соответствует текущему ETag в записи (что означает, что запись изменилась на сервере с момента ее последнего извлечения), то сервер возвращает код состояния HTTP 412 Precondition Failed .

Если вы не можете легко писать заголовки HTTP или у вас есть другие причины избегать использования заголовка If-Match , вы можете вместо этого использовать атрибут gd:etag .

Если вы не отправляете заголовок If-Match , сервер использует значение атрибута gd:etag обновленной записи в качестве подразумеваемого значения If-Match .

Чтобы переопределить систему управления версиями и обновить запись независимо от того, обновлял ли ее кто-то другой после того, как вы ее получили, используйте If-Match: * вместо указания ETag в заголовке.

Информацию о том, какие сервисы поддерживают надежные ETag, см. в Руководстве по миграции .

Удаление записей

Удаление записей, в которых используются надежные ETag, очень похоже на их обновление.

Чтобы удалить запись с сильным ETag, сначала вы извлекаете запись, которую хотите удалить, а затем отправляете запрос DELETE на URL-адрес редактирования записи.

Если вы хотите убедиться, что не удаляете запись, которая была изменена другим клиентом с момента ее извлечения, включите HTTP-заголовок If-Match , содержащий значение ETag исходной записи.

Если вы хотите переопределить систему управления версиями и удалить запись независимо от того, обновил ли ее кто-то другой после того, как вы ее извлекли, используйте If-Match: * вместо указания ETag в заголовке.

Если запись не имеет строгого ETag, то запрос DELETE всегда выполняется успешно.

Частичный ответ (экспериментальный)

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

Чтобы узнать, доступен ли частичный ответ для используемого вами продукта, см. документацию по его API.

Чтобы запросить частичный ответ, используйте параметр запроса fields , чтобы указать элементы или атрибуты, которые вы хотите вернуть. Вот пример:

http://www.example.com/feeds?fields=link,entry(@gd:etag,id,updated,link[@rel='edit']))

Ответ сервера содержит только элементы ссылки и записи для фида; элементы entry содержат только ETag, ID, обновленную информацию и информацию о ссылке редактирования. Синтаксис параметров запроса fields рассматривается в следующих разделах. Дополнительные сведения об ответе см. в разделе Обработка частичных ответов .

Примечание . Параметр запроса fields можно использовать с любым запросом, который возвращает данные. В дополнение к GET сюда входят POST и PUT (а также PATCH , который используется для выполнения частичных обновлений ). Однако параметр запроса fields влияет только на данные ответа; это не влияет на данные, которые вы должны предоставить, или на то, какие поля обновляются или создаются.

Краткое описание синтаксиса параметров полей

Формат значения параметра запроса fields основан на синтаксисе XPath; однако он поддерживает только подмножество допустимых выражений XPath. Поддерживаемый синтаксис приведен ниже, а дополнительные примеры приведены в следующем разделе.

• Используйте список, разделенный запятыми, чтобы выбрать несколько полей.
• Используйте a/b для выбора элемента b , вложенного в элемент a ; используйте a/b/c , чтобы выбрать элемент c , вложенный в b .
• Используйте префикс '@' для обозначения атрибута с заданным именем; опустите префикс '@' для ссылки на элемент.
• Примените условия поля для выбора элементов, соответствующих определенным критериям, поместив выражения в скобки " [ ] " после элемента, который вы хотите ограничить.

  Например, fields=entry[author/name='Elizabeth'] возвращает только записи ленты, автором которых является Элизабет.

• Укажите подселекторы полей для запроса только определенных атрибутов или подэлементов, поместив выражения в круглые скобки " ( ) " после любого выбранного элемента.

  Например, fields=entry(id,author/email) возвращает только идентификатор и адрес электронной почты автора для каждой записи фида.

• Вы можете разделить строки, используя двойные или одинарные кавычки .
  
  Чтобы избежать двойной или одинарной кавычки, повторите кавычку . Например, """Hello,"" he said" производит строку "Hello," he said , а '''Hello,'' he said' производит строку 'Hello,' he said .
• Вы можете использовать подстановочные знаки в выборе полей.

  Например, entry/gd:* выбирает все дочерние элементы entry в пространстве gd , а entry/@gd:* выбирает атрибуты дочерних элементов в том же пространстве имен.

Параметр запроса fields действует как выходной фильтр. Это означает, что частичный ответ вычисляется только после обработки остальной части запроса. Например, если вы также укажете параметр запроса max-results , чтобы указать, что вы хотите получить 20 результатов на страницу, то будут сгенерированы первые 20 результатов, и на их основе будет вычислен частичный ответ. Если спецификация fields не соответствует ни одной из первых 20 записей, выбранных запросом, вы получите пустой канал; вы не вернете первые 20 совпадающих записей.

Примечание. Не пытайтесь использовать условия поля в качестве селекторов запросов. То есть не пытайтесь получить полный фид и применять условия поля, чтобы отфильтровать интересующие элементы из очень большого набора данных. По возможности используйте другие параметры запроса, такие как start-index и max-results , чтобы уменьшить результаты каждого запроса до управляемого размера. В противном случае прирост производительности, возможный при частичном отклике, может быть перевешен серьезным ухудшением производительности, вызванным неправильным использованием.

Форматирование значения параметра fields

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

Примечание. Как и все значения параметра запроса, значение параметра fields должно быть закодировано в URL-адресе. Для лучшей читаемости в приведенных ниже примерах кодировка не используется.

Определите поля, которые вы хотите вернуть, или выберите поля .

Значение параметра запроса fields представляет собой список разделенных запятыми элементов или атрибутов (совместно называемых полями ), и каждое поле указывается относительно корневого элемента представления ресурса. Таким образом, если вы получаете ленту, поля указываются относительно элемента <feed> , а если вы получаете одну запись, поля указываются относительно элемента <entry> . Если выбранный вами элемент является (или является его частью) повторяющимся элементом в ленте, служба возвращает все экземпляры этого элемента.

Вот несколько примеров на уровне фида:

Примеры	Эффект
entry	Возвращает все элементы <entry> и все подэлементы этих записей, но не любые другие дочерние элементы <feed> .
id,entry	Возвращает как фид <id> , так и все элементы <entry> .
entry/title	Возвращает элемент <title> для всех записей канала. Всякий раз, когда возвращается вложенный элемент, ответ включает закрывающие теги для любого родительские элементы. Родительские теги не включают никаких других дочерних элементов или атрибутов, если только они не выбраны явным образом.
entry/author/uri	Возвращает только подэлемент <uri> элемента <author> для всех записей канала.
entry/*:rating	Возвращает только вложенные элементы с rating локального имени в любом пространстве имен для всех записей веб-канала.

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

Примеры	Эффект
author	Возвращает дочерний элемент <author> целевой записи.
@gd:etag	Возвращает атрибут etag целевой записи.
author/uri	Возвращает подэлемент <uri> элемента <author> для целевой записи.
media:group/media:*	Возвращает все подполя <media:group> в пространстве имен media для целевой записи.

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

По умолчанию, если в вашем запросе указан элемент, который встречается более одного раза, частичный ответ будет включать все экземпляры этого элемента. Однако вы также можете указать, что ответ должен включать только элементы, которые имеют определенное значение атрибута, или элементы, которые удовлетворяют другому условию, используя синтаксис « [ ] », как показано в примерах ниже. Дополнительные сведения см. в разделе о синтаксисе условия поля .

Примеры	Эффект
entry[link/@rel='edit']	Возвращает все записи фида, содержащие элемент <link> со значением атрибута rel , равным 'edit' .
entry/title[text()='Today']	Возвращает любые элементы <title> , встречающиеся в записях фида, если их содержимое — 'Today' .
entry/author[name='Jo']	Возвращает любые элементы <author> , встречающиеся в записях фида, если они имеют подэлемент <name> с содержимым 'Jo' .
author[name='Jo']	Возвращает элемент <author> в целевой записи, если он имеет подэлемент <name> с содержимым 'Jo' .

Запрашивайте только части выбранных элементов или используйте подвыборки полей .

По умолчанию, если в вашем запросе указаны определенные элементы, служба возвращает элементы целиком. Вы можете указать, что ответ должен включать только определенные подэлементы в пределах выбранных элементов. Вы делаете это, используя синтаксис подвыбора " ( ) ", как в примерах ниже.

Примеры	Эффект
entry/author(uri)	Возвращает только подэлемент <uri> для авторов в записях канала.
entry/author[name='Jo'](uri)	Возвращает только подэлемент <uri> элемента <author> для любых записей с именем автора 'Jo' .
entry(link(@rel, @href))	Возвращает только значения атрибутов rel и href для каждого элемента <link> в записях канала.
entry(title,link[@rel='edit'])	Возвращает только элементы <title> и <link> с атрибутами edit rel для каждой записи фида.
entry(title,author(uri)	Возвращает как элементы <title> , так и элементы <uri> автора для каждой записи фида.

Подробнее о синтаксисе условия поля

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

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

В следующей таблице показаны операторы XPath, которые поддерживаются для полевых условий, и приведены некоторые примеры.

Handling partial responses

After a server that supports partial response processes a valid request that includes the fields query parameter, it sends back an HTTP 200 OK status code along with the requested attributes or elements. If the fields query parameter has an error or is otherwise invalid, the server returns an HTTP 400 Bad Request status code.

The root element of the response is either <feed> or <entry> , depending on the target URI. The root element's content includes only the selected fields for that feed or entry, along with the enclosing tags for any parent elements.

The value of the the request's fields query parameter can be echoed back in two ways:

• The root element has a gd:fields attribute that shows value of the fields query parameter specified in the request.
• If the target URI is a feed, each editable entry has a gd:fields attribute that shows the portion of the fields selection that applies to it.

Note: In order to see these gd:fields attribute values in your partial response, you must include them in your fields query parameter specification. You can do this explicitly, using @gd:fields , or using the more general @gd:* , which also includes ETag information.

The following example query asks the server to return a document that contains only attributes in the gd namespace (at both the feed and entry level), as well as the feed ID, the title, and the edit link for each feed entry:

http://example.com/myFeed?fields=@gd:*,id,entry(@gd:*,title,link[@rel='edit'])

The server returns the following partial response, along with a 200 Successful HTTP status code:

<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='W/"DEAEQH47eCp7IWA9WxBVGUo."'
    gd:fields='@gd:*,id,entry(@gd:*,title,link[@rel='edit'])>
  <id>http://example.com/myFeed</id>
  <entry gd:etag='"EksPTg1Bfyp7IWA6WhJT"'
      gd:fields="@gd:*,title,link[@rel='edit']">
    <link rel='edit' href='http://example.com/myFeed/1/'/>
    <title>This year</title>
  </entry>
  <entry gd:etag='"EksPQA1Cdyp7IWA6WhJT"'
      gd:fields="@gd:*,title,link[@rel='edit']">
    <link rel='edit' href='http://example.com/myFeed/2/'/>
    <title>Last year</title>
  </entry>
  <entry d:etag='"EksPQAxHeCp7IWA6WhJT"'
      gd:fields="@gd:*,title,link[@rel='edit']">
    <link rel='edit' href='http://example.com/myFeed/3/'/>
    <title>Today</title>
  </entry>
</feed>

If the selected fields do not match anything, the service still returns a 200 Successful HTTP status code, but the partial response is an empty feed:

<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
  xmlns:gd='http://schemas.google.com/g/2005'
  gd:etag='W/"DEAEQH47eCp7IWA9WxBVGUo."'
  gd:fields='@gd:*,id,entry(@gd:*,title,link[@rel='edit'])>
</feed>

Partial update (Experimental)

Google products that support partial response and editable resources also allow you to use partial update . With partial update, you send only the fields you want to update, rather sending a modified version of the full resource representation. This lets your client application be more efficient when making updates, as well as when using partial response to retrieve data.

Instead of using PUT , however, you must use a PATCH request when making a partial update. The semantics for PATCH are powerful enough to let you add, replace, and delete specific fields for a particular entry, all with a single request.

To find out if partial update is available for the product you are using, refer to the product-specific documentation.

Submitting a partial update request

To submit a partial update request, you send an HTTP PATCH request to the same URL that you would normally use with PUT to update the resource. The body of the PATCH request is a partial <entry> element that specifies the fields you want to add or modify. The entry's gd:fields attribute indicates the fields you want to delete.

The server processes PATCH requests in a specific order:

1. It first removes from the resource representation the fields specified by the gd:fields attribute.

   The syntax for the gd:fields attribute is the same as for the fields query parameter used when requesting a partial response. See Supported syntax for more details.

2. It then merges into the existing resource representation the data provided in the body of the request.

   More details on how the data is merged are provided in Adding or updating fields below.

Note: Since the body of a PATCH request is not typically compliant with the Atom Syndication Format, the Content-Type you use with a PATCH request is application/xml .

Here is an example of a partial update request:

PATCH /myFeed/1/1/
Content-Type: application/xml

<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:fields='description'>
  <title>New title</title>
</entry>

This PATCH request makes the following changes to the resource representation stored on the server for the target URI's entry:

• Removes the <description> element.
• Updates the <title> element.

Semantics of a partial update request

The instructions below explain how to set up your PATCH request to delete, add, or update specific fields within an entry. A single PATCH request can perform any combination of these operations.

• Deleting fields. Use the <entry> element's gd:fields attribute to identify any fields you want deleted from the resource. The following sample request deletes the title and summary associated with an entry. However the request does not add or update any other data for the entry.

  PATCH /myfeed/1/1/
  Content-Type: application/xml
  
  <entry xmlns='http://www.w3.org/2005/Atom'
      xmlns:gd='http://schemas.google.com/g/2005'
      gd:fields='title,summary'/>
  

• Adding or updating fields. Use the body of the <entry> element to specify the data that you want to add or update for a resource. These fields are merged into the existing data for the resource, after any deletions are made, according to the following rules:

  • Fields not already present are added. If the resource data does not already specify a value for a field, then the field is added to the existing data. For example, if an entry does not have a title, and your PATCH request contains a <title> element, then the new title is added to the entry.

  • Fields already present are replaced or appended. The specific behavior for merging fields that are already specified in the resource data depends on the characteristics of the field:

    • Non-repeating fields are replaced. If the resource data already specifies a value for a non-repeating element, then the value you specify in the PATCH request replaces the existing value for that element. For example, in the example below, the new title replaces the existing title.

      PATCH /myFeed/1/1/
      Content-Type: application/xml
      
        <entry xmlns='http://www.w3.org/2005/Atom'
          xmlns:gd='http://schemas.google.com/g/2005'>
        <title>New Title</title>
      </entry>

      A more complex example is given below. For this example, assume that the entry can have only one author, and that the target resource already has values for the author's name and email address. Even though <author> element has two child fields, only the <name> element is present in the data provided. As a result, only that field's value is overwritten. The value of the <email> element, which is missing from the data provided, remains unchanged.

      PATCH /myfeed/1/1/
      Content-Type: application/xml
      
      <entry xmlns='http://www.w3.org/2005/Atom'
          xmlns:gd='http://schemas.google.com/g/2005'>
        <author>
          <name>New Name</name>
        </author>
      </entry>

    • Repeating fields are appended. If the resource data already specifies a value for a repeating element, then the new element you provide is added to the existing set of values.

      Note that there might be times when you want to do something other than add a new instance of a repeating element. For example, you might want to do one of the following:

      • Replace an entire list of repeating elements. You can delete all the repeating fields using the gd:fields attribute ( gd:fields='ns:accessControl' , for example) and provide a complete set of the replacement fields. Since all the existing elements are deleted first, the set of fields you provide do not conflict with any existing values when they are appended.

      • Replace one value in a set of existing values for a repeating element. In this case, simply remove the single element by defining the gd:fields value narrowly enough to avoid deleting other values that you want to keep. For example, to remove only an access control with an action of embed , you might use gd:fields='ns:accessControl[@action="embed"]' . Then you provide the single field that you want to replace it with in the body of the <entry> element:

        PATCH /myfeed/1/1/
        Content-Type: application/xml
        
        <entry xmlns='http://www.w3.org/2005/Atom'
            xmlns:gd='http://schemas.google.com/g/2005'
            gd:fields='ns:accessControl[@action="embed"]>
          <ns:accessControl action="embed" permission="allowed" />
        </entry>

Handling the response to a partial update

After processing a valid partial update request, the API returns a 200 OK HTTP response code. By default, the body of the response is the complete entry that you updated. The server updates ETag values when it successfully processes a PATCH request, just as it does with PUT .

If a PATCH request results in a new resource state that is syntactically or semantically invalid, the server returns an HTTP 400 Bad Request or 422 Unprocessable Entity HTTP status code, and the resource state remains unchanged. For example, if you attempt to delete a required field and do not provide a replacement, the server returns an error.

Note: It is important to understand how different fields relate to each other. It might be possible to put a resource into an inconsistent state by updating only part of mutually interdependent values. For example, it might be possible to update a start time to a later value than an end time. Although the API should return an error code, we recommend that you fully test these kinds of conditions to ensure consistency.

Alternate notation when PATCH is not supported

If your firewall does not allow PATCH , then do an HTTP POST request and set the override header to PATCH , as shown below:

POST /myfeed/1/1/
X-HTTP-Method-Override: PATCH
Content-Type: application/xml
...

Using partial response with partial update

You can use a partial response as the basis of a subsequent partial update request. If you do this, specify a fields query parameter that includes edit links, as well as @gd:* . This ensures that the partial response includes information like the ETag and gd:fields attribute values, which are important for subsequent requests.

Here is an example that returns a partial response that you could use as the basis for a future partial update:

http://example.com/myFeed/1/1/?fields=@gd:*,link[@rel='edit'](@href),gd:who

Сервер отвечает:

<?xml version='1.0' encoding='utf-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='"E0UKRAREeCp7IWA6WhJT"'
    gd:fields="@gd;*,link[@rel='edit'](@href),gd:who">
  <link href='http://example.com/myFeed/1/1/'/>
  <gd:who email='liz@gmail.com'/>
  <gd:who email='jo@gmail.com'/>
  <gd:who email='jane@gmail.com'/>
</entry>

Suppose that you want to remove the user with email 'jane@gmail.com' , add a user with email 'will@gmail.com' , and change the email for the user currently listed as 'jo@gmail.com' to 'josy@gmail.com' .

You can make these changes simply by starting with the results of the previous response, modifying only the fields that are different, and submitting the modified partial entry as the body of the PATCH request. For this example, the needed modifications are:

• Delete <gd:who email='jane'/> from the list of elements provided.
• Add <gd:who email='will@gmail.com'/> to the list of elements provided.
• Replace <gd:who email='jo@gmail.com'/> with <gd:who email='josy@gmail.com'/> .

The PATCH request based on the pevious partial response is shown below:

PATCH /myFeed/1/1/
Content-Type: application/xml

<entry gd:fields="@gd:*,link[@rel='edit'](@href),gd:who"
    gd:etag="FE8LQQJJeSp7IWA6WhVa">
  <link href='http://example.com/myFeed/1/1'/>
  <gd:who email='liz@gmail.com'/>
  <gd:who email='josy@gmail.com'/>
  <gd:who email='will@gmail.com'/>
</entry>

Note: This approach relies on the gd:fields and gd:etag (if supported) attributes being included in the partial response for the entry. The body of the partial entry must retain all fields and attribute that were present in the partial response — except for those you explicitly want to remove. You can update any of the existing fields in the body with new values, and you can include any new fields you want to add.

Аутентификация

When a client tries to access a service, it may need to provide the user's credentials to the service, to demonstrate that the user has the authority to perform the action in question.

The approach that a client should use for authentication depends on the type of client:

• A desktop application should use a Google-specific authentication system called Account Authentication for Installed Applications (also known as "ClientLogin"). (Web-based clients should not use this system.)
• A web-based client, such as a third-party front end to a Google service, should use a Google-specific authentication system called Account Authentication Proxy for Web-Based Applications (also known as "AuthSub").

In the ClientLogin system, the desktop client asks the user for their credentials, and then sends those credentials to the Google authentication system.

If authentication succeeds, then the authentication system returns a token that the client subsequently uses (in an HTTP Authorization header) when it sends Data API requests.

If authentication fails, then the server returns a 403 Forbidden status code, along with a WWW-Authenticate header containing a challenge applicable to the authentication.

The AuthSub system works similarly, except that instead of asking the user for their credentials, it connects the user to a Google service that requests credentials. The service then returns a token that the web application can use; the advantage of this approach is that Google (rather than the web front end) securely handles and stores the user's credentials.

For details about these authentication systems, see the Google Data APIs Authentication Overview or the Google Account Authentication documentation.

Session state

Many business logic implementations require session stickiness—keeping track of the state of a user's session.

Google tracks session state in two ways: using cookies, and using a token that can be sent as a query parameter. Both methods achieve the same effect. We recommend that clients support one of these session-state tracking methods (either one is sufficient). If a client doesn't support either of these methods, then that client will still work with Data APIs, but performance may suffer compared to clients that do support these methods. Specifically, if a client doesn't support these methods, then every request results in a redirect, and therefore every request (and any associated data) is sent to the server twice, which affects the performance of both the client and the server.

The Google client libraries handle session state for you, so if you use our libraries, you don't have to do anything to get session state support.

Дополнительные ресурсы

Вам могут пригодиться следующие сторонние документы:

• Comparison of Atom and RSS from intertwingly
• Обзор Atom от IBM
• Dublin Core extensions to RSS
• определения методов HTTP 1.1; спецификация для GET , POST , PUT и DELETE
• Определения кода состояния HTTP 1.1
• Как создать протокол REST
• Создание веб-сервисов в стиле REST
• Техническое введение в XML
• Пространства имен XML на примере
• ETag section of HTTP specification

Вернуться к вершине