存取飯店 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：建立新的 DevConsole 專案
Google Developers Console (「DevConsole」) 是 Google 為開發人員打造的體驗，可管理和查看專案所用 Google API 的流量資料、驗證和帳單資訊。
在 DevConsole 中，「專案」是一組設定、憑證，以及您目前使用的應用程式或應用程式的中繼資料，這類專案會使用 Google Developer API 和 Google Cloud 資源。
您可以在 DevConsole 管理專案的以下面向，例如產生 API 憑證、啟用 API 及管理與專案相關聯的團隊和帳單資訊。
如何建立新的 DevConsole 專案：
登入 Gmail/Google 帳戶。
開啟 Google 開發人員控制台。如果這是您的第一個專案，主要檢視畫面會顯示簡單的「CREATE PROJECT」按鈕：
按一下「建立專案」按鈕。DevConsole 會顯示「New Project」對話方塊：
在「Project name」(專案名稱) 輸入欄位中輸入新專案的好記名稱。在欄位下方，DevConsole 會為您產生專案 ID，確保所有專案的 ID 皆不重複。舉例來說，如果輸入「My New Project」(我的新專案)，DevConsole 會指派一個 ID，例如
my-new-project-266022。按一下「建立」按鈕，建立新專案。
使用導覽選單選取「APIs & Services」(API 和服務) >「Dashboard」(資訊主頁)。
下圖顯示 Dev Console 左上方的導覽選單。畫面會顯示專案的「Dashboard」(資訊主頁) 檢視畫面：
詳情請參閱「在 Developers Console 中管理專案」。
建立新專案時，專案尚未連結至任何 API。在下一個步驟中，您將為新專案啟用 Travel Partner API。
步驟 2：為新專案啟用 Travel Partner API
如要使用飯店 API，您必須在新的 DevConsole 專案中啟用 Travel Partner API。
如要為新專案啟用飯店 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」(憑證)。Dev Console 會顯示「Credentials」(憑證) 檢視畫面。
「Credentials」(憑證) 檢視畫面會顯示專案的用戶端 ID 和憑證。您的應用程式會在要求 OAuth 2.0 存取權杖時，使用用戶端 ID。新專案目前不會有任何用戶端或憑證。
按一下「API 和服務中的憑證」連結。
按一下「建立憑證」按鈕，然後在下拉式選單中選取「服務帳戶金鑰」。系統隨即會顯示「建立服務帳戶金鑰」檢視畫面。
從「服務帳戶」下拉式選單中，選取「新增服務帳戶」。
輸入服務帳戶名稱和服務帳戶 ID。
您可以視需要使用任何名稱，但所有專案中的帳戶 ID 都不得重複。DevConsole 會根據您輸入的名稱產生一個專屬帳戶 ID。
選取「P12」P12做為金鑰類型，如下所示。必須提供 P12。
按一下 [Create] (建立) 按鈕。DevConsole 會為專案產生私密/公開金鑰組。私密金鑰會儲存於瀏覽器儲存下載內容的預設位置。您必須下載
.p12格式 (二進位檔)，而不是.json檔案格式。您會在指令碼或其他可存取 Travel Partner API 的應用程式中使用私密金鑰。
DevConsole 會在產生金鑰的過程中顯示以下通知：
按一下「好，我知道了」按鈕。Deployment Console 會讓您返回「Credentials」(憑證) 檢視畫面。如要確認服務帳戶的詳細資料，以及查看與專案相關聯的服務帳戶，請按一下這個檢視畫面中的「管理服務帳戶」。
這個服務帳戶現在具有以下相關聯的憑證：
- 用戶端 ID：應用程式要求 OAuth 2.0 存取權杖時使用的不重複 ID。
- 電子郵件地址：服務帳戶產生的電子郵件地址，格式為「<帳戶名稱>account_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 的驗證機制會將這個金鑰交換給 OAuth 2.0 存取權杖，這是您在應用程式 API 呼叫中傳入 Authorization 標頭的權杖。
存取權杖 (也稱為「鄰近權杖」) 屬於 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 Developers Console 中建立專案？
- 您找到並啟用 Travel Partner API 了嗎？
- 您是否已下載
.p12檔案 (也就是在點選「Create client ID」(建立用戶端 ID) 並選取「Service account」(服務帳戶) 後) 的私密金鑰？ - 您是否已取得以下表單的服務帳戶用戶端 ID 電子郵件地址：
nnnnnnn@app_name.google.com.iam.gserviceaccount.com？ - 您是否曾點選「共用這個帳戶」按鈕，與服務帳戶共用 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。 |