Use o OAuth 2.0 para autorizar seu aplicativo quando acessar as APIs do hotel.
Configuração do OAuth 2.0
O OAuth 2.0 exige que você se identifique usando uma conta de serviço associada à sua Conta do Google. A conta de serviço envia a chave privada em troca de um token de acesso do OAuth 2.0. Você pode usar esse token em chamadas para APIs de hotéis para dados somente leitura, como dados de preços, de hotéis e de relatórios de diagnóstico sobre seu feed de preços para hotéis.
Os tokens de acesso são válidos por uma hora (3.600 segundos).
Se você já tiver implementado o ChromeVox, a abordagem do OAuth 2.0 vai ser semelhante, com as seguintes diferenças:
- O aplicativo usa uma conta de serviço do Google para acessar a API.
- Você transmite um token de acesso do OAuth 2.0 no cabeçalho HTTP
Authorizationao chamar APIs.
Para configurar sua conta para usar o OAuth 2.0 com o Travel Partner API, siga estas etapas:
Criar um novo projeto no Google Developers Console (DevConsole)
Permitir que sua conta de serviço acesse os dados do seu hotel
Cada uma dessas etapas é descrita nas seções a seguir.
Etapa 1: criar um novo projeto do DevConsole
O Google Developers Console ("DevConsole") é a experiência de desenvolvimento do Google para gerenciar e visualizar dados de tráfego, autenticação e informações de faturamento das APIs do Google que seus projetos usam.
No DevConsole, um projeto é um conjunto de configurações, credenciais e metadados sobre o aplicativo ou os aplicativos em que você está trabalhando, que usam as APIs Google Developer e os recursos do Google Cloud.
É no DevConsole que você gerencia esses aspectos do projeto, como gerar credenciais, ativar APIs e gerenciar as informações de equipe e faturamento associadas ao projeto.
Para criar um novo projeto no DevConsole:
Faça login na sua Conta do Google ou do Gmail.
Abra o Google Play Console. Se este for seu primeiro projeto, a visualização principal vai mostrar um botão simples CRIAR PROJETO:
Clique no botão CRIAR PROJETO. O DevConsole exibe a caixa de diálogo Novo projeto:
Insira um nome amigável para o novo projeto no campo de entrada Nome do projeto. Abaixo do campo, o DevConsole gera um ID de projeto para você, garantindo que ele seja exclusivo em todos os projetos. Por exemplo, se você inserir "Meu novo projeto", o DevConsole atribuirá um ID como
my-new-project-266022.Clique no botão Criar para criar seu novo projeto.
Use o menu de navegação para selecionar APIs e serviços > Painel.
A imagem abaixo mostra o menu de navegação no canto superior esquerdo do DevConsole. Isso faz com que a visualização Painel do projeto seja exibida:
Para mais informações, consulte Gerenciar projetos no Developers Console.
Quando você cria um novo projeto, ele ainda não tem APIs associadas a ele. Na próxima etapa, você vai ativar o Travel Partner API para o novo projeto.
Etapa 2: ativar o Travel Partner API para o novo projeto
Para usar as APIs do hotel, ative Travel Partner API no novo projeto do DevConsole.
Para ativar as APIs de hotéis no novo projeto:
Acesse a visualização Painel do seu projeto, conforme descrito acima.
Clique em Ativar APIs e serviços. A página de boas-vindas da biblioteca de APIs vai aparecer.
No campo de pesquisa, comece a digitar Travel Partner API. O Console de APIs do Google exibe uma lista de APIs que correspondem ao que você digita.
Clique em Travel Partner API na tabela de APIs correspondentes. O DevConsole exibe uma descrição sobre a API.
Clique no botão Ativar API para ativar esta API no seu projeto.
Para mais informações, consulte Ativar e desativar APIs.
As APIs de hotel agora estão ativadas para o novo projeto de sua Conta do Google.
A próxima etapa é criar uma conta de serviço e gerar chaves para ela.
Etapa 3: criar uma conta de serviço e gerar as credenciais dela
As contas de serviço são usadas por interações entre servidores, como aquelas entre um aplicativo da Web e os dados de hotéis.
Para criar e configurar uma conta de serviço, faça o seguinte:
Na visualização principal do Console de APIs do Google, clique em Credenciais na navegação à esquerda. O DevConsole mostra a visualização Credenciais.
A visualização Credenciais exibe os IDs do cliente e as credenciais para seu projeto. Seu aplicativo usará o ID do cliente ao solicitar um token de acesso do OAuth 2.0. Novos projetos ainda não terão clientes ou credenciais.
Clique no link Credenciais em APIs e serviços.
Clique no botão Criar credenciais e selecione Chave da conta de serviço na lista suspensa. A visualização Criar chave da conta de serviço é exibida.
No menu suspenso Conta de serviço, selecione Nova conta de serviço.
Insira um nome e um ID para a conta de serviço.
É possível usar o nome como quiser, mas o ID da conta precisa ser exclusivo em todos os projetos. O DevConsole gera um ID de conta exclusivo com base no nome inserido.
Selecione P12 como o tipo de chave, conforme mostrado abaixo. O P12 é obrigatório.
Clique no botão Criar. O DevConsole gera um par de chaves privada/pública para o projeto. A chave privada é salva no local padrão em que os downloads são armazenados pelo navegador. Faça o download do formato
.p12(binário), em vez do formato de arquivo.json.Você usa a chave privada nos seus scripts ou em outros aplicativos que acessam o Travel Partner API.
O DevConsole exibe o seguinte aviso quando termina de gerar as chaves:
Clique no botão OK, entendi. O DevConsole retorna à visualização Credenciais. Para confirmar os detalhes sobre sua conta de serviço e ver as contas de serviço associadas ao projeto, clique em Gerenciar contas de serviço nesta visualização.
A conta de serviço agora tem as seguintes credenciais associadas a ela:
- ID do cliente:um identificador exclusivo usado pelo aplicativo ao solicitar um token de acesso do OAuth 2.0.
- Endereço de e-mail: um endereço de e-mail gerado para a conta de serviço com o formato "account_name@project_name.google.com.iam.gserviceaccount.com".
- Impressões digitais do certificado:o ID da chave privada que você fez o download.
Para mais informações, consulte Usar o OAuth 2.0 para aplicativos de servidor para servidor.
Etapa 4: conceder à conta de serviço acesso aos seus dados da Central para Hotéis
A etapa final é conceder à nova conta de serviço acesso à sua Central para Hotéis. A conta de serviço é identificada pelo endereço de e-mail gerado que você criou na etapa anterior. Você fornece acesso a essa conta nas configurações de compartilhamento da Central para Hotéis.
Para conceder a uma conta de serviço acesso aos seus dados da Central para Hotéis:
Se você não tiver o acesso necessário para adicionar usuários à conta, entre em contato com a equipe de Hotéis no Google usando o formulário de contato e solicite a configuração da propriedade da sua conta. Você pode solicitar que um ou mais e-mails sejam enviados a um proprietário. Para mais informações sobre o acesso à Central para Hotéis, consulte Vincular a Central para Hotéis ao Google Ads.
Em uma nova janela do navegador, abra a Central para Hotéis.
No banner Central para Hotéis do Google, clique no ícone de adição de usuário para abrir a caixa de diálogo de compartilhamento.
No campo Adicionar mais pessoas, insira o endereço de e-mail da conta de serviço que você quer adicionar à Central para Hotéis.
Mantenha a opção Notificar pessoas selecionada.
No menu suspenso, selecione Gerenciar.
Clique no botão Convidar.
Depois de adicionar usuários à Central para Hotéis, sua conta de serviço será ativada para acesso à API em cerca de 24 horas.
Depois que o Google avisar que o acesso à API está ativado na sua conta de serviço, comece a acessar a API com o OAuth.
Como usar o OAuth 2.0
Para acessar a API, seu aplicativo precisa se identificar para o Google com o
endereço de e-mail gerado e a chave privada da conta de serviço. O mecanismo
de autenticação do Google troca essa chave por um token de acesso do OAuth 2.0 que
você transmite no cabeçalho Authorization nas chamadas de API do seu app.
Os tokens de acesso (também conhecidos como tokens do portador) fazem parte do padrão OAuth 2.0. A sintaxe para especificar um token de acesso em um cabeçalho HTTP é:
Authorization: Bearer *oauth2_access_token*
O exemplo a seguir mostra exemplos de cabeçalhos HTTP de uma solicitação que acessa a 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
Para gerar um token de acesso, crie um aplicativo em qualquer linguagem que você escolher.
O exemplo a seguir gera o token no Python. É possível usar esse
token nos cabeçalhos Authorization das suas solicitações ao acessar o 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>
Ao desenvolver seu aplicativo, siga as práticas recomendadas para usar as chaves de API com segurança.
A amostra de script Python gera um token do portador do cabeçalho Authorization, como mostra o exemplo a seguir:
$ python sample.py Authorization: Bearer ya29.42424242sample_420icu8122KSvoh4T42cRoG3rW1lc0Q $
Use o valor do token nas suas solicitações. Ele é válido por 1 hora depois de ser gerado.
Solução de problemas
Está com problemas? Uma verificação rápida dos itens a seguir pode resolver o problema.
- Você criou um projeto no Google Play Console?
- Você encontrou e ativou o Travel Partner API?
- Você fez o download de um arquivo
.p12, uma chave privada depois de clicar em Criar ID do cliente e selecionar Conta de serviço? - Você recebeu um endereço de e-mail do ID do cliente da conta de serviço de um formulário:
nnnnnnn@app_name.google.com.iam.gserviceaccount.com? - Você compartilhou sua conta da Central de anúncios de hotéis com a conta de serviço clicando no botão Compartilhar esta conta?
- Você enviou o endereço de e-mail da conta de serviço e seu ID de parceiro ao Gerente técnico de contas (TAM)?
- Suas chamadas Travel Partner API estão transmitindo um token recebido recentemente no
cabeçalho
Authorization? - O token do portador do cabeçalho
Authorizationtem mais de uma hora?
A tabela a seguir lista alguns erros comuns e possíveis soluções:
| Erro | Descrição |
|---|---|
| Invalid credentials | Isso pode significar várias coisas. Se você encontrar esse erro, verifique se:
|
| Not found | Provavelmente, seu endpoint está malformado. Verifique se você está enviando uma
solicitação GET e se o URL da solicitação é válido (está em conformidade
com a sintaxe da API que você está tentando acessar). |
| Invalid string value | Uma ou mais partes do endpoint têm sintaxe inválida. Por exemplo, você pode ter digitado parte do caminho incorretamente. Verifique se você usou os sublinhados, a capitalização e o texto corretos em todo o caminho. |
| Unsupported output format | Esse erro ocorre com mais frequência quando você usa a API Reports. Você precisa especificar "alt=csv" no URL da sua solicitação GET. A API Reports não é compatível com JSON. |
| AccessTokenRefreshError/Invalid grant | Ao executar o app Python de amostra, esse erro pode ser causado
pelo seguinte:
|
| HotelAdsAPIConnection object has no attribute credentials | Ao executar o aplicativo Python de amostra, o caminho para o arquivo .p12
está incorreto. |
| Invalid scope | Ao executar o aplicativo Python de amostra, o escopo da API precisa ser
https://www.googleapis.com/auth/travelpartner. |
| Forbidden | Você não tem autorização para acessar o ID da conta que está usando. Se você for proprietário de uma subconta, talvez não consiga acessar o ID da conta principal ou raiz. |