Авторизация API

В этой документации приведены пошаговые инструкции по настройке OAuth 2.0 в вашем приложении для доступа к API, связанным с гостиницами, например Travel Partner API и Price Feeds API. Чтобы авторизовать приложение, ознакомьтесь со статьей Использование OAuth 2.0 для доступа к API Google.

Как настроить OAuth 2.0

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

Токены доступа действительны в течение часа (3600 секунд).

Если вы ранее использовали ClientLogin, то подход OAuth 2.0 будет вам знаком. Однако между ними есть следующие различия:

• Для доступа к API приложение использует сервисный аккаунт Google.
• При вызове API вы передаете токен доступа OAuth 2.0 в HTTP-заголовке Authorization.

Чтобы настроить аккаунт для использования OAuth 2.0 с любым Hotels API, выполните следующие действия:

1. Как создать проект в консоли Google Cloud

2. Как создать сервисный аккаунт и его учетные данные

3. Как предоставить сервисному аккаунту доступ к данным о гостиницах

Каждый из этих шагов описан в следующих разделах.

Шаг 1. Создайте проект в консоли Google Cloud

Консоль Google Cloud используется для управления и просмотра данных о трафике, аутентификации и платежных данных для API Google, которые используются в ваших проектах.

В Google Cloud Console проект – это набор настроек, учетных данных и метаданных, связанных с приложением, над которым вы работаете и которое использует Google Developer API и ресурсы Google Cloud.

Консоль Google Cloud также используется для создания учетных данных API, активации API и управления информацией о команде и платежными данными, связанными с вашим проектом.

Важно! Вы можете использовать один и тот же проект для нескольких Hotel API.

Чтобы создать проект в консоли Google Cloud:

1. Войдите в аккаунт Gmail или Google.

2. Откройте консоль Google Cloud. Если это ваш первый проект, в основном представлении будет кнопка Создать проект.

   

3. Нажмите кнопку Создать проект. В консоли Google Cloud откроется диалоговое окно New Project (Новый проект).

   

   В поле Project name (Название проекта) введите понятное название проекта. Под полем консоль Google Cloud сгенерирует для вас идентификатор проекта, который будет уникальным для всех проектов. Например, если вы введете "Мой новый проект", консоль Google Cloud назначит идентификатор my-new-project-266022.

4. Нажмите кнопку Создать.

5. В меню навигации выберите APIs & Services (API и сервисы) > Dashboard (Панель управления).

   

   На изображении ниже показано меню навигации в левом верхнем углу консоли Google Cloud. Откроется панель управления проекта.

   

Подробнее о создании проектов и управлении ими…

Шаг 2. Создайте сервисный аккаунт и сгенерируйте его учетные данные

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

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

1. В главном окне Google API Console нажмите Credentials (Учетные данные) на панели навигации слева. В консоли Google Cloud откроется раздел Учетные данные.

   В представлении Учетные данные показаны идентификаторы клиентов и учетные данные для вашего проекта. Идентификатор клиента используется приложением при запросе токена доступа OAuth 2.0. В новых проектах нет клиентов и учетных данных.

2. Нажмите на ссылку Credentials in APIs and services (Учетные данные в API и сервисах).

3. Нажмите кнопку Create credentials (Создать учетные данные) и выберите в фильтре Service account key (Ключ сервисного аккаунта). Откроется страница Создание ключа сервисного аккаунта.

4. В фильтре Сервисный аккаунт выберите Новый сервисный аккаунт.

5. Укажите название и идентификатор сервисного аккаунта.

   Название может быть любым, но идентификатор аккаунта должен быть уникальным для всех проектов. Консоль Google Cloud генерирует для вас уникальный идентификатор аккаунта на основе введенного вами имени.

6. В качестве типа ключа выберите JSON. Требуется JSON.

7. Нажмите кнопку Создать. Консоль Google Cloud создаст пару из закрытого и открытого ключей для вашего проекта. Закрытый ключ сохраняется в папке, которая используется в браузере для скачивания файлов по умолчанию. Скачайте файл в формате .JSON.

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

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

   Когда ключи будут созданы, в консоли Google Cloud появится сообщение "Сервисный аккаунт создан".

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

8. Нажмите кнопку ОК. Консоль Google Cloud возвращает вас на страницу Credentials (Учетные данные). Чтобы посмотреть сведения о сервисном аккаунте и узнать, какой сервисный аккаунт связан с вашим проектом, нажмите Управление сервисными аккаунтами.

   Теперь с сервисным аккаунтом связаны следующие учетные данные:

   • Идентификатор клиента. Уникальный идентификатор, который ваше приложение использует при запросе токена доступа OAuth 2.0.
   • Адрес электронной почты. Сгенерированный адрес электронной почты сервисного аккаунта в формате account_name@project_name.google.com.iam.gserviceaccount.com.
   • Цифровые отпечатки сертификатов. Идентификатор скачанного закрытого ключа.

