Основы протокола

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

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

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

Аудитория

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

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

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

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

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

Примеры

В следующих примерах показаны HTTP-запросы, которые вы можете отправить в универсальную службу напрямую с использованием протокола Google Data Protocol API, и результаты, которые вы можете получить. Примеры отправки запросов с использованием различных языков программирования см. в примерах и клиентских библиотеках для конкретных языков. Для получения информации об использовании протокола данных Google с определенными службами Google см. документацию по конкретной службе.

Запрос фида или другого ресурса

Предположим, что есть канал с именем /myFeed, и предположим, что в настоящее время он не содержит никаких записей. Чтобы увидеть его, отправьте на сервер следующий HTTP-запрос:

GET /myFeed

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

200 OK

<?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."'>
  <title>Foo</title>
  <updated>2006-01-23T16:25:00-08:00</updated>
  <id>http://www.example.com/myFeed</id>
  <author>
    <name>Jo March</name>
  </author>
  <link href='/myFeed' rel='self'/>
</feed>

Обратите внимание, что хотя канал не содержит записей, он содержит метаданные, такие как название и имя автора. Он также содержит идентификатор версии в виде HTTP ETag .

Вставка новой записи

Чтобы создать новую запись, отправьте запрос POST и укажите XML-представление новой записи:

POST /myFeed

<?xml version='1.0' encoding='utf-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'>
  <author>
    <name>Elizabeth Bennet</name>
    <email>liz@gmail.com</email>
  </author>
  <title type='text'>Entry 1</title>
  <content type='text'>This is my entry</content>
</entry>

Обратите внимание, что вы не предоставляете стандартные элементы Atom <id> , <link> или <updated> ; сервер создает их в ответ на ваш запрос POST . Также обратите внимание, что автор фида не обязательно должен совпадать с автором записи.

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

201 CREATED

<?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='"CUUEQX47eCp7ImA9WxRVEkQ."'>
  <id>http://www.example.com/id/1</id>
  <link rel='edit' href='http://example.com/myFeed/1/1/'/>
  <updated>2006-01-23T16:26:03-08:00</updated>
  <author>
    <name>Elizabeth Bennet</name>
    <email>liz@gmail.com</email>
  </author>
  <title type='text'>Entry 1</title>
  <content type='text'>This is my entry</content>
</entry>

Поиск строки

Чтобы выполнить полнотекстовый поиск определенной строки, при использовании службы, поддерживающей полнотекстовый поиск, отправьте запрос GET с параметром q . Дополнительные сведения о параметрах запроса см. в разделе Запросы запросов в справочном документе по протоколу.

GET /myFeed?q=This

Сервер отвечает фидом, содержащим все записи, соответствующие поисковой строке This . (В данном случае только один.)

200 OK

<?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/"S0wCTlpIIip7ImA0X0QI"'>
  <title>Foo</title>
  <updated>2006-01-23T16:26:03-08:00</updated>
  <id>http://www.example.com/myFeed</id>
  <author>
    <name>Jo March</name>
  </author>
  <link href='/myFeed' rel='self'/>
  <entry gd:etag='"CUUEQX47eCp7ImA9WxRVEkQ."'>
    <id>http://www.example.com/id/1</id>
    <link rel='edit' href='http://example.com/myFeed/1/'/>
    <updated>2006-01-23T16:26:03-08:00</updated>
    <author>
      <name>Elizabeth Bennet</name>
      <email>liz@gmail.com</email>
    </author>
    <title type='text'>Entry 1</title>
    <content type='text'>This is my entry</content>
  </entry>
</feed>

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

Чтобы обновить существующую запись, вам необходимо выполнить следующие шаги.

  1. Получите запись, которую вы хотите обновить.
  2. Измените его по желанию.
  3. Отправьте запрос PUT с обновленной записью в теле сообщения на URI редактирования записи. URI редактирования отображается в предыдущем примере как атрибут href элемента <link rel='edit'> .

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

