APIs de terceiros

Um recurso avançado dos scripts do Google Ads é a capacidade de integração com dados e serviços de APIs de terceiros.

Este guia aborda os seguintes conceitos que podem ajudar você a escrever scripts para se conectar a outros serviços:

  • Como fazer solicitações HTTP: como usar UrlFetchApp para acessar APIs externas.
  • Autenticação: abordamos alguns cenários comuns de autenticação.
  • Análise de respostas: como processar dados JSON e XML retornados.

Também incluímos exemplos para várias APIs conhecidas que ilustram esses conceitos.

Buscar dados com UrlFetchApp

UrlFetchApp fornece a funcionalidade principal necessária para interagir com APIs de terceiros.

O exemplo a seguir mostra como buscar dados meteorológicos do OpenWeatherMap. Escolhemos o OpenWeatherMap devido ao esquema de autorização e à API relativamente simples.

Fazer uma solicitação

A documentação do OpenWeatherMap especifica o formato para solicitar o clima atual da seguinte maneira:

http://api.openweathermap.org/data/2.5/weather?q=[location]&apikey=[apikey]

O URL fornece nosso primeiro exemplo de autorização: o parâmetro apikey é obrigatório, e o valor é exclusivo para cada usuário. Essa chave é obtida ao se inscrever.

Após a inscrição, uma solicitação usando a chave pode ser emitida da seguinte maneira:

const location = 'London,uk';
const apikey = 'da.......................81'; // Replace with your API key
const currentWeatherUrl = `http://api.openweathermap.org/data/2.5/weather?q=${location}&apiKey=${apiKey}`;
const response = UrlFetchApp.fetch(currentWeatherUrl);
console.log(response.getContentText());

A execução desse código resulta em uma longa string de texto JSON gravada na janela de registro nos scripts do Google Ads.

A próxima etapa é converter isso em um formato que possa ser usado no seu script.

Dados JSON

Muitas APIs fornecem respostas no formato JSON. Isso representa uma serialização de objetos JavaScript, de modo que objetos, matrizes e tipos básicos possam ser representados e transferidos como strings.

Para converter uma string JSON, como a retornada pelo OpenWeatherMap, de volta em um objeto JavaScript, use o método JSON.parse integrado. Continuando com o exemplo anterior:

const json = response.getContentText();
const weatherData = JSON.parse(json);
console.log(weatherData.name);
//  "London"

O método JSON.parse converte a string em um objeto, que tem uma propriedade name.

Consulte a seção Analisar respostas para mais detalhes sobre como trabalhar com respostas da API em diferentes formatos.

Tratamento de erros

O tratamento de erros é uma consideração importante ao trabalhar com APIs de terceiros nos seus scripts, porque elas costumam mudar com frequência e gerar valores de resposta inesperados, por exemplo:

  • O URL ou os parâmetros da API podem mudar sem seu conhecimento.
  • Sua chave de API (ou outra credencial de usuário) pode expirar.
  • O formato da resposta pode mudar sem aviso prévio.

Códigos de status HTTP

Devido à possibilidade de respostas inesperadas, inspecione o código de status HTTP. Por padrão, UrlFetchApp vai gerar uma exceção se um código de erro HTTP for encontrado. Para mudar esse comportamento, é necessário transmitir um parâmetro opcional, como no exemplo a seguir:

const options = {
  muteHttpExceptions: true
}
const response = UrlFetchApp.fetch(url, options);
// Any status code greater or equal to 400 is either a client or server error.
if (response.getResponseCode() >= 400) {
  // Error encountered, send an email alert to the developer
  sendFailureEmail();
}

Estrutura da resposta

Quando as APIs de terceiros mudam, talvez você não perceba imediatamente as alterações que podem afetar seus scripts. Por exemplo, se a propriedade name retornada no exemplo do OpenWeatherMap for alterada para locationName, os scripts que usam essa propriedade vão falhar.

Por isso, pode ser útil testar se a estrutura retornada é a esperada, por exemplo:

