Часто задаваемые вопросы

    Обзор

  1. Что такое API данных Google?
  2. У меня есть запрос на новую функцию или сообщение об ошибке. Где мне его разместить?
  3. Где мне следует задать вопрос по конкретному API?
  4. Что такое JSON?
  5. Обязательно ли использовать XML? Доступны ли другие форматы данных?
  6. Почему вы используете REST?
  7. Есть ли у вас какие-либо советы или короткие примеры кода для решения распространенных проблем?
  8. Есть ли у Gmail API данных?

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

  9. Каково имя службы в ClientLogin для каждого API данных?
  10. Когда пользователь выходит из приложения, необходимо ли информировать об этом серверы API?
  11. Имеет ли токен аутентификации ClientLogin срок действия?
  12. У меня есть общий вопрос по аккаунтам Google. Куда мне обратиться?
  13. Как выполнить аутентификацию в API?
  14. Какое значение следует использовать для параметра области действия AuthSub/OAuth 1?
  15. Существуют ли разные типы токенов AuthSub? Имеют ли токены срок действия?
  16. В чем основное отличие ClientLogin от AuthSub/OAuth 1?
  17. Могу ли я использовать аутентификацию ClientLogin в сторонних веб-приложениях?
  18. Что такое CAPTCHA?
  19. Как создать CAPTCHA-задание?
  20. Стоит ли использовать ClientLogin в моем веб-приложении?
  21. Как узнать имя пользователя при использовании AuthSub/OAuth 1?
  22. Как использовать OAuth 1 с клиентскими библиотеками Google Data API?
  23. Как использовать AuthSub с клиентскими библиотеками Google Data API?
  24. Как использовать ClientLogin с клиентскими библиотеками Google Data API?

    25. Клиентские библиотеки

  25. Какие языки программирования поддерживают клиентские библиотеки Google?
  26. Как сообщить об ошибке или запросить новую функцию для одной из клиентских библиотек Google Data?
  27. Как включить параметры отладки в клиентских библиотеках?
  28. Где я могу найти справочную документацию по классам клиентской библиотеки?

    29. Поиск неисправностей

  29. Какие есть хорошие инструменты для отладки HTTP?
  30. Как получить информацию журнала HTTP в клиентской библиотеке Java?
  31. Как получить информацию журнала HTTP в клиентской библиотеке .NET?
  32. Как включить кодирование gzip из каналов данных Google?
  33. Почему я вижу ошибку «Невозможно подключиться к sslv2» при использовании PHP-клиента?
  34. Как получить документ службы Atom, описывающий канал?

Обзор

Что такое API данных Google?

API Google Data — это API, основанный на протоколе Google Data . Протокол Google Data основан на форматах синдикации Atom 1.0 и RSS 2.0 , а также на протоколе публикации Atom (APP).

Протокол Google Data расширяет эти стандарты различными способами, используя встроенные в них механизмы расширения. Ленты соответствуют форматам синдикации Atom или RSS. Модель публикации соответствует протоколу публикации Atom.

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

У меня есть запрос на новую функцию или сообщение об ошибке. Где мне его разместить?
Посетите наш трекер проблем . Найдите свой запрос на функцию и отметьте его звёздочкой, чтобы добавить поддержку и получать обновления о его статусе.
Где мне следует задать вопрос по конкретному API?
Если вашей проблемы нет в списке или вам нужны дополнительные разъяснения, существуют группы обсуждения, посвященные каждому API данных Google:
Что такое JSON?

JSON относится к нотации объектов JavaScript .

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

Подробнее об использовании JSON с API Google Data .

Обязательно ли использовать XML? Доступны ли другие форматы данных?
Формат данных по умолчанию для API Google Data — XML в виде фида Atom. Однако при запросе фида можно указать альтернативный формат с помощью параметра запроса alt .
  • alt=rss
    Данные ответа отформатированы в виде RSS-канала.
  • alt=json или alt=json-in-script
    Возвращает JSON-представление XML-структуры фида Atom. Дополнительным преимуществом JSON является его более простой анализ в клиентском коде JavaScript. В настоящее время использование JSON доступно только в режиме чтения. Однако использование клиентской библиотеки JavaScript с сервисами Blogger , Contacts или Calendar позволяет как читать, так и записывать данные.

    Подробнее читайте о запросе и использовании каналов JSON .

  • alt=atom-in-script
    Аналогично alt=json-in-script , но результаты возвращаются в виде строки Atom XML, а не JSON.
  • alt=rss-in-script
    Аналогично alt=atom-in-script , но результаты возвращаются в виде строки RSS XML, а не Atom.