В следующем примере мы меняем текст записи со старого значения («Это моя запись») на новое значение («Это моя первая запись».):

PUT /myFeed/1/1/

<?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='"CUUEQX47eCp7ImA9WxRVEkQ."'>
  <id>http://www.example.com/id/1</id>
  <link rel='edit' href='http://example.com/myFeed/1/'/>
  <updated>2006-01-23T16:28:05-08:00</updated>
  <author>
    <name>Elizabeth Bennet</name>
    <email>liz@gmail.com</email>
  </author>
  <title type='text'>Entry 1</title>
  <content type='text'>This is my first entry.</content>
</entry>

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

200 OK

<?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='"FkkOQgZGeip7ImA6WhVR"'>
  <id>http://www.example.com/id/1</id>
  <link rel='edit' href='http://example.com/myFeed/1/'/>
  <updated>2006-01-23T16:28:05-08:00</updated>
  <author>
    <name>Elizabeth Bennet</name>
    <email>liz@gmail.com</email>
  </author>
  <title type='text'>Entry 1</title>
  <content type='text'>This is my first entry.</content>
</entry>

Обратите внимание, что ETag изменился. Дополнительные сведения о версиях ресурсов см. в разделе Управление версиями ресурсов (ETags) справочного документа по протоколу.

Чтобы увидеть новую запись в контексте, снова запросите весь ресурс:

GET /myFeed

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

200 OK

<?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/"D08FQn8-eil7ImA9WxZbFEw."'>
  <title>Foo</title>
  <updated>2006-01-23T16:28:05-08:00</updated>
  <id>http://www.example.com/myFeed</id>
  <author>
    <name>Jo March</name>
  </author>
  <link href='/myFeed' rel='self'/>
  <entry gd:etag='"FkkOQgZGeip7ImA6WhVR"'>
    <id>http://www.example.com/id/1</id>
    <link rel='edit' href='http://example.com/myFeed/1/'/>
    <updated>2006-01-23T16:28:05-08:00</updated>
    <author>
      <name>Elizabeth Bennet</name>
      <email>liz@gmail.com</email>
    </author>
    <title type='text'>Entry 1</title>
    <content type='text'>This is my first entry.</content>
  </entry>
</feed>

Примечание. Если ваш брандмауэр не разрешает PUT , выполните HTTP POST и установите заголовок переопределения метода следующим образом:

X-HTTP-Method-Override: PUT

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

Чтобы удалить существующую запись, отправьте запрос DELETE , используя URI редактирования записи (предоставленный сервером в предыдущем примере).

Если ваш брандмауэр не разрешает DELETE , выполните HTTP POST и установите заголовок переопределения метода следующим образом:

X-HTTP-Method-Override: DELETE

Когда вы удаляете запись, вы можете выбрать, выполнять ли условное удаление (удалять только в том случае, если запись не изменилась с момента ее последнего извлечения) или безусловное удаление. Дополнительные сведения см. в разделе Управление версиями ресурсов (ETags) справочного документа по протоколу. Чтобы выполнить безусловное удаление, установите следующий заголовок HTTP:

If-Match: *

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

DELETE /myFeed/1/

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

200 OK

Выполните еще один GET , чтобы увидеть, что лента теперь не содержит записей:

GET /myFeed

Сервер отвечает лентой, которая не содержит ничего, кроме метаданных:

200 OK

<?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/"D0cERnk-eip7ImA9WBBXGEg."'>
  <title>Foo</title>
  <updated>2006-01-23T16:30:11-08:00</updated>
  <id>http://www.example.com/myFeed</id>
  <author>
    <name>Jo March</name>
  </author>
  <link href='/myFeed' rel='self'/>
</feed>

Если удаление не удается, то сервер отвечает кодом ошибки. Дополнительные сведения см. в разделе Коды состояния HTTP в справочном документе по протоколу.

Запрос частичных фидов или записей (экспериментальный)

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

Чтобы запросить частичный ответ , используйте параметр запроса fields , чтобы указать, какие элементы или атрибуты вы хотите вернуть. Дополнительные сведения см. в разделе «Частичный ответ» в справочном документе по протоколу.

