API 授权

使用 OAuth 2.0 为您的应用授权 。

OAuth 2.0 设置

OAuth 2.0 要求您使用服务账号来表明自己的身份 与您的 Google 账号相关联。该服务账号会将您的 密钥来换取 OAuth 2.0 访问令牌。然后，您可以在 调用 Hotel API 以获取只读数据，例如定价、酒店和 与您的酒店价格 Feed 有关的诊断报告数据。

访问令牌的有效期为 1 小时（3,600 秒）。

如果您之前实施了 ClientLogin，则 OAuth 2.0 方法与之类似， 具体区别如下：

  • 您的应用使用 Google 服务账号来访问 API。
  • 在以下情况下，您会在 Authorization HTTP 标头中传递 OAuth 2.0 访问令牌： 调用 API。

如需设置您的账号以通过 Travel Partner API 使用 OAuth 2.0，请按以下步骤操作：

  1. 在 Google Developers Console (DevConsole) 中创建新项目

  2. 为新项目启用对 Travel Partner API 的访问权限

  3. 创建服务账号及其凭据

  4. 向服务账号授予对酒店数据的访问权限

后续几个部分将介绍其中每个步骤。

第 1 步：创建新的 DevConsole 项目

Google Developers Console（简称“DevConsole”）是 Google 为开发者提供的服务， 用于管理和查看流量数据、身份验证和结算信息 。

在 DevConsole 中，项目是一系列设置、凭据、 以及您正在开发的应用的相关元数据 它使用 Google Developer API 和 Google Cloud 资源。

在 DevConsole 中，您可以管理项目的这些方面，例如 生成 API 凭据、启用 API 以及管理团队和结算 与项目相关的信息

要创建新的 DevConsole 项目，请执行以下操作：

  1. 登录您的 Gmail/Google 账号。

  2. 打开 Google Developer Console。如果您是首次创建项目，主视图会显示 简单的 CREATE PROJECT 按钮：

    fig1

  3. 点击创建项目按钮。开发者控制台会显示 New Project 对话框：

    fig2

    在项目名称中，为新项目输入一个易记名称。 输入字段。在该字段下方，DevConsole 会为您生成一个项目 ID， 确保此 ID 在所有项目中都是唯一的。例如，如果您 输入“My New Project”后，开发者控制台会分配一个 ID，如 my-new-project-266022。

  4. 点击 Create 按钮以创建新项目。

  5. 在导航菜单中选择 API 和服务 >信息中心。

    fig3

    下图显示了左上角的导航菜单 “管理”部分系统将显示项目的信息中心视图：

    fig4

有关详情，请参阅在 Developers 控制台。

创建新项目时，该项目还没有任何关联的 API。在 下一步，您将为新项目启用 Travel Partner API。

第 2 步：为新项目启用 Travel Partner API

如需使用 Hotel API，您必须在新的 DevConsole 项目中启用 Travel Partner API。

如需为新项目启用 Hotel API，请执行以下操作：

  1. 按照上述说明，转到项目的“信息中心”视图。

  2. 点击启用 API 和服务。系统会显示 API 库欢迎界面 页面。

  3. 在搜索字段中，开始输入 Travel Partner API。 Google API 控制台会显示与您输入的内容相匹配的 API 列表。

  4. 点击匹配 API 表格中的 Travel Partner API。DevConsole 会显示有关 API 的说明。

  5. 点击启用 API 按钮，为您的项目启用此 API。

有关详情，请参阅激活和停用 API。

您 Google 账号的新项目现已启用 Hotel API。

下一步是创建服务账号并为其生成密钥。

第 3 步：创建服务账号并生成其凭据

服务账号用于服务器与服务器之间的互动，例如 Web 应用和您的酒店数据。

如需创建和配置服务账号，请执行以下操作：

  1. 在 Google API 控制台主视图中，点击凭据 “管理”部分DevConsole 会显示凭据视图。

    凭据视图会显示 项目。您的应用程序将在请求 OAuth 2.0 访问令牌。新项目将没有客户端或凭据 。

  2. 点击 API 和服务中的凭据链接。

  3. 点击创建凭据按钮，然后选择服务账号密钥 下拉列表系统随即会显示创建服务账号密钥视图。

  4. 从服务账号下拉列表中，选择新的服务账号。

  5. 输入服务账号名称和服务账号 ID。

    您可以任意设置名称，但账号 ID 必须是唯一的 跨所有项目。开发者控制台会为您生成一个唯一的账号 ID， 。

  6. 选择 P12 作为密钥类型，如下所示。必须提供 P12。

    fig5

  7. 点击创建按钮。DevConsole 生成私钥/公钥对 私钥会保存到 浏览器会存储下载内容您必须下载 .p12 格式（二进制），而不是 .json 文件格式。

    您在自己的脚本或其他访问 Travel Partner API。

    开发者控制台在完成生成 键：

    fig6

  8. 点击知道了按钮。开发者控制台会将您返回到 凭据视图。确认有关您的服务账号的详细信息 要查看与您的项目关联的服务账号，请点击管理 服务账号。

    该服务账号现在拥有以下关联的凭据：

    • 客户端 ID：您的应用在广告展示时使用的唯一标识符 请求 OAuth 2.0 访问令牌。
    • 电子邮件地址：为服务账号生成的电子邮件地址，位于 表单 “account_name@project_name.google.com.iam.gserviceaccount.com”。account_nameaccount_name
    • 证书指纹：您验证过的私钥的 ID 已下载。
