API di terza parte

Una potente funzionalità degli script Google Ads è la possibilità di integrare i dati e servizi da API di terze parti.

Questa guida tratta i seguenti concetti che possono aiutarti a scrivere script per connettersi ad altri servizi:

  • Effettuare richieste HTTP. Come utilizzare UrlFetchApp per accedere tramite le API esterne.
  • Autenticazione: esaminiamo alcuni scenari di autenticazione comuni.
  • Analisi delle risposte: come elaborare i dati JSON e XML restituiti.

Includiamo anche samples per un numero delle API più diffuse che illustrano questi concetti.

Recupera i dati con UrlFetchApp

UrlFetchApp fornisce la funzionalità di base richiesta per interagire con le API di terze parti.

L'esempio seguente mostra il recupero dei dati meteo da OpenWeatherMap. Abbiamo scelto OpenWeatherMap per il seguente motivo: lo schema di autorizzazione e l'API relativamente semplici.

Fai una richiesta

La documentazione di OpenWeatherMap specifica per richiedere il meteo attuale come segue:

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

L'URL fornisce il nostro primo esempio di autorizzazione: il parametro apikey è e il valore è univoco per ogni utente. Questa chiave si ottiene la registrazione.

Dopo la registrazione, è possibile inviare una richiesta utilizzando la chiave nel seguente modo:

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());

L'esecuzione di questo codice genera una lunga stringa di JSON il testo scritto nella finestra di logging negli script Google Ads.

Il passaggio successivo consiste nel convertire questo formato in un formato utilizzabile all'interno della tua lo script.

Dati JSON

Molte API forniscono risposte in formato JSON. Questo rappresenta una semplice serializzazione di oggetti JavaScript, come oggetti, array e tipi base possono essere rappresentati e trasferiti come stringhe.

Per convertire una stringa JSON, come quella restituita da OpenWeatherMap: torna in un oggetto JavaScript, utilizza la funzione JSON.parse. Riprendendo l'esempio precedente:

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

Il metodo JSON.parse converte la stringa in un oggetto, che ha una proprietà name.

Consulta la sezione Analizzare le risposte per ulteriori dettagli su lavorare con le risposte dell'API in formati diversi.

Gestione degli errori

La gestione degli errori è una considerazione importante quando si lavora con API di terze parti negli script perché le API di terze parti cambiano spesso e generano valori di risposta imprevisti, ad esempio:

  • L'URL o i parametri dell'API possono cambiare a tua insaputa.
  • La tua chiave API (o un'altra credenziale utente) può scadere.
  • Il formato della risposta può cambiare senza preavviso.

Codici di stato HTTP

Considerato il potenziale di risposte impreviste, dovresti controllare l'HTTP codice di stato. Per impostazione predefinita, UrlFetchApp genererà un'eccezione se viene rilevato un codice di errore HTTP. A modificare questo comportamento, è necessario passare un parametro facoltativo, come nell'esempio seguente:

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();
}

Struttura della risposta

Quando le API di terze parti cambiano, spesso gli sviluppatori non sono immediatamente al corrente modifiche che potrebbero influire sugli script. Ad esempio, se la proprietà name restituito nell'esempio OpenWeatherMap è cambiato in locationName, gli script l'utilizzo di questa proprietà non riuscirà.

Per questo motivo può essere utile verificare se la struttura restituita come previsto, ad esempio:

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

POST dei dati con UrlFetchApp

L'esempio introduttivo con OpenWeatherMap recuperati solo dai dati. In genere, le chiamate API che non cambiano stato al server utilizza HTTP GET .

Il metodo GET è quello predefinito per UrlFetchApp. Tuttavia, alcune chiamate API, come le chiamate a un servizio che invia SMS, richiede altri metodi, come POST o PUT.

Per illustrare l'uso delle chiamate POST con UrlFetchApp, il seguente esempio dimostra l'integrazione con Slack, un servizio di messaggistica per inviare un messaggio Slack a utenti e gruppi Slack.

