API 授權

使用 OAuth 2.0 授權應用程式 可前往飯店 API

OAuth 2.0 設定

OAuth 2.0 會要求您使用服務帳戶進行識別 。服務帳戶傳送您的私人資訊 金鑰並用來交換 OAuth 2.0 存取權杖。接著,您可以將這個權杖用於 針對唯讀資料 (例如價格、飯店和 飯店價格動態饋給的診斷報表資料。

存取權杖的有效期限為一小時 (3,600 秒)。

如果您先前實作了 ClientLogin,OAuth 2.0 方法也很類似。 但下列差異:

  • 應用程式透過 Google 服務帳戶存取 API。
  • 您在 Authorization HTTP 標頭中傳遞 OAuth 2.0 存取權杖。 呼叫 API

如要將帳戶設為透過 Travel Partner API 使用 OAuth 2.0,請執行下列步驟:

  1. 在 Google Developers Console (Dev Console) 中建立新專案

  2. 為新專案啟用 Travel Partner API 存取權

  3. 建立服務帳戶及其憑證

  4. 授權服務帳戶存取您的飯店資料

每個步驟都會在後續章節中說明。

步驟 1:建立新的開發人員工具專案

Google Developers Console (「DevConsole」) 是 Google 提供的開發人員體驗 用於管理及查看流量資料、驗證和帳單資訊 。

在 Developer Console 中,專案包含一組設定、憑證、 和中繼資料 此 API 會使用 Google Developer API 和 Google Cloud 資源

您可以透過 Developer Console 管理專案的這些面向,例如 產生 API 憑證、啟用 API,以及管理團隊和帳單 取得專案相關資訊

如何建立新的 Developer Console 專案:

  1. 登入 Gmail/Google 帳戶。

  2. 開啟 Google 開發人員控制台。如果這是您的第一個專案,主要檢視畫面會顯示 簡單的「建立專案」按鈕

    fig1

  3. 按一下 [建立專案] 按鈕。DevConsole 會顯示 「New Project」對話方塊:

    fig2

    在「專案名稱」中,為新專案輸入易記的名稱 輸入欄位在欄位下方,DevConsole 會為您產生專案 ID。 確保所有專案的 ID 皆不重複。舉例來說,如果您在 輸入「My New Project」(我的新專案) 之後,DevConsole 會指派一個 ID,例如 my-new-project-266022

  4. 按一下「建立」按鈕,即可建立新專案。

  5. 使用導覽選單選取 API 和服務 >資訊主頁。

    fig3

    下圖顯示 Play 管理中心。這樣會顯示專案的「資訊主頁」檢視畫面:

    fig4

詳情請參閱「在 Developers 中管理專案 控制台

建立新專案時,該專案尚未與任何 API 建立關聯。在 下一步,您將為新專案啟用 Travel Partner API

步驟 2:為新專案啟用 Travel Partner API

如要使用飯店 API,請在新的開發人員控制台專案中啟用 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:建立服務帳戶並產生憑證

服務帳戶會使用服務帳戶進行伺服器對伺服器的互動 網頁應用程式和飯店資料

如要建立並設定服務帳戶:

  1. 在 Google API 控制台主要檢視畫面中,按一下「憑證」。 左側導覽面板Developer Console 會顯示「Credentials」(憑證) 檢視畫面。

    「Credentials」(憑證) 檢視畫面會顯示 專案。應用程式在要求 OAuth 2.0 存取權杖。新專案不會有用戶端或憑證 。

  2. 按一下「API 和服務中的憑證」連結。

  3. 按一下「建立憑證」按鈕,然後選取「服務帳戶金鑰」。 。「建立服務帳戶金鑰」檢視畫面隨即顯示。

  4. 在「服務帳戶」下拉式選單中,選取「新增服務帳戶」

  5. 輸入服務帳戶名稱和服務帳戶 ID。

    名稱可以是任何名稱,但帳戶 ID 不得重複 和專案DevConsole 會為您產生一組專屬帳戶 ID, 根據您的名稱篩選搜尋結果

  6. 選取「P12」P12做為金鑰類型,如下所示。必須提供 P12

    fig5

  7. 按一下 [Create] (建立) 按鈕。DevConsole 會產生私密/公開金鑰組 。私密金鑰會儲存至 瀏覽器儲存的下載內容。您必須下載 .p12 格式 (二進位),而不是 .json 檔案格式

    您在指令碼或其他可存取存取碼的應用程式中使用私密金鑰 Travel Partner API

    DevConsole 會在產生 金鑰:

    fig6

  8. 按一下 [好,我知道了] 按鈕。DevConsole 會將您傳回 「Credentials」(憑證) 檢視畫面。確認服務帳戶詳細資料 如要查看與專案相關聯的服務帳戶,請按一下「管理」 服務帳戶

    這個服務帳戶現在已具有下列相關聯的憑證:

    • 用戶端 ID:應用程式使用的專屬 ID 要求 OAuth 2.0 存取權杖。
    • 電子郵件地址:系統為服務帳戶產生的電子郵件地址,位於 表單 「<帳戶名稱>account_name@<專案名稱>account_name.google.com.iam.gserviceaccount.com」。
    • Certificate 指紋:您私密金鑰的 ID 已下載完成。
,瞭解如何調查及移除這項存取權。

詳情請參閱「將 OAuth 2.0 用於伺服器 伺服器應用程式

步驟 4:授權服務帳戶存取您的 Hotel Center 資料

最後一個步驟是授權新服務帳戶存取 Hotel Center:服務帳戶會透過系統產生的電子郵件地址識別 您在上一個步驟中建立的名稱您提供帳戶存取權的方式為: Hotel Center 的共用設定。

如要授權服務帳戶存取 Hotel Center 資料,請按照下列步驟操作:

如果您沒有適當的存取權,無法在帳戶中新增使用者,請與 Google 飯店團隊使用與我們聯絡表單,要求我們設定 即可。您可以要求將一或多封電子郵件傳送給擁有者。 如要進一步瞭解 Hotel Center 存取權,請參閱連結 Hotel Center 和 Google Ads

  1. 在新的瀏覽器視窗中開啟 Hotel Centerfig7

  2. 在「Hotel Center by Google」橫幅中,按一下「新增使用者」圖示即可開啟 共用對話方塊

    fig8

  3. 在「新增更多使用者」欄位中,輸入服務的電子郵件地址 要新增至 Hotel Center 的帳戶。

  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 產生權杖。接著您就能 符記存取 Travel Partner APIAuthorization 標頭。

#!/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 標頭的不記名 符記,如以下範例所示:

$ 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. 您是否曾點選連結,將 Hotel Ads Center 帳戶與服務帳戶共用 該如何分享「共用這個帳戶」按鈕?
  6. 您是否傳送服務帳戶的電子郵件地址和合作夥伴 ID 給 您的客戶技術顧問 (TAM)?
  7. Travel Partner API 呼叫是否在 「Authorization」標頭?
  8. Authorization 標頭的不記名權杖是否已建立超過 1 小時?

下表列出一些常見錯誤和可能的解決方法:

錯誤 說明
Invalid credentials 這可能代表很多項目。如果發生這個錯誤,請確認下列事項:
  • 您指定了包含有效不記名的 Authorization 標頭 產生下一個符記
  • 不記名權杖存在不到一小時。權杖效期為一小時。
  • 您指定的合作夥伴名稱正確無誤 (使用「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 應用程式時,這個錯誤可能是由 下列項目:
  • 您的服務帳戶電子郵件地址有誤。查看電子郵件 帳戶,並確保已取得授權,可存取 也能使用 Google Cloud CLI 或 Compute Engine 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