Uỷ quyền API

Tài liệu này cung cấp hướng dẫn từng bước để thiết lập OAuth 2.0 trong ứng dụng của bạn khi truy cập vào các API khách sạn như API Đối tác du lịch và API Nguồn cấp dữ liệu giá. Hãy tham khảo phần Sử dụng OAuth 2.0 để truy cập vào các API của Google để uỷ quyền cho ứng dụng của bạn.

Thiết lập OAuth 2.0

OAuth 2.0 yêu cầu bạn sử dụng một tài khoản dịch vụ có liên kết với Tài khoản Google của bạn để xác định bản thâ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ể dùng mã truy cập này trong các lệnh gọi đến API khách sạn để nhận dữ liệu chỉ có thể đọc, chẳng hạn như giá cả, 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á của khách sạn.

Mã truy cập có giá trị trong một giờ (3.600 giây).

Nếu trước đó bạn đã triển khai ClientLogin, thì phương pháp OAuth 2.0 cũng tương tự, ngoại trừ một số đ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 gửi mã truy cập OAuth 2.0 vào tiêu đề HTTP Authorization khi gọi API.

Để thiết lập tài khoản của bạn để sử dụng OAuth 2.0 với bất kỳ API Khách sạn nào, hãy thực hiện các bước sau:

1. Tạo một dự án mới trong Google Cloud Console

2. Tạo một tài khoản dịch vụ và thông tin xác thực của tài khoản đó

3. Cấp quyền truy cập vào dữ liệu khách sạn của bạn cho tài khoản dịch vụ

Mỗi bước được mô tả trong các phần tiếp theo.

Bước 1: Tạo một Dự án mới trên Google Cloud Console

Google Cloud Console được dùng để 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 của các API của Google mà dự án của bạn sử dụng.

Trong Google Cloud Console, dự án là một tập hợp gồm 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 của Google Developer và tài nguyên của Google Cloud.

Google Cloud Console cũng được dùng để tạo thông tin xác thực cho API, kích hoạt API và quản lý nhóm cũng như thông tin thanh toán có liên kết với dự án của bạn.

Cách tạo một dự án mới trên Google Cloud Console:

1. Đăng nhập vào Gmail hoặc Tài khoản Google của bạn.

2. Mở Google Cloud Console. Nếu đây là dự án đầu tiên của bạn, giao diện chính sẽ hiển thị nút TẠO DỰ ÁN:

   

3. Nhấp vào nút TẠO DỰ ÁN. Google Cloud Console sẽ hiển thị hộp thoại Dự án mới:

   

   Đặt tên dễ nhớ cho dự án mới trong trường nhập dữ liệu Tên dự án. Bên dưới trường này, Google Cloud Console sẽ tạo cho bạn một mã dự án, đảm bảo rằng mỗi dự án chỉ có một mã riêng biệt. Ví dụ: nếu bạn nhập "Dự án mới của tôi", Google Cloud Console sẽ gán một mã nhận dạng như my-new-project-266022.

4. Nhấp vào nút Tạo để tạo dự án mới.

5. Sử dụng trình đơn điều hướng để chọn API và dịch vụ > Trang tổng quan.

   

   Hình ảnh sau đây cho thấy trình đơn điều hướng ở phía trên bên trái của bảng điều khiển Google Cloud. Trình đơn 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, hãy tham khảo bài viết Tạo và quản lý dự án.

Bước 2: 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ụ sẽ được sử dụng trong việc 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à định cấu hình tài khoản dịch vụ:

1. Trong chế độ xem chính trên Bảng điều khiển API của Google, hãy nhấp vào Thông tin xác thực trong trình đơn điều hướng bên trái. Bảng điều khiển Google Cloud sẽ chuyển sang chế độ xem Thông tin xác thực.

   Chế độ xem Thông tin xác thực cho thấy 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. Dự án mới chưa có ứng dụng khách hoặc thông tin xác thực.

2. Nhấp vào đường liên kết Thông tin xác thực trong API và dịch vụ.

3. Nhấp vào nút Tạo thông tin xác thực rồi chọn Khoá tài khoản dịch vụ trong bộ lọc. Bạn sẽ thấy chế độ xem Tạo khoá tài khoản dịch vụ.

4. Trong bộ lọc Tài khoản dịch vụ, hãy chọn Tài khoản dịch vụ mới.

5. 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 tuỳ ý, nhưng mã tài khoản phải là duy nhất trên tất cả các dự án. Google Cloud Console sẽ tạo một mã tài khoản riêng biệt cho bạn, dựa trên tên mà bạn đã nhập.

6. Chọn JSON cho loại khoá. Bạn bắt buộc phải có JSON.

7. Nhấp vào nút Tạo. Google Cloud Console sẽ tạo một cặp khoá riêng tư hoặc công khai cho dự án của bạn. Khoá riêng tư sẽ đượ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 tệp ở định dạng .JSON xuống.

   Bạn sử dụng khoá riêng tư trong các tập lệnh hoặc ứng dụng khác có quyền truy cập vào API của bạn.

   Bảng điều khiển Google Cloud sẽ hiển thị thông báo "Đã tạo tài khoản dịch vụ" khi hoàn tất quá trình tạo khoá.

8. Nhấp vào nút Đã hiểu. Google Cloud Console sẽ đưa bạn trở lại chế độ xem Thông tin xác thực. Để xác nhận thông tin về tài khoản dịch vụ và xem 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ó những thông tin xác thực sau:

   • Mã ứng dụng khách: Giá trị nhận dạng riêng biệ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 được tạo cho tài khoản dịch vụ, có dạng "tên_tài_khoản@tên_dự_án.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 3: Cấp quyền truy cập vào dữ liệu Hotel Center cho tài khoản dịch vụ

Bước cuối cùng là cấp quyền truy cập vào Hotel Center cho tài khoản dịch vụ mới. 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 đó. Hãy sử dụng chế độ cài đặt chia sẻ của Hotel Center để cấp quyền truy cập cho tài khoản này.

Nếu bạn không có quyền truy cập phù 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 của Google bằng biểu mẫu liên hệ với chúng tôi và yêu cầu 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 thiết lập quyền sở hữu đối với một hoặc nhiều email. Để 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.

Cách cấp cho tài khoản dịch vụ quyền truy cập vào dữ liệu trong Hotel Center:

1. Trong một cửa sổ trình duyệt mới, hãy mở Hotel Center.

2. 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ẻ.

   

3. 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.

4. Chọn mục Thông báo cho mọi người.

5. Chọn Quản lý trong bộ lọc.

6. Nhấp vào nút Mời.

7. 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 bật quyền truy cập API trong vòng khoảng 24 giờ.

Sau khi Google thông báo 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 2.0.

Cách 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 sẽ gửi vào phần tiêu đề Authorization trong các lệnh gọi API của ứng dụng.

Hãy tham khảo bài viết Chuẩn bị thực hiện lệnh gọi API được uỷ quyền.

Phạm vi

Sau đây là SCOPES cho Hotels API:

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

Price Feeds API: "https://www.googleapis.com/auth/travel-partner-price-upload"

Bạn nên chỉ định tài khoản dịch vụ khi tạo thông tin đăng nhập. Tham khảo phần Tạo tài khoản dịch vụ và tạo thông tin xác thực cho tài khoản đó.

Trong quá trình phát triển ứng dụng, đừng quên làm theo các phương pháp hay nhất để xác thực ứng dụng bằng khoá API. Tìm hiểu thêm.

Ví dụ:

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 cho phép các đối tác lưu trú truy xuất thông tin Hotel Center và thay đổi dữ liệu Hotel Center để quản lý các tài khoản lớn hoặc phức tạp.

Làm theo hướng dẫn thiết lập OAUTH 2.0 để được uỷ quyền cho Travel Partner API.

Khi tạo một dự án mới cho Travel Partners API, bạn cần bật quyền truy cập vào dự án mới của mình trên Google Cloud Console.

Hãy làm theo các bước sau để bật quyền truy cập vào Travel Partners API:

1. Chuyển đến chế độ xem Trang tổng quan của dự án.

2. 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.

3. Trong trường tìm kiếm, hãy bắt đầu nhập "API Đối tác du lịch", sau đó, bảng điều khiển sẽ hiển thị danh sách các API phù hợp với nội dung bạn nhập.

4. Nhấp vào API phù hợp trong bảng. Bảng điều khiển Google Cloud sẽ hiển thị nội dung mô tả về API đó.

5. Nhấp vào nút Bật API để bật API này cho dự án của bạn.

Để biết thêm thông tin, hãy xem phần Bật và tắt dịch vụ.