Подробнее об альтернативных форматах читайте в справочном руководстве Google Data .

Почему вы используете REST?
REST прост, легок, масштабируем и отлично подходит для представления и раскрытия данных.
Есть ли у вас какие-либо советы или короткие примеры кода для решения распространенных проблем?
Вам следует просмотреть блог Google Data API Tips Blog, где вы найдете помощь как с нашими клиентскими библиотеками, так и с выполнением необработанных запросов.
Есть ли у Gmail API данных?

Нет, но вы можете использовать ленту Atom Gmail с AuthSub или OAuth 1, чтобы запросить доступ только для чтения к непрочитанным сообщениям пользователя. Область действия должна быть установлена на https://mail.google.com/mail/feed/atom/ . Пример запроса:

GET https://mail.google.com/mail/feed/atom/

Если вы заинтересованы в управлении своей почтой, Gmail также поддерживает IMAP/POP .

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

В документации API данных Google «OAuth» относится к OAuth 1; подробности об OAuth 2.0 см. в документации по вашему индивидуальному API.

Каково имя службы в ClientLogin для каждого API данных?
«Имя службы» — это короткая строка, которую система аутентификации ClientLogin использует для идентификации службы Google.
API Google Название услуги
API данных Google Analytics analytics
API G Suite
(Информация о домене и управление им)		 apps
API данных Google Сайтов jotspot
API данных Blogger blogger
API данных поиска книг print
API данных календаря cl
API данных поиска Google Code codesearch
API данных контактов cp
API контента для покупок structuredcontent
API данных списка документов writely
API финансовых данных finance
Gmail Atom-канал mail
API данных о здоровье health
weaver (песочница H9)
API данных карт local
API данных веб-альбомов Picasa lh2
API данных Sidewiki annotateweb
API данных электронных таблиц wise
API инструментов для веб-мастеров sitemaps
API данных YouTube youtube

Дополнительную информацию о других параметрах, используемых в запросе ClientLogin, см. в документации ClientLogin .

Когда пользователь выходит из приложения, необходимо ли информировать об этом серверы API?
Нет, сообщать Google Data API о выходе пользователя из приложения необязательно. Однако, если вашему приложению больше не требуется использовать выданный токен AuthSub, оно должно отозвать его .
Имеет ли токен аутентификации ClientLogin срок действия?
Токен ClientLogin может действовать в течение 2 недель с даты выдачи, но этот срок зависит от сервиса и может быть короче.
У меня есть общий вопрос по аккаунтам Google. Куда мне обратиться?
Посетите Справочный центр аккаунтов Google.
Как выполнить аутентификацию в API?
Ваш HTTP-запрос должен включать заголовок Authorization, содержащий токен, полученный с помощью ClientLogin , AuthSub или OAuth 1 .
Какое значение следует использовать для параметра области действия AuthSub/Oauth 1?
Для AuthSub и OAuth 1 требуется параметр scope , чтобы определить, к каким сервисам Google будет иметь доступ ваше приложение. Подробную информацию об OAuth 2.0 см. в документации по вашему API.

API Google Имя службы ClientLogin
API данных Google Analytics https://www.google.com/analytics/feeds/
API данных Google Сайтов http(s)://sites.google.com/feeds/
API данных Blogger http://www.blogger.com/feeds/
API данных поиска книг http://www.google.com/books/feeds/
API данных календаря http(s)://www.google.com/calendar/feeds/
API данных контактов http(s)://www.google.com/m8/feeds/
API контента для покупок https://www.googleapis.com/auth/structuredcontent
API данных списка документов http(s)://docs.google.com/feeds/
API финансовых данных http://finance.google.com/finance/feeds/
Gmail Atom-канал https://mail.google.com/mail/feed/atom/
API данных о здоровье https://www.google.com/health/feeds/
https://www.google.com/h9/feeds/ (песочница H9)
API данных карт http://maps.google.com/maps/feeds/
API данных веб-альбомов Picasa http://picasaweb.google.com/data/
API переносимых контактов http://www-opensocial.googleusercontent.com/api/people
API данных Sidewiki http://www.google.com/sidewiki/feeds/
API данных электронных таблиц http(s)://spreadsheets.google.com/feeds/
API инструментов для веб-мастеров http://www.google.com/webmasters/tools/feeds/
API данных YouTube http://gdata.youtube.com
Существуют ли разные типы токенов AuthSub? Имеют ли токены срок действия?
Существует два типа токенов AuthSub. Первый — одноразовый токен, который предоставляется вашему веб-приложению через параметр запроса «token». Срок действия токена истекает после первого использования в сервисе, для которого он был выпущен, или при обмене на токен сеанса.