const weatherData = JSON.parse(json);
if (weatherData && weatherData.name) {
  console.log('Location is : ' + name);
} else {
  console.log('Data not in expected format');
}

Dados POST com UrlFetchApp

O exemplo introdutório com o OpenWeatherMap apenas buscou dados. Normalmente, as chamadas de API que não mudam o estado no servidor remoto usam o método HTTP GET.

O método GET é o padrão para UrlFetchApp. No entanto, algumas chamadas de API, como as chamadas para um serviço que envia mensagens SMS, exigem outros métodos, como POST ou PUT.

Para ilustrar o uso de chamadas POST com UrlFetchApp, o exemplo a seguir demonstra a integração com o Slack, um aplicativo de mensagens colaborativas, para enviar uma mensagem do Slack para usuários e grupos do Slack.

Configurar o Slack

Neste guia, pressupomos que você já criou uma conta do Slack.

Assim como no OpenWeatherMap no exemplo anterior, é necessário receber um token para permitir o envio de mensagens. O Slack fornece um URL exclusivo para você enviar mensagens à sua equipe, chamado de Webhook de entrada.

Configure um webhook de entrada clicando em Adicionar integração com o webhook de entrada e seguindo as instruções. O processo deve emitir um URL para ser usado em mensagens.

Fazer uma solicitação POST

Depois de configurar o webhook de entrada, para fazer uma solicitação POST, é necessário usar algumas propriedades extras no parâmetro options transmitido para UrlFetchApp.fetch:

  • method: como mencionado, o padrão é GET, mas aqui vamos substituí-lo e defini-lo como POST.
  • payload: são os dados a serem enviados ao servidor como parte da solicitação POST. Neste exemplo, o Slack espera um objeto serializado no formato JSON, conforme descrito na documentação do Slack. Para isso, o método [JSON.stringify][json-stringify-url] é usado, e o Content-Type é definido como application/json.

      // Change the URL for the one issued to you from 'Setting up Slack'.
      const SLACK_URL = 'https://hooks.slack.com/services/AAAA/BBBB/CCCCCCCCCC';
      const slackMessage = {
        text: 'Hello, slack!'
      };
    
      const options = {
        method: 'POST',
        contentType: 'application/json',
        payload: JSON.stringify(slackMessage)
      };
      UrlFetchApp.fetch(SLACK_URL, options);
    

Exemplo estendido do Slack

O exemplo anterior mostra o código mínimo necessário para ativar as mensagens recebidas no Slack. Um exemplo estendido ilustra a criação e o envio de um Relatório de performance de campanhas para um grupo, além de algumas opções de formatação e exibição.

Mensagem recebida

Consulte a formatação de mensagens na documentação do Slack para mais detalhes sobre as mensagens do Slack.

Dados do formulário

O exemplo anterior demonstrou o uso de uma string JSON como a propriedade payload para a solicitação POST.

Dependendo do formato de payload, UrlFetchApp usa abordagens diferentes para criar a solicitação POST:

  • Quando payload é uma string, o argumento de string é enviado como o corpo da solicitação.
  • Quando payload é um objeto, por exemplo, um mapa de valores:

    {to: 'mail@example.com', subject:'Test', body:'Hello, World!'}
    

    Os pares de chave-valor são convertidos em dados de formulário:

    subject=Test&to=mail@example.com&body=Hello,+World!
    

    Além disso, o cabeçalho Content-Type da solicitação está definido como application/x-www-form-urlencoded.

Algumas APIs exigem o uso de dados de formulário ao enviar solicitações POST. Por isso, é importante lembrar dessa conversão automática de objetos JavaScript em dados de formulário.

Autenticação básica HTTP

A autenticação básica HTTP é uma das formas mais simples de autenticação e é usada por muitas APIs.

A autenticação é feita anexando um nome de usuário e uma senha codificados aos cabeçalhos HTTP em cada solicitação.

Autenticação básica HTTP

Criar uma solicitação

