Otorisasi API

Gunakan OAuth 2.0 untuk memberikan otorisasi pada aplikasi Anda saat mengakses API hotel.

Penyiapan OAuth 2.0

OAuth 2.0 mengharuskan Anda mengidentifikasi diri menggunakan akun layanan yang terkait dengan Akun Google Anda. Akun layanan akan mengirimkan kunci pribadi Anda untuk ditukar dengan token akses OAuth 2.0. Selanjutnya, Anda dapat menggunakan token ini dalam panggilan ke API hotel untuk data hanya baca, seperti data pelaporan harga, hotel, dan diagnostik tentang feed harga hotel.

Token akses berlaku selama satu jam (3.600 detik).

Jika sebelumnya Anda telah menerapkan ClientLogin, pendekatan OAuth 2.0 serupa dengan perbedaan berikut:

• Aplikasi Anda menggunakan akun layanan Google untuk mengakses API.
• Anda meneruskan token akses OAuth 2.0 di header HTTP Authorization saat memanggil API.

Untuk menyiapkan akun Anda agar menggunakan OAuth 2.0 dengan Travel Partner API, lakukan langkah-langkah berikut:

1. Membuat project baru di Google Developers Console (DevConsole)

2. Mengaktifkan akses ke Travel Partner API untuk project baru

3. Membuat akun layanan dan kredensialnya

4. Memberi akun layanan akses ke data hotel Anda

Setiap langkah ini dijelaskan di bagian berikut.

Langkah 1: Buat Project DevConsole baru

Google Developers Console ('DevConsole') adalah pengalaman developer Google untuk mengelola dan melihat data traffic, autentikasi, dan informasi penagihan untuk Google API yang digunakan project Anda.

Di DevConsole, project adalah kumpulan setelan, kredensial, dan metadata tentang aplikasi atau aplikasi yang sedang Anda kerjakan yang menggunakan Google Developer API dan resource Google Cloud.

DevConsole adalah tempat Anda mengelola aspek-aspek project ini, seperti membuat kredensial API, mengaktifkan API, serta mengelola informasi tim dan penagihan yang terkait dengan project Anda.

Untuk membuat project DevConsole baru:

1. Login ke Akun Gmail/Google Anda.

2. Buka Google Developers Console. Jika ini adalah project pertama Anda, tampilan utama akan menampilkan tombol CREATE PROJECT sederhana:

   

3. Klik tombol CREATE PROJECT. DevConsole menampilkan kotak dialog New Project:

   

   Masukkan nama yang sesuai untuk project baru Anda di kolom input Project name. Di bawah kolom ini, DevConsole menghasilkan project ID untuk Anda, yang memastikan bahwa ID tersebut bersifat unik di semua project. Misalnya, jika Anda memasukkan "My New Project", DevConsole menetapkan ID seperti my-new-project-266022.

4. Klik tombol Create untuk membuat project baru.

5. Gunakan menu navigasi untuk memilih APIs & Services > Dashboard.

   

   Gambar di bawah ini menunjukkan menu navigasi di kiri atas DevConsole. Tindakan ini akan menampilkan tampilan Dashboard untuk project Anda:

   

Untuk informasi selengkapnya, lihat Mengelola project di Konsol Play.

Saat Anda membuat project baru, belum ada API yang terkait dengannya. Pada langkah berikutnya, Anda akan mengaktifkan Travel Partner API untuk Project baru Anda.

Langkah 2: Aktifkan Travel Partner API untuk project baru

Untuk menggunakan API hotel, Anda harus mengaktifkan Travel Partner API dalam project DevConsole baru.

Untuk mengaktifkan API hotel bagi project baru Anda:

1. Buka tampilan Dashboard project Anda seperti yang dijelaskan di atas.

2. Klik Aktifkan API dan Layanan. Tindakan ini akan menampilkan halaman sambutan Library API.

3. Di kolom penelusuran, mulai ketik Travel Partner API. Konsol API Google menampilkan daftar API yang sesuai dengan yang Anda ketik.

   Poin Penting: Travel Partner API hanya dapat dilihat oleh partner tepercaya. Jika Anda tidak menemukan API saat melakukan penelusuran, hubungi Manajer Akun Teknis (TAM).

4. Klik Travel Partner API di tabel API yang cocok. DevConsole menampilkan deskripsi tentang API.

5. Klik tombol Enable API untuk mengaktifkan API ini untuk project Anda.

Untuk mengetahui informasi selengkapnya, lihat Mengaktifkan dan menonaktifkan API.

Hotel API kini diaktifkan untuk project baru Akun Google Anda.

Langkah berikutnya adalah membuat akun layanan dan menghasilkan kunci untuk akun tersebut.

Langkah 3: Buat akun layanan dan buat kredensialnya

Akun layanan digunakan oleh interaksi server ke server seperti interaksi antara aplikasi web dan data hotel Anda.