Configura Slack

Questa guida presuppone che tu abbia già effettuato la registrazione a un account Slack.

Come per OpenWeatherMap nell'esempio precedente, è necessario ottenere una per abilitare l'invio dei messaggi. Slack fornisce un URL univoco che consente di di inviare messaggi al tuo team, chiamato Webhook in arrivo.

Configura un webhook in entrata facendo clic su Aggiungi l'integrazione dei webhook in entrata e segui le istruzioni. La dovrebbe emettere un URL da utilizzare per i messaggi.

Effettua una richiesta POST

Dopo aver configurato il webhook in entrata, per effettuare una richiesta POST devi semplicemente l'uso di alcune proprietà aggiuntive nel parametro options passato UrlFetchApp.fetch:

  • method: come accennato, il valore predefinito è GET, ma in questo caso lo sostituisci e imposta su POST.

  • payload: questi sono i dati da inviare al server nell'ambito di POST richiesta. In questo esempio, Slack si aspetta un oggetto serializzato in formato JSON come descritto in Slack documentazione. Per questo motivo, JSON.stringify e Content-Type è impostato su 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);

Esempio di Slack esteso

L'esempio precedente mostra le operazioni minime necessarie per abilitare i messaggi in arrivo in Slack. Un Un esempio esteso illustra creazione e invio di un rendimento della campagna Segnala a un gruppo, nonché alcune opzioni di formattazione e visualizzazione.

Messaggio in arrivo

Visualizzare la formattazione dei messaggi in Slack per ulteriori dettagli sui messaggi Slack.

Dati modulo

L'esempio precedente ha dimostrato l'utilizzo di una stringa JSON come proprietà payload per la richiesta POST.

A seconda del formato di payload, UrlFetchApp adotta approcci diversi per creare la richiesta POST:

  • Quando payload è una stringa, l'argomento stringa viene inviato come corpo della richiesta.

  • Quando payload è un oggetto, ad esempio una mappa di valori:

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

    Le coppie chiave/valore vengono convertite in dati modulo:

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

    Anche l'intestazione Content-Type per la richiesta è impostata su application/x-www-form-urlencoded.

Alcune API richiedono l'uso dei dati del modulo quando si inviano richieste POST, quindi conversione automatica dagli oggetti JavaScript ai dati del modulo è utile a mente.

Autenticazione HTTP di base

HTTP di base autenticazione è uno dei è la forma di autenticazione più semplice ed è utilizzata da molte API.

L'autenticazione si ottiene collegando un nome utente e una password codificati al Intestazioni HTTP in ogni richiesta.

Autenticazione HTTP di base

Crea una richiesta

Per produrre una richiesta autenticata sono necessari i seguenti passaggi:

  1. Crea la passphrase unendo il nome utente e la password a un Due punti, ad esempio username:password.
  2. Base64 codifica la passphrase. Ad esempio, username:password diventa dXNlcm5hbWU6cGFzc3dvcmQ=.
  3. Allega un'intestazione Authorization alla richiesta, nel modulo Authorization: Basic <encoded passphrase>

Il seguente snippet illustra come ottenere questo risultato negli script 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);

Esempi di autenticazione di base

Gli esempi di codice contiene due esempi che illustrano l'utilizzo dell'autenticazione di base HTTP:

Plivo

Plivo è un servizio che facilita l'invio e la ricezione di messaggi SMS tramite l'API. Questo esempio illustra l'invio messaggi.

  1. Registrati con Plivo.
  2. Incolla lo script di esempio in un nuovo script in Google Ads.
  3. Sostituisci i valori PLIVO_ACCOUNT_AUTHID e PLIVO_ACCOUNT_AUTHTOKEN con i valori della dashboard di gestione.
  4. Inserisci il tuo indirizzo email come specificato nello script per la notifica di errori.
  5. Per utilizzare Plivo, devi acquistare numeri o aggiungere numeri alla prova . Aggiungi i numeri di sandbox che possono da usare con l'account di prova.
  6. Aggiungi sia il numero che verrà visualizzato come mittente sia il destinatario numero.
  7. Aggiorna PLIVO_SRC_PHONE_NUMBER nello script con uno dei numeri sandbox appena registrato. Deve includere il prefisso internazionale per esempio 447777123456 per un numero del Regno Unito.