As etapas a seguir são necessárias para produzir uma solicitação autenticada:

  1. Forme a senha longa juntando o nome de usuário e a senha com dois pontos, por exemplo, username:password.
  2. Codifique a senha longa em Base64. Por exemplo, username:password se torna dXNlcm5hbWU6cGFzc3dvcmQ=.
  3. Anexe um cabeçalho Authorization à solicitação, no formato Authorization: Basic <encoded passphrase>.

O snippet a seguir ilustra como fazer isso nos scripts do Google Ads:

const USERNAME = 'your_username';
const PASSWORD = 'your_password';
const API_URL = 'http://<place_api_url_here>';

const authHeader = 'Basic ' + Utilities.base64Encode(USERNAME + ':' + PASSWORD);
const options = {
  headers: {Authorization: authHeader}
}
// Include 'options' object in every request
const response = UrlFetchApp.fetch(API_URL, options);

Exemplos de autenticação básica

A seção de exemplos de código contém dois exemplos que ilustram o uso da autenticação básica HTTP:

Plivo

O Plivo é um serviço que facilita o envio e o recebimento de mensagens SMS com a API dele. Este exemplo ilustra o envio de mensagens.

  1. Registre-se na Plivo.
  2. Cole o exemplo de script em um novo script no Google Ads.
  3. Substitua os valores PLIVO_ACCOUNT_AUTHID e PLIVO_ACCOUNT_AUTHTOKEN pelos valores do painel de gerenciamento.
  4. Insira seu endereço de e-mail conforme especificado no script para notificação de erros.
  5. Para usar o Plivo, é preciso comprar números ou adicionar números à conta de teste. Adicione números de sandbox que podem ser usados com a conta de teste.
  6. Adicione o número que vai aparecer como remetente e o número do destinatário.
  7. Atualize PLIVO_SRC_PHONE_NUMBER no script para um dos números de sandbox que acabaram de ser registrados. Isso inclui o código internacional do país, por exemplo, 447777123456 para um número do Reino Unido.

Twilio

O Twilio é outro serviço que facilita o envio e o recebimento de mensagens SMS com a API dele. Este exemplo ilustra o envio de mensagens.

  1. Registre-se no Twillio.
  2. Cole o exemplo de script em um novo script no Google Ads.
  3. Substitua os valores TWILIO_ACCOUNT_SID e TWILIO_ACCOUNT_AUTHTOKEN pelos valores mostrados na página do console da conta.
  4. Substitua TWILIO_SRC_PHONE_NUMBER pelo número do painel, que é o número autorizado pela Twilio para enviar mensagens.

OAuth 1.0

Muitos serviços conhecidos usam o OAuth para autenticação. O OAuth tem vários tipos e versões.

Enquanto na autenticação básica HTTP um usuário tem apenas um nome de usuário e uma senha, o OAuth permite que aplicativos de terceiros tenham acesso à conta e aos dados de um usuário usando credenciais específicas para esse aplicativo de terceiros. Além disso, o nível de acesso também será específico para esse aplicativo.

Para mais informações sobre o OAuth 1.0, consulte o guia OAuth Core. Em especial, consulte o item 6. Como autenticar com o OAuth. No OAuth 1.0 de três etapas completo, o processo é o seguinte:

  1. O aplicativo ("Consumidor") recebe um token de solicitação.
  2. O usuário autoriza o token de solicitação.
  3. O aplicativo troca o token de solicitação por um token de acesso.
  4. Para todas as solicitações de recursos subsequentes, o token de acesso é usado em uma solicitação assinada.

Para que serviços de terceiros usem o OAuth 1.0 sem interação do usuário (por exemplo, como os scripts do Google Ads exigiriam), as etapas 1, 2 e 3 não são possíveis. Portanto, alguns serviços emitem um token de acesso no console de configuração, permitindo que o aplicativo vá diretamente para a etapa 4. Isso é conhecido como OAuth 1.0 de uma etapa.

OAuth1