Срок действия токенов сеанса не истекает, если только токен не будет явно отозван пользователем или вызовом API AuthSubRevokeToken . Одноразовый токен можно обменять на токен сеанса, только если в исходном URL-адресе AuthSubRequest указано session=1 в качестве параметра запроса.
В чем основное отличие ClientLogin от AuthSub/OAuth 1?

AuthSub разработан для веб-приложений. Он обеспечивает безопасную передачу учётных данных пользователя напрямую из веб-браузера на серверы Google, а не через сторонний веб-сайт.

ClientLogin предназначен для установленных настольных приложений. Для этого запрашивающее приложение должно передать учётные данные пользователя в Google от его имени.

См. документацию по API аутентификации аккаунта Google .

Могу ли я использовать аутентификацию ClientLogin в сторонних веб-приложениях?
Использование ClientLogin в сторонних веб-приложениях допустимо, но настоятельно не рекомендуется. Рекомендуется, чтобы веб-приложение никогда не запрашивало у пользователя его учётные данные (это может быть подвержено перехвату). Вместо этого приложение должно хранить учётные данные пользователя на стороне сервера и иметь единую учётную запись службы (service-account), которая всегда используется для аутентификации в Google.
Что такое CAPTCHA?
CAPTCHA (полностью автоматизированный публичный тест Тьюринга для различения компьютеров и людей) — это тип теста типа «вызов-ответ», используемый для определения, является ли пользователь человеком. Термин зарегистрирован как торговая марка Университета Карнеги-Меллона. Подробнее см. в Википедии . Мы внедрили CAPTCHA в ClientLogin.
Как создать CAPTCHA-задание?
Для определения необходимости проверки CAPTCHA во время аутентификации используется собственный алгоритм. Повторные попытки аутентификации с неверными учётными данными часто приводят к необходимости проверки CAPTCHA.
Стоит ли использовать ClientLogin в моем веб-приложении?
Нет, ClientLogin должен использоваться приложениями, установленными на оборудовании пользователя. Использование API ClientLogin в веб-приложениях небезопасно и настоятельно не рекомендуется.
Как узнать имя пользователя при использовании AuthSub/OAuth 1?
Поскольку Google предоставляет вам только токен, предоставляющий доступ к лентам пользователя, вы можете не знать его имя пользователя. Это может создать проблему, если URL ленты, которую вы хотите использовать, содержит имя пользователя. В этом случае вы можете использовать специальное имя пользователя default , которое будет означать «пользователь, чей токен аутентификации я использую».
Как использовать OAuth 1 с клиентскими библиотеками Google Data API?
См. статью Использование OAuth 1 с клиентскими библиотеками Google Data API .
Как использовать AuthSub с клиентскими библиотеками Google Data API?
См. статью Использование AuthSub с клиентскими библиотеками Google Data API .
Как использовать ClientLogin с клиентскими библиотеками Google Data API?
См. статью Использование ClientLogin с клиентскими библиотеками Google Data API .

Клиентские библиотеки

Какие языки программирования поддерживают клиентские библиотеки Google?

Клиентские библиотеки Java , .NET , Python и Objective-C официально поддерживаются Google. Кроме того, наш партнёр Zend разработал клиентскую библиотеку PHP . Используя эти библиотеки, вы можете создавать запросы по протоколу Google Data, отправлять их сервису и обрабатывать ответы сервера. Существует также клиентская библиотека JavaScript , которая в настоящее время поддерживает только Blogger, Calendar и Google Contacts.

Если вы пишете клиентскую библиотеку на языке, отличном от Java, .Net, Python или Objective-C, и хотите поделиться ею с сообществом разработчиков Data API, опубликуйте её в группе обсуждения Google Data API . Мы будем рады вашим отзывам!

Как сообщить об ошибке или запросить новую функцию для одной из клиентских библиотек?

Информацию об ошибках или предложения по улучшению клиентских библиотек можно отправлять по следующим адресам:

После публикации сообщения об ошибке создайте тему на форуме разработчиков для соответствующего API.