Важно! При получении токена доступа для API используйте адрес электронной почты в качестве сервисного аккаунта. НЕ используйте для этого идентификатор клиента или отпечаток закрытого ключа.

Подробнее об использовании OAuth 2.0 для серверных приложений…

Шаг 3. Предоставьте сервисному аккаунту доступ к данным Hotel Center

Последний шаг – предоставить новому сервисному аккаунту доступ к Hotel Center. Сервисный аккаунт идентифицируется по адресу электронной почты, который вы создали на предыдущем шаге. Предоставить доступ к этому аккаунту можно в настройках доступа Hotel Center.

Если у вас нет прав на добавление пользователей в аккаунт, свяжитесь с командой поиска отелей в Google через форму обратной связи и запросите права владельца аккаунта. Вы можете запросить у владельца один или несколько адресов электронной почты. Подробнее о том, как связать Hotel Center и Google Рекламу…

Чтобы предоставить сервисному аккаунту доступ к данным Hotel Center, выполните следующие действия:

1. В новом окне браузера откройте Hotel Center.

2. На баннере Hotel Center от Google нажмите на значок добавления пользователя, чтобы открыть диалоговое окно доступа.

   

3. В поле Добавить пользователей введите адрес электронной почты сервисного аккаунта, который вы хотите добавить в Hotel Center.

4. Оставьте флажок Уведомить пользователей установленным.

5. В фильтре выберите Настроить.

6. Нажмите кнопку Пригласить.

7. После того как вы добавите пользователей в Hotel Center, доступ к API для вашего сервисного аккаунта будет включен в течение 24 часов.

После того как Google уведомит вас о том, что доступ к API для вашего сервисного аккаунта включен, вы сможете начать использовать API с OAuth 2.0.

Как использовать OAuth 2.0

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

Подробнее о том, как подготовить делегированный вызов API…

Области действия

Ниже перечислены SCOPES для Hotels API.

Travel Partner API: "https://www.googleapis.com/auth/travelpartner"

Price Feeds API: "https://www.googleapis.com/auth/travel-partner-price-upload"

При создании учетных данных необходимо указать сервисный аккаунт. Подробнее о том, как создать сервисный аккаунт и его учетные данные…

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

Важно! Если вы создаете несколько сервисных аккаунтов, им также необходимо предоставить доступ к аккаунтам Hotel Center.

Пример

from google.oauth2 import service_account
from google.auth.transport.requests import Request

# You can use a single or multiple scopes
SCOPES =
['https://www.googleapis.com/auth/travel-partner-price-upload','https://www.googleapis.com/auth/travelpartner']
SERVICE_ACCOUNT_FILE = 'service_account_key_file.json'

cred = service_account.Credentials.from_service_account_file(
                        SERVICE_ACCOUNT_FILE,
                        scopes=SCOPES)
cred.refresh(Request())
headers = {}
cred.apply(headers)

Travel Partner API

Travel Partner API позволяет партнерам по размещению получать информацию из Hotel Center и изменять данные в Hotel Center для управления крупными или сложными аккаунтами.

Чтобы получить авторизацию для Travel Partner API, следуйте инструкциям по настройке OAUTH 2.0.

При создании нового проекта для Travel Partners API необходимо включить доступ к новому проекту консоли Google Cloud.

Чтобы включить доступ к Travel Partners API, выполните следующие действия:

1. Перейдите на панель управления проекта.

2. Нажмите Enable APIs and Services (Включить API и сервисы). Откроется главная страница библиотеки API.

3. В строке поиска начните вводить "Travel Partner API". В консоли появится список API, соответствующих вашему запросу.

4. Выберите нужный API в таблице. В консоли Google Cloud появится описание этого API.

5. Нажмите кнопку Enable API (Включить API), чтобы включить этот API для своего проекта.

Подробнее о том, как включить или отключить сервис…

Travel Partner API будет включен для нового проекта в вашем аккаунте Google.

Область действия Travel Partner API: "https://www.googleapis.com/auth/travelpartner"

Конечная точка Travel Partner API: "https://travelpartner.googleapis.com/v3/accounts/<account_id>/<path>"

Важно! Travel Partner API доступен только доверенным партнерам. Если вы не можете найти API при его включении во время операции поиска, обратитесь к техническому менеджеру аккаунта (TAM).

Price Feeds API

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

Что важно помнить

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

1. Партнерам необходимо создать новый проект OAuth 2.0 для фидов с ценами в консоли Google Cloud, следуя инструкциям из статьи Настройка OAuth 2.0.

2. Включать Price Feeds API в консоли Google Cloud не требуется. Вам нужен только один сервисный аккаунт и ключ. С их помощью вы сможете предоставить проекту "Фид с ценами" доступ к данным Hotel Center. Выполните остальные шаги, описанные в разделе "Настройка OAuth 2.0", чтобы завершить настройку API.