OAuth 1.0 nos scripts do Google Ads

Para os scripts do Google Ads, cada script geralmente é interpretado como um aplicativo. No console ou na página de configurações de administração do serviço, geralmente é necessário:

  • Defina uma configuração de aplicativo para representar o script.
  • Especifique quais permissões estão sendo estendidas ao script.
  • Consiga o token do cliente, o secret do consumidor, o token de acesso e o secret de acesso para usar com o OAuth de uma etapa.

OAuth 2.0

O OAuth 2.0 é usado em APIs conhecidas para fornecer acesso aos dados do usuário. O proprietário de uma conta de um determinado serviço de terceiros concede permissão a aplicativos específicos para que eles acessem os dados do usuário. As vantagens são que o proprietário:

  • Não precisa compartilhar as credenciais da conta com o aplicativo.
  • É possível controlar quais aplicativos têm acesso aos dados individualmente e em que medida. Por exemplo, o acesso concedido pode ser somente leitura ou apenas a um subconjunto dos dados.

Para usar serviços ativados com o OAuth 2.0 nos scripts do Google Ads, siga estas etapas:

Fora do script

Autorize os scripts do Google Ads a acessar seus dados de usuário pela API de terceiros. Na maioria dos casos, isso envolve configurar um aplicativo no console do serviço de terceiros. Esse aplicativo representa seu script.

Você especifica quais direitos de acesso o aplicativo de scripts do Google Ads deve receber, e geralmente um ID do cliente é atribuído a ele. Isso permite que você, por meio do OAuth 2.0, controle quais aplicativos têm acesso aos seus dados no serviço de terceiros e também quais aspectos desses dados eles podem ver ou modificar.

No script

Autorize com o servidor remoto. Dependendo do tipo de permissão de acesso permitido pelo servidor, um conjunto diferente de etapas, conhecido como fluxo, precisará ser seguido, mas todas resultarão na emissão de um token de acesso que será usado para essa sessão em todas as solicitações subsequentes.

Fazer solicitações de API. Transmita o token de acesso com cada solicitação.

Fluxos de autorização

Cada tipo de permissão de acesso e fluxo correspondente atende a diferentes cenários de uso. Por exemplo, um fluxo diferente é usado quando um usuário está participando de uma sessão interativa, em contraste com um cenário em que um aplicativo precisa ser executado em segundo plano sem a presença de um usuário.

Os provedores de API decidem quais tipos de permissão de acesso aceitam, e isso orienta como o usuário procede com a integração da API.

Implementação

Para todos os diferentes fluxos de OAuth, o objetivo é conseguir um token de acesso que possa ser usado no restante da sessão para autenticar solicitações.

Uma biblioteca de amostra ilustra como autenticar para cada tipo de fluxo diferente. Cada um desses métodos retorna um objeto que recebe e armazena o token de acesso e facilita as solicitações autenticadas.

O padrão de uso geral é:

// Authenticate using chosen flow type
const urlFetchObj = OAuth2.<flow method>(args);
// Make request(s) using obtained object.
const response1 = urlFetchObj.fetch(url1);
const response2 = urlFetchObj.fetch(url2, options);

Permissão de acesso por credenciais do cliente

A [concessão de credenciais do cliente][client-credentials-rfc] é uma das formas mais simples do fluxo do OAuth2, em que o aplicativo troca um ID e um secret, exclusivos do aplicativo, em troca da emissão de um token de acesso com limite de tempo.

Credencial do cliente

// Access token is obtained and cached.
const authUrlFetch = OAuth2.withClientCredentials(
    tokenUrl, clientId, clientSecret, optionalScope));
// Use access token in each request
const response = authUrlFetch.fetch(url);
// ... use response

Concessão de token de atualização

A concessão do token de atualização é semelhante à concessão de credenciais do cliente, em que uma solicitação ao servidor retorna um token de acesso que pode ser usado na sessão.

Token de atualização

Gerar um token de atualização