Untuk membuat dan mengonfigurasi akun layanan:

1. Di tampilan utama Konsol API Google, klik Credentials di navigasi sebelah kiri. DevConsole menampilkan tampilan Credentials.

   Tampilan Credentials menampilkan client ID dan kredensial untuk project Anda. Aplikasi Anda akan menggunakan client ID saat meminta token akses OAuth 2.0. Project baru belum memiliki klien atau kredensial.

2. Klik link Credentials in APIs and services.

3. Klik tombol Create credentials, lalu pilih Service account key dari menu dropdown. Tampilan Buat kunci akun layanan akan ditampilkan.

4. Dari menu dropdown Service account, pilih New service account.

5. Masukkan nama akun layanan dan ID akun layanan.

   Anda dapat menggunakan nama apa pun sesuai keinginan, tetapi ID akun harus unik di semua project. DevConsole akan menghasilkan ID akun unik untuk Anda, berdasarkan nama yang Anda masukkan.

6. Pilih P12 untuk jenis kunci, seperti yang ditunjukkan di bawah. P12 wajib diisi.

   

7. Klik tombol Buat. DevConsole menghasilkan pasangan kunci pribadi/publik untuk project Anda. Kunci pribadi disimpan ke lokasi default tempat browser Anda menyimpan download. Anda harus mendownload format .p12 (biner), bukan format file .json.

   Anda menggunakan kunci pribadi dalam skrip Anda atau aplikasi lain yang mengakses Travel Partner API.

   Perhatian: File kunci pribadi berisi data sensitif yang harus diakses oleh klien untuk mendapatkan token, sehingga harus disimpan di tempat yang aman.

   DevConsole menampilkan pemberitahuan berikut setelah selesai membuat kunci:

   

8. Klik tombol OK, get it. DevConsole mengembalikan Anda ke tampilan Credentials. Untuk mengonfirmasi detail tentang akun layanan dan melihat akun layanan yang terkait dengan project, klik Manage service accounts di tampilan ini.

   Akun layanan kini memiliki kredensial berikut yang terkait dengannya:

   • Client ID: ID unik yang digunakan aplikasi Anda saat meminta token akses OAuth 2.0.
   • Alamat email: Alamat email yang dibuat untuk akun layanan, dalam bentuk "account_name@project_name.google.com.iam.gserviceaccount.com".
   • Sidik jari sertifikat: ID kunci pribadi yang Anda download.

Poin Penting: Gunakan Alamat email sebagai akun layanan saat mendapatkan token akses untuk API. JANGAN menggunakan client ID atau sidik jari kunci pribadi untuk tujuan ini.

Untuk informasi selengkapnya, lihat Menggunakan OAuth 2.0 untuk Aplikasi Server ke Server.

Langkah 4: Beri akun layanan akses ke data Pusat Pengelolaan Hotel Anda

Langkah terakhir adalah memberi akun layanan baru akses ke Pusat Pengelolaan Hotel Anda. Akun layanan diidentifikasi berdasarkan alamat email yang dihasilkan yang Anda buat di langkah sebelumnya. Anda memberikan akses ke akun ini menggunakan setelan berbagi Pusat Pengelolaan Hotel.

Untuk memberi akun layanan akses ke data Pusat Pengelolaan Hotel Anda:

Jika Anda tidak memiliki akses yang sesuai untuk menambahkan pengguna ke akun, hubungi tim Hotel di Google menggunakan formulir hubungi kami dan minta kami untuk menyiapkan kepemilikan akun Anda. Anda dapat meminta satu atau beberapa email agar dibuat ke pemilik. Untuk informasi selengkapnya tentang akses Pusat Pengelolaan Hotel, lihat Menautkan Pusat Pengelolaan Hotel dan Google Ads.

1. Di jendela browser baru, buka Pusat Pengelolaan Hotel.

2. Pada banner Pusat Pengelolaan Hotel dari Google, klik ikon tambahkan pengguna untuk membuka dialog berbagi.

   

3. Di kolom Tambahkan orang lainnya, masukkan alamat email akun layanan yang ingin Anda tambahkan ke Pusat Pengelolaan Hotel.

4. Pastikan opsi Beri tahu orang tetap dipilih.

5. Dari menu drop-down, pilih Kelola.

6. Klik tombol Undang.

7. Setelah Anda menambahkan pengguna ke Pusat Pengelolaan Hotel, akun layanan Anda akan diaktifkan untuk akses API dalam waktu sekitar 24 jam.

Setelah Google memberi tahu Anda bahwa akses API diaktifkan untuk akun layanan, Anda dapat mulai mengakses API dengan OAuth.

Menggunakan OAuth 2.0

