APIs de terceiros

Um recurso poderoso 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 de autenticação comuns.
  • Análise de respostas: como processar dados JSON e XML retornados.

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

Buscar dados com UrlFetchApp

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

O exemplo a seguir mostra a busca de 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 a previsão do tempo 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 script.

Dados JSON

Muitas APIs fornecem respostas no formato JSON. Isso representa uma serialização simples 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, em um objeto JavaScript, use o método JSON.parse integrado. Continuando o exemplo acima:

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 processamento de erros é uma consideração importante ao trabalhar com APIs de terceiros nos scripts, porque elas mudam com frequência e geram valores de resposta inesperados, por exemplo:

  • O URL ou os parâmetros da API podem mudar sem que você saiba.
  • 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 ao potencial de respostas inesperadas, inspecione o código de status HTTP. Por padrão, UrlFetchApp gera 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 abaixo:

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, os desenvolvedores nem sempre sabem imediatamente sobre as mudanças que podem afetar os 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 está como esperado, por exemplo:

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

Enviar dados POST com o UrlFetchApp

O exemplo introdutório com o OpenWeatherMap só buscou dados. Normalmente, as chamadas de API que não mudam de 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 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 colaborativo, para enviar uma mensagem aos usuários e grupos do Slack.

Configurar o Slack

Este guia pressupõe que você já se inscreveu para uma conta do Slack.

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

Configure um webhook de entrada clicando em Adicionar integração de WebHooks de entrada e seguindo as instruções. O processo precisa emitir um URL para usar nas mensagens.

Fazer uma solicitação POST

Depois de configurar o webhook de entrada, fazer uma solicitação POST requer apenas o uso de algumas propriedades extras no parâmetro options transmitido para UrlFetchApp.fetch:

  • method: como mencionado, o padrão é GET, mas aqui ele é substituído e definido como POST.

  • payload: são os dados que serão 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 (em inglês). Para isso, o método JSON.stringify é 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 de Slack estendido

O exemplo acima mostra o mínimo para ativar as mensagens recebidas no Slack. Um exemplo detalhado ilustra a criação e o envio de um relatório de performance da campanha para um grupo, além de algumas opções de formatação e exibição.

Mensagem recebida

Consulte Formatação de mensagens na documentação do Slack para mais detalhes.

Dados do formulário

O exemplo acima 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 é definido como application/x-www-form-urlencoded.

Algumas APIs exigem o uso de dados de formulário ao enviar solicitações POST. Portanto, é útil 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. Para formar a frase de acesso, una o nome de usuário e a senha com um dois-pontos, por exemplo, username:password.
  2. Codifique a frase de acesso em Base64. Por exemplo, username:password se torna dXNlcm5hbWU6cGFzc3dvcmQ=.
  3. Anexe um cabeçalho Authorization à solicitação no formulário 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 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 a recepção de mensagens SMS pela API. Este exemplo ilustra o envio de mensagens.

  1. Cadastre-se na Plivo.
  2. Cole o script de exemplo em um novo script no Google Ads.
  3. Substitua os valores de PLIVO_ACCOUNT_AUTHID e PLIVO_ACCOUNT_AUTHTOKEN pelos valores do painel de controle de gerenciamento.
  4. Insira seu endereço de e-mail conforme especificado no script para receber notificações de erros.
  5. Para usar o Plivo, é necessário comprar 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 recém registrados. Isso deve incluir 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 pela API. Este exemplo ilustra o envio de mensagens.

  1. Cadastre-se no Twillio.
  2. Cole o script de exemplo 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 pelo Twilio para enviar mensagens.

OAuth 1.0

Muitos serviços populares usam o OAuth para autenticação. O OAuth tem várias versões e variaçõ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. Além disso, o acesso também será específico para esse aplicativo.

Para saber mais sobre o OAuth 1.0, consulte o guia do OAuth Core. Consulte, especificamente, 6. Autenticação com o OAuth. No OAuth 1.0 de três pernas 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 recurso 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 exigem), as etapas 1, 2 e 3 não são possíveis. Portanto, alguns serviços emitem um token de acesso do console de configuração, permitindo que o aplicativo vá diretamente para a etapa 4. Isso é conhecido como OAuth 1.0 de uma perna.

OAuth1

OAuth 1.0 em scripts do Google Ads

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

  • Configure uma configuração do aplicativo para representar o script.
  • Especifique quais permissões estão sendo estendidas ao script.
  • Receba a chave do consumidor, o secret do consumidor, o token de acesso e o secret de acesso para uso com OAuth de uma perna.

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.
  • Pode controlar quais aplicativos têm acesso aos dados individualmente e em que grau. Por exemplo, o acesso concedido pode ser somente leitura ou apenas a um subconjunto dos dados.

Para usar serviços habilitados para OAuth 2.0 em scripts do Google Ads, siga estas etapas:

Fora do seu script

Conceda autorização para que os scripts do Google Ads acessem os dados do 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 do Google Ads.

Você especifica quais direitos de acesso o aplicativo do script do Google Ads precisa ter. Geralmente, um ID de cliente é atribuído a ele. Isso permite que você controle, usando o OAuth 2, quais aplicativos têm acesso aos seus dados no serviço de terceiros e quais aspectos desses dados eles podem ver ou modificar.

No seu script

Autorizar com o servidor remoto. Dependendo do tipo de concessão que o servidor permitiu, um conjunto diferente de etapas, conhecido como fluxo, precisa ser seguido, mas todos 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 concessão e fluxo correspondente atende a diferentes cenários de uso. Por exemplo, um fluxo diferente é usado quando um usuário participa 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 vão decidir quais tipos de concessão aceitarão, e isso vai orientar como o usuário vai proceder com a integração da API.