Как получить токен доступа OAuth 2.0 для фидов с ценами

Следующий шаг – получить токен доступа OAuth 2.0 с областью загрузки цен на жилье, используя файл ключа сервисного аккаунта. Вы можете авторизовать запросы к проекту фидов с ценами, следуя инструкциям в разделе Подготовка к делегированному вызову API, а затем извлечь токен доступа из полученных учетных данных и установить его в HTTP-заголовке "Authorization".

Область действия для загрузки цен на жилье: "https://www.googleapis.com/auth/travel-partner-price-upload"

Загрузить цены

Получив токен доступа, партнеры могут загрузить фид с ценами так же, как при использовании статического IP-адреса для аутентификации и авторизации, но со следующим изменением:

• Укажите токен доступа в HTTP-заголовке "Authorization".

curl -X POST -H "Authorization: Bearer <access token>"
www.google.com/travel/lodging/uploads/accounts/<acc>ount_id/ota/hotel_rate_amount_notif --data-binary @<price_feed_file_location>

Как протестировать настройки OAuth 2.0 для Price Feeds API

Чтобы проверить настройки OAuth 2.0, загрузите пустой файл или файл с реальными ценами по любому из путей загрузки. Проверьте статус HTTP-ответа по таблице.

Статус HTTP-ответа	Сообщение
200	Successful (OK)
401	Service account creation or access token fetch was not successful
403	Service account access wasn't granted to the Hotel Center account or both the service account key and access token has expired

Устранение неполадок

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

1. Вы создали проект в консоли Google Cloud?
2. Вы включили сервис в проекте?
3. Скачали ли вы файл .JSON (закрытый ключ) после того, как нажали Создать идентификатор клиента и выбрали Сервисный аккаунт?
4. Получили ли вы адрес электронной почты идентификатора клиента сервисного аккаунта в таком формате: nnnnnnn@app_name.google.com.iam.gserviceaccount.com?
5. Предоставили ли вы сервисному аккаунту доступ к своему аккаунту Hotel Ads Center, нажав кнопку Открыть доступ к аккаунту?
6. Отправили ли вы адрес электронной почты сервисного аккаунта и идентификатор партнера техническому менеджеру аккаунта?
7. Передают ли вызовы API недавно полученный токен в заголовке Authorization?
8. Токен был создан более часа назад?

В таблице ниже перечислены распространенные ошибки и способы их устранения.

Ошибка	Описание
Invalid credentials	Это может означать следующее: Если вы столкнулись с этой ошибкой, проверьте следующее: Вы указали заголовок Authorization с действительным токеном на предъявителя. Токен на предъявителя был создан менее часа назад. Токен действителен только в течение одного часа. Вы указали правильное название партнера (с помощью параметра строки запроса partner ). Значение – это ваш уникальный идентификатор партнера, а не название партнера, которое отображается в Центре рекламы гостиниц. Если вы не знаете свой идентификатор партнера, обратитесь к техническому менеджеру аккаунта.
Not found	Скорее всего, конечная точка неправильно сформирована. Убедитесь, что вы отправляете запрос GET и что URL запроса действителен (соответствует синтаксису API, к которому вы пытаетесь получить доступ).
Invalid string value	Одна или несколько частей конечной точки содержат недопустимый синтаксис. Например, вы могли допустить опечатку в пути. Проверьте, правильно ли вы указали символы подчеркивания, заглавные буквы и слова в пути.
Unsupported output format	Чаще всего эта ошибка возникает при использовании Reports API. В URL запроса GET необходимо указать "alt=csv". Reports API не поддерживает JSON.
AccessTokenRefreshError/Invalid grant	При запуске приложения эта ошибка может возникать по следующим причинам: Адрес электронной почты сервисного аккаунта указан неверно. Проверьте аккаунт электронной почты в консоли Google Cloud и убедитесь, что у него есть доступ к API. У адреса электронной почты нет доступа к API. Проверьте, есть ли у этого адреса электронной почты доступ к данным о гостиницах, которые передаются через Hotel Center. Файл ключа не соответствует сервисному аккаунту. Скачайте новый сертификат .JSON в консоли Google Cloud и убедитесь, что ваше приложение указывает на правильный сертификат.
HotelAdsAPIConnection object has no attribute credentials	При запуске приложения путь к файлу .JSON указан неверно.
Invalid scope	При запуске приложения область действия API должна быть одной из следующих: "https://www.googleapis.com/auth/travelpartner" "https://www.googleapis.com/auth/travel-partner-price-upload"
Forbidden	У вас нет доступа к аккаунту с указанным идентификатором. Если вы владелец дочернего аккаунта, у вас может не быть доступа к идентификатору родительского или корневого аккаунта.