APIs de terceiros

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

Neste guia, abordamos os seguintes conceitos que podem ajudar você a escrever scripts para conectar-se 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.

Observação: ao usar uma API de terceiros por escrito ou com um script que usa uma API de terceiros, recomendamos que você leia os Termos e Condições associados à API para garantir que o uso pretendido obedeça a eles.

Buscar dados com UrlFetchApp

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

Observação: o UrlFetchApp é fundamental para interagir com APIs de terceiros. No entanto, há cotas no uso que você precisa conhecer ao desenvolver suas soluções.

O exemplo a seguir mostra a busca de dados meteorológicos do OpenWeatherMap. Escolhemos o OpenWeatherMap devido ao seu esquema de autorização e à sua 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. Para conseguir essa chave, faça sua inscrição.

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

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 escrito na janela de geração de registros nos scripts do Google Ads.

A próxima etapa é fazer a conversão para 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 podem ser representados e transferidos como strings.

Para converter uma string JSON (como a retornada de OpenWeatherMap) de volta em um objeto JavaScript, use o método JSON.parse integrado. Continuando com 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 de 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 essas APIs geralmente 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 à 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, os desenvolvedores geralmente não ficam sabendo imediatamente das mudanças que podem afetar os scripts deles. Por exemplo, se a propriedade name retornada no exemplo do OpenWeatherMap mudar para locationName, os scripts que usam essa propriedade vão falhar.

Por esse motivo, pode ser vantajoso testar se a estrutura retornada está conforme o 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');
}

Dados POST com UrlFetchApp

O exemplo introdutório com o OpenWeatherMap somente busca 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 as para um serviço que envia mensagens SMS, exigirão 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 a usuários e grupos do Slack.

Configurar o Slack

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

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

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

Fazer uma solicitação POST

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

• method: conforme mencionado, o padrão é GET, mas aqui o substituimos e o definimos 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 para o formato JSON, conforme descrito na documentação do Slack. 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 do Slack estendido

O exemplo acima mostra o mínimo 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.

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

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 dessa string é enviado como o corpo da solicitação.

• Quando payload é um objeto, por exemplo, um mapa de valores:

  {to: '[e-mail]', subject:'Test', body:'Hello, World!'}
  

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

  subject=Test&to=[e-mail]&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 ter em mente a conversão automática de objetos JavaScript para 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 é realizada anexando um nome de usuário e uma senha codificados aos cabeçalhos HTTP em cada solicitação.

Criar uma solicitação

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

1. Crie 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 mostra 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);

Plivo

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

1. Registre-se no Plivo.
2. Cole o script de exemplo 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, você precisa comprar números ou adicionar números à conta de avaliação. Adicione números de sandbox que possam ser usados com a conta de teste.
6. Adicione o número que 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 acabados de serem registrados. Inclua 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 via API. Este exemplo ilustra o envio de mensagens.

1. Inscreva-se no Twillio (em inglês).
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. Esse é o número autorizado pelo Twilio a enviar mensagens.

OAuth 1.0

Muitos serviços conhecidos usam o OAuth para autenticação. O OAuth apresenta diversas variações e versões.

Enquanto a autenticação básica HTTP, um usuário tem apenas um nome de usuário e senha, o OAuth permite que aplicativos de terceiros recebam acesso à conta e aos dados de um usuário, usando credenciais específicas desse aplicativo. Além disso, a extensão do acesso também será específica para esse aplicativo.

Para mais informações sobre o OAuth 1.0, consulte o Guia do OAuth Core. Especificamente, consulte 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 recurso subsequentes, o token de acesso será usado em uma solicitação assinada.

Para que os serviços de terceiros usem o OAuth 1.0 sem interação do usuário (por exemplo, como os scripts do Google Ads exigiriam), não é possível realizar as etapas 1, 2 e 3. 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 etapa.

OAuth 1.0 em scripts do Google Ads

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

• Definir uma configuração do aplicativo para representar o script.
• Especifique quais permissões estão sendo estendidas para o script.
• Conseguir a chave do cliente, o segredo do cliente, o token de acesso e o segredo de acesso para usar com o OAuth de uma perna.

OAuth 2.0

O OAuth 2.0 é usado em APIs conhecidas para fornecer acesso a dados do usuário. O proprietário da conta de um determinado serviço de terceiros concede permissão a aplicativos específicos para acessar 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 medida. Por exemplo, o acesso concedido pode ser somente leitura ou apenas a um subconjunto dos dados.

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

Fora do script

Conceda autorização para que os scripts do Google Ads acessem seus dados de usuário por meio da API de terceiros. Na maioria dos casos, isso envolve a configuração de um aplicativo no console do serviço de terceiros. Este aplicativo representa seu script do Google Ads.

Você especifica quais direitos de acesso o aplicativo do Script do Google Ads deve ser fornecido e geralmente recebe um ID de cliente. Isso permite que você, por meio do OAuth 2, controle 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 roteiro

Autorizar com o servidor remoto. Dependendo do tipo de concessão que o servidor permitiu, será necessário seguir um conjunto diferente de etapas, conhecidas como fluxos, mas todas resultam na emissão de um token de acesso que será usado para essa sessão em todas as solicitações subsequentes.

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

Fluxos de autorização

Cada tipo de concessão e o fluxo correspondente atendem 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 decidirão sobre quais tipos de concessão aceitam, e isso guiará como o usuário prossegue com a integração da API.

Implementação

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

Uma biblioteca de amostras mostra como autenticar cada tipo de fluxo diferente. Cada um desses métodos retorna um objeto que recebe e armazena o token de acesso, além de facilitar 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);