В следующем примере запрашивается только идентификатор фида, а также автор и заголовок для каждой записи фида.

GET /myFeed?fields=id,entry(author)

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

200 OK

<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
  xmlns:gd='http://schemas.google.com/g/2005'>
  <id>http://www.example.com/myFeed</id>
  <entry>
    <author>
      <name>Elizabeth Bennet</name>
      <email>liz@gmail.com</email>
    </author>
    <title type='text'>Entry 1</title>
  </entry>
  <entry>
    <author>
      <name>Elizabeth Bennet</name>
      <email>liz@gmail.com</email>
    </author>
    <title type='text'>Entry 2</title>
  </entry>
</feed>

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

Примечание. Параметр запроса fields управляет только данными, отправляемыми обратно в ответ на запрос; это не влияет на данные, которые вы должны предоставить в теле запроса PUT , POST или PATCH .

Примеры для POST и PUT показаны ниже.

  • Когда вы делаете запрос POST для частичного ответа, вы все равно должны предоставить те же данные, как описано в разделе Вставка новой записи . В следующем примере запрашивается частичный ответ, содержащий только заголовок вновь созданной записи: 
    POST /myFeed?fields=title
      
...data...

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

    200 OK

<?xml version='1.0' encoding='utf-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'>
  <title type='text'>Entry 1</title>
</entry>
  • Когда вы делаете запрос PUT для частичного ответа, вы все равно должны предоставить измененную версию полного представления ресурсов, как описано в разделе Обновление записи. . В следующем примере запрашивается частичный ответ, содержащий только новое значение ETag измененной записи: 
    PUT /myFeed/1/1?fields=@gd:etag
  
...data...

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

    200 OK

<?xml version='1.0' encoding='utf-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'
  gd:etag='"FkkOQgZGeip7ImA6WhVR"'/>

Обновление определенных полей (экспериментально)

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

Чтобы использовать частичное обновление, вы отправляете запрос PATCH на тот же URI редактирования, который вы используете с PUT . Данные, которые вы отправляете с помощью PATCH должны соответствовать определенным соглашениям. Однако семантика достаточно гибкая, чтобы вы могли заменять данные в целевом ресурсе, добавлять к нему или даже удалять из него все с помощью одного запроса.

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

Дополнительные сведения об PATCH и его семантике см. в разделе «Частичное обновление» в справочном документе по протоколу.

В этом примере показан запрос частичного обновления, который изменяет заголовок записи:

PATCH /myFeed/1/1/

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

Когда сервер получает запрос PATCH , он сначала удаляет все поля, указанные в атрибуте записи gd:fields (если он присутствует); затем он объединяет любые данные, предоставленные в теле запроса, с целевым ресурсом. В этом примере элемент заголовка сначала удаляется из целевого ресурса; затем новое значение заголовка объединяется. По сути, этот запрос заменяет старый заголовок новым.

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

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

Разница между тем, как объединяются повторяющиеся и неповторяющиеся поля, показана в следующем примере, в котором к записи добавляется новый заголовок и автор без использования атрибута gd:fields для предварительного удаления любого из них.

PATCH /myFeed/1/1/

<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:edtag="EksPTg1Bfyp7IWA6WhJT">
  <title>A new title</title>
  <author>
    <name>Fitzwilliam Darcy</name>
    <email>darcy@gmail.com</email>
  </author>
</entry>

Поскольку представление частичной записи не имеет атрибута gd:fields , никакие поля не удаляются. Однако новые значения для элементов <title> и <author> объединяются с целевым ресурсом:

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

    Примечание. Не все API соответствуют стандарту Atom. Например, некоторые API допускают только один элемент <author> для каждой записи; другие наследуют автора записи с уровня фида, делая поле доступным только для чтения.

После обработки сервером действительного запроса PATCH он возвращает код состояния HTTP 200 вместе с копией полного представления обновленной записи.

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

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

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

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