Xác thực API

Xác thực ứng dụng của bạn bằng OAuth 2.0 để bạn có thể truy cập API khách sạn.

Thiết lập OAuth 2.0

API 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 một khóa riêng tư (do bạn tạo) để đổi lại một mã truy cập OAuth 2.0. Sau đó, bạn sẽ dùng lệnh gọi để gửi mã truy cập này đến API khách sạn để nhận các 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 này sẽ tồn tại trong 3600 giây (một giờ).

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 thực hiện lệnh gọi API.

Để thiết lập tài khoản của bạn để sử dụng OAuth 2.0 cho "API Đối tác du lịch", hãy làm theo hướng dẫn chung sau đây:

  1. Tạo một Dự án mới trong Google Developers Console (DevConsole)
  2. Cấp quyền truy cập vào "API Đối tác du lịch" cho Dự án mới
  3. 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 đó
  4. 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 trong DevConsole

Google Developers Console ("DevConsole") là nơi Google cho phép 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 của 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 gồm các chế độ cài đặt, thông tin xác thực và siêu dữ liệu về (những) ứ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.

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ý 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 trong DevConsole:

  1. Đăng nhập vào Gmail/Tài khoản Google của bạn.
  2. Mở Google Developers 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 Tạo dự án:
  3. Nhấp vào nút Tạo dự án. DevConsole sẽ hiển thị hộp thoại 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, DevConsole 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", DevConsole sẽ gán một mã nhận dạng như "dụ-án-mới-của-tôi-266022".

  4. Nhấp vào nút Tạo để tạo dự án mới. DevConsole sẽ 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.

    Như bạn có thể thấy trong hình, trình đơn điều hướng nằm ở phía trên bên trái của DevConsole. 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 Quản lý dự án trong Developers Console.

Khi bạn tạo dự án mới, chưa có API nào được liên kết với dự án đó. Trong bước tiếp theo, bạn sẽ bật API Đối tác du lịch cho Dự án mới của mình.

Bước 2: Bật API Đối tác du lịch cho Dự án mới

Để sử dụng API khách sạn, bạn phải bật API Đối tác du lịch trong dự án mới của mình trong DevConsole.

Cách bật API khách sạn cho dự án mới:

  1. Chuyển đến chế độ xem Trang tổng quan của dự án như đã mô tả ở trên.
  2. Nhấp vào mục 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". Bảng điều khiển API của Google 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 mục API Đối tác du lịch trong bảng hiển thị những API phù hợp. DevConsole 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 tham khảo phần Kích hoạt và hủy kích hoạt API.

Vậy là API khách sạ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 khóa 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ụ 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à thiết lập 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, 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. DevConsole 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 sẽ không 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 Khóa của tài khoản dịch vụ trong trình đơn thả xuống.

    Bạn sẽ thấy chế độ xem Tạo khóa tài khoản dịch vụ.

  4. Trong trình đơn thả xuống Tài khoản dịch vụ, 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 tùy ý, nhưng Mã tài khoản phải là riêng biệt cho mỗi dự án. DevConsole sẽ tạo một Mã tài khoản riêng biệt dựa theo Tên mà bạn nhập.

  6. Chọn Loại khóa là P12 như hình bên dưới. Bắt buộc phải chọn P12.
  7. Nhấp vào nút Tạo. DevConsole sẽ tạo một cặp khóa riêng tư/công khai cho dự án của bạn. Khóa 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 định dạng .p12 (nhị phân) xuống, chứ không phải định dạng tệp .json.

    Khóa riêng tư được dùng trong các tập lệnh của bạn hoặc các ứng dụng khác có quyền truy cập vào API Đối tác du lịch.

    DevConsole sẽ hiển thị thông báo sau đây khi hoàn tất quá trình tạo khóa:

  8. Nhấp vào nút Đã hiểu. DevConsole sẽ quay 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 các Tài khoản dịch vụ đã 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 khóa 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 hoạt động giữa các máy chủ.

Bước 4: 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ụ

Bước cuối cùng là cấp quyền truy cập vào dữ liệu Quảng cáo khách sạn của bạn 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 tùy chọn cài đặt chia sẻ của Trung tâm Quảng cáo khách sạn để cấp quyền truy cập cho tài khoản này.

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

  1. Hãy mở một cửa sổ trình duyệt mới, sau đó truy cập Trung tâm Quảng cáo khách sạn.
  2. Nhấp vào biểu tượng Chia sẻ tài khoản này trên trang chủ của Trung tâm Quảng cáo khách sạn:

    Trung tâm Quảng cáo khách sạn sẽ hiển thị hộp thoại Cài đặt chia sẻ.

  3. Trong trường Mời người khác, hãy nhập địa chỉ email của Tài khoản dịch vụ mà DevConsole đã tạo ở 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ên_tài_khoản@tên_dự_án.google.com.iam.gserviceaccount.com").

    Chọn mục Thông báo cho mọi người qua email và chọn quyền là Có thể chỉnh sửa như ví dụ dưới đây:

  4. Nhấp vào nút Gửi.

  5. Sau khi thêm Tài khoản dịch vụ vào tài khoản Trung tâm Quảng cáo khách sạn, địa chỉ email của Tài khoản dịch vụ sẽ có thể 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, theo hướng dẫn trong phần Sử dụng OAuth 2.0.

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à khóa 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 khóa 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.

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 phần tiêu đề HTTP là:

