存取飯店 API 時，請使用 OAuth 2.0 授權您的應用程式。
OAuth 2.0 設定
OAuth 2.0 會要求您使用與 Google 帳戶相關聯的服務帳戶來識別身分。服務帳戶會傳送您的私密金鑰以交換 OAuth 2.0 存取權杖。接下來，就能在呼叫飯店 API 時使用這個符記來取得唯讀資料，例如飯店價格動態饋給的定價、飯店和診斷報表資料。
存取權杖的有效期限為一小時 (3,600 秒)。
如果您之前已實作 ClientLogin，則 OAuth 2.0 方法大致上很類似，但有以下差異：
- 應用程式透過 Google 服務帳戶存取 API。
- 呼叫 API 時，您會在
AuthorizationHTTP 標頭中傳遞 OAuth 2.0 存取權杖。
如要將帳戶設為透過 Travel Partner API 使用 OAuth 2.0，請執行下列步驟：
每個步驟都會在後續章節中說明。
步驟 1：建立新的開發人員工具專案
Google Developers Console (「DevConsole」) 是 Google 為開發人員打造的體驗，可用來管理及查看專案所用 Google API 的流量資料、驗證和帳單資訊。
在 Developer Console 中，專案是您目前處理的應用程式或應用程式的一組設定、憑證和中繼資料，這些項目會使用 Google Developer API 和 Google Cloud 資源。
您可以透過 DevConsole 管理專案的這些事項，例如產生 API 憑證、啟用 API，以及管理與專案相關的團隊和帳單資訊。
如何建立新的 Developer Console 專案：
登入 Gmail/Google 帳戶。
開啟 Google 開發人員控制台。如果這是您的第一個專案，主要檢視畫面會顯示簡單的「建立專案」按鈕：
按一下 [建立專案] 按鈕。DevConsole 會顯示「New Project」對話方塊：
在「Project name」(專案名稱) 輸入欄位中輸入新專案的名稱。在欄位下方，DevConsole 會產生專案 ID，確保該 ID 在所有專案中均不重複。舉例來說，如果輸入「我的新專案」，DevConsole 會指派
my-new-project-266022之類的 ID。按一下「建立」按鈕，即可建立新專案。
在導覽選單中，依序選取「API 和服務」>「資訊主頁」。
下圖顯示 Developer Console 左上方的導覽選單。這樣會顯示專案的「資訊主頁」檢視畫面：
詳情請參閱在 Developers Console 中管理專案。
建立新專案時，該專案尚未與任何 API 建立關聯。在下一個步驟中，您將為新專案啟用 Travel Partner API。
步驟 2：為新專案啟用 Travel Partner API
如要使用飯店 API，請在新的開發人員控制台專案中啟用 Travel Partner API。
如要為新專案啟用 Hotel API，請按照下列步驟操作：
按照上述方式前往專案的資訊主頁檢視畫面。
按一下「啟用 API 和服務」。畫面會顯示 API 程式庫歡迎頁面。
在搜尋欄位中輸入 Travel Partner API。Google API 控制台會顯示符合輸入內容的 API 清單。
按一下相符 API 表格中的 Travel Partner API。DevConsole 會顯示該 API 的說明。
按一下「啟用 API」按鈕，為專案啟用這個 API。
詳情請參閱「啟用及停用 API」。
Google 帳戶的新專案現已啟用 Hotel API。
下一步是建立服務帳戶，並為其產生金鑰。
步驟 3：建立服務帳戶並產生憑證
服務帳戶會使用服務帳戶進行伺服器對伺服器的互動，例如網頁應用程式和飯店資料之間的互動。
如要建立並設定服務帳戶：
在 Google API 控制台主要檢視畫面中，按一下左側導覽面板中的「Credentials」。Developer Console 會顯示「Credentials」(憑證) 檢視畫面。
「Credentials」(憑證) 檢視畫面會顯示專案的用戶端 ID 和憑證。您的應用程式在要求 OAuth 2.0 存取權杖時會使用用戶端 ID。新專案目前不會有任何用戶端或憑證。
按一下「API 和服務中的憑證」連結。
按一下「建立憑證」按鈕，然後從下拉式選單中選取「服務帳戶金鑰」。「建立服務帳戶金鑰」檢視畫面隨即顯示。
在「服務帳戶」下拉式選單中，選取「新增服務帳戶」。
輸入服務帳戶名稱和服務帳戶 ID。
名稱可以是任何項目，但所有專案中的帳戶 ID 不得重複。DevConsole 會根據您輸入的名稱產生專屬帳戶 ID。
選取「P12」P12做為金鑰類型，如下所示。必須提供 P12。
按一下 [Create] (建立) 按鈕。DevConsole 會產生專案的私密/公開金鑰組。私密金鑰會儲存至瀏覽器儲存下載的預設位置。您必須下載
.p12格式 (二進位檔)，而非.json檔案格式。您可以在指令碼或其他存取 Travel Partner API 的應用程式中使用私密金鑰。
當 DevConsole 產生金鑰時，會顯示以下通知：
按一下 [好，我知道了] 按鈕。DevConsole 會帶您返回「Credentials」(憑證) 檢視畫面。如要確認服務帳戶的詳細資料，並查看與專案相關聯的服務帳戶，請按一下這個檢視畫面中的「Manage service accounts」(管理服務帳戶)。
這個服務帳戶現在已具有下列相關聯的憑證：
- 用戶端 ID：應用程式在要求 OAuth 2.0 存取權杖時使用的不重複 ID。
- 電子郵件地址：系統為服務帳戶產生的電子郵件地址，格式為「account_nameaccount_name@project_nameaccount_name.google.com.iam.gserviceaccount.com」。
- 憑證指紋：已下載私密金鑰的 ID。
詳情請參閱「針對伺服器對伺服器應用程式使用 OAuth 2.0」一文。
步驟 4：授權服務帳戶存取您的 Hotel Center 資料
最後一步是將 Hotel Center 的存取權提供給新的服務帳戶。服務帳戶可透過您在上一個步驟中建立的產生電子郵件地址識別。您可以透過 Hotel Center 共用設定，提供這個帳戶的存取權。
如要授權服務帳戶存取 Hotel Center 資料，請按照下列步驟操作：
如果您沒有適當權限，無法將使用者新增至帳戶，請透過與我們聯絡表單與 Google 飯店團隊聯絡，要求我們設定帳戶的擁有權。你可以要求將一或多封電子郵件傳送給擁有者。 如要進一步瞭解 Hotel Center 存取權，請參閱連結 Hotel Center 和 Google Ads 一文。
在新的瀏覽器視窗中開啟 Hotel Center。
在「Hotel Center by Google」橫幅上，按一下「新增使用者」圖示，開啟共用對話方塊。
在「新增更多使用者」欄位中，輸入要新增至 Hotel Center 的服務帳戶電子郵件地址。
保持選取「通知邀請對象」選項。
在下拉式選單中選取「管理」。
按一下「邀請」按鈕。
將使用者加入 Hotel Center 後，您的服務帳戶應該會在 24 小時內啟用 API 存取權。
Google 通知您已啟用服務帳戶的 API 存取權之後，您就可以開始使用 OAuth 存取 API。
使用 OAuth 2.0
如要存取 API，應用程式必須使用服務帳戶產生的電子郵件地址和私密金鑰，向 Google 表明自身。Google 的驗證機制會交換這組金鑰，以取得您在應用程式 API 呼叫中 Authorization 標頭傳遞的 OAuth 2.0 存取權杖。
存取權杖 (又稱為「不記名權杖」) 是 OAuth 2.0 標準的一部分。在 HTTP 標頭中指定存取權杖的語法如下：
Authorization: Bearer *oauth2_access_token*
以下範例顯示存取 Reports API 的要求 HTTP 標頭範例：
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 API 時，在要求的 Authorization 標頭中使用這個符記。
#!/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 個小時內
疑難排解
遇到問題了嗎？快速檢查下列項目或許能解決問題。
- 您是否已在 Google Developer Console 中建立專案？
- 您找到並啟用 Travel Partner API 了嗎？
- 您是否下載了
.p12檔案 (點選「Create client ID」(建立用戶端 ID)) 並選取「Service account」(服務帳戶) 後，是否下載了私密金鑰？ - 您是否收到了表單 (
nnnnnnn@app_name.google.com.iam.gserviceaccount.com) 的服務帳戶用戶端 ID 電子郵件地址？ - 您是否點選「共用這個帳戶」按鈕，與服務帳戶共用 Hotel Ads Center 帳戶？
- 您是否傳送服務帳戶的電子郵件地址和合作夥伴 ID 給客戶技術顧問 (TAM)？
- 您的 Travel Partner API 呼叫是否在
Authorization標頭中傳遞最近取得的權杖？ Authorization標頭的不記名權杖是否已建立超過 1 小時？
下表列出一些常見錯誤和可能的解決方法：
| 發生錯誤 | 說明 |
|---|---|
| Invalid credentials | 這可能代表很多項目。如果發生這個錯誤，請確認下列事項：
|
| Not found | 您的端點很可能是格式錯誤。請確認您提交的 GET 要求有效，且要求網址有效 (符合您嘗試存取的 API 語法)。 |
| Invalid string value | 端點的一或多個部分包含無效的語法。例如路徑中可能有錯字。請檢查整個路徑是否使用正確的底線、大小寫和用語。 |
| Unsupported output format | 這項錯誤最常出現在使用 Reports API 時。您必須在 GET 要求的網址中指定 "alt=csv"。Reports API 不支援 JSON。 |
| AccessTokenRefreshError/Invalid grant | 執行範例 Python 應用程式時，這個錯誤可能是由下列原因造成：
|
| HotelAdsAPIConnection object has no attribute credentials | 執行範例 Python 應用程式時，.p12 檔案的路徑不正確。 |
| Invalid scope | 執行範例 Python 應用程式時，API 範圍必須為 https://www.googleapis.com/auth/travelpartner。 |
| Forbidden | 您使用的帳戶 ID 是您無權存取的帳戶 ID。如果您是子帳戶的擁有者，可能無法存取上層帳戶或根帳戶 ID。 |