Twilio

Twilio è un altro servizio che facilita l'invio e la ricezione di messaggi SMS tramite l'API. Questo esempio illustra l'invio messaggi.

  1. Registrati a Twillio.
  2. Incolla lo script di esempio in un nuovo script Google Ads.
  3. Sostituisci i valori TWILIO_ACCOUNT_SID e TWILIO_ACCOUNT_AUTHTOKEN con i valori visualizzati nella pagina della console account.
  4. Sostituisci TWILIO_SRC_PHONE_NUMBER con il numero della dashboard: questa è la numero autorizzato da Twilio a inviare messaggi.

OAuth 1.0

Molti servizi popolari utilizzano OAuth per l'autenticazione. OAuth è disponibile in diverse sapori e versioni.

Mentre con l'autenticazione di base HTTP, un utente ha un solo nome utente e una sola password, OAuth consente alle applicazioni di a cui è stato concesso l'accesso all'account e ai dati di un utente, utilizzando per applicazioni di terze parti. Inoltre, anche la portata dell'accesso sarà specifiche dell'applicazione.

Per informazioni su OAuth 1.0, consulta la guida di OAuth Core. In particolare, vedi 6. Autenticazione con OAuth. A tre vie complete OAuth 1.0, la procedura è la seguente:

  1. L'applicazione ("Consumer") ottiene un token di richiesta.
  2. L'utente autorizza il token di richiesta.
  3. L'applicazione scambia il token di richiesta con un token di accesso.
  4. Per tutte le richieste di risorse successive, il token di accesso viene utilizzato in un ambiente richiesta.

Per consentire ai servizi di terze parti di utilizzare OAuth 1.0 senza interazione dell'utente (ad esempio come richiederebbero gli script Google Ads) i passaggi 1, 2 e 3 non sono possibili. Pertanto, alcuni servizi emettono un token di accesso dalla loro configurazione e consentire all'applicazione di andare direttamente al passaggio 4. Questo sistema è noto come OAuth 1.0 a una vie.

OAuth1

OAuth 1.0 negli script Google Ads

Per gli script Google Ads, ogni script viene generalmente interpretato come un'applicazione. Tramite la pagina delle impostazioni della console/di amministrazione per il servizio, di solito necessarie per:

  • Imposta una configurazione dell'applicazione per rappresentare lo script.
  • Specifica quali autorizzazioni vengono estese allo script.
  • Ottenere la chiave utente, il segreto utente, il token di accesso e il segreto di accesso da utilizzare con OAuth a una vie.

OAuth 2.0

OAuth 2.0 è utilizzato in API molto diffuse per fornire l'accesso a dati utente. Il proprietario di un account per un determinato servizio di terze parti concede autorizzazioni specifiche per consentire loro di accedere ai dati utente. La vantaggi sono che il proprietario:

  • Non deve condividere le credenziali dell'account con l'applicazione.
  • Possibilità di controllare quali applicazioni hanno accesso ai dati individualmente e fino a che punto. Ad esempio, l'accesso concesso potrebbe essere di sola lettura o solo a un un sottoinsieme di dati.)

Per utilizzare i servizi abilitati per OAuth 2.0 negli script Google Ads, esistono diverse passaggi:

Al di fuori dello script

Concedi agli script Google Ads l'autorizzazione ad accedere ai tuoi dati utente tramite la tramite un'API di terze parti. Nella maggior parte dei casi, ciò comporterà l'impostazione di application nella console del servizio di terze parti. Questa applicazione rappresenta lo script Google Ads.

Specifica i diritti di accesso dell'applicazione dello script Google Ads e di solito gli verrà assegnato un ID client. Ciò consente di, mediante OAuth 2 per controllare quali applicazioni hanno accesso ai tuoi dati nel servizi di terze parti e anche gli aspetti di tali dati che l'utente può visualizzare modificare.

Nello script

Autorizza con il server remoto. A seconda del tipo di autorizzazione, consentito dal server, una serie di passaggi diversa, nota come flow, dovrà ma tutte daranno origine a un token di accesso emessi che verranno utilizzati per quella sessione per tutte le richieste successive.

Effettuare richieste API. Passa il token di accesso con ogni richiesta.

Flussi di autorizzazione

Ogni tipo di concessione e il flusso corrispondente si adattano a scenari di utilizzo diversi. Per Ad esempio, viene usato un flusso diverso quando un utente partecipa a un a differenza di uno scenario in cui è richiesta l'esecuzione di un'applicazione sullo sfondo senza la presenza di un utente.

e saranno i provider di API a decidere quali tipi di concessione accettare. Questa guida in che modo l'utente procede con l'integrazione dell'API.

Implementazione

Per tutti i diversi flussi OAuth, lo scopo è ottenere un token di accesso che può quindi essere utilizzato per il resto della sessione per autenticare le richieste.

Una raccolta di esempio illustra come eseguire l'autenticazione per ogni tipo di flusso diverso. Ciascuno di questi restituisce un oggetto che ottiene e archivia il token di accesso e facilitano le richieste autenticate.

Lo schema di utilizzo generale è:

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

Concessione di credenziali client

La concessione delle credenziali client è una delle forme più semplici di flusso OAuth2, in cui l'applicazione scambia ID e secret, univoci per l'applicazione, in cambio dell'emissione di un token di accesso a tempo limitato.

Credenziale client

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

Aggiorna concessione token

La concessione del token di aggiornamento è simile alla concessione delle credenziali del client, in quanto una semplice richiesta al server restituirà un token di accesso che può essere usato durante la sessione.

Aggiorna token

Ottenere un token di aggiornamento

La differenza con la concessione del token di aggiornamento è che, mentre i dettagli richieste per la concessione di credenziali client provengono dalla configurazione dell'applicazione (ad esempio, nel pannello di controllo del servizio), il token di aggiornamento viene concesso nell'ambito di un flusso più complesso, come un codice di autorizzazione Concedi, che richiederà all'utente interazione:

Codice di autorizzazione

Utilizzo di OAuth Playground per ottenere un token di aggiornamento

OAuth2 Playground offre una UI che consente all'utente la procedura di concessione del codice di autorizzazione per ottenere un token di aggiornamento.

Il pulsante delle impostazioni in alto a destra ti consente di definire tutti i parametri da utilizzare nel flusso OAuth, tra cui:

  • Endpoint di autorizzazione: utilizzato come inizio del flusso per l'autorizzazione.
  • Endpoint del token: utilizzato con il token di aggiornamento per ottenere un token di accesso.
  • client ID and secret (ID client e secret): credenziali per l'applicazione.

OAuth Playground

Utilizzo di uno script per ottenere un token di aggiornamento

Un'alternativa basata su script al completamento del flusso è disponibile nel token di aggiornamento campione.

Aggiorna utilizzo token

Una volta eseguita l'autorizzazione iniziale, i servizi possono eseguire un aggiornamento che può essere utilizzato in modo simile al flusso delle credenziali client. Di seguito sono riportati due esempi:

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

Esempio di Search Ads 360

Search Ads 360 è un esempio di API che può essere utilizzata con un token di aggiornamento. In questo esempio, uno script genera e restituisce un oggetto report. Consulta il team di Search Ads Riferimento API 360 per i dettagli completi delle altre azioni che è possibile eseguire.

Crea lo script
  1. Crea un nuovo progetto nella console API e ottenere un ID client, un client secret e un token di aggiornamento seguendo il nella guida di DoubleClick, verificando di attivare l'API di DoubleClick Search.
  2. Incolla l'esempio in un nuovo script in Google Ads.
  3. Incolla il codice OAuth2 di esempio libreria sotto dell'elenco di codice.
  4. Modifica lo script in modo che contenga i valori corretti per ID client, client secret e aggiorna il token.

Esempio di API Apps Script Execution

Questo esempio illustra l'esecuzione di una funzione in Apps Script utilizzando il comando API Script Execution. Questo permette ad Apps Script dagli script Google Ads.

Creare uno script Apps Script

Crea un nuovo script. Il seguente esempio elencherà 10 file da Drive:

function listFiles() {
  const limit = 10;
  const files = [];
  const fileIterator = DriveApp.getFiles();
  while (fileIterator.hasNext() && limit) {
    files.push(fileIterator.next().getName());
    limit--;
  }
  return files;
}
Configura l'esecuzione di Apps Script
  1. Salva lo script.
  2. Fai clic su Risorse > progetto Google Cloud.
  3. Fai clic sul nome del progetto per passare alla console API.
  4. Vai ad API e Servizi.
  5. Abilita le API appropriate, in questo caso Drive API e le app Esecuzione script l'API.
  6. Crea le credenziali OAuth dalla voce Credentials (Credenziali) del menu.
  7. Torna allo script e pubblica lo script per l'esecuzione da Pubblica > Esegui il deployment come API Executable.
Creare lo script Google Ads
  1. Incolla l'esempio script in un nuovo script in Google Ads.
  2. Inoltre, incolla il codice OAuth2 di esempio libreria sotto dell'elenco di codice.
  3. Modifica lo script in modo che contenga i valori corretti per ID client, client secret e aggiorna il token.

Account di servizio

Un'alternativa ai tipi di concessioni di cui sopra è il concetto di servizio Google Cloud.

Gli account di servizio sono diversi da quelli precedenti in quanto non vengono utilizzati per accedere data: dopo l'autenticazione, le richieste vengono effettuate dall'account di servizio per conto dell'applicazione, non dell'utente che potrebbe essere il proprietario del progetto. Ad esempio, se l'account di servizio doveva utilizzare l'API Drive per creare un file, appartengono all'account di servizio e, per impostazione predefinita, non sarebbero accessibili proprietario del progetto.

Esempio di API Natural Language di Google

L'API Natural Language fornisce sentiment l'analisi dei dati e entità per il testo.

Questo esempio illustra il calcolo sentimento per il testo dell'annuncio, ad esempio titolo o descrizione. In questo modo viene fornita una misura quanto è positivo il messaggio e la sua portata: "qual è, cosa migliore?" Vendiamo torte o Vendiamo le migliori torte di Londra. Acquistare oggi!?

Configurare lo script
  1. Crea un nuovo progetto nella console API
  2. Attiva il linguaggio naturale dell'API
  3. Abilitare la fatturazione per il progetto.
  4. Crea un servizio Account. Scarica il file JSON delle credenziali.
  5. Incolla l'esempio script in una nuova in Google Ads.
  6. Inoltre, incolla il codice OAuth2 di esempio libreria sotto dell'elenco di codice.
  7. Sostituisci i valori necessari:
    • serviceAccount: l'indirizzo email dell'account di servizio, ad esempio xxxxx@yyyy.iam.gserviceaccount.com.
    • key: la chiave del file JSON scaricato durante la creazione del servizio Account. Inizia il giorno -----BEGIN PRIVATE KEY... e termina il giorno ...END PRIVATE KEY-----\n.

Risposte API

Le API possono restituire dati in una serie di formati. I più importanti sono i file XML e JSON.

JSON