Observação :como os scripts do Google Ads são de curta duração, nenhuma tentativa de atualizar os tokens de acesso obtidos é feita nessa biblioteca de amostra.

Concessão de credenciais de cliente

A concessão de credenciais de cliente é 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 por tempo limitado.

// 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

Atualizar concessão de token

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

Receber um token de atualização

A diferença com a concessão do token de atualização é que, enquanto os detalhes necessários para a 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, que exige a interação do usuário:

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 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 do OAuth, incluindo:

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

Uso de um script para receber 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.

Atualizar uso do token

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. Veja 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. Nesta amostra, um script gera e retorna um relatório. Consulte a referência da API Search Ads 360 para saber 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 do cliente, uma chave secreta do cliente e um token de atualização seguindo o procedimento no guia da DoubleClick e não deixe de ativar a API DoubleClick Search.
2. Cole o script de amostra em um novo script no Google Ads.
3. Cole a biblioteca OAuth2 de exemplo abaixo da lista de códigos.
4. Altere o script para conter 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 o Apps Script seja chamado a partir dos scripts do Google Ads.

Crie um script do Apps Script

Crie um novo script. O exemplo a seguir listará 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 navegar até o Console de APIs.
4. Navegue até APIs e serviços.
5. Ative as APIs apropriadas. Neste caso, a API Drive e a API Apps Script Execution.
6. Crie credenciais OAuth no item Credenciais do menu.
7. De volta ao script, publique-o para execução em Publish > Deploy as API Executable.

Criar o script do Google Ads

1. Cole o script de amostra em um novo script no Google Ads.
2. Além disso, cole a biblioteca OAuth2 de exemplo abaixo da lista de códigos.
3. Altere o script para conter 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 concessão acima é o conceito de contas de serviço.

As contas de serviço diferem do acima 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, e 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, isso pertenceria à conta de serviço e, por padrão, não poderia ser acessado pelo proprietário do projeto.

Exemplo da API Natural Language do Google

A API Natural Language fornece análise de sentimento e análise de entidade 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 do quanto a mensagem é positiva e a magnitude da mensagem: o que é melhor, Vendemos bolos ou Vendemos os melhores bolos em Londres. Compre hoje mesmo!?

Configurar o script

1. Crie um novo projeto no Console de APIs
2. Ative a API Natural Language.
3. Ative o faturamento do projeto.
4. Crie uma conta de serviço. Faça o download do arquivo JSON de credenciais.
5. Cole o script de amostra 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, [e-mail].
   • key: a chave do arquivo JSON salvo 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

Geralmente, o JSON é mais simples que o XML para trabalhar como formato de resposta. No entanto, ainda há alguns problemas que podem surgir.

Validação da resposta

Após receber uma resposta bem-sucedida da chamada à API, a próxima etapa típica é usar JSON.parse para converter a string JSON em um objeto JavaScript. Nesse momento, é sensato 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

Validação

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

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 de acordo, ela não permite validar o XML em relação a um esquema.

Elemento raiz

Dada 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 a seguir, a API Sportradar é usada para receber resultados de futebol para as partidas selecionadas. A resposta XML tem este 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:

• Extraia o atributo de namespace do documento.
• Use este 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);

Extrair valores

Dada a amostra da tabela de futebol:

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

É possível recuperar atributos, por exemplo:

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

O texto de um elemento pode ser lido usando getText(), mas ele será concenado onde houver vários filhos de texto de um elemento. Considere usar getChildren() e iterar em cada filho nos casos em que houver vários filhos de texto.

Exemplo do Sportradar

Este exemplo completo do Sportradar ilustra a recuperação de detalhes de partidas de futebol, especificamente as partidas da Premier League inglesa. A API Futebol é um dos vários feeds de esportes oferecidos pelo Sportradar.

Configurar uma conta do Sportradar

1. Acesse o site para desenvolvedores do Sportradar.
2. Crie uma conta de teste.
3. Após o registro, faça login na sua conta.
4. Após fazer login, acesse MyAccount.

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

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

Após a conclusão, uma página com a nova chave de API será aberta.

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

Solução de problemas

Ao trabalhar com APIs de terceiros, os erros podem ocorrer 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.
• Clientes que atingem os limites de uso.
• Clientes que fornecem parâmetros inválidos.

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

Analisar respostas

Por padrão, qualquer resposta que retornar 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 serão usados. 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 apropriado 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 esclarecimentos.

• 400 Bad Request normalmente significa que algo não está correto na formatação ou na estrutura da solicitação enviada ao servidor. Inspecione a solicitação e a compare com as especificações da API para garantir que esteja em conformidade com as expectativas. Consulte Como inspecionar solicitações para ver detalhes sobre como examinar as solicitações.

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

  • Se a API usar 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 do portador.
  • Para quaisquer outras variações 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, o 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 da API está correto.
  • Se estiver buscando um recurso, verifique se ele existe (por exemplo, se o arquivo existe para uma API baseada em arquivos).

Inspecionar solicitações

A inspeção de solicitações é útil quando as respostas da API indicam que a solicitação foi mal formada, por exemplo, um código de status 400. Para ajudar a examinar solicitações, UrlFetchApp tem um método complementar para o método 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 de formulário na sua solicitação consistem em muitas strings concatenadas, o erro pode estar na função criada para gerar esses dados do formulário. De forma mais simples:

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

permite que você inspecione 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 simples para UrlFetchApp.fetch() a fim de registrar solicitações e respostas.

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

2. Adicione a seguinte função ao final do seu 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.