A diferença com a concessão de token de atualização é que, enquanto os detalhes necessários para uma concessão de credenciais de cliente vêm da configuração do aplicativo (por exemplo, no painel de controle do serviço), o token de atualização é concedido como parte de um fluxo mais complexo, como uma [concessão de código de autorização][authorization-code-rfc], que exigirá interação do usuário:

Código de autorização

Como usar o OAuth Playground para receber um token de atualização

O OAuth2 playground fornece uma interface que permite ao usuário passar pela concessão do código de autorização para receber um token de atualização.

O botão de configurações no canto superior direito permite definir todos os parâmetros a serem usados no fluxo do OAuth, incluindo:

  • Endpoint de autorização: usado como o início do fluxo de autorização.
  • Endpoint do token: usado com o token de atualização para receber um token de acesso.
  • ID do cliente e chave secreta: credenciais do aplicativo.

    OAuth Playground

Uso do token de atualização

Depois que a autorização inicial é realizada, os serviços podem emitir um token de atualização, que pode ser usado de maneira semelhante ao fluxo de credenciais do cliente:

const authUrlFetch = OAuth2.withRefreshToken(tokenUrl, clientId, clientSecret,
    refreshToken, optionalScope);
const response = authUrlFetch.fetch(url);
// ... use response

Exemplo do Search Ads 360

O Search Ads 360 é um exemplo de API que pode ser usada com um token de atualização. Neste exemplo, um script gera e retorna um relatório. Consulte a referência da API Search Ads 360 para ver detalhes completos de outras ações que podem ser realizadas.

Criar o script
  1. Crie um projeto no console do Google Cloud e receba um ID do cliente, uma chave secreta do cliente e um token de atualização seguindo o procedimento no guia do Search Ads 360. Ative a API Search Ads 360.
  2. Cole o [script de exemplo][search-ads-360-example] em um novo script no Google Ads.
  3. Cole o [exemplo de biblioteca OAuth2][oauth20-library-example] abaixo da listagem de código.
  4. Altere o script para que ele contenha os valores corretos de ID do cliente, chave secreta do cliente e token de atualização.

Exemplo da API Apps Script Execution

Este exemplo ilustra a execução de uma função no Apps Script usando a API Apps Script Execution. Isso permite que você chame o Apps Script usando os scripts do Google Ads.

Criar um script do Apps Script

Crie um novo script. O exemplo a seguir lista 10 arquivos do Drive:

function listFiles() {
  const limit = 10;
  const files = [];
  const fileIterator = DriveApp.getFiles();
  while (fileIterator.hasNext() && limit) {
    files.push(fileIterator.next().getName());
    limit--;
  }
  return files;
}
Configurar o Apps Script para execução
  1. Salve o script.
  2. Clique em Recursos > Projeto do Cloud Platform.
  3. Clique no nome do projeto para acessar o console do Google Cloud.
  4. Acesse APIs e serviços.
  5. Ative as APIs adequadas, neste caso, a API Drive e a API Apps Script Execution.
  6. Crie credenciais do OAuth no item Credenciais do menu.
  7. De volta ao script, publique-o para execução em Publicar > Implantar como executável de API.
Criar o script do Google Ads
  1. Cole o script de exemplo em um novo script no Google Ads.
  2. Além disso, cole a [biblioteca de exemplo do OAuth2][oauth20-library-example] abaixo da listagem de código.
  3. Altere o script para que ele contenha os valores corretos de ID do cliente, chave secreta do cliente e token de atualização.

Contas de serviço

Uma alternativa aos tipos de permissão de acesso é o conceito de contas de serviço.

As contas de serviço são diferentes dos tipos de permissão de acesso porque não são usadas para acessar dados do usuário: após a autenticação, as solicitações são feitas pela conta de serviço em nome do aplicativo, não como o usuário que pode ser o proprietário do projeto. Por exemplo, se a conta de serviço usasse a API Drive para criar um arquivo, ele pertenceria à conta de serviço e, por padrão, não seria acessível ao proprietário do projeto.