。

有关详情，请参阅使用适用于服务器的 OAuth 2.0 服务器应用。

第 4 步：向服务账号授予对您 Hotel Center 数据的访问权限

最后一步是为新服务账号提供访问您的 Hotel Center。服务账号由 您在上一步中创建的代码您可以使用 Hotel Center 共享设置。

如需向服务账号授予对 Hotel Center 数据的访问权限，请执行以下操作：

如果您没有适当的访问权限，无法向账号添加用户，请联系 Google 酒店团队，使用与我们联系表单申请在以下地点设置所有权： 您的账号。您可以申请将一封或多封电子邮件发送给某个所有者。 如需详细了解 Hotel Center 访问权限，请参阅将 Hotel Center 和 Google Ads。

  1. 在新的浏览器窗口中，打开 Hotel Center。 fig7

  2. 在 Hotel Center by Google 横幅中，点击“添加用户”图标以打开 共享对话框。

    fig8

  3. 在添加更多人字段中，输入相应服务的电子邮件地址 账号。

  4. 让通知对方选项保持选中状态。

  5. 从下拉菜单中选择管理。

  6. 点击邀请按钮。

  7. 将用户添加到 Hotel Center 后，您的服务账号应 在大约 24 小时内即可启用 API 访问。

当 Google 通知您已为服务启用 API 访问权限后 您可以开始使用 OAuth 访问 API

使用 OAuth 2.0

要访问该 API，您的应用必须通过 服务账号生成的电子邮件地址和私钥。Google 的 身份验证机制使用该密钥交换 OAuth 2.0 访问令牌， 您在应用的 API 调用中传入 Authorization 标头。

访问令牌（也称为不记名令牌）是 OAuth 2.0 的一部分 标准。在 HTTP 标头中指定访问令牌的语法如下：

Authorization: Bearer *oauth2_access_token*

以下示例展示了访问 Reports API：

GET /travelpartner/v2.0/42000042/reports/top_opportunity_7_day HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer nd42.fdLSKkljD98344444444444lSDF42fdLSKkljD98344444444444lSDF42
Cache-Control: no-cache

要生成访问令牌，请使用您选择的任意语言创建应用。 以下示例在 Python 中生成令牌。然后，您可以使用 令牌Authorization 标头。Travel Partner API

#!/usr/bin/python2.7
#
""" Sample code to get an auth header that you can use in your HTTP requests
    1. Please see https://developers.google.com/api-client-library/python/start/installation
       to download and install the google-api-python-client package.
    2. Edit lines below marked _SERVICE_ACCOUNT, _KEY_FILE,  _PARTNER_NAME,
       and _API_VERSION.
    3. Run the program using: "python sample.py". The app returns the value that
       you use for the Authorization header's Bearer token in your request.
    4. Copy the token and use it in requests to the Travel Partner API.
       For example (2.0):
       https://www.googleapis.com/travelpartner/2.0/42000042/reports/budget
       For example (1.x):
       https://www.googleapis.com/travelpartner/1.2/reports?report_type=BUDGET
"""
import httplib2
import json
import os
import sys
import urllib

HAS_CRYPTO = False

from apiclient import discovery
from oauth2client.client import flow_from_clientsecrets
try:
  # Some systems may not have OpenSSL installed so can't use SignedJwtAssertionCredentials.
  from oauth2client.client import SignedJwtAssertionCredentials
  HAS_CRYPTO = True
except ImportError:
  print "Unable to import SignedJwtAssertionCredentials"

from oauth2client import tools
from oauth2client.file import Storage

# Authorization scope for our requests (do not change)
_DEFAULT_APISCOPE = 'https://www.googleapis.com/auth/travelpartner'

# Use the service account you set up in the Google Developers Platform.
# It will be of the form "gsaccount_name@project_name.google.com.iam.gserviceaccount.com".
_SERVICE_ACCOUNT = ('myserviceaccount@my-hotel-project.google.com.iam.gserviceaccount.com')

# Set this to the full path to your service account's private binary .p12 key file
# that you downloaded from the Google Developer's Console and stored in a secure place.
# DO NOT use the json version of the certificate.
_KEY_FILE = '../mylocaldir/api-keys/8482bb2bdb08.p12'

# Set this to the case-sensitive "Partner Key", NOT the account
# name in the Hotel Ads Center or the numeric partner ID.
# Check with your TAM if you do not know your "Partner Key" name.
_PARTNER_NAME = 'testpartner2'