Как включить параметры отладки в клиентских библиотеках Google Data API?
Информацию о включении отладки с помощью некоторых клиентских библиотек см. в следующей статье: Отладка клиентов Google Data API: исследование трафика из вашей программы.
Где я могу найти справочную документацию по классам клиентской библиотеки?
Клиентская библиотека Справочное руководство
Ява Javadoc
JavaScript JSdoc
.СЕТЬ Ндок
PHP phpDoc
Питон PyDoc

Поиск неисправностей

Какие есть хорошие инструменты для отладки HTTP?

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

Wireshark
Wireshark — это «анализатор сетевых протоколов». Он позволяет захватывать сетевой трафик и анализировать его содержимое. Он очень полезен для отладки трафика в библиотеках, где нет прямого доступа к потокам HTTP-запросов и ответов. Трафик между вашим приложением и службами аутентификации невозможно проанализировать с помощью Wireshark, поскольку соединение зашифровано с помощью SSL. Wireshark также можно использовать для анализа трафика, захваченного с помощью таких инструментов, как tcpdump. Разработчики Wireshark предлагают как исходный код, так и установщик для Windows. Существуют сторонние пакеты для многих платформ.
Скрипач
Fiddler — это «HTTP-отладочный прокси-сервер». Если вы можете настроить свой код или среду выполнения на использование прокси-сервера для HTTP-трафика, Fiddler станет посредником между вашим приложением и службами Google Data, позволяя вам анализировать трафик. Fiddler 2 поддерживает SSL. В настоящее время Fiddler доступен только для Windows.
cURL
cURL — это инструмент командной строки, который может выполнять HTTP/HTTPS-запросы. Он очень полезен для быстрого тестирования взаимодействия со службой без необходимости предварительной реализации поддержки HTTP в клиенте.
Как получить информацию журнала HTTP в клиентской библиотеке Java?

Клиентские библиотеки Java используют пакет java.util.logging для регистрации HTTP-запросов. Это позволит вам регистрировать заголовки запросов и ответов, а также коды состояния и URL-адреса запросов. В настоящее время он не регистрирует полные потоки запросов и ответов. Имя логгера, используемое для этих журналов, — com.google.gdata.client.http.HttpGDataRequest .

В случае возврата серверами кода ошибки генерируется исключение Exception. Классы исключений наследуют от com.google.gdata.util.ServiceException и включают открытый метод getResponseBody() . Подробнее см. в документации Javadoc .

Как получить информацию журнала HTTP в клиентской библиотеке .NET?
Библиотека .NET использует методы трассировки System.Diagnostics для регистрации пути выполнения, если трассировка включена. Кроме того, в случае ошибки генерируется исключение GDataRequestException . Исключение содержит строку ResponseString , позволяющую получить доступ к телу HTTP-ответа.
Как включить кодирование gzip из каналов данных Google?

Чтобы получить ответ, закодированный с помощью gzip, от одного из API Google Data, необходимо выполнить два действия: установить заголовок «Accept-Encoding» и изменить пользовательский агент, добавив строку «gzip». Пример правильно сформированных заголовков:

User-Agent: my program (gzip)
Accept-Encoding: gzip
Почему я вижу ошибку «Невозможно подключиться к sslv2» при использовании PHP-клиента?

С июля 2009 года мы начали отключать SSLv2 на наших серверах в качестве меры предосторожности для повышения безопасности. К сожалению, в ранних версиях клиентской библиотеки PHP, выпущенных до июля 2007 года (версия 1.0.0 и более ранние), есть ошибка, которая заставляет соединения использовать SSLv2. При подключении к серверу, на котором SSLv2 отключен, возникает следующая ошибка:

PHP Fatal error:  Uncaught exception 'Zend_Http_Client_Adapter_Exception' with message 'Unable to Connect to sslv2://www.google.com:443.'

Чтобы исправить эту ошибку, обновите клиентскую библиотеку PHP до более новой версии, доступной по адресу http://framework.zend.com/download .

Если вы не можете выполнить обновление до более новой версии, вы можете исправить это, добавив в свое приложение следующий код, где $gdata — ваш существующий экземпляр Zend_Gdata (или соответствующий подкласс):

$gdata->getHttpClient()->setConfig(array('ssltransport' => 'ssl'));
Как получить документ службы Atom, описывающий канал?

Вы можете получить сервисный документ Atom, передав параметр alt=atom-service в запрос. Примечание: Только версия 2 API Google Data возвращает сервисный документ, соответствующий синтаксису сервисного документа AtomPub . Версия 1 API Google Data по-прежнему возвращает сервисный документ, но он основан на более раннем проекте спецификации AtomPub (между двумя версиями есть изменения в синтаксисе и пространстве имён).