Użyj OAuth 2.0 do autoryzowania aplikacji podczas uzyskiwania dostępu do interfejsów API hoteli.
Konfiguracja protokołu OAuth 2.0
Protokół OAuth 2.0 wymaga podania tożsamości przy użyciu konta usługi powiązanego z Twoim kontem Google. Konto usługi wysyła klucz prywatny w zamian za token dostępu OAuth 2.0. Następnie możesz używać tego tokena w wywołaniach interfejsów API hoteli w celu zbierania danych tylko do odczytu, takich jak informacje o cenach, hotelach i raportach diagnostycznych dotyczących pliku danych z cenami za pokoje hotelowe.
Tokeny dostępu są ważne przez godzinę (3600 sekund).
Jeśli korzystasz już z metody ClientLogin, protokół OAuth 2.0 działa podobnie, z tymi różnicami:
- Twoja aplikacja uzyskuje dostęp do interfejsu API za pomocą konta usługi Google.
- Podczas wywoływania interfejsów API przekazujesz token dostępu OAuth 2.0 w nagłówku HTTP
Authorization.
Aby skonfigurować swoje konto do używania protokołu OAuth 2.0 w połączeniu z Travel Partner API, wykonaj te czynności:
Każdy z tych kroków jest opisany w dalszej części tego artykułu.
Krok 1. Utwórz nowy projekt DevConsole
Google Developers Console („DevConsole”) to narzędzie Google dla programistów, które służy do zarządzania i przeglądania danych o ruchu, uwierzytelniania i płatności związanych z interfejsami API Google używanymi w Twoich projektach.
Projekt w DevConsole to zbiór ustawień, danych logowania i metadanych dotyczących aplikacji lub aplikacji, nad którymi pracujesz, korzystających z interfejsów Google Developer API i zasobów Google Cloud.
DevConsole to miejsce, w którym zarządzasz tymi aspektami projektu, takimi jak generowanie danych logowania do interfejsów API, aktywowanie interfejsów API oraz zarządzanie informacjami o zespole i rozliczeniach związanymi z projektem.
Aby utworzyć nowy projekt w DevConsole:
Zaloguj się na swoje konto Gmail/Google.
Otwórz Google Developer Console. Jeśli to Twój pierwszy projekt, w widoku głównym zobaczysz prosty przycisk UTWÓRZ PROJEKT:
Kliknij przycisk UTWÓRZ PROJEKT. DevConsole wyświetli okno Nowy projekt:
W polu do wprowadzania danych Nazwa projektu wpisz przyjazną nazwę nowego projektu. Pod tym polem devConsole wygeneruje identyfikator projektu, dzięki czemu będzie on unikalny dla wszystkich projektów. Jeśli na przykład wpiszesz „Mój nowy projekt”, DevConsole przypisze im identyfikator taki jak
my-new-project-266022.Aby utworzyć nowy projekt, kliknij przycisk Utwórz.
W menu nawigacyjnym kliknij Interfejsy API i usługi > Panel.
Na ilustracji poniżej widać menu nawigacyjne w lewym górnym rogu konsoli DevConsole. Wyświetli się widok Panel projektu:
Więcej informacji znajdziesz w artykule Zarządzanie projektami w konsoli programisty.
Gdy utworzysz nowy projekt, nie będą z nim powiązane żadne interfejsy API. W następnym kroku włączysz Travel Partner API dla swojego nowego projektu.
Krok 2. Włącz Travel Partner API w nowym projekcie
Aby korzystać z interfejsów API hoteli, musisz włączyć usługę Travel Partner API w nowym projekcie DevConsole.
Aby włączyć w nowym projekcie interfejsy API hoteli:
Otwórz widok panelu projektu w sposób opisany powyżej.
Kliknij Włącz interfejsy API i usługi. Wyświetli się strona powitalna Biblioteki interfejsów API.
W polu wyszukiwania zacznij wpisywać Travel Partner API. Konsola interfejsów API Google wyświetla listę interfejsów API pasujących do wpisywanego tekstu.
Kliknij Travel Partner API w tabeli pasujących interfejsów API. W DevConsole wyświetlany jest opis interfejsu API.
Kliknij przycisk Włącz API, aby włączyć ten interfejs API w swoim projekcie.
Więcej informacji znajdziesz w artykule Aktywowanie i dezaktywowanie interfejsów API.
Interfejsy API hoteli zostały włączone w nowym projekcie na Twoim koncie Google.
Następnym krokiem jest utworzenie konta usługi i wygenerowanie dla niego kluczy.
Krok 3. Utwórz konto usługi i wygeneruj jego dane logowania
Konta usługi są używane w ramach interakcji między serwerami, np. między aplikacją internetową a danymi hoteli.
Aby utworzyć i skonfigurować konto usługi:
W głównym widoku konsoli interfejsów API Google kliknij Dane logowania w panelu nawigacyjnym po lewej stronie. DevConsole wyświetla widok Credentials (Dane logowania).
Widok Dane logowania zawiera identyfikatory klientów i dane logowania projektu. Aplikacja będzie używać tego identyfikatora w żądaniu tokena dostępu OAuth 2.0. Nowe projekty nie będą jeszcze mieć klientów ani danych logowania.
Kliknij link Dane logowania w interfejsach API i usługach.
Kliknij przycisk Utwórz dane logowania i z menu wybierz Klucz konta usługi. Pojawi się widok Utwórz klucz konta usługi.
W menu Konto usługi wybierz Nowe konto usługi.
Wpisz nazwę i identyfikator konta usługi.
Nazwa może być dowolna, ale identyfikator konta musi być niepowtarzalny dla wszystkich projektów. DevConsole wygeneruje dla Ciebie unikalny identyfikator konta na podstawie wpisanej przez Ciebie nazwy.
Wybierz P12 jako typ klucza, jak pokazano poniżej. Parametr P12 jest wymagany.
Kliknij przycisk Utwórz. DevConsole generuje parę kluczy (prywatny/publiczny) dla Twojego projektu. Klucz prywatny jest zapisywany w domyślnej lokalizacji, w której przeglądarka przechowuje pobrane pliki. Musisz pobrać plik w formacie
.p12(binarny), a nie w formacie.json.Klucza prywatnego używasz w skryptach lub innych aplikacjach mających dostęp do Travel Partner API.
Po zakończeniu generowania kluczy DevConsole wyświetli to powiadomienie:
Kliknij przycisk OK, rozumiem. DevConsole wróci do widoku Dane logowania. Aby potwierdzić szczegóły konta usługi i wyświetlić konta usługi powiązane z Twoim projektem, kliknij Zarządzaj kontami usługi w tym widoku.
Z kontem usługi są teraz powiązane te dane logowania:
- Identyfikator klienta: unikalny identyfikator używany przez aplikację, gdy żądasz tokena dostępu OAuth 2.0.
- Adres e-mail: wygenerowany adres e-mail konta usługi w formacie „account_name@account_name.google.com.iam.gserviceaccount.com”.
- Odciski cyfrowe certyfikatu: identyfikator pobranego klucza prywatnego.
Więcej informacji znajdziesz w artykule Używanie protokołu OAuth 2.0 w aplikacjach między serwerami.
Krok 4. Przyznaj kontu usługi dostęp do danych z Hotel Center
Ostatnim krokiem jest przyznanie nowemu kontu usługi dostępu do Twojego konta Hotel Center. Konto usługi jest identyfikowane przez wygenerowany adres e-mail utworzony w poprzednim kroku. Aby zapewnić dostęp do tego konta, użyj ustawień udostępniania Hotel Center.
Aby przyznać kontu usługi dostęp do danych z Hotel Center:
Jeśli nie masz odpowiednich uprawnień, aby dodać użytkowników do konta, skontaktuj się z zespołem Google Hotels za pomocą formularza kontaktowego i poproś nas o udzielenie praw własności do Twojego konta. Możesz poprosić o przyznanie jednego lub kilku e-maili do właściciela. Więcej informacji o dostępie do Hotel Center znajdziesz w artykule Łączenie Hotel Center i Google Ads.
W nowym oknie przeglądarki otwórz Hotel Center.
Na banerze Hotel Center by Google kliknij ikonę dodawania użytkownika, aby otworzyć okno udostępniania.
W polu Dodaj więcej osób wpisz adres e-mail konta usługi, które chcesz dodać do Hotel Center.
Pozostaw zaznaczoną opcję Powiadom innych.
W menu wybierz Zarządzaj.
Kliknij przycisk Zaproś.
Gdy dodasz użytkowników do Hotel Center, Twoje konto usługi powinno mieć dostęp do interfejsu API w ciągu około 24 godzin.
Gdy Google powiadomi Cię, że dostęp przez interfejs API jest włączony dla Twojego konta usługi, możesz zacząć korzystać z interfejsu API przy użyciu protokołu OAuth.
Korzystanie z OAuth 2.0
Aby uzyskać dostęp do interfejsu API, aplikacja musi zidentyfikować się w Google za pomocą adresu e-mail wygenerowanego przez konto usługi i klucza prywatnego. Mechanizm uwierzytelniania Google wymienia ten klucz na token dostępu OAuth 2.0, który przekazujesz w nagłówku Authorization w wywołaniach interfejsu API aplikacji.
Tokeny dostępu (nazywane też tokenami okaziciela) są częścią standardu OAuth 2.0. Składnia, która służy do określania tokena dostępu w nagłówku HTTP:
Authorization: Bearer *oauth2_access_token*
Poniższy przykład pokazuje przykładowe nagłówki HTTP żądania uzyskującego dostęp do interfejsu 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
Aby wygenerować token dostępu, utwórz aplikację w dowolnym języku.
Poniższy przykład generuje token w Pythonie. Następnie możesz używać tego tokena w nagłówkach Authorization swoich żądań przy uzyskiwaniu dostępu do 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 = ('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 "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>
Podczas tworzenia aplikacji postępuj zgodnie ze sprawdzonymi metodami korzystania z kluczy interfejsu API.
Przykładowy skrypt Pythona generuje token okaziciela nagłówka Authorization, jak widać w tym przykładzie:
$ python sample.py Authorization: Bearer ya29.42424242sample_420icu8122KSvoh4T42cRoG3rW1lc0Q $
Używaj wartości tokena w żądaniach. Są one przechowywane przez godzinę po wygenerowaniu.
Rozwiązywanie problemów
Masz problemy? Szybkie sprawdzenie podanych niżej elementów może rozwiązać problem.
- Czy masz projekt utworzony w Google Developer Console?
- Czy udało Ci się znaleźć i włączyć Travel Partner API?
- Czy pobrałeś plik
.p12- klucz prywatny po kliknięciu Utwórz identyfikator klienta i wybraniu Konto usługi? - Czy masz adres e-mail powiązany z identyfikatorem klienta konta usługi i formularzem:
nnnnnnn@app_name.google.com.iam.gserviceaccount.com? - Czy konto Hotel Ads Center zostało udostępnione kontu usługi przez kliknięcie przycisku Udostępnij to konto?
- Czy adres e-mail konta usługi i identyfikator partnera zostały wysłane do technicznego menedżera konta (TAM)?
- Czy Twoje wywołania Travel Partner API przekazują w nagłówku
Authorizationostatnio uzyskany token? - Czy token okaziciela nagłówka
Authorizationma więcej niż godzinę?
W poniższej tabeli znajdziesz listę kilku częstych błędów i możliwych sposobów ich rozwiązania:
| Błąd | Opis |
|---|---|
| Invalid credentials | Może to oznaczać kilka rzeczy. W przypadku tego błędu sprawdź, czy:
|
| Not found | Punkt końcowy najprawdopodobniej jest uszkodzony. Sprawdź, czy przesyłasz żądanie GET oraz czy adres URL żądania jest prawidłowy (jest zgodny ze składnią interfejsu API, do którego próbujesz uzyskać dostęp). |
| Invalid string value | Co najmniej jedna część punktu końcowego zawiera nieprawidłową składnię. Na przykład część ścieżki mogła zawierać literówkę. Sprawdź, czy podkreślenia, wielkie litery i słownictwo są użyte w całej ścieżce. |
| Unsupported output format | Ten błąd występuje najczęściej podczas korzystania z interfejsu Reports API. Musisz określić "alt=csv" w adresie URL żądania GET. Interfejs Reports API nie obsługuje formatu JSON. |
| AccessTokenRefreshError/Invalid grant | Podczas uruchamiania przykładowej aplikacji w Pythonie ten błąd może być spowodowany przez:
|
| HotelAdsAPIConnection object has no attribute credentials | Podczas uruchamiania przykładowej aplikacji w Pythonie ścieżka do pliku .p12 jest nieprawidłowa. |
| Invalid scope | Podczas uruchamiania przykładowej aplikacji w Pythonie zakres interfejsu API musi wynosić https://www.googleapis.com/auth/travelpartner. |
| Forbidden | Identyfikator konta, którego używasz, jest kontem, do którego nie masz uprawnień dostępu. Jeśli jesteś właścicielem subkonta, możesz nie mieć dostępu do identyfikatora konta nadrzędnego lub głównego. |