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

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

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

Аудитория

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

Если вы ищете руководство разработчика для определенного API, посетите каталог API протокола данных Google .

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

Фон

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

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

Если вы пишете код, который напрямую использует протокол данных Google, он обращается к API с помощью HTTP-запросов, таких как GET или POST . С помощью этих запросов данные, хранящиеся в продукте Google, передаются туда и обратно по сети в виде потоков данных. Каналы данных представляют собой просто структурированные списки, содержащие данные. Исторически основным форматом ленты был AtomPub XML, но теперь в качестве альтернативного формата доступен также JSON или нотация объектов JavaScript.

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

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

Версии протокола

Протокол версии 2.0 и протокол версии 1.0

Первая версия протокола данных Google была разработана до окончательной доработки протокола публикации Atom. Вторая версия протокола данных Google полностью соответствует стандарту AtomPub RFC 5023 .

Протокол данных Google версии 2.0 также поддерживает:

• ETag HTTP . Веб-стандарт, помогающий вашим клиентским приложениям лучше использовать кэширование HTTP. Службы, включенные в клиентские библиотеки, поддерживающие протокол версии 2.0, автоматически обрабатывают ETag.
• Частичный ответ и частичное обновление (экспериментальное) . Функции, которые позволяют выполнять запросы, передающие меньше данных. Запрашивая только ту информацию, которая вам действительно нужна, или отправляя обновления, содержащие только те данные, которые вы действительно хотите изменить, ваше клиентское приложение может намного эффективнее использовать ресурсы сети, ЦП и памяти. В настоящее время частичный ответ и частичное обновление доступны только для некоторых продуктов; см. документацию по конкретному продукту, чтобы узнать, поддерживает ли его ваш API.

Обновление вашего приложения

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

Обновление клиента на основе клиентской библиотеки

Если ваше клиентское приложение использует клиентскую библиотеку, например клиентскую библиотеку Java или клиентскую библиотеку .NET, оно может содержать версию API, поддерживающую функции протокола версии 2.0. Чтобы выяснить это, обратитесь к документации API для продукта Google, который вы используете, чтобы узнать, верны ли оба следующих утверждения:

• Существует версия API, которая поддерживает функции Google Data Protocol v2.0.
• Используемая вами клиентская библиотека также поддерживает эту версию API.

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

Обновление необработанного HTTP-клиента

Если вы написали свое клиентское приложение напрямую с использованием протокола данных Google, вам необходимо внести следующие изменения:

• Запросы версии не по умолчанию. Добавляйте заголовок версии HTTP ( GData-Version: X .0 ) к каждому отправляемому HTTP-запросу, где X — это версия API, которая поддерживает функции Google Data Protocol версии 2.0. В качестве альтернативы добавьте параметр запроса ( v= X .0 ) к URL-адресу каждого запроса, где X , опять же, правильная версия API. Если вы не укажете более позднюю версию, ваши запросы по умолчанию отправляются в самую раннюю поддерживаемую версию API.
• Оптимистичный параллелизм. Если вы использовали версию API, поддерживающую оптимистичный параллелизм, вам может потребоваться изменить обновление и удалить код для использования ETag. Дополнительные сведения см. в разделе ETags справочной документации по протоколу данных Google, а также в разделах «Обновление» и «Удалить» руководства разработчика протокола для службы, используемой вашим клиентским приложением.
• Самостоятельно или изменить URI. Если ваш клиент отслеживает себя или редактирует URI для фидов или записей, обратите внимание, что эти URI могли измениться. Чтобы получить новый URI, повторно запросите элемент, используя старый URI, но пометьте запрос как запрос версии X .0, где X — это версия API, которая поддерживает функции Google Data Protocol v2.0. Сервер возвращает новое представление записи, включая новые URI, которые вы можете сохранить вместо старых.
• URI пространства имен. Если ваш клиент хранит URI пространств имен Google Data Protocol API локально или имеет их жестко закодированные, вам необходимо обновить их:
  • Пространство имен AtomPub (префикс app ) было изменено с http://purl.org/atom/app на http://www.w3.org/2007/app .
  • Пространство имен OpenSearch (префикс openSearch ) было изменено с http://a9.com/-/spec/opensearchrss/1.0/ на http://a9.com/-/spec/opensearch/1.1/ .