API 授權

本文提供逐步操作說明，引導您在存取飯店 API (例如 Travel Partner API 和 Price Feeds API) 時，在應用程式中設定 OAuth 2.0。請參閱「使用 OAuth 2.0 存取 Google API」一文，瞭解如何授權應用程式。

OAuth 2.0 設定

OAuth 2.0 要求您使用與 Google 帳戶相關聯的服務帳戶來識別身分。服務帳戶會傳送私密金鑰，換取 OAuth 2.0 存取權杖。接著，您可以在飯店 API 的呼叫中使用這個權杖，取得唯讀資料，例如飯店價格動態饋給的價格、飯店和診斷報表資料。

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

如果您先前實作過 ClientLogin，OAuth 2.0 方法與其類似，但有以下差異：

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

如要設定帳戶，以便透過任何 Hotels API 使用 OAuth 2.0，請按照下列步驟操作：

1. 在 Google Cloud 控制台中建立新專案

2. 建立服務帳戶和相關憑證

3. 授予服務帳戶飯店資料存取權

以下各節將說明這些步驟。

步驟 1：建立新的 Google Cloud 控制台專案

您可以使用 Google Cloud 控制台，管理及查看專案所用 Google API 的流量資料、驗證和帳單資訊。

在 Google Cloud 控制台中，專案是您正在開發的應用程式相關設定、憑證和中繼資料的集合，這些應用程式會使用 Google Developer API 和 Google Cloud 資源。

您也可以透過 Google Cloud 控制台產生 API 憑證、啟用 API，以及管理與專案相關聯的團隊和帳單資訊。

如要建立新的 Google Cloud 控制台專案，請按照下列步驟操作：

1. 登入 Gmail 或 Google 帳戶。

2. 開啟 Google Cloud 控制台。 如果是第一個專案，主要檢視畫面會顯示「建立專案」按鈕：

   

3. 按一下「建立專案」按鈕。Google Cloud 控制台會顯示「新專案」對話方塊：

   

   在「專案名稱」輸入欄位中，輸入新專案的易記名稱。Google Cloud 控制台會在欄位下方為您產生專案 ID，確保 ID 在所有專案中都是不重複的。舉例來說，如果您輸入「My New Project」，Google Cloud 控制台會指派類似 my-new-project-266022 的 ID。

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

5. 使用導覽選單，依序選取「API 和服務」>「資訊主頁」。

   

   下圖顯示 Google Cloud 控制台左上方的導覽選單。這會顯示專案的「資訊主頁」檢視畫面：

   

詳情請參閱「建立及管理專案」。

步驟 2：建立服務帳戶並產生憑證

服務帳戶用於伺服器之間的互動，例如網頁應用程式與飯店資料之間的互動。

如要建立及設定服務帳戶，請按照下列步驟操作：

1. 在 Google API 控制台主畫面中，按一下左側導覽選單中的「憑證」。Google Cloud 控制台會顯示「憑證」檢視畫面。

   「憑證」檢視畫面會顯示專案的用戶端 ID 和憑證。應用程式會在要求 OAuth 2.0 存取權杖時使用用戶端 ID。新專案目前沒有任何用戶端或憑證。

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

3. 按一下「建立憑證」按鈕，然後從篩選器中選取「服務帳戶金鑰」。系統會顯示「建立服務帳戶金鑰」檢視畫面。

4. 從「Service account」(服務帳戶) 篩選器選取「New service account」(新增服務帳戶)。

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

   名稱可以隨意設定，但帳戶 ID 在所有專案中不得重複。Google Cloud 控制台會根據您輸入的名稱，為您產生專屬帳戶 ID。

6. 選取「JSON」做為金鑰類型。必須提供 JSON。

7. 按一下 [Create] (建立) 按鈕。Google Cloud 控制台會為專案產生私密或公開金鑰組。私密金鑰會儲存至瀏覽器儲存下載內容的預設位置。請務必下載 .JSON 格式的檔案。

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

   Google Cloud 控制台完成金鑰產生作業後，會顯示「已建立服務帳戶」訊息。

8. 按一下「我知道了」按鈕。Google Cloud 控制台會將您帶回「憑證」檢視畫面。如要確認服務帳戶的詳細資料，並查看與專案相關聯的服務帳戶，請點選這個檢視畫面中的「管理服務帳戶」。

   服務帳戶現在已與下列憑證建立關聯：

   • 用戶端 ID：應用程式要求 OAuth 2.0 存取權杖時使用的專屬 ID。
   • 電子郵件地址：系統為服務帳戶產生的電子郵件地址，格式為「account_name@project_name.google.com.iam.gserviceaccount.com」。
   • 憑證指紋：您下載的私密金鑰 ID。

詳情請參閱「針對伺服器對伺服器應用程式使用 OAuth 2.0」一文。

步驟 3：授予服務帳戶存取 Hotel Center 資料的權限

最後一個步驟是授予新服務帳戶 Hotel Center 的存取權。服務帳戶會透過您在上一個步驟中建立的電子郵件地址來識別。您可以使用 Hotel Center 共用設定，提供這個帳戶的存取權。

如果沒有適當的存取權可將使用者新增至帳戶，請使用「與我們聯絡」表單與 Google 飯店團隊聯絡，並要求為帳戶設定擁有權。你可以要求系統傳送一或多封電子郵件給擁有者。 如要進一步瞭解 Hotel Center 存取權，請參閱「連結 Hotel Center 和 Google Ads」。