Untuk mengakses API, aplikasi Anda harus mengidentifikasi dirinya ke Google dengan alamat email dan kunci pribadi yang dihasilkan oleh akun layanan. Mekanisme autentikasi Google menukar kunci ini dengan token akses OAuth 2.0 yang Anda teruskan dalam header Authorization dalam panggilan API aplikasi Anda.

Token akses (disebut juga token pemilik) adalah bagian dari standar OAuth 2.0. Sintaksis untuk menentukan token akses di header HTTP adalah:

Authorization: Bearer *oauth2_access_token*

Contoh berikut menunjukkan contoh header HTTP permintaan yang mengakses Reports API:

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

Untuk membuat token akses, buat aplikasi dalam bahasa apa pun yang Anda pilih. Contoh berikut menghasilkan token di Python. Selanjutnya, Anda dapat menggunakan token ini dalam header Authorization permintaan saat mengakses 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 = ('[e-mail]')

# 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>

Saat mengembangkan aplikasi, pastikan untuk mengikuti Praktik terbaik untuk menggunakan kunci API dengan aman.

Contoh skrip Python menghasilkan token Pembawa header Authorization, seperti yang ditunjukkan contoh berikut:

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

Gunakan nilai token dalam permintaan Anda. Token ini berlaku 1 jam setelah Anda membuatnya.

Pemecahan masalah

Mengalami masalah? Melakukan pemeriksaan cepat pada item berikut dapat mengatasi masalah tersebut.

1. Apakah Anda membuat project di Google Developers Console?
2. Apakah Anda menemukan dan mengaktifkan Travel Partner API?
3. Apakah Anda mendownload file .p12—kunci pribadi setelah mengklik Buat client ID dan memilih Akun layanan?
4. Apakah Anda mendapatkan alamat email client ID akun layanan dengan formulir: nnnnnnn@app_name.google.com.iam.gserviceaccount.com?
5. Apakah Anda membagikan akun Pusat Bantuan Iklan Hotel ke akun layanan tersebut dengan mengklik tombol Bagikan akun ini?
6. Apakah Anda mengirimkan alamat email akun layanan dan ID partner ke Manajer Akun Teknis (TAM)?
7. Apakah panggilan Travel Partner API Anda meneruskan token yang baru diperoleh di header Authorization?
8. Apakah Token pemilik header Authorization Anda sudah lebih dari 1 jam?

Tabel berikut mencantumkan beberapa error umum dan kemungkinan penyelesaiannya:

Error	Deskripsi
Invalid credentials	Informasi ini bisa berarti beberapa hal. Jika Anda mengalami error ini, pastikan: Anda menentukan header Authorization dengan token pemilik yang valid. Token pemilik baru berusia kurang dari satu jam. Token hanya berlaku selama satu jam. Anda menentukan nama partner yang benar (dengan parameter string kueri partner). Nilainya adalah ID partner unik, bukan nama partner yang muncul di Pusat Bantuan Iklan Hotel. Jika tidak mengetahui ID partner Anda, hubungi Manajer Akun Teknis (TAM) Anda.
Not found	Kemungkinan besar format endpoint Anda salah. Pastikan Anda mengirim permintaan GET dan bahwa URL permintaan valid (sesuai dengan sintaksis API yang Anda coba akses).
Invalid string value	Satu atau beberapa bagian endpoint berisi sintaksis yang tidak valid. Misalnya, Anda mungkin salah mengeja bagian jalur. Pastikan Anda menggunakan garis bawah, huruf besar, dan kata yang benar di seluruh jalur.
Unsupported output format	Error ini paling sering terjadi saat menggunakan Reports API. Anda harus menentukan "alt=csv" dalam URL permintaan GET Anda. Reports API tidak mendukung JSON.
AccessTokenRefreshError/Invalid grant	Saat menjalankan contoh aplikasi Python, error ini mungkin disebabkan oleh hal berikut: Alamat email akun layanan Anda salah. Periksa akun email di Google Developers Console dan pastikan akun telah diberi otorisasi untuk mengakses API. Alamat email tidak memiliki akses API. Periksa apakah alamat email telah diberi otorisasi untuk mengakses data hotel Anda (dibagikan melalui Pusat Pengelolaan Hotel). File kunci bukan file yang benar untuk akun layanan. Gunakan DevConsole untuk mendownload sertifikat .p12 baru dan pastikan aplikasi Python Anda mengarah ke sertifikat yang benar.
HotelAdsAPIConnection object has no attribute credentials	Saat menjalankan contoh aplikasi Python, jalur ke file .p12 Anda salah.
Invalid scope	Saat menjalankan contoh aplikasi Python, cakupan API harus berupa https://www.googleapis.com/auth/travelpartner.
Forbidden	ID akun yang Anda gunakan adalah ID yang tidak dapat Anda akses. Jika Anda adalah pemilik sub-akun, Anda mungkin tidak dapat mengakses ID akun induk atau root.