Implementação

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

Uma biblioteca de exemplos ilustra como fazer a autenticação para cada tipo de fluxo. Cada um desses métodos retorna um objeto que obtém e armazena o token de acesso e facilita 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);

Concessão de credenciais do cliente

A concessão de credenciais do cliente é uma das formas mais simples de fluxo OAuth2, em que o aplicativo troca um ID e uma chave secreta exclusivos em troca da emissão de um token de acesso com tempo limitado.

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 de token de atualização é semelhante à concessão de credenciais do cliente, já que uma solicitação simples para o servidor retorna um token de acesso que pode ser usado na sessão.

Token de atualização

Conseguir 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 do 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, que exige a interação do usuário:

Código de autorização

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

O OAuth2 playground (link em inglês) oferece uma interface que permite ao usuário percorrer a concessão de 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 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 e chave secreta do cliente: credenciais do aplicativo.

Playground do OAuth

Usar um script para conseguir um token de atualização

Uma alternativa baseada em script para concluir o fluxo está disponível no exemplo de geração de token de atualização.

Uso do token de atualização

Depois que a autorização inicial for realizada, os serviços poderão emitir um token de atualização, que poderá ser usado de maneira semelhante ao fluxo de credenciais do cliente. Confira dois exemplos abaixo:

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 conferir todos os detalhes sobre outras ações que podem ser realizadas.

Criar o script
  1. Crie um novo projeto no Console de APIs e receba um ID de cliente, um segredo de cliente e um token de atualização seguindo o procedimento no guia do DoubleClick, garantindo que você ativa a API Search do DoubleClick.
  2. Cole o script de exemplo em um novo script no Google Ads.
  3. Cole a biblioteca de exemplo do OAuth2 abaixo da lista de códigos.
  4. Modifique o script para que ele contenha os valores corretos de ID, chave secreta e token de atualização do cliente.

Exemplo da API Apps Script Execution

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

Criar um script do Apps Script

Crie um 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 Resources > Cloud Platform project.
  3. Clique no nome do projeto para acessar o Console de APIs.
  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. No script, publique para execução em Publish > Deploy as API Executable.
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 OAuth2 de exemplo abaixo da lista de códigos.
  3. Modifique o script para que ele contenha os valores corretos de ID, chave secreta e token de atualização do cliente.

Contas de serviço

Uma alternativa aos tipos de concessão acima é o conceito de contas de serviço.

As contas de serviço diferem das anteriores 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 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 fornece análise de sentimento e análise de entidades para texto.

Este exemplo ilustra o cálculo do sentimento do 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: qual é melhor, Venda de bolos ou Venda dos melhores bolos em Londres. Compre hoje!?

Configurar o script
  1. Crie um novo projeto no Console de APIs.
  2. Ative a API Natural Language.
  3. Ative o faturamento no projeto.
  4. Crie uma conta de serviço. Faça o download do arquivo JSON de credenciais.
  5. Cole o script de exemplo em um novo script no Google Ads.
  6. Além disso, cole a biblioteca OAuth2 de exemplo abaixo da lista de códigos.
  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 transferido por download ao criar a conta de serviço. Começa -----BEGIN PRIVATE KEY... e termina ...END PRIVATE KEY-----\n.

Respostas da API

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

JSON

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

Validação da resposta

Depois de receber uma resposta da chamada para a API, a próxima etapa normal é usar JSON.parse para converter a string JSON em um objeto JavaScript. Nesse ponto, é sensato processar 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 que 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

Validação

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

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

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

Elemento raiz

Considerando a análise bem-sucedida do documento XML, o elemento raiz é obtido usando o método getRootElement():

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

Namespaces

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

<schedule xmlns="http://feed.elasticstats.com/schema/soccer/sr/v2/matches-schedule.xsd">
  <matches>
     ...
  </matches>
</schedule>

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 <matches> no snippet de documento acima:

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

Obter valores

Considerando o exemplo da programação de futebol:

<match status="..." category="..." ... >
  ...
</match>

Os atributos podem ser recuperados, por exemplo:

const status = matchElement.getAttribute('status').getValue();

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

Exemplo da Sportradar

Este exemplo completo do Sportradar mostra como recuperar detalhes de partidas de futebol, especificamente da Premier League. A API Soccer é uma das várias opções de feeds esportivos oferecidos pela Sportradar.

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

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

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

Se for bem-sucedido, isso vai resultar em uma página com sua nova chave de API.

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

Solução de problemas

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

  • Clientes que enviam solicitações para o 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 atingem 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 o seguinte:

    • Algumas APIs permitem especificar quais campos e/ou formato de resposta 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 um recurso diferente pode ser mais adequado para uso e 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 mais esclarecimentos.

  • 400 Bad Request normalmente significa que algo não está correto na formatação ou 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 em conformidade com as expectativas. Consulte Como 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 com sucesso.

    • Se a API usa autorização básica, verifique se o cabeçalho Authorization está sendo criado 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 de portador.
    • Para qualquer outra variação de 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 arquivos.

  • 404 Not Found significa que o recurso solicitado não existe.

    • Verifique se o URL usado para o endpoint da API está correto.
    • Se estiver extraindo 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().

Em vez de enviar uma solicitação ao servidor, esse método constrói 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 sua solicitação consistirem em muitas strings concatenadas, o erro pode estar na função criada para gerar esses dados. De forma mais 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 em todo o processo de inspeção de solicitações e respostas a uma API de terceiros, a função auxiliar a seguir pode ser usada como uma substituição de 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 função a seguir 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.