Authorization: Bearer oauth2_access_token

Sau đây là tiêu đề HTTP mẫu của một yêu cầu có quyền 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ữ lập trình bạn muốn. Ví dụ dưới đây sẽ tạo ra mã truy cập bằng ngôn ngữ Python. Sau đó, bạn có thể đưa mã truy cập này vào phần tiêu đề Authorization của yêu cầu khi truy cập API Đối tác du lịch.

Mã truy cập có giá trị trong 1 giờ.

#!/usr/bin/python2.7
#
# Copyright 2016 Google Inc. All Rights Reserved.
#
""" 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 "TECHNCIAL" partner account name, NOT the account
# name in the Hotel Ads Center or the numeric partner ID.
# Check with your TAM if you do not know your technical partner account 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)

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 để sử dụng khóa 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ư ví dụ dưới đây:

$ python sample.py
Authorization: Bearer ya29.42424242sample_420icu8122KSvoh4T42cRoG3rW1lc0Q
$

Sử dụng giá trị của mã truy cập này trong yêu cầu của bạn. Mã có giá trị trong vòng 1 giờ kể từ lúc được tạo ra.

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 Developers Console không?
  2. Bạn đã tìm thấy và bật “API Đối tác du lịch” chưa?
  3. Bạn đã tải tệp .p12 (khóa riêng tư có được sau khi nhấp vào mục “Tạo mã máy khách” và chọn “Tài khoản dịch vụ”) xuống 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@tên_ứng-dụng.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 bạn đến travelads-partners@google.com chưa?
  7. Các lệnh gọi API Đối tác du lịch 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 truy cập của tiêu đề Authorization đã đượ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:

Lỗi Mô tả
Invalid Credentials Thông báo này có thể mang nhiều ý nghĩa. Nếu gặp phải lỗi này, hãy kiểm tra xem:
  • Bạn đã chọn một tiêu đề Authorization có mã thông báo truy cập hợp lệ chưa.
  • Đã quá một giờ kể từ khi nhận được mã thông báo truy cập chưa. Mã thông báo chỉ có giá trị trong vòng một giờ.
  • Bạn đã chỉ định đúng tên đối tác hay chưa (bằng tham số của chuỗi truy vấn partner). Giá trị của tham số này chính là mã đối tác riêng biệt của bạn, chứ không phải là tên đối tác có trong Trung tâm Quảng cáo khách sạn. Nếu bạn không biết mã đối tác của mình, hãy liên hệ với Giám đốc Quản lý Khách hàng về Kỹ thuật (TAM).
Not Found Rất có thể điểm cuối của bạn không đúng định dạng. Kiểm tra xem có phải bạn đang gửi yêu cầu GET hay không và URL yêu cầu đã hợp lệ hay chưa (URL phải đúng với cú pháp của API mà bạn muốn truy cập).
Invalid string value Điểm cuối có một hoặc nhiều phần chứa cú pháp không hợp lệ. Ví dụ: bạn có thể đã gõ sai một phần của đường dẫn. Kiểm tra xem bạn đã sử dụng đúng dấu gạch dưới, cách viết hoa và cách dùng từ trong toàn bộ đường dẫn của mình chưa.
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 tham số "alt=csv" trong URL của yêu cầu GET. API Báo cáo không hỗ trợ định dạng JSON.
AccessTokenRefreshError/Invalid Grant Khi chạy ứng dụng Python mẫu, lỗi này có thể là do một trong các nguyên nhân sau đây:
  • Địa chỉ email của Tài khoản dịch vụ không chính xác. Hãy kiểm tra tài khoản email trong Google Developers Console và đảm bảo rằng tài khoản này đã được cấp quyền truy cập API.
  • Địa chỉ email không có quyền truy cập API. Kiểm tra để đảm bảo địa chỉ email đó đã được cấp quyền truy cập vào dữ liệu khách sạn của bạn (chia sẻ thông qua Hotel Center).
  • Tệp khóa dùng cho Tài khoản dịch vụ chưa đúng. Sử dụng DevConsole để tải chứng chỉ .p12 mới xuống và đảm bảo rằng ứng dụng viết bằng Python của bạn trỏ đến đúng chứng chỉ này.
'HotelAdsAPIConnection' object has no attribute 'credentials' Khi chạy ứng dụng mẫu viết bằng Python, đường dẫn tới tệp .p12 của bạn không chính xác.
Invalid Scope Khi chạy ứng dụng mẫu viết bằng Python, phạm vi của API phải là "https://www.googleapis.com/auth/travelpartner".
Forbidden Mã tài khoản mà bạn sử dụng chưa được cấp quyền truy cập. Nếu bạn là chủ sở hữu tài khoản phụ, có thể bạn sẽ không có quyền truy cập vào mã tài khoản của tài khoản chính hoặc tài khoản gốc.

Nếu vấn đề vẫn chưa được giải quyết, vui lòng liên hệ với bộ phận hỗ trợ kỹ thuật của Google.