Vậy là API Đối tác du lịch đã được bật cho dự án mới trong Tài khoản Google của bạn.

Phạm vi của Travel Partner API là: "https://www.googleapis.com/auth/travelpartner"

Điểm cuối của Travel Partner API là: "https://travelpartner.googleapis.com/v3/accounts/<account_id>/<path>"

Price Feeds API

Price Feeds API giúp các đối tác lưu trú cung cấp dữ liệu giá tuỳ chỉnh cho từng khách sạn. Các đối tác khách sạn của Google có thể sử dụng OAuth 2.0 để xác thực và uỷ quyền cho chính mình khi tải giá lên Google. Làm theo hướng dẫn thiết lập OAUTH 2.0 để được uỷ quyền cho Price Feeds API.

Những điểm cần lưu ý

Lưu ý những điểm khác biệt quan trọng trong hướng dẫn uỷ quyền cho Price Feeds API.

1. Các đối tác nên tạo một dự án mới về Nguồn cấp dữ liệu về giá theo OAuth 2.0 trong Bảng điều khiển Google Cloud bằng cách làm theo hướng dẫn tương tự như hướng dẫn trong phần Thiết lập OAuth 2.0.

2. Bạn KHÔNG bắt buộc phải bật Price Feeds API trong Google Cloud Console và có thể bỏ qua bước này. Bạn chỉ cần một tài khoản dịch vụ và khoá, sau đó sử dụng cùng một tài khoản dịch vụ và khoá để cấp quyền truy cập vào dự án Nguồn cấp dữ liệu giá cho dữ liệu Hotel Center của bạn. Làm theo các bước còn lại được đề cập trong phần thiết lập OAuth 2.0 để hoàn tất việc định cấu hình API.

Nhận mã truy cập OAuth 2.0 cho nguồn cấp dữ liệu về giá

Bước tiếp theo là lấy mã truy cập OAuth 2.0 có phạm vi tải lên giá lưu trú bằng tệp khoá tài khoản dịch vụ. Bạn có thể uỷ quyền cho các yêu cầu đến dự án Nguồn cấp dữ liệu về giá bằng cách làm theo hướng dẫn trong phần Chuẩn bị thực hiện lệnh gọi API được uỷ quyền, sau đó trích xuất mã truy cập từ thông tin đăng nhập đã nhận được và đặt mã này trong tiêu đề HTTP "Authorization".

Phạm vi tải giá lưu trú lên là: "https://www.googleapis.com/auth/travel-partner-price-upload"

Tải giá lên

Sau khi nhận được mã truy cập, các đối tác có thể tải nguồn cấp dữ liệu giá lên tương tự như việc sử dụng IP tĩnh để xác thực và uỷ quyền với nội dung sửa đổi sau:

• Đặt mã truy cập trong tiêu đề HTTP "Authorization"

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>

Kiểm thử chế độ thiết lập OAuth 2.0 cho Price Feeds API

Bạn có thể kiểm thử chế độ thiết lập OAuth 2.0 bằng cách tải một tệp trống lên hoặc bằng dữ liệu giá thực tế lên bất kỳ đường dẫn tải lên nào. Hãy sử dụng bảng này để kiểm tra trạng thái phản hồi HTTP.

Khắc phục sự cố

Bạn gặp sự cố? Kiểm tra nhanh các mục sau có thể giúp bạn giải quyết sự cố.

1. Bạn có tạo dự án trong Bảng điều khiển Google Cloud không?
2. Bạn có bật dịch vụ này trong dự án của mình không?
3. Bạn đã tải tệp .JSON xuống chưa? Đây là một khoá riêng tư có được sau khi bạn nhấp vào Tạo mã ứng dụng và chọn Tài khoản dịch vụ.
4. Bạn có nhận được địa chỉ email mã máy khách của tài khoản dịch vụ có dạng: nnnnnnn@app_name.google.com.iam.gserviceaccount.com không?
5. Bạn đã chia sẻ tài khoản Hotel Ads Center 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?
6. 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 Giám đốc Quản lý Khách hàng về Kỹ thuật (TAM) chưa?
7. Các lệnh gọi API của bạn có gửi mã truy cập vừa nhận được trong tiêu đề Authorization không?
8. Mã thông báo của bạn đã được tạo hơn 1 giờ chưa?

Bảng sau đây liệt kê một số lỗi phổ biến và những giải pháp có thể áp dụng: