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.

Este guia aborda os seguintes conceitos que podem ajudar você a escrever scripts para 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 samples para um número; de APIs populares que ilustram esses conceitos.

Observação :por escrito ou por um script que usa uma API de terceiros, é recomendado analisar os Termos e Condições associados à API para garante que o uso pretendido esteja em conformidade com elas.

Buscar dados com UrlFetchApp

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

Observação: UrlFetchApp é fundamental para interagir com APIs de terceiros, mas há cotas relacionadas, que você precisa considerar ao desenvolver suas soluções.

O exemplo a seguir mostra a busca de dados meteorológicos em OpenWeatherMap. Escolhemos o OpenWeatherMap devido ao seu esquema de autorização e API relativamente simples.

Fazer uma solicitação

A documentação do OpenWeatherMap especifica formato para solicitar a previsão atual da seguinte forma:

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 é único para cada usuário. Essa chave é obtida por meio de 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 string longa de JSON na janela de geração de registros nos scripts do Google Ads.

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

Dados JSON

Muitas APIs fornecem respostas no formato JSON. Isso representa um processo simples serialização de objetos JavaScript, como objetos, matrizes e tipos básicos podem ser representados e transferidos como strings.

Para converter uma string JSON, como a retornada do OpenWeatherMap: de volta ao objeto JavaScript, use o JSON.parse. 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 trabalhar com respostas de APIs em diferentes formatos.

Tratamento de erros

O tratamento de erros é uma consideração importante ao trabalhar com APIs de terceiros nos scripts, porque as APIs de terceiros mudam com frequência e geram 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 HTTP com o código de status atual. Por padrão, UrlFetchApp vai gerar uma exceção se um código de erro HTTP for encontrado. Para alterar esse comportamento, é necessário passar 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 muitas vezes não estão cientes imediatamente mudanças que podem afetar os scripts. Por exemplo, se a propriedade name retornado no exemplo do OpenWeatherMap é alterado para locationName, os scripts o uso dessa propriedade vai falhar.

Por esse motivo, pode ser útil testar se a estrutura retornada é 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');
}

Dados POST com UrlFetchApp

O exemplo de introdução com OpenWeatherMap apenas dados buscados. Normalmente, as chamadas de API que não mudam de estado no servidor use o HTTP GET .

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

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

Configurar o Slack

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

Assim como o OpenWeatherMap no exemplo anterior, é necessário obter uma para ativar o envio de mensagens. O Slack tem um URL exclusivo para você enviar mensagens para sua equipe, chamadas de Webhook de entrada.

Configure um Webhook de entrada clicando em Adicione a integração de webhooks de entrada e siga as instruções. A processo deve emitir um URL para usar para mensagens.

Fazer uma solicitação POST

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

• method: como mencionado, o padrão é GET, mas aqui vamos substituí-lo e Defina-o como POST.

• payload: são os dados que serão enviados ao servidor como parte da POST. solicitação. Neste exemplo, o Slack espera um objeto serializado para o formato JSON. conforme descrito no Lista de artigos do Documentação. Para isso, JSON.stringify é usado, e 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 acima mostra o mínimo para ativar mensagens recebidas no Slack. Um sample estendida ilustra a a criação e o envio de uma solicitação de desempenho de campanha Denuncie a um bem como algumas opções de formatação e exibição.

Veja a formatação de mensagens no Slack para conferir mais detalhes sobre as mensagens do Slack.

Dados do formulário

O exemplo acima demonstrado usando uma string JSON como a propriedade payload. para a solicitação POST.

Dependendo do formato da payload, o 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: '[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, esse a conversão automática de objetos JavaScript para dados de formulário é útil levar em conta em mente.

Autenticação básica HTTP

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

A autenticação é realizada ao anexar um nome de usuário e uma senha codificados ao 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. Forme a senha longa unindo o nome de usuário e a senha com uma 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 básicos de autenticação

Os exemplos de código (em inglês) contém dois exemplos que ilustram o uso da Autenticação básica HTTP:

• Como enviar mensagens SMS pelo Plivo
• Como enviar mensagens SMS via Twilio

Plivo

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

1. Registre-se no Plivo.
2. Cole o script de exemplo no 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 ou adicionar números à avaliação do Compute Engine. Adicione números de sandbox que possam ser usado com a conta de teste.
6. Adicione o número que aparecerá como remetente e o destinatário. número
7. Atualize PLIVO_SRC_PHONE_NUMBER no script para um dos números do sandbox que você acabou de se registrar. Isso deve incluir o código internacional de país, por exemplo 447777123456 para um número do Reino Unido.

