Основы протокола API данных Google

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

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

Аудитория

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

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

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

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

Примеры

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

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

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

GET /myFeed

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

200 OK

<?xml version="1.0"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <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>

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

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

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

POST /myFeed

<?xml version="1.0"?>
<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"?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <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"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <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>
    <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>
</feed>

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

Чтобы обновить существующую запись, используйте PUT с URI редактирования записи (предоставленным сервером в предыдущем примере в элементе <link rel="edit"> ).

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

X-HTTP-Method-Override: PUT

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

PUT /myFeed/1/1/

<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <id>http://www.example.com/id/1</id>
  <link rel="edit" href="http://example.com/myFeed/1/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"?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <id>http://www.example.com/id/1</id>
  <link rel="edit" href="http://example.com/myFeed/1/2/"/>
  <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>

Обратите внимание, что URI редактирования изменился; теперь он заканчивается на «/2/» вместо «/1/». Последнее число в URI редактирования — это номер версии. Дополнительные сведения о версиях см. в разделе Оптимистичный параллелизм справочного документа по протоколу.

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

GET /myFeed

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

200 OK

<?xml version="1.0"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <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>
    <id>http://www.example.com/id/1</id>
    <link rel="edit" href="http://example.com/myFeed/1/2/"/>
    <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>

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

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

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

 X-HTTP-Method-Override: DELETE

В следующем примере удаляется запись:

DELETE /myFeed/1/2/

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

200 OK

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

GET /myFeed

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

200 OK

<?xml version="1.0"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <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 в справочном документе по протоколу.

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

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

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