Ủy quyền API

Tài liệu này cung cấp hướng dẫn từng bước để thiết lập OAuth2.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 bài viết Sử dụng OAuth 2.0 để truy cập vào 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 xác định bản thân bằng một 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 để nhận dữ liệu chỉ có thể đọc, chẳng hạn như 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ó 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 truyền 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 cho bất kỳ API Khách sạn nào, hãy làm theo các bước sau:

1. Tạo 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ả cụ thể trong phần tiếp theo.

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

Google Cloud Console dùng để 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 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 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 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ị một nút CREATE PROJECT (TẠO DỰ ÁN):

   

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

   

   Đặt tên dễ nhớ cho dự án 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. 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 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 mục Thông tin xác thực trong trình đơn điều hướng bên trái. Google Cloud Console sẽ hiển thị 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ử 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. Chế độ xem Tạo khoá tài khoản dịch vụ sẽ xuất hiện.

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à riêng biệt cho mỗi 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 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 của mình hoặc cá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ài khoản dịch vụ đã được tạo" 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 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 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 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 by 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 để truy cập API sau khoảng 24 giờ.

Sau khi Google thông báo đã bật quyền truy cập API 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.

Tham khảo phần Chuẩn bị thực hiện lệnh gọi API được uỷ quyền.

Phạm vi

Sau đây là SCOPES cho API Khách sạn:

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

API nguồn cấp dữ liệu giá: "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 xác thực. Hãy 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, hãy nhớ 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 trên Hotel Center và thay đổi dữ liệu trên 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 API Đối tác du lịch.

Khi tạo một dự án mới cho API Đối tác du lịch, bạn cần bật quyền truy cập vào dự án mới của mình trong Google Cloud Console.

Hãy làm theo các bước sau để bật quyền truy cập vào API Đối tác du lịch:

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 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. Google Cloud Console sẽ hiển thị thông tin 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ụ.

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

Phạm vi của API Đối tác du lịch 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>"

API nguồn cấp dữ liệu giá

API nguồn cấp dữ liệu giá cho phép các đối tác lưu trú cung cấp dữ liệu giá tuỳ chỉnh cho mọi khách sạn. Đối tác lưu trú của Google có thể sử dụng OAuth2.0 để tự xác thực và uỷ quyền 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 API Nguồn cấp dữ liệu giá.

Những điểm cần nhớ

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

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

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

Nhận mã truy cập OAuth2.0 cho nguồn cấp dữ liệu giá

Bước tiếp theo là lấy mã truy cập OAuth2.0 có phạm vi tải giá phòng lên bằng tệp khoá tài khoản dịch vụ. Bạn có thể uỷ quyền các yêu cầu đến dự án Price Feeds 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 xác thực đã thu được và đặt mã truy cập đó trong tiêu đề HTTP "Authorization".

Phạm vi tải giá phòng lên là: "https://www.googleapis.com/auth/travel-partner-price-upload"

Tải giá lên

Sau khi nhận được mã thông báo truy cập, đối tác có thể tải nguồn cấp dữ liệu giá lên tương tự như khi sử dụng IP tĩnh để xác thực và uỷ quyền bằng 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 OAuth2.0 cho API Nguồn cấp dữ liệu giá

Bạn có thể kiểm thử chế độ thiết lập OAuth2.0 bằng cách tải một tệp trống hoặc tệp có dữ liệu giá thực lên bất kỳ đường dẫn tải lên nào. 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 Google Cloud Console không?
2. Bạn đã bật dịch vụ này trong dự án của mình chưa?
3. Bạn đã tải tệp .JSON (khoá riêng tư) xuống sau khi nhấp vào Tạo mã ứng dụng khách và chọn Tài khoản dịch vụ chưa?
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 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?
6. Bạn đã gửi địa chỉ email của tài khoản dịch vụ và mã đối tác của mình đến 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: