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

Обзор

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

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

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. Что такое капча?
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. Какие языки программирования поддерживает клиентские библиотеки Google?
26. Как сообщить об ошибке или запросе функции для одной из клиентских библиотек данных Google?
27. Как включить параметры отладки в клиентских библиотеках?
28. Где я могу найти справочные документы для классов клиентской библиотеки?

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

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

---

Обзор

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

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

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

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

У меня есть запрос функции или отчет об ошибке. Где я должен публиковать?

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

Где я должен задать вопрос по конкретному API?

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

• G Suite (см. отдельные API в семействе G Suite)
• База
• Блогер
• Календарь
• Поиск кода
• Контакты
• Сайты Google
• Таблицы
• Список документов
• Федеративный вход / OpenID
• Финансы
• Здоровье
• Веб-альбомы Picasa
• Инструменты для веб-мастеров
• YouTube

Что такое JSON?

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

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

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

Должен ли я использовать XML? Доступны ли другие форматы данных?

Форматом данных по умолчанию для API данных Google является XML в форме фида Atom. Однако при запросе фида вы можете указать альтернативный формат, используя параметр запроса alt .

• alt=rss
  Данные ответа отформатированы как RSS-канал.
• alt=json или alt=json-in-script
  Возвращает JSON-представление XML-структуры фида Atom. Дополнительным преимуществом JSON является то, что его легче «анализировать» в клиентском коде JavaScript. В настоящее время использование JSON доступно только для чтения. Однако использование клиентской библиотеки JavaScript со службами Blogger , Контакты или Календарь позволяет как читать, так и записывать данные.

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

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

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

Почему вы используете REST?

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

Есть ли у вас какие-либо советы или краткий пример кода для решения распространенных проблем?

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

Есть ли в Gmail API данных?

Нет, но вы можете использовать ленту Gmail Atom с 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.

Google API	Наименование услуги
API данных Google Аналитики	analytics
API-интерфейсы G Suite (информация о домене и управление им)	apps
API данных Сайтов Google	jotspot
API данных Blogger	blogger
API данных поиска книг	print
API данных календаря	cl
API данных поиска кода Google	codesearch
API данных контактов	cp
API контента для покупок	structuredcontent
API данных списка документов	writely
API финансовых данных	finance
Фид Gmail Atom	mail
API данных о здоровье	health weaver (песочница H9)
API данных Карт	local
API данных веб-альбомов Picasa	lh2
API данных Викикомментариев	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?

Параметр scope необходим для AuthSub и OAuth 1, чтобы определить, к каким службам Google будет иметь доступ ваше приложение. Для получения подробной информации об OAuth 2.0 см. документацию для вашего конкретного API.

Google API	Имя службы входа в систему
API данных Google Аналитики	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 данных Викикомментариев	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 в сторонних веб-приложениях допустимо, но настоятельно не рекомендуется. Рекомендуется, чтобы веб-приложение никогда не запрашивало у пользователя его учетные данные для входа (это может быть подвержено отслеживанию). Вместо этого приложение должно хранить учетные данные пользователя на стороне сервера и иметь единую «служебную учетную запись», которая всегда используется для аутентификации в Google.

Что такое капча?

CAPTCHA (полностью автоматизированный публичный тест Тьюринга, позволяющий различать компьютеры и людей) — это тип теста «вызов-ответ», используемый для определения того, является ли пользователь человеком. Термин является товарным знаком Университета Карнеги-Меллона. Подробнее см. в Википедии . Мы внедрили CAPTCHA в ClientLogin.

Как сгенерировать тест CAPTCHA?

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

Должен ли я использовать ClientLogin в своем веб-приложении?

Нет, ClientLogin должен использоваться установленными приложениями на пользовательском оборудовании. Использование API ClientLogin в веб-приложениях небезопасно и настоятельно не рекомендуется.

Как узнать имя пользователя при использовании AuthSub/OAuth 1?

Поскольку вам предоставляется только токен от Google, который предоставляет доступ к фидам пользователей, вы можете не знать их имя пользователя. Это может создать проблему, если URL-адрес фида, который вы хотите использовать, содержит имя пользователя. В этом случае вы можете использовать специальное имя пользователя default , означающее «пользователь, чей токен аутентификации я использую».

Как использовать OAuth 1 с клиентскими библиотеками Google Data API?

См. статью Использование OAuth 1 с клиентскими библиотеками API данных Google .

Как использовать AuthSub с клиентскими библиотеками Google Data API?

См. статью Использование AuthSub с клиентскими библиотеками API данных Google .

Как использовать 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, и хотели бы поделиться ею с сообществом разработчиков API данных, опубликуйте сообщение в группе обсуждения API данных Google . Мы были бы рады получить известия от вас!

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

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

• Джава
• JavaScript
• .СЕТЬ
• PHP
• питон
• Цель-C

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

Как включить параметры отладки в клиентских библиотеках Google Data API?

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

Где я могу найти справочные документы для классов клиентской библиотеки?

Клиентская библиотека	Справочное руководство
Джава	Javadoc
JavaScript	JSdoc
.СЕТЬ	НДок
PHP	phpDoc
питон	Пидок

---

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

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

Ниже перечислены некоторые инструменты, но вы также можете прочитать статью On the Wire: Network Capture Tools for API Developers , в которой подробно описаны примеры WireShark и Fiddler.

Wireshark

Wireshark — это «анализатор сетевых протоколов». Он предоставляет возможность захвата сетевого трафика и анализа содержимого. Это очень полезно при отладке трафика, происходящего в библиотеках, где у вас нет прямого доступа к потокам HTTP-запросов и ответов. Трафик между вашим приложением и службами аутентификации не может быть проанализирован с помощью Wireshark, поскольку связь шифруется с использованием SSL. Wireshark также можно использовать для анализа трафика, захваченного с помощью таких инструментов, как tcpdump. Wireshark доступен от разработчиков как в виде исходного кода, так и в виде установщика Windows. Сторонние пакеты доступны для многих платформ.

Скрипач

Fiddler — это «прокси-сервер отладки HTTP». Если вы можете настроить свой код или среду выполнения для использования прокси-сервера для HTTP-трафика, Fiddler будет находиться между вашим приложением и службами данных Google, где он позволит вам проверять трафик. Fiddler 2 включает поддержку SSL. В настоящее время Fiddler доступен только для Windows.

CURL

cURL — это инструмент командной строки, который может выполнять запросы HTTP/HTTPS. Это очень полезно для быстрого тестирования взаимодействия со службой без предварительной настройки поддержки HTTP в вашем клиенте.

Как получить информацию журнала HTTP в клиентской библиотеке Java?

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

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

Как получить информацию журнала HTTP в клиентской библиотеке .NET?

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

Как включить кодировку gzip из фидов данных Google?

Чтобы получить закодированный gzip ответ от одного из API данных Google, вы должны сделать две вещи: установить заголовок «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 будет возвращать служебный документ, соответствующий синтаксису служебного документа AtomPub . Версия 1 API данных Google по-прежнему будет возвращать служебный документ, но она основана на более ранней черновой спецификации AtomPub (между двумя версиями есть изменения в синтаксисе и пространстве имен).