Exemplo da API Natural Language do Google

A [API Natural Language][natural-language-api-docs] fornece [análise de sentimento][sentiment-analysis-api-docs] e [análise de entidade][entity-analysis-api-docs] para texto.

Este exemplo ilustra o cálculo do [sentimento][sentiment-api-docs] para o texto do anúncio, incluindo o título ou a descrição. Isso fornece uma medida de quão positiva é a mensagem e a magnitude dela: o que é melhor, Vendemos bolos ou Vendemos os melhores bolos de Londres? Compre hoje mesmo!?

Configurar o script
  1. Crie um novo projeto no Console do Google Cloud.
  2. Ative a [API Natural Language][natural-language-api].
  3. Ative o faturamento do projeto.
  4. [Criar uma conta de serviço][create-service-account]. Faça o download do arquivo JSON de credenciais.
  5. Cole o [exemplo de script][natural-language-example] em um novo script no Google Ads.
  6. Além disso, cole a [biblioteca de exemplo do OAuth2][oauth20-library-example] abaixo da listagem de código.
  7. Substitua os valores necessários:
    • serviceAccount: o endereço de e-mail da conta de serviço, por exemplo, xxxxx@yyyy.iam.gserviceaccount.com.
    • key: a chave do arquivo JSON baixado ao criar a conta de serviço. Começa em -----BEGIN PRIVATE KEY... e termina em ...END PRIVATE KEY-----\n.

Respostas da API

As APIs podem retornar dados em vários formatos. Os mais notáveis são XML e JSON.

JSON

O JSON geralmente é mais simples do que o XML para trabalhar como um formato de resposta. No entanto, ainda podem surgir alguns problemas.

Validação de resposta

Depois de receber uma resposta bem-sucedida da chamada para a API, a próxima etapa típica é usar JSON.parse para converter a string JSON em um objeto JavaScript. Nesse ponto, é recomendável lidar com o caso em que a análise falha:

const json = response.getContentText();
try {
  const data = JSON.parse(json);
  return data;
} catch(e) {
  // Parsing of JSON failed - handle error.
}

Além disso, se a API não estiver sob seu controle, considere que a estrutura da resposta pode mudar e as propriedades podem não existir mais:

// Less good approach
// Assumes JSON was in form {"queryResponse": ...} when parsed.
const answer = data.queryResponse;

// Better approach
if (data && data.queryResponse) {
  const answer = data.queryResponse;
} else {
  // Format of API response has changed - alert developer or handle accordingly
}

XML

O XmlService permite que seus scripts analisem e extraiam dados de corpos de resposta XML.

Validação

O XML ainda é um formato comum para criar APIs. Uma resposta de uma chamada de API pode ser analisada usando o método parse do XmlService:

const responseText = response.getContentText();
try {
  const document = XmlService.parse(responseText);
} catch(e) {
  // Error in XML representation - handle accordingly.
}

Embora o XmlService.parse detecte erros no XML e gere exceções adequadamente, ele não oferece a capacidade de validar o XML em relação a um esquema.

Elemento raiz

Após a análise do documento XML, o elemento raiz é obtido usando o método getRootElement():

const document = XmlService.parse(responseText);
const rootElement = document.getRootElement();

Namespaces

No exemplo a seguir, a API Sportradar é usada para receber resultados de futebol de partidas selecionadas. A resposta XML tem o seguinte formato:

<schedule_schedules xmlns="http://schemas.sportradar.com/sportsapi/soccer/v4">
  <schedule>
     ...
  </schedule>
</schedule_schedules>

Observe como o namespace é especificado no elemento raiz. Por isso, é necessário:

  • Extraia o atributo de namespace do documento.
  • Use esse namespace ao percorrer e acessar elementos filhos.

O exemplo a seguir mostra como acessar o elemento <schedule> e pesquisar os elementos filhos <sport_event> no snippet de documento anterior:

