Autenticazione API

Con OAuth 2.0 puoi autenticare la tua applicazione per accedere alle API per gli hotel.

Configurare OAuth 2.0

L'API OAuth 2.0 richiede di identificarti utilizzando un account di servizio associato al tuo Account Google. L'account di servizio invia una chiave privata (creata da te) e riceve un token di accesso OAuth 2.0. Successivamente, passerai il token nelle chiamate alle API hotel per dati di sola lettura, come quelli dei prezzi, degli hotel e dei rapporti diagnostici relativi al tuo feed prezzo dell'hotel.

Il token di accesso è valido per 3600 secondi (un'ora).

Se avevi implementato ClientLogin, noterai che l'approccio per OAuth 2.0 è analogo, ma con le seguenti differenze:

  • L'applicazione utilizza un account di servizio Google per accedere all'API.
  • Passi il token di accesso OAuth 2.0 nell'intestazione HTTP Authorization durante le chiamate API.

Per configurare l'account per l'utilizzo di OAuth 2.0 con l'API Travel Partner, esegui la procedura generale indicata di seguito:

  1. Crea un nuovo progetto in Google Developers Console (DevConsole)
  2. Abilita l'accesso all'API Travel Partner per il nuovo progetto
  3. Crea un account di servizio e le relative credenziali
  4. Consenti all'account di servizio di accedere ai dati sugli hotel

Ogni passaggio è descritto nelle sezioni seguenti.

Passaggio 1: crea un nuovo progetto DevConsole

Google Developers Console ("DevConsole") è uno strumento rivolto agli sviluppatori di Google che consente di gestire e visualizzare dati sul traffico, sull'autenticazione e sulla fatturazione per le API di Google utilizzate nei tuoi progetti.

In DevConsole, un progetto è una raccolta di impostazioni, credenziali e metadati riguardanti le applicazioni che stai sviluppando e che utilizzano le API Google Developers e le risorse di Google Cloud.

In DevConsole puoi gestire vari aspetti del tuo progetto, ad esempio generare credenziali per le API, attivare le API e gestire le informazioni sui team e i dati di fatturazione associati al progetto.

Per creare un nuovo progetto DevConsole:

  1. Accedi al tuo account Gmail/Account Google.
  2. Apri Google Developers Console. Se questo è il tuo primo progetto, nella visualizzazione principale viene mostrato un semplice pulsante Crea progetto:
  3. Fai clic sul pulsante Crea progetto. In DevConsole viene visualizzata la finestra di dialogo Nuovo progetto:

    Inserisci un nome intuitivo per il nuovo progetto nel campo di immissione Nome progetto. Sotto il campo, DevConsole genera un ID progetto, garantendo che l'ID sia univoco per tutti i progetti. Ad esempio, se inserisci "My New Project", DevConsole assegna un ID simile a "my-new-project-266022".

  4. Fai clic sul pulsante Crea per creare il nuovo progetto. DevConsole crea il nuovo progetto.
  5. Utilizza il menu di navigazione per selezionare API e servizi > Dashboard.

    Come puoi vedere nell'immagine, il menu di navigazione si trova in alto a sinistra in DevConsole. Viene presentata la visualizzazione Dashboard del progetto:

Per ulteriori informazioni, consulta Gestire i progetti in Developers Console.

Appena creato, un nuovo progetto non è ancora associato ad alcuna API. Nel passaggio successivo, attiverai l'API Travel Partner per il tuo nuovo progetto.

Passaggio 2: attiva l'API Travel Partner per il nuovo progetto

Per utilizzare le API per gli hotel, devi attivare l'API Travel Partner nel nuovo progetto DevConsole.

Per attivare le API per gli hotel nel tuo nuovo progetto:

  1. Vai alla visualizzazione Dashboard del tuo progetto come descritto sopra.
  2. Fai clic su Abilita API e servizi. Viene visualizzata la pagina di benvenuto della libreria API.
  3. Nel campo di ricerca, inizia a digitare "Travel Partner". La console API di Google visualizza un elenco di API corrispondenti al testo digitato.
  4. Fai clic sull'API Travel Partner nella tabella delle API corrispondenti. In DevConsole viene visualizzata una descrizione dell'API.
  5. Fai clic sul pulsante Abilita API per abilitare l'API in questione per il progetto.

Per ulteriori informazioni, consulta Attivare e disattivare le API.

Le API per gli hotel sono ora abilitate per il nuovo progetto del tuo Account Google.

Il passaggio successivo consiste nel creare un account di servizio e generare le relative chiavi.

Passaggio 3: crea un account di servizio e genera le relative credenziali

Gli account di servizio vengono utilizzati nelle interazioni tra server, come quelle tra un'applicazione web e i tuoi dati sugli hotel.

Per creare e configurare un account di servizio:

  1. Nella visualizzazione principale della console API di Google, fai clic su Credenziali nella barra di navigazione a sinistra. La visualizzazione in DevConsole passa a Credenziali.

    La visualizzazione Credenziali mostra gli ID client e le credenziali del tuo progetto. L'applicazione utilizzerà l'ID client durante la richiesta di un token di accesso OAuth 2.0. I progetti nuovi non sono ancora associati a client o credenziali.

  2. Fai clic sul link Credenziali in API e servizi.
  3. Fai clic sul pulsante Crea credenziali e seleziona Chiave account di servizio dal menu a discesa.

    La visualizzazione passa a Crea chiave account di servizio.

  4. Dal menu a discesa Account di servizio, seleziona Nuovo account di servizio.
  5. Inserisci un nome per l'account di servizio e un ID account di servizio.

    Puoi scegliere il nome che preferisci, ma l'ID account deve essere univoco per tutti i progetti. DevConsole genererà un ID account univoco basato sul nome da te inserito.

  6. Per Tipo di chiave, seleziona P12, come mostrato di seguito. P12 è obbligatorio.
  7. Fai clic sul pulsante Crea. DevConsole genera una coppia di chiavi pubblica/privata per il tuo progetto. La chiave privata viene salvata nel percorso predefinito in cui il browser archivia i download. Devi scaricare il file in formato .p12 (programma binario) anziché il file .json.

    La chiave privata viene utilizzata negli script o in altre applicazioni che accedono all'API Travel Partner.

    Una volta terminata la generazione delle chiavi, in DevConsole viene visualizzato il seguente avviso:

  8. Fai clic sul pulsante OK. DevConsole torna alla visualizzazione Credenziali. Per confermare i dettagli del tuo account di servizio e vedere gli account di servizio associati al progetto, fai clic su Gestisci account di servizio in questa visualizzazione.

    All'account di servizio sono ora associate le seguenti credenziali:

    • ID client: identificatore univoco utilizzato dall'applicazione per richiedere un token di accesso OAuth 2.0.
    • Indirizzo email: un indirizzo email generato per l'account di servizio, nel formato "account_name@project_name.google.com.iam.gserviceaccount.com".
    • Fingerprint del certificato: ID della chiave privata scaricata.

Per ulteriori informazioni, consulta Utilizzo di OAuth 2.0 per applicazioni da server a server.

Passaggio 4: consenti all'account di servizio di accedere ai dati sugli hotel

Il passaggio finale consiste nel fornire al nuovo account di servizio l'accesso ai tuoi dati di Hotel Ads. L'account di servizio è identificato dall'indirizzo email generato che hai creato nel passaggio precedente. Devi fornire l'accesso a questo account utilizzando le impostazioni di condivisione di Hotel Center.

Per consentire all'account di servizio di accedere ai dati di Hotel Ads:

  1. In una nuova finestra del browser, apri Hotel Center.
  2. Fai clic sull'icona Condividi questo account nella home page di Hotel Center:

    In Hotel Center viene visualizzata la finestra di dialogo Impostazioni di condivisione.

  3. Nel campo Invita persone, inserisci l'indirizzo email dell'account di servizio generato da DevConsole nel passaggio 3: creare un account di servizio e generare le relative credenziali ("account_name@project_name.google.com.iam.gserviceaccount.com").

    Mantieni selezionate l'opzione Invia notifica via email e l'autorizzazione Può modificare, come mostrato nell'esempio seguente:

  4. Fai clic sul pulsante Invia.

  5. Dopo aver aggiunto l'account di servizio al tuo account Hotel Center, l'indirizzo email dell'account di servizio viene abilitato per l'accesso all'API entro 24 ore circa.

Una volta che Google ti ha notificato che il tuo account di servizio può accedere all'API, puoi iniziare ad accedere all'API con OAuth 2.0, come descritto in Utilizzare OAuth 2.0.

Utilizzare OAuth 2.0

Per poter accedere all'API, la tua applicazione deve identificarsi con Google tramite la chiave privata e l'indirizzo email generati per l'account di servizio. Il meccanismo di autenticazione di Google scambia questa chiave con un token di accesso OAuth 2.0, che trasmetti nell'intestazione HTTP Authorization nelle chiamate API della tua app.

I token di accesso (detti anche token di connessione) fanno parte dello standard OAuth 2.0. La sintassi per specificare un token di accesso in un'intestazione HTTP è la seguente:

Authorization: Bearer oauth2_access_token

L'esempio seguente mostra intestazioni HTTP campione di una richiesta che accede all'API Reports:

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

Per generare un token di accesso, crea un'applicazione in un linguaggio a tua scelta. L'esempio seguente genera il token in Python. Potrai quindi utilizzare questo token nelle intestazioni Authorization delle tue richieste per accedere all'API Travel Partner.

Il token di accesso è valido per 1 ora.

#!/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)

Durante lo sviluppo dell'applicazione, assicurati di seguire le best practice per l'utilizzo sicuro delle chiavi API.

Lo script Python di esempio restituisce un token di connessione dell'intestazione Authorization, come illustrato nell'esempio seguente:

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

Utilizza il valore del token nelle richieste. Il token è valido per un'ora dopo che è stato generato.

Risoluzione dei problemi

Stai riscontrando problemi? Prova a verificare rapidamente quanto segue.

  1. Hai creato un progetto in Google Developers Console?
  2. Hai trovato e attivato l'API "Travel Partner"?
  3. Hai scaricato un file .p12 (una chiave privata) dopo aver fatto clic su "Crea ID client" e aver scelto "Account di servizio"?
  4. Hai ricevuto un indirizzo email per l'ID client dell'account di servizio (nel formato "nnnnnnn@app_name.google.com.iam.gserviceaccount.com")?
  5. Hai condiviso il tuo account Hotel Center con l'account di servizio facendo clic sul pulsante "Condividi questo account"?
  6. Hai inviato l'indirizzo email dell'account di servizio e il tuo ID partner a travelads-partners@google.com?
  7. Nelle tue chiamate all'API Travel Partner trasmetti un token acquisito di recente nell'intestazione Authorization?
  8. Il token di connessione dell'intestazione Authorization è stato generato da più di un'ora?

La seguente tabella elenca alcuni errori comuni e le possibili soluzioni:

Errore Descrizione
Invalid Credentials Questo può indicare diversi problemi. Se si verifica questo errore, controlla quanto segue:
  • Hai specificato un'intestazione Authorization con un token di connessione valido.
  • Il token di connessione è stato generato da meno di un'ora. Un token è valido solo per un'ora.
  • Hai specificato il nome partner corretto (con il parametro partner della stringa di query). Il valore è il tuo ID partner univoco, non il nome partner visualizzato in Hotel Center. Se non conosci il tuo ID partner, contatta il Technical Account Manager (TAM).
Not Found È molto probabile che il formato del tuo endpoint non sia corretto. Verifica di inviare una richiesta GET e che l'URL della richiesta sia valido (conforme alla sintassi dell'API a cui stai tentando di accedere).
Invalid string value Una o più parti dell'endpoint contengono una sintassi non valida. Ad esempio, potresti avere scritto in modo errato una parte del percorso. Verifica di aver utilizzato la combinazione corretta di trattini bassi, lettere maiuscole e minuscole e stringhe nell'intero percorso.
Unsupported Output Format Questo errore si verifica con la maggiore frequenza durante l'utilizzo dell'API Reports. Devi specificare "alt=csv" nell'URL della tua richiesta GET. L'API Reports non supporta il formato JSON.
AccessTokenRefreshError/Invalid Grant Durante l'esecuzione dell'app Python di esempio, questo errore potrebbe essere causato da uno dei seguenti problemi:
  • L'indirizzo email dell'account di servizio non è corretto. Controlla l'account email in Google Developers Console e assicurati che sia autorizzato ad accedere all'API.
  • L'indirizzo email non ha accesso all'API. Verifica che l'indirizzo email sia autorizzato ad accedere ai dati degli hotel (condivisi tramite Hotel Center).
  • Il file della chiave non è quello corretto per l'account di servizio. Utilizza DevConsole per scaricare un nuovo certificato .p12 e assicurati che la tua app Python stia puntando al file corretto.
'HotelAdsAPIConnection' object has no attribute 'credentials' Durante l'esecuzione dell'app Python di esempio, il percorso del file .p12 non è corretto.
Invalid Scope Durante l'esecuzione dell'app Python di esempio, l'ambito dell'API deve essere "https://www.googleapis.com/auth/travelpartner".
Forbidden Non hai l'autorizzazione per accedere all'ID account che stai utilizzando. Se sei proprietario di un subaccount, potresti non essere in grado di accedere all'ID account principale o root.

Se il problema persiste, contatta l'assistenza tecnica di Google.