API 授權

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

OAuth 2.0 設定

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

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

如果您先前實作了 ClientLogin，OAuth 2.0 方法與之相似，但有以下差異：

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

如要設定帳戶，以便使用 OAuth 2.0 搭配任何 Hotels API，請執行下列步驟：

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 控制台。如果這是您的第一個專案，主畫面會顯示「CREATE PROJECT」按鈕：

   

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

   

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

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

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

   

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

   

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

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

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

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

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

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

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

3. 按一下「建立憑證」按鈕，然後從篩選器中選取「服務帳戶金鑰」。畫面上會顯示「Create service account key」畫面。

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

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

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

6. 在「金鑰類型」中選取「JSON」JSON，必須使用 JSON。

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

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

   Google Cloud 控制台產生金鑰後，會顯示「Service account created」(已建立服務帳戶) 訊息。

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. 在新的瀏覽器視窗中開啟 Hotel Center。

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"

Price Feeds 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

旅遊合作夥伴 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. 按一下「Enable 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

價格動態饋給 API 可讓住宿合作夥伴為每間飯店提供自訂價格資料。Google 住宿合作夥伴可使用 OAuth 2.0 驗證身分，並在將價格上傳至 Google 時授權自己。請按照 OAuth 2.0 設定操作說明，取得價格動態饋給 API 的授權。

注意事項

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

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

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

取得價格動態饋給的 OAuth 2.0 存取權杖

接下來，請使用服務帳戶金鑰檔案，取得具有住宿價格上傳範圍的 OAuth 2.0 存取權杖。您可以按照「準備發出委派的 API 呼叫」一文中的指示，從取得的憑證中擷取存取權權杖，然後將其設在 "Authorization" HTTP 標頭中，即可授權 Price Feeds 專案的要求。

住宿價格上傳的範圍如下： "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>

測試價格動態饋給 API 的 OAuth 2.0 設定

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

疑難排解

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

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

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