const document = XmlService.parse(xmlText);
const rootElement = document.getRootElement();
// The namespace is required for accessing child elements in the schema.
const namespace = rootElement.getNamespace();
const scheduleElement = rootElement.getChild('schedule', namespace);
const sportEvents = scheduleElement.getChildren('sport_event', namespace);

Obter valores

Considerando o exemplo da programação de futebol:

<sport_event_status status="..." ... />

Os atributos podem ser recuperados, por exemplo:

const statusElement = sportEventElement.getChild('sport_event_status', namespace);
const status = statusElement.getAttribute('status').getValue();

O texto contido em um elemento pode ser lido usando getText(), mas eles serão concatenados quando houver vários filhos de texto de um elemento. Considere usar getChildren() e iterar em cada filho nos casos em que vários filhos de texto são prováveis.

Exemplo da Sportradar

Este exemplo completo da Sportradar ilustra a recuperação de detalhes de partidas de futebol, especificamente da Premier League inglesa. A API Soccer é um dos muitos feeds de esportes oferecidos pela Sportradar.

Configurar uma conta da Sportradar
  1. Acesse o site para desenvolvedores da Sportradar.
  2. Crie uma conta de teste.
  3. Depois de se registrar, faça login na sua conta.
  4. Depois de fazer login, acesse Minha conta.

A Sportradar separa os esportes em APIs diferentes. Por exemplo, você pode comprar acesso à API Soccer, mas não à API Tennis. Cada aplicativo criado pode ter diferentes esportes associados a ele e chaves diferentes.

  1. Em "Applications", clique em Create a new Application. Dê um nome e uma descrição ao aplicativo e ignore o campo do site.
  2. Selecione apenas Emitir uma nova chave para o Soccer Trial Europe v2.
  3. Clique em Registrar aplicativo.

Se tudo der certo, uma página com sua nova chave de API vai aparecer.

  1. Cole o exemplo de script em um novo script no Google Ads.
  2. Substitua a chave de API na listagem pela nova chave emitida e edite o campo de endereço de e-mail.

Solução de problemas

Ao trabalhar com APIs de terceiros, podem ocorrer erros por vários motivos, por exemplo:

  • Clientes que emitem solicitações ao servidor em um formato não esperado pela API.
  • Clientes que esperam um formato de resposta diferente do encontrado.
  • Clientes que usam tokens ou chaves inválidos ou valores deixados como marcadores de posição.
  • Clientes que atingiram os limites de uso.
  • Clientes que fornecem parâmetros inválidos.

Em todos esses casos, e em outros, uma boa primeira etapa para identificar a causa do problema é examinar os detalhes da resposta que está causando o erro.

Analisar respostas

Por padrão, qualquer resposta que retorne um erro (um código de status de 400 ou mais) será gerada pelo mecanismo de scripts do Google Ads.

Para evitar esse comportamento e permitir que o erro e a mensagem de erro sejam inspecionados, defina a propriedade muteHttpExceptions dos parâmetros opcionais como UrlFetchApp.fetch. Exemplo:

const params = {
  muteHttpExceptions: true
};
const response = UrlFetchApp.fetch(url, params);
if (response.getResponseCode() >= 400) {
  // ... inspect error details...
}