如要授予服務帳戶 Hotel Center 資料的存取權，請按照下列步驟操作：

1. 開啟新的瀏覽器視窗，然後開啟飯店中心。

2. 在「Google 飯店中心」橫幅上，按一下「新增使用者」圖示，開啟分享對話方塊。

   

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

4. 請保持選取「通知使用者」選項。

5. 選取篩選器中的「管理」。

6. 按一下「邀請」按鈕。

7. 將使用者新增至 Hotel Center 後，服務帳戶應會在 24 小時內啟用 API 存取權。

Google 通知您服務帳戶已啟用 API 存取權後，您就可以開始使用 OAuth 2.0 存取 API。

如何使用 OAuth 2.0

如要存取 API，應用程式必須使用服務帳戶產生的電子郵件地址和私密金鑰，向 Google 識別自身。Google 的驗證機制會將這個金鑰換成 OAuth 2.0 存取權杖，您可以在應用程式的 API 呼叫中，將這個權杖傳遞至 Authorization 標頭。

請參閱「準備發出委派的 API 呼叫」。

範圍

以下是 Hotels API 的 SCOPES：

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

價格動態饋給 API："https://www.googleapis.com/auth/travel-partner-price-upload"

建立憑證時，請指定服務帳戶。請參閱「建立服務帳戶並產生憑證」。

開發應用程式時，請務必遵循最佳做法，使用 API 金鑰驗證應用程式。瞭解詳情。

範例

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 資料，以便管理大型或複雜的帳戶。

按照 OAUTH 2.0 設定說明，取得 Travel Partner API 的授權。

為 Travel Partners API 建立新專案時，您需要啟用新 Google Cloud 控制台專案的存取權。

請按照下列步驟啟用 Travel Partners API 的存取權：

1. 前往專案的「資訊主頁」檢視畫面。

2. 按一下「啟用 API 和服務」。系統會顯示 API 程式庫歡迎頁面。

3. 在搜尋欄位中輸入「Travel Partner API」，控制台隨即會顯示與您輸入內容相符的 API 清單。

4. 在表格中按一下相符的 API。Google Cloud 控制台會顯示該 API 的說明。

5. 按一下「啟用 API」按鈕，為專案啟用這項 API。

詳情請參閱「啟用及停用服務」。

Google 帳戶的新專案現已啟用 Travel Partner API。

Travel Partner API 的範圍如下： "https://www.googleapis.com/auth/travelpartner"

Travel Partner API 的端點為： "https://travelpartner.googleapis.com/v3/accounts/<account_id>/<path>"

Price Feeds API

住宿合作夥伴可透過 Price Feeds API，為每間飯店提供自訂價格資料。Google 住宿合作夥伴可使用 OAuth 2.0 驗證及授權，將價格上傳至 Google。按照 OAUTH 2.0 設定說明操作，取得 Price Feeds API 的授權。

注意事項

請注意，授權價格動態饋給 API 的操作說明有重要差異。

1. 合作夥伴應在 Google Cloud 控制台中，按照OAuth 2.0 設定中的操作說明，建立新的 Price Feeds OAuth 2.0 專案。

2. 在 Google Cloud 控制台中啟用 Price Feeds API「並非」必要步驟，可以忽略。您只需要一個服務帳戶和金鑰，然後使用相同的服務帳戶和金鑰，授予價格動態饋給專案存取 Hotel Center 資料的權限。按照 OAuth 2.0 設定中提及的其餘步驟，完成 API 設定。

取得價格動態饋給的 OAuth2.0 存取權杖

下一步是使用服務帳戶金鑰檔案，取得具有住宿價格上傳範圍的 OAuth 2.0 存取權杖。如要授權對價格動態饋給專案的要求，請按照「準備發出委派的 API 呼叫」一文中的操作說明進行，然後從取得的憑證中擷取存取權杖，並在 "Authorization" HTTP 標頭中設定。

住宿價格上傳範圍： "https://www.googleapis.com/auth/travel-partner-price-upload"

上傳價格

取得存取權杖後，合作夥伴即可上傳價格動態饋給，做法與使用靜態 IP 進行驗證和授權類似，但須進行下列修改：

• 在 "Authorization" HTTP 標頭中設定存取權杖

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

測試 Price Feeds API 的 OAuth2.0 設定

你可以上傳空白檔案或實際價格資料至任一上傳路徑，測試 OAuth 2.0 設定。請使用下表檢查 HTTP 回應狀態。

疑難排解

遇到問題了嗎？快速檢查下列項目，或許就能解決問題。

1. 您是否已在 Google Cloud 控制台中建立專案？
2. 您是否已在專案中啟用服務？
3. 您是否已下載 .JSON 檔案 (私密金鑰)，方法是按一下「建立用戶端 ID」，然後選取「服務帳戶」？
4. 您是否收到服務帳戶用戶端 ID 電子郵件地址，格式如下： nnnnnnn@app_name.google.com.iam.gserviceaccount.com？
5. 您是否已點按「共用這個帳戶」按鈕，將 Hotel Ads Center 帳戶與服務帳戶共用？
6. 你是否已將服務帳戶的電子郵件地址和合作夥伴 ID 傳送給客戶技術管理員 (TAM)？
7. 您的 API 呼叫是否在 Authorization 標頭中傳遞最近取得的權杖？
8. 您的權杖是否已超過 1 小時？

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