Twilio

O Twilio é outro serviço que facilita o envio e recebimento de mensagens SMS pela API. Este exemplo mostra o envio e envio de mensagens.

1. Registre-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 da dashboard: este é o número autorizado pelo Twilio para enviar mensagens.

OAuth 1.0

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

Com 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 sejam concedeu acesso à conta e aos dados de um usuário, usando credenciais específicas para aquela aplicativo de terceiros. Além disso, a extensão do acesso também será específicas desse aplicativo.

Para mais informações sobre o OAuth 1.0, consulte o guia do OAuth Core. Consulte especificamente 6. Como autenticar com o OAuth. No três pernas completo OAuth 1.0, 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 um solicitação.

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

OAuth 1.0 nos scripts do Google Ads

Nos scripts do 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 para:

• Defina uma configuração de aplicativo para representar o script.
• Especifique quais permissões estão sendo estendidas para o script.
• Obter a chave e o segredo do consumidor, o token de acesso e o segredo de acesso para uso com o OAuth unidirecional.

OAuth 2.0

O OAuth 2.0 é usado em APIs populares para fornecer acesso a 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 permitir que eles acessem os dados do usuário. A 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 para até que ponto. Por exemplo, o acesso concedido pode ser somente leitura ou apenas para um subconjunto dos dados.

Para usar os serviços com o OAuth 2.0 ativado nos scripts do Google Ads, você precisa de várias etapas:

Fora do seu script

Permita que os scripts do Google Ads acessem seus dados de usuário por meio do API de terceiros. Na maioria dos casos, isso envolve a configuração de uma application 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 ter. fornecido e geralmente recebe um ID do cliente. Isso permite que você, OAuth 2 para controlar quais aplicativos têm acesso a seus dados na serviços 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, o servidor permitir, um conjunto diferente de etapas, conhecido como fluxo, precisará ser seguidas, mas todas resultarão em um token de acesso sendo emitidas que serão usadas para essa sessão para 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. Para exemplo, um fluxo diferente é usado quando um usuário está participando de um diferente de um cenário em que um aplicativo precisa ser executado segundo plano sem a presença do usuário.

Os provedores de API vão decidir quais tipos de concessão aceitam, e isso como o usuário procede com a integração da API.

Implementação

Para todos os diferentes fluxos de OAuth, o objetivo é obter um token de acesso que pode 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 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);

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

Concessão de credenciais do cliente

A concessão de credenciais do cliente é uma das formas mais simples do fluxo OAuth2, na qual o aplicativo troca uma ID e segredo, exclusivos para o 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 do token

A concessão do token de atualização é semelhante à concessão de credenciais do cliente, já que uma simples solicitação 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árias 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 um código de autorização conceder, o que exigirá que o usuário interaçã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 obter um token de atualização.

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

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

Como usar um script para receber um token de atualização

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

Atualizar uso do token

Depois que a autorização inicial é realizada, os serviços podem atualizar que pode ser usado de forma semelhante ao fluxo de credenciais do cliente. Dois exemplos são fornecidos 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 uma . Consulte a documentação do Search Ads Referência da API 360 para detalhes completos de outras ações que podem ser executadas.

Criar o script

1. Crie um novo projeto no Console de APIs. e obtenha um ID do cliente, uma chave secreta do cliente e um token de atualização seguindo o no guia da DoubleClick, não se esqueça de ativar a API do DoubleClick Search.
2. Cole a amostra script em um novo script no Google Ads.
3. Cole a amostra de OAuth2 biblioteca abaixo da listagem de códigos.
4. Altere o script para conter os valores corretos para ID do cliente, chave secreta do cliente, e o 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 API Script Execution. Isso permite que o Apps Script ser chamado dos scripts do Google Ads.

Criar um script do Apps Script

Crie um novo script. O exemplo a seguir listará 10 arquivos do Google 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 adequadas. Neste caso, o Drive da API e a API Execução de script API.
6. Crie credenciais do OAuth no item Credenciais no menu.
7. De volta ao seu script, publique o script para execução em Publicar > Implantar como executável da API

Criar o script do Google Ads

1. Cole a amostra script em um novo script no Google Ads.
2. Além disso, cole o exemplo de OAuth2 biblioteca abaixo da listagem de códigos.
3. Altere o script para conter os valores corretos para ID do cliente, chave secreta do cliente, e o token de atualização.

Contas de serviço

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