JSON è in genere più semplice di XML da utilizzare come formato di risposta. Tuttavia, possono sorgere alcuni problemi.

Convalida della risposta

Dopo aver ottenuto una risposta positiva dalla chiamata all'API, il tipico il passaggio successivo è usare JSON.parse per convertire la stringa JSON in un . A questo punto, è opportuno gestire il caso in cui l'analisi non supera:

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

Inoltre, se l'API non è sotto il vostro controllo, considerate che la struttura del la risposta potrebbe cambiare e le proprietà potrebbero non esistere più:

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

Convalida

XML è ancora un formato popolare per la creazione di API. Una risposta a una chiamata API possono essere analizzati utilizzando XmlService parse: :

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

Mentre XmlService.parse rileva errori nel file XML e genera eccezioni. di conseguenza, non offre la possibilità di convalidare il file XML rispetto a .

Elemento principale

Una volta analizzata correttamente il documento XML, si ottiene l'elemento radice utilizzando il metodo getRootElement():

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

Spazi dei nomi

Nell'esempio seguente, l'API Sportradar viene utilizzato per ottenere risultati di calcio per partite selezionate. La risposta XML richiede nel seguente formato:

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

Nota come lo spazio dei nomi viene specificato nell'elemento principale. Per questo motivo, necessarie per:

  • Estrai l'attributo dello spazio dei nomi dal documento.
  • Utilizza questo spazio dei nomi quando attraversi e accedi agli elementi secondari.

L'esempio seguente mostra come accedere all'elemento <matches> in alto snippet 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);

Ottenere i valori

Dato il campione del calendario del football:

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

È possibile recuperare gli attributi, ad esempio:

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

Il testo contenuto in un elemento può essere letto utilizzando getText(), ma questi concatenate in cui ci sono più elementi di testo secondari di un elemento. Prendi in considerazione usando getChildren() e ripetendo ogni figlio nei casi in cui di testo secondari.

Esempio di Sportradar

Questa presentazione completa di Sportradar un esempio illustra recupero dei dettagli delle partite di calcio, in particolare della Premier League inglese corrispondenze. L'API Soccer fa parte dell'ampia gamma di feed sportivi offerti da Sportradar.

Configurare un account Sportradar
  1. Vai al sito per sviluppatori Sportradar.
  2. Registrati per un account di prova.
  3. Dopo aver eseguito la registrazione, accedi al tuo account.
  4. Dopo aver eseguito l'accesso, vai a MyAccount.

Sportradar separa i vari sport in API differenti. Ad esempio, potrebbe acquistare l'accesso all'API Soccer ma non all'API Tennis. Ciascuna All'applicazione che crei possono essere associati diversi sport. diverse chiavi.

  1. In Applications (Applicazioni), fai clic su Create a new Application (Crea nuova applicazione). Invia l'applicazione un nome e una descrizione e ignora il campo del sito web.
  2. Seleziona solo l'opzione Issue a new key for Soccer Trial Europe v2 (Invia una nuova chiave per la prova di calcio in Europa v2).
  3. Fai clic su Registra richiesta.

Se l'operazione ha esito positivo, dovrebbe essere visualizzata una pagina con la nuova chiave API.

  1. Incolla lo script di esempio in un nuovo script Google Ads.
  2. Sostituisci la chiave API nell'elenco con la chiave ottenuta in precedenza e modifica il valore dell'indirizzo email.

Risoluzione dei problemi

Quando si utilizzano API di terze parti, gli errori possono verificarsi per diversi motivi, ad esempio: esempio:

  • Client che inviano richieste al server in un formato non previsto dall'API.
  • Clienti che si aspettano un formato di risposta diverso da quello riscontrato.
  • Client che utilizzano chiavi o token non validi oppure valori lasciati come segnaposto.
  • Client che stanno per raggiungere i limiti di utilizzo.
  • Clienti che forniscono parametri non validi.

