Sử dụng OAuth 2.0 để uỷ quyền cho ứng dụng của bạn khi truy cập vào các API khách sạn.
Thiết lập OAuth 2.0
OAuth 2.0 yêu cầu bạn xác nhận danh tính của mình bằng tài khoản dịch vụ liên kết với Tài khoản Google của bạn. Tài khoản dịch vụ sẽ gửi khoá riêng tư của bạn để đổi lấy mã truy cập OAuth 2.0. Sau đó, bạn có thể sử dụng mã thông báo này trong các lệnh gọi đến API khách sạn đối với dữ liệu chỉ có thể đọc, chẳng hạn như dữ liệu báo cáo về giá, khách sạn và chẩn đoán về nguồn cấp dữ liệu giá khách sạn.
Mã truy cập có hiệu lực trong một giờ (3.600 giây).
Nếu bạn đã triển khai ClientLogin trước đây, thì phương pháp OAuth 2.0 cũng tương tự, ngoại trừ những điểm khác biệt sau:
- Ứng dụng của bạn sử dụng tài khoản dịch vụ của Google để truy cập API.
- Bạn truyền mã truy cập OAuth 2.0 vào tiêu đề HTTP
Authorizationkhi gọi API.
Để thiết lập tài khoản của bạn nhằm sử dụng OAuth 2.0 với Travel Partner API, hãy thực hiện các bước sau:
Tạo một dự án mới trong Google Developers Console (DevConsole)
Tạo tài khoản dịch vụ và thông tin xác thực của tài khoản đó
Cấp cho tài khoản dịch vụ quyền truy cập vào dữ liệu khách sạn của bạn
Mỗi bước trong số này được mô tả trong các phần tiếp theo.
Bước 1: Tạo một Dự án mới trong DevConsole
Google Developers Console ("DevConsole") là trải nghiệm dành cho nhà phát triển của Google để quản lý và xem dữ liệu lưu lượng truy cập, thông tin xác thực và thông tin thanh toán cho các API của Google mà dự án của bạn sử dụng.
Trong DevConsole, dự án là một tập hợp các chế độ cài đặt, thông tin xác thực và siêu dữ liệu về (các) ứng dụng mà bạn đang xây dựng có sử dụng API Google Developer và tài nguyên của Google Cloud.
DevConsole là nơi bạn quản lý các chương trình thành phần này của dự án, chẳng hạn như tạo thông tin xác thực API, kích hoạt API và quản lý thông tin nhóm cũng như thông tin thanh toán liên kết với dự án của bạn.
Cách tạo một dự án mới trong DevConsole:
Đăng nhập vào Gmail/Tài khoản Google của bạn.
Mở Google Developer Console. Nếu đây là dự án đầu tiên của bạn, thì khung hiển thị chính sẽ cho thấy một nút TẠO DỰ ÁN đơn giản:
Nhấp vào nút TẠO DỰ ÁN. DevConsole sẽ hiển thị hộp thoại Dự án mới:
Nhập tên dễ nhớ cho dự án mới vào trường nhập dữ liệu Project name (Tên dự án). Bên dưới trường này, DevConsole sẽ tạo một mã dự án cho bạn, đảm bảo rằng mã đó là duy nhất trên tất cả các dự án. Ví dụ: nếu bạn nhập "Dự án mới của tôi", DevConsole sẽ gán một mã nhận dạng như
my-new-project-266022.Nhấp vào nút Create (Tạo) để tạo dự án mới.
Sử dụng trình đơn điều hướng để chọn API và dịch vụ > Trang tổng quan.
Hình ảnh dưới đây hiển thị trình đơn điều hướng ở phía trên bên trái của DevConsole. Thao tác này sẽ hiển thị giao diện Trang tổng quan cho dự án của bạn:
Để biết thêm thông tin, vui lòng tham khảo bài viết Quản lý dự án trong Developers Console.
Khi bạn tạo một dự án mới, dự án chưa có API nào được liên kết. Ở bước tiếp theo, bạn sẽ bật Travel Partner API cho Dự án mới của mình.
Bước 2: Bật Travel Partner API cho dự án mới
Để sử dụng API khách sạn, bạn phải bật Travel Partner API trong dự án mới trong DevConsole.
Cách bật API khách sạn cho dự án mới:
Chuyển đến chế độ xem Trang tổng quan của dự án như mô tả ở trên.
Nhấp vào Enable APIs and Services (Bật API và dịch vụ). Thao tác này sẽ hiển thị trang chào mừng của Thư viện API.
Trong trường tìm kiếm, bắt đầu nhập Travel Partner API. Bảng điều khiển API của Google sẽ hiển thị một danh sách API phù hợp với nội dung bạn nhập.
Nhấp vào biểu tượng Travel Partner API trong bảng các API phù hợp. DevConsole sẽ hiển thị nội dung mô tả về API.
Nhấp vào nút Enable API (Bật API) để bật API này cho dự án của bạn.
Để biết thêm thông tin, hãy tham khảo bài viết Kích hoạt và huỷ kích hoạt API.
API khách sạn hiện đã được bật cho dự án mới của Tài khoản Google.
Tiếp theo, hãy tạo một tài khoản dịch vụ và tạo khoá cho tài khoản đó.
Bước 3: Tạo tài khoản dịch vụ và tạo thông tin xác thực cho tài khoản đó
Tài khoản dịch vụ được sử dụng trong các hoạt động tương tác từ máy chủ đến máy chủ, chẳng hạn như giữa các ứng dụng web và dữ liệu khách sạn của bạn.
Cách tạo và định cấu hình tài khoản dịch vụ:
Trong chế độ xem chính của Bảng điều khiển API Google, hãy nhấp vào Thông tin xác thực trong bảng điều hướng bên trái. DevConsole sẽ hiển thị chế độ xem Thông tin xác thực.
Chế độ xem Credentials (Thông tin xác thực) cho thấy mã ứng dụng khách và thông tin đăng nhập cho dự án của bạn. Ứng dụng của bạn sẽ sử dụng mã ứng dụng khách khi yêu cầu mã truy cập OAuth 2.0. Các dự án mới sẽ chưa có ứng dụng khách hoặc thông tin xác thực.
Nhấp vào đường liên kết Thông tin xác thực trong API và dịch vụ.
Nhấp vào nút Create credentials (Tạo thông tin xác thực) rồi chọn Service account key (Khoá tài khoản dịch vụ) trong trình đơn thả xuống. Bạn sẽ thấy chế độ xem Tạo khoá tài khoản dịch vụ.
Trong trình đơn thả xuống Tài khoản dịch vụ, hãy chọn Tài khoản dịch vụ mới.
Nhập tên tài khoản dịch vụ và mã tài khoản dịch vụ.
Bạn có thể đặt tên bất kỳ theo ý muốn, nhưng mã tài khoản phải là duy nhất trên tất cả dự án. DevConsole sẽ tạo một mã tài khoản duy nhất cho bạn, dựa trên tên mà bạn đã nhập.
Chọn P12 cho loại khoá như minh hoạ dưới đây. Bắt buộc phải có P12.
Nhấp vào nút Tạo. DevConsole sẽ tạo một cặp khoá riêng tư/công khai cho dự án của bạn. Khoá riêng tư được lưu vào vị trí mặc định mà trình duyệt của bạn lưu trữ nội dung tải xuống. Bạn phải tải định dạng
.p12xuống (tệp nhị phân), thay vì định dạng tệp.json.Bạn sử dụng khoá riêng tư trong các tập lệnh hoặc các ứng dụng khác truy cập vào Travel Partner API.
DevConsole sẽ hiển thị thông báo sau đây khi tạo xong các khoá:
Nhấp vào nút OK. DevConsole sẽ quay lại chế độ xem Thông tin xác thực. Để xác nhận thông tin chi tiết về tài khoản dịch vụ và xem các tài khoản dịch vụ được liên kết với dự án của bạn, hãy nhấp vào Manage service account (Quản lý tài khoản dịch vụ) trong chế độ xem này.
Tài khoản dịch vụ hiện được liên kết với thông tin đăng nhập sau:
- Mã ứng dụng khách: Giá trị nhận dạng duy nhất mà ứng dụng của bạn dùng khi yêu cầu mã truy cập OAuth 2.0.
- Địa chỉ email: Địa chỉ email được tạo cho tài khoản dịch vụ, có dạng "account_name@project_name.google.com.iam.gserviceaccount.com".
- Dấu vân tay chứng chỉ: Mã của khoá riêng tư mà bạn đã tải xuống.
Để biết thêm thông tin, hãy tham khảo bài viết Sử dụng OAuth 2.0 cho ứng dụng từ máy chủ đến máy chủ.
Bước 4: Cấp cho tài khoản dịch vụ quyền truy cập vào dữ liệu Hotel Center của bạn
Bước cuối cùng là cấp cho tài khoản dịch vụ mới quyền truy cập vào Hotel Center. Tài khoản dịch vụ được xác định bằng địa chỉ email mà bạn đã tạo ở bước trước. Bạn cấp quyền truy cập vào tài khoản này bằng cách sử dụng chế độ cài đặt chia sẻ của Hotel Center.
Cách cấp cho tài khoản dịch vụ quyền truy cập vào dữ liệu trên Hotel Center:
Nếu bạn không có quyền truy cập thích hợp để thêm người dùng vào tài khoản, hãy liên hệ với nhóm Khách sạn trên Google bằng cách sử dụng biểu mẫu liên hệ với chúng tôi và yêu cầu chúng tôi thiết lập quyền sở hữu cho tài khoản của bạn. Bạn có thể yêu cầu gửi một hoặc nhiều email cho chủ sở hữu. Để biết thêm thông tin về quyền truy cập vào Hotel Center, hãy tham khảo bài viết Liên kết Hotel Center với Google Ads.
Trong cửa sổ trình duyệt mới, hãy mở Hotel Center.
Trên biểu ngữ Hotel Center của Google, hãy nhấp vào biểu tượng thêm người dùng để mở hộp thoại chia sẻ.
Trong trường Thêm người khác, hãy nhập địa chỉ email của tài khoản dịch vụ bạn muốn thêm vào Hotel Center.
Chọn mục Thông báo cho những người.
Trong trình đơn thả xuống, hãy chọn Quản lý.
Nhấp vào nút Mời.
Sau khi bạn thêm người dùng vào Hotel Center, tài khoản dịch vụ của bạn sẽ có quyền truy cập vào API trong vòng khoảng 24 giờ.
Sau khi Google thông báo cho bạn rằng quyền truy cập API đã được bật cho tài khoản dịch vụ của bạn, bạn có thể bắt đầu truy cập API bằng OAuth.
Sử dụng OAuth 2.0
Để truy cập API, ứng dụng của bạn phải xác định danh tính với Google bằng địa chỉ email và khoá riêng tư đã tạo của tài khoản dịch vụ. Cơ chế xác thực của Google sẽ đổi khoá này để lấy mã truy cập OAuth 2.0 mà bạn chuyển vào tiêu đề Authorization trong các lệnh gọi API của ứng dụng.
Mã truy cập (còn gọi là mã thông báo truy cập) là một phần của tiêu chuẩn OAuth 2.0. Cú pháp để xác định mã truy cập trong tiêu đề HTTP là:
Authorization: Bearer *oauth2_access_token*
Ví dụ sau đây cho thấy các tiêu đề HTTP mẫu của một yêu cầu truy cập vào API Báo cáo:
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
Để tạo mã truy cập, hãy tạo một ứng dụng bằng ngôn ngữ bất kỳ mà bạn chọn.
Ví dụ sau đây sẽ tạo mã thông báo bằng Python. Sau đó, bạn có thể sử dụng mã thông báo này trong tiêu đề Authorization của yêu cầu khi truy cập vào Travel Partner API.
#!/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>
Khi phát triển ứng dụng, hãy nhớ làm theo Các phương pháp hay nhất để sử dụng khoá API một cách an toàn.
Tập lệnh Python mẫu sẽ xuất ra Mã thông báo truy cập của tiêu đề Authorization, như trong ví dụ dưới đây:
$ python sample.py Authorization: Bearer ya29.42424242sample_420icu8122KSvoh4T42cRoG3rW1lc0Q $
Sử dụng giá trị của mã thông báo trong yêu cầu của bạn. Mã sẽ có hiệu lực trong vòng 1 giờ kể từ khi bạn tạo.
Khắc phục sự cố
Bạn gặp sự cố? Kiểm tra nhanh các mục sau có thể giải quyết được sự cố.
- Bạn có tạo dự án trong Google Developer Console không?
- Bạn có tìm thấy và bật Travel Partner API không?
- Bạn đã tải tệp
.p12xuống (một khoá riêng tư sau khi nhấp vào Tạo mã ứng dụng khách) và chọn Tài khoản dịch vụ (Service account) chưa? - Bạn có nhận được địa chỉ email của một biểu mẫu
nnnnnnn@app_name.google.com.iam.gserviceaccount.comtrong mã ứng dụng khách của tài khoản dịch vụ không? - Bạn đã chia sẻ tài khoản Trung tâm Quảng cáo khách sạn với tài khoản dịch vụ bằng cách nhấp vào nút Chia sẻ tài khoản này chưa?
- Bạn đã gửi địa chỉ email của tài khoản dịch vụ và mã đối tác cho Nhà quản lý tài khoản hỗ trợ kỹ thuật (TAM) của mình chưa?
- Các lệnh gọi Travel Partner API của bạn có truyền một mã thông báo nhận được gần đây trong tiêu đề
Authorizationkhông? - Mã thông báo truy cập của tiêu đề
Authorizationđã được tạo cách đây hơn 1 giờ chưa?
Bảng sau đây liệt kê một số lỗi phổ biến và các giải pháp có thể áp dụng:
| Lỗi | Nội dung mô tả |
|---|---|
| Invalid credentials | Điều này có thể có nhiều nghĩa. Nếu bạn gặp lỗi này, hãy kiểm tra để đảm bảo:
|
| Not found | Rất có thể điểm cuối của bạn không đúng định dạng. Kiểm tra để đảm bảo rằng bạn đang gửi yêu cầu GET và URL yêu cầu là hợp lệ (URL này tuân thủ cú pháp API mà bạn đang cố gắng truy cập). |
| Invalid string value | Một hoặc nhiều phần của điểm cuối chứa cú pháp không hợp lệ. Ví dụ: bạn có thể đã nhập sai một phần của đường dẫn. Kiểm tra để chắc chắn rằng bạn đã sử dụng đúng dấu gạch dưới, cách viết hoa và từ ngữ trong toàn bộ đường dẫn của mình. |
| Unsupported output format | Lỗi này thường xảy ra nhất khi sử dụng API Báo cáo. Bạn phải chỉ định "alt=csv" trong URL của yêu cầu GET. API Báo cáo không hỗ trợ JSON. |
| AccessTokenRefreshError/Invalid grant | Khi chạy ứng dụng Python mẫu, lỗi này có thể do các nguyên nhân sau gây ra:
|
| HotelAdsAPIConnection object has no attribute credentials | Khi chạy ứng dụng mẫu Python, đường dẫn đến tệp .p12
của bạn không chính xác. |
| Invalid scope | Khi chạy ứng dụng Python mẫu, phạm vi API phải là https://www.googleapis.com/auth/travelpartner. |
| Forbidden | Mã tài khoản mà bạn sử dụng là mã mà bạn không có quyền truy cập. Nếu là chủ sở hữu tài khoản phụ, bạn có thể không truy cập được vào mã tài khoản chính hoặc tài khoản gốc. |