Sử dụng OAuth 2.0 để cho phép ứng dụng khi truy cập API khách sạn.
Thiết lập OAuth 2.0
OAuth 2.0 yêu cầu bạn xác định chính mình đang sử dụ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 để lấy 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à dữ liệu báo cáo 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 trước đây bạn đã triển khai ClientLogin, thì phương pháp OAuth 2.0 cũng tương tự, chỉ có 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 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ụ của bạn quyền truy cập vào dữ liệu khách sạn của bạn
Từng bước này được mô tả trong 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 của Google dành cho nhà phát triển để quản lý và xem dữ liệu về 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ề ứng dụng mà bạn đang phát triển (có sử dụng API Nhà phát triển của Google và tài nguyên của Google Cloud).
DevConsole là nơi bạn quản lý các khía cạnh này của dự án, chẳng hạn như tạo thông tin xác thực cho 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 quan đến 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, khung hiển thị chính sẽ hiển thị 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 hộp thoại New Project (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ã này là duy nhất trong 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 bên dưới cho thấy 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ị chế độ xem Trang tổng quan cho dự án của bạn:
Để biết thêm thông tin, hãy tham khảo phần Quản lý dự án trong Developers Console.
Khi bạn tạo một dự án mới, chưa có API nào liên kết với dự án đó. Ở 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 các 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 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, hãy bắt đầu nhập Travel Partner API. Google API Console hiển thị 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 trong Tài khoản Google của bạn.
Bước tiếp theo là tạo 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 giữa các máy chủ, chẳng hạn như giữa một ứng dụng web và dữ liệu khách sạn của bạn.
Cách tạo và thiết lập tài khoản dịch vụ:
Trong chế độ xem chính của Bảng điều khiển API của Google, hãy nhấp vào phần Thông tin xác thực trong trình đơn điều hướng bên trái. DevConsole sẽ hiện chế độ xem Thông tin xác thực.
Chế độ xem Thông tin xác thực hiển thị mã ứng dụng khách và thông tin xác thực 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 hoặc thông tin đăng nhập.
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ỳ, 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 chọn 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 nội dung tải xuống. Bạn phải tải định dạng
.p12(tệp nhị phân) xuống, 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 ứ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 hoàn tất việc tạo khoá:
Nhấp vào nút OK. DevConsole sẽ đưa bạn trở 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 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ó các thông tin xác thực sau được liên kết với nó:
- Mã ứng dụng khách: Giá trị nhận dạng duy nhất mà ứng dụng của bạn sử dụng khi yêu cầu mã truy cập OAuth 2.0.
- Địa chỉ email: Địa chỉ email đã tạo cho tài khoản dịch vụ, ở dạng "account_name@project_name.google.com.iam.gserviceaccount.com".
- Vân tay số 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 của bạn trên Hotel Center
Bước cuối cùng là cung cấp quyền truy cập vào Hotel Center cho tài khoản dịch vụ mới của bạn. Tài khoản dịch vụ được xác định bằng địa chỉ email đã tạo 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 cách chia sẻ trong Hotel Center.
Cách cấp quyền truy cập vào dữ liệu của bạn trên Hotel Center cho tài khoản dịch vụ:
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 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à Google Ads.
Trong một 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ụ mà bạn muốn thêm vào Hotel Center.
Chọn mục Thông báo cho mọi 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 phải được kích hoạt quyền truy cập 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 vào 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 vào API đó bằng OAuth.
Sử dụng OAuth 2.0
Để truy cập vào API này, ứ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ẽ trao đổi khoá này để lấy mã truy cập OAuth 2.0 mà bạn sẽ 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 để chỉ định mã truy cập trong tiêu đề HTTP là:
Authorization: Bearer *oauth2_access_token*
Ví dụ sau đây cho thấy 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ể 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ụ sau đâ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 1 giờ sau khi bạn tạo.
Khắc phục sự cố
Bạn gặp sự cố? Việc kiểm tra nhanh các mục sau có thể giải quyết được vấn đề.
- 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 rồi chọn Tài khoản dịch vụ? - Bạn có nhận được địa chỉ email có mã ứng dụng khách của tài khoản dịch vụ theo biểu mẫu:
nnnnnnn@app_name.google.com.iam.gserviceaccount.comkhông? - Bạn đã chia sẻ tài khoản Trung tâm Quảng cáo khách sạn của mình 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 của bạn cho Nhà quản lý tài khoản hỗ trợ kỹ thuật (TAM) chưa?
- Các lệnh gọi Travel Partner API của bạn có truyền 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đã tồn tại hơn 1 giờ chưa?
Bảng sau đây liệt kê một số lỗi phổ biến và cách khắc phục:
| 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. Hãy 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 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ể đã viết sai chính tả một phần của đường dẫn. Kiểm tra để đảm bảo 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 Python mẫu, đườ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ã 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 mã tài khoản gốc. |