Códigos de status comuns

  • 200 OK indica sucesso. Se a resposta não contiver os dados esperados, considere que:

    • Algumas APIs permitem especificar quais campos, formato de resposta ou ambos usar. Consulte a documentação da API para mais detalhes.
    • Uma API pode ter vários recursos que podem ser chamados. Consulte a documentação para determinar se outro recurso é mais adequado e se ele vai retornar os dados necessários.
    • A API pode ter mudado desde que o código foi escrito. Consulte a documentação ou o desenvolvedor para esclarecimentos.
  • 400 Bad Request normalmente significa que algo está incorreto na formatação ou na estrutura da solicitação enviada ao servidor. Inspecione a solicitação e compare-a com as especificações da API para garantir que ela esteja de acordo com as expectativas. Consulte Inspecionar solicitações para saber como examinar as solicitações.

  • 401 Unauthorized geralmente significa que a API está sendo chamada sem fornecer ou realizar a autorização.

    • Se a API usar autorização básica, verifique se o cabeçalho Authorization está sendo construído e fornecido na solicitação.
    • Se a API usar o OAuth 2.0, verifique se o token de acesso foi recebido e está sendo fornecido como um token do portador.
    • Para qualquer outra variação na autorização, verifique se as credenciais necessárias para a solicitação estão sendo fornecidas.
  • 403 Forbidden indica que o usuário não tem permissão para o recurso que está sendo solicitado.

    • Verifique se o usuário recebeu as permissões necessárias, por exemplo, concedendo acesso a um arquivo em uma solicitação baseada em arquivo.
  • 404 Not Found significa que o recurso solicitado não existe.

    • Verifique se o URL usado para o endpoint de API está correto.
    • Se estiver buscando um recurso, verifique se o recurso referenciado existe (por exemplo, se o arquivo existe para uma API baseada em arquivos).

Inspecionar solicitações

Inspecionar solicitações é útil quando as respostas da API indicam que a solicitação está mal formada, por exemplo, um código de status 400. Para ajudar a examinar as solicitações, o UrlFetchApp tem um método complementar ao fetch(), chamado getRequest(url, params).

Em vez de enviar uma solicitação ao servidor, esse método cria a solicitação que teria sido enviada e a retorna. Isso permite que o usuário inspecione elementos da solicitação para garantir que ela esteja correta.

Por exemplo, se os dados do formulário na solicitação consistirem em muitas strings concatenadas, o erro pode estar na função que você criou para gerar esses dados do formulário. Em termos simples:

const request = UrlFetchApp.getRequest(url, params);
console.log(request);
// Now make the fetch:
const response = UrlFetchApp.fetch(url, params);
// ...

permite inspecionar os elementos da solicitação.

Registrar solicitações e respostas

Para ajudar no processo de inspeção de solicitações e respostas para uma API de terceiros, a função auxiliar a seguir pode ser usada como um substituto para UrlFetchApp.fetch(), para registrar solicitações e respostas.

  1. Substitua todas as instâncias de UrlFetchApp.fetch() no código por logUrlFetch().

  2. Adicione a seguinte função ao final do script.

    function logUrlFetch(url, opt_params) {
     const params = opt_params || {};
     params.muteHttpExceptions = true;
     const request = UrlFetchApp.getRequest(url, params);
     console.log('Request:       >>> ' + JSON.stringify(request));
     const response = UrlFetchApp.fetch(url, params);
     console.log('Response Code: <<< ' + response.getResponseCode());
     console.log('Response text: <<< ' + response.getContentText());
     if (response.getResponseCode() >= 400) {
       throw Error('Error in response: ' + response);
     }
     return response;
    }
    

Ao executar o script, os detalhes de todas as solicitações e respostas são registrados no console, facilitando a depuração.

[json-stringify-url]: //developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify [client-credentials-rfc]: //datatracker.ietf.org/doc/html/rfc6749#section-4.4 [authorization-code-rfc]: //datatracker.ietf.org/doc/html/rfc6749#section-1.3.1 [oauth20-library-example]: /google-ads/scripts/docs/examples/oauth20-library [search-ads-360-example]: /google-ads/scripts/docs/examples/search-ads-360 [natural-language-api]: //console.developers.google.com/apis/api/language.googleapis.com/overview [create-service-account]: //console.developers.google.com/apis/credentials/serviceaccountkey [natural-language-example]: /google-ads/scripts/docs/examples/natural-language [natural-language-api-docs]: //cloud.google.com/natural-language/docs/ [sentiment-api-docs]: //cloud.google.com/natural-language/docs/reference/rest/v1beta2/Sentiment [sentiment-analysis-api-docs]: //cloud.google.com/natural-language/docs/analyzing-sentiment [entity-analysis-api-docs]: //cloud.google.com/natural-language/docs/analyzing-entities