As contas de serviço diferem das opções acima porque não são usadas para acessar o usuário dados: 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 proprietário do projeto. Por exemplo, se a conta de serviço usasse a API Drive para criar um arquivo, pertencem à conta de serviço e, por padrão, não podem ser acessados pelo proprietário do projeto.

Exemplo da API Google Natural Language

A API Natural Language oferece sentimento análise e entidade análise de texto.

Este exemplo ilustra o cálculo do sentimento para o texto do anúncio, incluindo o título ou a descrição. Isso fornece uma medida quão positiva é a mensagem e a magnitude da mensagem: qual é 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 linguagem natural API
3. Ative o faturamento do projeto.
4. Criar um serviço Google Workspace. Faça o download do arquivo JSON de credenciais.
5. Cole a amostra script em uma nova script no Google Ads.
6. Além disso, cole o exemplo de OAuth2 biblioteca abaixo da listagem 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 transferido por download ao criar o serviço Conta. 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 os XML, e JSON.

JSON

O JSON é normalmente mais simples do que o XML para trabalhar como o formato da resposta. No entanto, ainda existem alguns problemas que podem surgir.

Validação da resposta

Após obter uma resposta bem-sucedida da chamada para a API, a solicitação a próxima etapa é usar JSON.parse para converter a string JSON em um JavaScript objeto. Nesse ponto, é 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 do a resposta pode mudar e as propriedades podem deixar de existir:

// 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 popular para a criação de APIs. Uma resposta de uma chamada de API podem ser analisados usando o XmlService parse :

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

Enquanto XmlService.parse detecta erros no XML e gera exceções Portanto, ele não fornece a capacidade de validar o XML em relação a uma 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 abaixo, a API Sportradar é usado para obter resultados de futebol para partidas selecionadas. A resposta XML leva 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 para:

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

O exemplo a seguir mostra como acessar o elemento <matches> no exemplo acima snippet do documento:

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

Dado o exemplo da tabela 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 ser concatenados quando há vários filhos de texto de um elemento. Considere usando getChildren() e iterando cada filho nos casos em que vários texto com filhos provavelmente.

Exemplo do Sportradar

Esta versão completa do Sportradar exemplo ilustra recuperação de detalhes de partidas de futebol, especificamente da Premier League inglesa correspondências. A API Soccer é um dos vários feeds de esportes oferecidos pelo Sportradar.

Configurar uma conta da Sportradar

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

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

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

Se tudo der certo, será exibida uma página com a 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: exemplo:

• Clientes que emitem 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 atingindo os limites de uso.
• Clientes fornecendo parâmetros inválidos.

Em todos esses casos, e em outros, um bom primeiro passo 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 status código maior que 400 ou mais). gerado pelo mecanismo de scripts do Google Ads.

Para impedir esse comportamento e permitir que o erro e a mensagem de erro sejam inspecionado, 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 tiver o resultado esperado dados, considere que:

  • Algumas APIs permitem a especificação de quais campos e/ou formato de resposta para usar. Consulte a documentação da API para mais detalhes.
  • Uma API pode ter vários recursos que podem ser chamados. Consulte 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 o ou ao desenvolvedor para esclarecimentos.

• 400 Bad Request normalmente significa que há algo de errado no a formatação ou a estrutura da solicitação enviada ao servidor. Inspecione o e compará-la com as especificações da API para garantir a conformidade com as expectativas da equipe. Consulte Como inspecionar solicitações para detalhes sobre como examinar as solicitações.

• 401 Unauthorized geralmente significa que a API está sendo chamada sem fornecer ou executando 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 usa o OAuth 2.0, verifique se o token de acesso foi enviado. e está sendo fornecido como um token do portador.
  • No caso de outras variações da autorização, verifique se as regras as credenciais da 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 ao usuário 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 o recurso referenciado existe (por exemplo, se o arquivo existir para uma API baseada em arquivo).

Inspecionar solicitações

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

Em vez de enviar uma solicitação ao servidor, este método constrói a solicitação que teria sido enviado e, em seguida, retorna. Isso permite que o usuário inspecionar os 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 juntos, o erro pode estar na função que você criou para gerar esse formulário dados. De forma mais simples:

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

permitirá que você inspecione os elementos da solicitação.

Registrar solicitações e respostas

Para ajudar no processo inteiro de inspeção de solicitações e respostas a uma de terceiros, a função auxiliar a seguir poderá ser usada como um drop-in substituto de UrlFetchApp.fetch(), para 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 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 seu script, os detalhes de todas as solicitações e respostas são registrados em no console, facilitando a depuração.