class HotelAdsAPIConnection(object):
  def __init__(self, service_account=_SERVICE_ACCOUNT, key=_KEY_FILE, partner=_PARTNER_NAME):
    self.key_file = key
    self.account = service_account
    self.partner = partner

  def InitializeCredentials(self, scope):
    '''Get credentials for use in API requests.
    Generates service account credentials if the key file is present,
    and regular user credentials if the file is not found.
    '''
    if os.path.exists(self.key_file):
      if not HAS_CRYPTO:
        raise Exception("Unable to use cryptographic functions "
                        + "Try installing OpenSSL")
      with open (self.key_file, 'rb') as file:
        key = file.read();
      creds = SignedJwtAssertionCredentials(self.account, key, scope)
      self.credentials = creds

  def authorize(self):
    '''Construct a HTTP client that uses the supplied credentials.'''
    return credentials.authorize(httplib2.Http())

  def print_creds(self):
    '''Prints the Authorization header to use in HTTP requests.'''
    cred_dict = json.loads(self.credentials.to_json())

    if 'access_token' in cred_dict:
      print 'Authorization: Bearer %s' % (cred_dict['access_token'],)
    else:
      print 'creds: %s' % (cred_dict,)

  def GetConnection(self):
    http = httplib2.Http()
    self.credentials.refresh(http)
    http = self.credentials.authorize(http)
    self.print_creds()
    return http

def main(args):
  # Create an instance of the HotelAdsAPIConnection inner class
  api = HotelAdsAPIConnection()

  # Generate credentials
  api.InitializeCredentials(_DEFAULT_APISCOPE)

  # Output the Authorization header to use in HTTP requests
  api.GetConnection()

if __name__ == "__main__":
    main(sys.argv)</pre>

在开发应用程序时，请务必遵循最佳做法 安全使用 API 密钥。

Python 脚本示例会输出 Authorization 标头的 Bearer 令牌，如以下示例所示：

$ python sample.py
Authorization: Bearer ya29.42424242sample_420icu8122KSvoh4T42cRoG3rW1lc0Q
$

在请求中使用令牌的值。在您使用后 1 小时内有效 生成它。

问题排查

遇到问题？快速检查以下各项也许能解决问题 问题。

  1. 您是否在 Google Developer Console 中创建了项目？
  2. 您是否找到并启用 Travel Partner API？
  3. 您是否下载了 .p12 文件（在点击后看到的私钥） 创建客户端 ID 并选择服务账号？
  4. 您是否获得了以下表单的服务账号客户端 ID 电子邮件地址： nnnnnnn@app_name.google.com.iam.gserviceaccount.com？
  5. 您是否通过点击 共享此账号按钮？
  6. 您是否将服务账号的电子邮件地址和合作伙伴 ID 发送给了 您的技术支持客户经理 (TAM) 吗？
  7. 您的 Travel Partner API 调用是否传递了 Authorization标题？
  8. 您的 Authorization 标头的不记名令牌是否已超过 1 小时？

下表列出了一些常见错误和可能的解决方法：

错误 说明
Invalid credentials 这可能意味着多种多样的。如果您遇到此错误，请检查： <ph type="x-smartling-placeholder">
    </ph>
  • 您指定了包含有效不记名的 Authorization 标头 令牌。
  • 不记名令牌存在时间未满一小时。一个令牌的有效期只有 1 小时。
  • 您已指定正确的合作伙伴名称（使用 partner） 查询字符串参数）。该值是您的唯一合作伙伴 ID，而不是您的 Hotel Ads Center 中显示的合作伙伴名称。如果您不认识自己的搭档 ID，请与您的技术支持客户经理 (TAM) 联系。
Not found 您的端点很可能格式有误。检查您提交的是 GET 请求，并且请求网址有效（符合 您尝试访问的 API 语法）。
Invalid string value 端点的一个或多个部分包含无效的语法。例如： 您可能拼错了路径的某些部分。检查您使用的是否正确无误 整个路径中使用下划线、大写字母和文字等字词。
Unsupported output format 此错误最常在使用 Reports API 时发生。您必须 在 GET 的网址中指定 "alt=csv" 请求。Reports API 不支持 JSON。
AccessTokenRefreshError/Invalid grant 运行示例 Python 应用时，此错误可能是由 下列各项： <ph type="x-smartling-placeholder">
    </ph>
  • 您的服务账号电子邮件地址不正确。查收电子邮件 Google Developers Console 中验证相应账号，并确保此账号有权访问 API。
  • 此电子邮件地址没有 API 访问权限。检查电子邮件 地址有权访问您的酒店数据（通过 Hotel Center 共享）。
  • 该密钥文件不是服务账号的正确文件。使用 在 DevConsole 中下载新的 .p12 证书，并确保 你的 Python 应用指向正确的网址
HotelAdsAPIConnection object has no attribute credentials 运行示例 Python 应用时，.p12 的路径 错误。
Invalid scope 运行示例 Python 应用时，API 作用域必须为 https://www.googleapis.com/auth/travelpartner。
Forbidden 您使用的账号 ID 未获授权 访问。如果您是子账号所有者，则可能无法访问 父级或根账号 ID。