In tutti questi casi, e in altri casi, è un buon primo passo per individuare la causa del problema consiste nell'esaminare i dettagli della risposta che ha causato l'errore.

Analizza risposte

Per impostazione predefinita, qualsiasi risposta che restituisce un errore (uno stato codice di almeno 400) generata dal motore degli script Google Ads.

Per evitare questo comportamento e consentire la visualizzazione del messaggio ispezionato, imposta la proprietà muteHttpExceptions dei parametri facoltativi su UrlFetchApp.fetch. Ad esempio:

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

Codici di stato comuni

  • 200 OK indica che l'operazione è riuscita. Se la risposta non contiene il valore di dati, considera che:

    • Alcune API consentono di specificare quali campi e/o formati di risposta per gli utilizzi odierni. Consulta la documentazione dell'API per maggiori dettagli.
    • Un'API può avere più risorse che è possibile chiamare. Consulta il documentazione per determinare se una risorsa diversa potrebbe essere appropriato da usare e restituirà i dati richiesti.
    • L'API potrebbe essere cambiata da quando è stato scritto il codice. Consulta il documentazione o lo sviluppatore per chiarimenti.

  • 400 Bad Request in genere indica che ci sono errori nel formattazione o struttura della richiesta inviata al server. Ispeziona richiesta e confrontarla con le specifiche dell'API per assicurarsi che sia conforme le aspettative. Consulta la sezione Ispezione delle richieste per maggiori dettagli su come esaminare le richieste.

  • 401 Unauthorized di solito significa che l'API viene chiamata senza fornire o aver eseguito correttamente l'autorizzazione.

    • Se l'API utilizza l'autorizzazione di base, assicurati che l'intestazione Authorization viene creato e fornito nella richiesta.
    • Se l'API utilizza OAuth 2.0, accertati di aver ottenuto il token di accesso e viene fornito come token di connessione.
    • Per qualsiasi altra variazione dell'autorizzazione, assicurati che i requisiti le credenziali per la richiesta.

  • 403 Forbidden indica che l'utente non dispone dell'autorizzazione per la risorsa richiesta.

    • Assicurati che all'utente siano state concesse le autorizzazioni necessarie, ad esempio: concedendo all'utente l'accesso a un file in una richiesta basata su file.

  • 404 Not Found indica che la risorsa richiesta non esiste.

    • Verifica che l'URL utilizzato per l'endpoint API sia corretto.
    • Se recuperi una risorsa, verifica che la risorsa a cui si fa riferimento esista (ad esempio, se il file esiste per un'API basata su file).

Ispeziona le richieste

L'ispezione delle richieste è utile quando le risposte dell'API indicano che la richiesta non è corretta formato, ad esempio, un codice di stato 400. Per facilitare l'esame delle richieste, UrlFetchApp ha un metodo associato al metodo fetch(), chiamato getRequest():

Anziché inviare una richiesta al server, questo metodo crea la richiesta che sarebbe stato inviato e lo restituisce. Ciò consente all'utente di esamina gli elementi della richiesta per assicurarti che sia corretta.

Ad esempio, se i dati del modulo nella tua richiesta sono costituiti da molte stringhe concatenate l'errore può risiedere nella funzione creata per generare il modulo e i dati di Google Cloud. Nella sua forma più semplice:

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

consente di controllare gli elementi della richiesta.

Registra richieste e risposte

Per assistere l'intero processo di ispezione delle richieste e delle risposte a un API di terze parti, la seguente funzione helper può essere utilizzata come un sostituzione di UrlFetchApp.fetch(), per registrare richieste e risposte.

  1. Sostituisci tutte le istanze di UrlFetchApp.fetch() nel codice con logUrlFetch().

  2. Aggiungi la funzione seguente alla fine dello 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;
}

Durante l'esecuzione dello script, i dettagli di tutte le richieste e le risposte vengono registrati della console, semplificando il debug.