API di terza parte

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

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

  • Invio di richieste HTTP: come utilizzare UrlFetchApp per accedere alle API esterne.
  • Autenticazione: vengono trattati alcuni scenari di autenticazione comuni.
  • Analisi delle risposte: come elaborare i dati JSON e XML restituiti.

Sono inclusi anche esempi per una serie di API di uso comune che illustrano questi concetti.

Recuperare i dati con UrlFetchApp

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

L'esempio seguente mostra il recupero dei dati meteo da OpenWeatherMap. Abbiamo scelto OpenWeatherMap per il suo schema di autorizzazione e la sua API relativamente semplici.

Fai una richiesta

La documentazione di OpenWeatherMap specifica il formato 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 è obbligatorio e il valore è univoco per ogni utente. Questa chiave viene ottenuta tramite la registrazione.

Dopo la registrazione, una richiesta che utilizza la chiave può essere emessa 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 testo JSON scritta nella finestra di registrazione negli script Google Ads.

Il passaggio successivo consiste nel convertire il file in un formato che possa essere utilizzato all'interno dello script.

Dati JSON

Molte API forniscono risposte in formato JSON. Si tratta di una semplice serializzazione di oggetti JavaScript, in modo che oggetti, array e tipi di base possano essere rappresentati e trasferiti come stringhe.

Per convertire una stringa JSON, come quella restituita da OpenWeatherMap, in un oggetto JavaScript, utilizza il metodo JSON.parse integrato. Proseguendo dall'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 con una proprietà name.

Per maggiori dettagli su come gestire le risposte dell'API in diversi formati, consulta la sezione Eseguire l'analisi delle risposte.

Gestione degli errori

La gestione degli errori è un aspetto importante quando si utilizzano API di terze parti nei tuoi script perché spesso cambiano frequentemente 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 altre credenziali utente) può scadere.
  • Il formato della risposta può cambiare senza preavviso.

Codici di stato HTTP

A causa della potenziale presenza di risposte impreviste, devi controllare il codice di stato HTTP. Per impostazione predefinita, UrlFetchApp genera un'eccezione se viene rilevato un codice di errore HTTP. Per cambiare 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 a conoscenza delle modifiche che potrebbero influire sui loro script. Ad esempio, se la proprietà name restaurata nell'esempio OpenWeatherMap viene modificata in locationName, gli script che utilizzano questa proprietà non andranno a buon fine.

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

Inviare dati POST con UrlFetchApp

L'esempio introduttivo con OpenWeatherMap recuperava solo i dati. In genere, le chiamate API che non modificano lo stato sul server remoto utilizzano il metodo HTTP GET.

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

Per illustrare l'utilizzo delle chiamate POST con UrlFetchApp, il seguente esempio mostra l'integrazione con Slack, un'applicazione di messaggistica collaborativa, per inviare un messaggio di Slack a utenti e gruppi di Slack.

Configurare Slack

Questa guida presuppone che tu abbia già creato un account Slack.

Come per OpenWeatherMap nell'esempio precedente, è necessario ottenere un token per attivare l'invio di messaggi. Slack fornisce un URL univoco che ti consente di inviare messaggi al tuo team, chiamato webhook in entrata.

Configura un webhook in entrata facendo clic su Aggiungi integrazione webhook in entrata e seguendo le istruzioni. Il procedura dovrebbe emettere un URL da utilizzare per la messaggistica.

Effettua una richiesta POST

Dopo aver configurato il webhook in entrata, per effettuare una richiesta POST è sufficiente utilizzare alcune proprietà aggiuntive nel parametro options passato a UrlFetchApp.fetch:

  • method: come accennato, il valore predefinito è GET, ma qui lo sostituiamo e lo impostiamo su POST.

  • payload: si tratta dei dati da inviare al server nell'ambito della richiesta POST. In questo esempio, Slack si aspetta un oggetto serializzato in formato JSON come descritto nella documentazione di Slack. A questo scopo, viene utilizzato il metodo JSON.stringify e Content-Type viene 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 riportato sopra mostra il minimo necessario per attivare i messaggi in arrivo in Slack. Un esempio dettagliato illustra la creazione e l'invio di un report sul rendimento della campagna a un gruppo, nonché alcune opzioni di formattazione e visualizzazione.

Messaggio in arrivo

Per ulteriori dettagli sui messaggi di Slack, consulta la sezione sulla formattazione dei messaggi nella documentazione di Slack.

Dati modulo

L'esempio riportato sopra mostra l'utilizzo di una stringa JSON come proprietà payload per la richiesta POST.

A seconda del formato di payload, UrlFetchApp adotta approcci diversi per la costruzione della 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 form-data:

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

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

Alcune API richiedono l'utilizzo dei dati del modulo quando invii richieste POST, quindi è utile tenere presente questa conversione automatica da oggetti JavaScript a dati del modulo.

Autenticazione di base HTTP

L'autenticazione di base HTTP è una delle forme di autenticazione più semplici ed è utilizzata da molte API.

L'autenticazione viene eseguita associando un nome utente e una password codificati alle intestazioni HTTP in ogni richiesta.

Autenticazione di base HTTP

Crea una richiesta

Per generare una richiesta autenticata, sono necessari i seguenti passaggi:

  1. Forma la passphrase unendo il nome utente e la password con un colon, ad esempio username:password.
  2. Codifica la passphrase in Base64, ad esempio username:password diventa dXNlcm5hbWU6cGFzc3dvcmQ=.
  3. Allega un'intestazione Authorization alla richiesta, nel formato Authorization: Basic <encoded passphrase>

Il seguente snippet illustra come ottenere questo risultato in Google Ads Scripts:

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

La sezione 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 la propria API. Questo esempio illustra l'invio di messaggi.

  1. Registrati a 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 quelli della dashboard di gestione.
  4. Inserisci il tuo indirizzo email come specificato nello script per la notifica degli errori.
  5. Per utilizzare Plivo, devi acquistare numeri o aggiungerli all'account di prova. Aggiungi numeri della sandbox che possono essere utilizzati con l'account di prova.
  6. Aggiungi sia il numero che verrà visualizzato come mittente sia il numero del destinatario.
  7. Aggiorna PLIVO_SRC_PHONE_NUMBER nello script con uno dei numeri della sandbox appena registrati. Deve includere il codice paese internazionale, ad esempio 447777123456 per un numero del Regno Unito.

Twilio

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

  1. Registrati a Twillio.
  2. Incolla lo script di esempio in un nuovo script in Google Ads.
  3. Sostituisci i valori TWILIO_ACCOUNT_SID e TWILIO_ACCOUNT_AUTHTOKEN con quelli visualizzati nella pagina della console dell'account.
  4. Sostituisci TWILIO_SRC_PHONE_NUMBER con il numero riportato nella dashboard, ovvero il numero autorizzato da Twilio per l'invio di messaggi.

OAuth 1.0

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

Mentre con l'autenticazione di base HTTP un utente ha un solo nome utente e una sola password, OAuth consente di concedere alle applicazioni di terze parti l'accesso all'account e ai dati di un utente utilizzando le credenziali specifiche dell'applicazione di terze parti. Inoltre, l'entità dell'accesso sarà specifica anche per l'applicazione.

Per informazioni generali su OAuth 1.0, consulta la guida di OAuth Core. In particolare, consulta 6. Autenticazione con OAuth. In OAuth 1.0 con tre token, la procedura è la seguente:

  1. L'applicazione ("Consumatore") 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 una richiesta firmata.

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 console di configurazione, consentendo all'applicazione di passare direttamente al passaggio 4. Questo è noto come OAuth 1.0 a una via.

OAuth1

OAuth 1.0 negli script Google Ads

Per gli script Google Ads, ogni script viene solitamente interpretato come un'applicazione. Nella pagina delle impostazioni della console/dell'amministrazione del servizio, in genere è necessario:

  • Configura una configurazione dell'applicazione per rappresentare lo script.
  • Specifica le autorizzazioni che vengono estese allo script.
  • Ottieni la chiave consumer, il secret consumer, il token di accesso e il secret di accesso da utilizzare con OAuth a un solo passaggio.

OAuth 2.0

OAuth 2.0 viene utilizzato nelle API più diffuse per fornire accesso ai dati utente. Il proprietario di un account per un determinato servizio di terze parti concede l'autorizzazione ad applicazioni specifiche per consentire loro di accedere ai dati utente. I vantaggi sono che il proprietario:

  • Non deve condividere le credenziali del proprio account con l'applicazione.
  • Può controllare singolarmente quali applicazioni hanno accesso ai dati e in che misura. Ad esempio, l'accesso concesso può essere di sola lettura o solo a un sottoinsieme di dati.

Per utilizzare i servizi compatibili con OAuth 2.0 negli script Google Ads, sono necessari diversi passaggi:

Al di fuori dello script

Concedere l'autorizzazione a Script Google Ads per accedere ai dati utente tramite l'API di terze parti. Nella maggior parte dei casi, sarà necessario configurare un'applicazione nella console del servizio di terze parti. Questa applicazione rappresenta lo script Google Ads.

Specifica i diritti di accesso che devono essere assegnati all'applicazione dello script Google Ads e in genere verrà assegnato un ID client. In questo modo, tramite OAuth 2 puoi controllare quali applicazioni hanno accesso ai tuoi dati nel servizio di terze parti e anche quali aspetti di questi dati possono visualizzare o modificare.

Nello script

Autorizza con il server remoto. A seconda del tipo di concessione consentito dal server, sarà necessario seguire una serie diversa di passaggi, noti come flusso, ma alla fine verrà generato un token di accesso che verrà utilizzato per la 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 sono adatti a scenari di utilizzo diversi. Ad esempio, viene utilizzato un flusso diverso quando un utente partecipa a una sessione interattiva, rispetto a uno scenario in cui è necessario che un'applicazione venga eseguita in background senza la presenza di un utente.

I fornitori di API decideranno quali tipi di concessioni accettare e questo determinerà come l'utente procederà con l'integrazione della propria API.

Implementazione

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

Una libreria di esempi, illustra come eseguire l'autenticazione per ogni tipo di flusso. Ciascuno di questi metodi restituisce un oggetto che ottiene e memorizza il token di accesso e semplifica le richieste autenticate.

Il pattern 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 delle credenziali client

La concessione delle credenziali client è una delle forme più semplici del flusso OAuth2, in cui l'applicazione scambia un ID e un segreto, 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

Concessione del token di aggiornamento

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

Aggiorna token

Ottenere un token di aggiornamento

La differenza con la concessione del token di aggiornamento è che, mentre i dettagli richiesti per la concessione delle 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, ad esempio una concessione del codice di autorizzazione, che richiede l'interazione dell'utente:

Codice di autorizzazione

Utilizzare OAuth Playground per ottenere un token di aggiornamento

OAuth2 Playground fornisce un'interfaccia utente che consente all'utente di eseguire 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 di autorizzazione.
  • Endpoint token: utilizzato con il token di aggiornamento per ottenere un token di accesso.
  • ID client e secret: le credenziali per l'applicazione.

OAuth Playground

Utilizzo di uno script per ottenere un token di aggiornamento

Un'alternativa basata su script per completare il flusso è disponibile nel sample di generazione del token di aggiornamento.

Utilizzo del token di aggiornamento

Una volta eseguita l'autorizzazione iniziale, i servizi possono emettere un token di 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 report. Consulta il riferimento all'API Search Ads 360 per informazioni dettagliate sulle altre azioni che è possibile eseguire.

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

Esempio di API Apps Script Execution

Questo esempio illustra l'esecuzione di una funzione in Apps Script utilizzando l'API Apps Script Execution. In questo modo, Apps Script può essere chiamato dagli script Google Ads.

Creare uno script di Apps Script

Crea un nuovo script. Il seguente esempio elenca 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;
}
Configurare Apps Script per l'esecuzione
  1. Salva lo script.
  2. Fai clic su Risorse > Progetto piattaforma cloud.
  3. Fai clic sul nome del progetto per accedere alla console API.
  4. Vai ad API e servizi.
  5. Abilita le API appropriate, in questo caso l'API Drive e l'API di esecuzione di script di app.
  6. Crea le credenziali OAuth dall'elemento Credenziali del menu.
  7. Torna allo script e pubblicalo per l'esecuzione da Pubblica > Esegui il deployment come API eseguibile.
Creare lo script Google Ads
  1. Incolla lo script di esempio in un nuovo script in Google Ads.
  2. Incolla anche la libreria OAuth2 di esempio sotto la lista di codici.
  3. Modifica lo script in modo che contenga i valori corretti per l'ID client, il client secret e il token di aggiornamento.

Account di servizio

Un'alternativa ai tipi di concessione sopra indicati è il concetto di account di servizio.

Gli account di servizio sono diversi da quanto sopra indicato in quanto non vengono utilizzati per accedere ai dati degli utenti: dopo l'autenticazione, le richieste vengono effettuate dall'account di servizio per conto dell'applicazione, non come utente che potrebbe essere il proprietario del progetto. Ad esempio, se l'account di servizio utilizzasse l'API Drive per creare un file, questo appartenrebbe all'account di servizio e per impostazione predefinita non sarebbe accessibile al proprietario del progetto.

Esempio di API Natural Language di Google

L'API di linguaggio naturale fornisce analisi del sentiment e analisi delle entità per il testo.

Questo esempio illustra il calcolo del sentiment per il testo dell'annuncio, incluso il titolo o la descrizione. Questo fornisce una misura della positività e dell'intensità del messaggio: cosa è meglio, Veniamo torte o Veniamo le migliori torte di Londra. Acquista oggi!

Configurare lo script
  1. Crea un nuovo progetto nella Console API
  2. Attiva l'API Natural Language
  3. Abilita la fatturazione per il progetto.
  4. Crea un account di servizio. Scarica il file JSON delle credenziali.
  5. Incolla lo script di esempio in un nuovo script in Google Ads.
  6. Incolla anche la libreria OAuth2 di esempio sotto la lista di codici.
  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 dell'account di servizio. Inizia il giorno -----BEGIN PRIVATE KEY... e termina il giorno ...END PRIVATE KEY-----\n.

Risposte API

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

JSON

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

Convalida della risposta

Dopo aver ottenuto una risposta positiva dalla chiamata all'API, il tipico passaggio successivo consiste nell'utilizzare JSON.parse per convertire la stringa JSON in un oggetto JavaScript. A questo punto, è opportuno gestire il caso in cui l'analisi sintattica non va a buon fine:

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 tuo controllo, tieni presente che la struttura della risposta può 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 molto utilizzato per la creazione di API. Una risposta di una chiamata API puoi essere analizzata utilizzando il metodo XmlService parse.

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

Sebbene XmlService.parse rilevi gli errori nel codice XML e generi le relative eccezioni, non consente di convalidare il codice XML in base a uno schema.

Elemento principale

Se l'analisi del documento XML è andata a buon fine, l'elemento principale viene ottenuto utilizzando il metodo getRootElement():

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

Spazi dei nomi

Nell'esempio seguente, l'API Sportradar viene utilizzata per ottenere i risultati delle partite di calcio selezionate. La risposta XML ha il seguente formato:

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

Tieni presente come lo spazio dei nomi viene specificato nell'elemento principale. Per questo motivo, è necessario:

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

L'esempio seguente mostra come accedere all'elemento <matches> nello snippet di documento riportato sopra:

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 programma di calcio di esempio:

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

Gli attributi possono essere recuperati, ad esempio:

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

Il testo contenuto in un elemento può essere letto utilizzando getText(), ma verrà concatenato se sono presenti più elementi secondari di testo di un elemento. Valuta la possibilità di utilizzare getChildren() e di eseguire l'iterazione su ogni elemento secondario nei casi in cui è probabile che siano presenti più elementi secondari di testo.

Esempio di Sportradar

Questo esempio completo di Sportradar illustra il recupero dei dettagli delle partite di calcio, in particolare delle partite della Premier League inglese. L'API Soccer è uno dei numerosi 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 la registrazione, accedi al tuo account.
  4. Una volta eseguito l'accesso, vai a MyAccount.

Sportradar separa gli sport in API diverse. Ad esempio, potresti acquistare l'accesso all'API Soccer, ma non all'API Tennis. Ogni applicazione che crei può avere sport diversi associati e chiavi diverse.

  1. In Applicazioni, fai clic su Crea una nuova applicazione. Assegna all'applicazione un nome e una descrizione e ignora il campo del sito web.
  2. Seleziona solo Genera una nuova chiave per la versione 2 di Soccer Trial Europe.
  3. Fai clic su Registra applicazione.

Se l'operazione è andata a buon fine, dovresti visualizzare una pagina con la nuova chiave API.

  1. Incolla lo script di esempio in un nuovo script in Google Ads.
  2. Sostituisci la chiave API nella scheda con quella ottenuta sopra e modifica il campo dell'indirizzo email.

Risoluzione dei problemi

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

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

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

Analizza le risposte

Per impostazione predefinita, qualsiasi risposta che restituisce un errore (un codice stato pari o superiore a 400) verrà generata dal motore di script di Google Ads.

Per impedire questo comportamento e consentire l'ispezione dell'errore e del messaggio di errore, 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 il successo. Se la risposta non contiene i dati previsti, tieni presente che:

    • Alcune API consentono di specificare quali campi e/o formato di risposta utilizzare. Per informazioni dettagliate, consulta la documentazione dell'API.
    • Un'API può avere più risorse che possono essere chiamate. Consulta la documentazione per determinare se una risorsa diversa potrebbe essere più appropriata da utilizzare e restituire i dati richiesti.
    • L'API potrebbe essere cambiata da quando è stato scritto il codice. Per chiarimenti, consulta la documentazione o lo sviluppatore.

  • 400 Bad Request in genere significa che c'è qualcosa di errato nella formattazione o nella struttura della richiesta inviata al server. Controlla la richiesta e confrontala con le specifiche dell'API per assicurarti che sia conforme alle aspettative. Per informazioni su come esaminare le richieste, consulta Ispezione delle richieste.

  • 401 Unauthorized in genere indica che l'API viene chiamata senza fornire o eseguire correttamente l'autorizzazione.

    • Se l'API utilizza l'autorizzazione di base, assicurati che l'intestazione Authorization sia stata creata e fornita nella richiesta.
    • Se l'API utilizza OAuth 2.0, assicurati che il token di accesso sia stato ottenuto e fornito come token di accesso.
    • Per qualsiasi altra variazione dell'autorizzazione, assicurati che vengano fornite le credenziali necessarie 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 granting the user access to a file in a file-based request.

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

    • Verifica che l'URL utilizzato per l'endpoint API sia corretto.
    • Se ottieni una risorsa, verifica che esista la risorsa a cui fai riferimento (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 è sbagliata, ad esempio un codice di stato 400. Per facilitare l'esame delle richieste, UrlFetchApp ha un metodo complementare al metodo fetch(), chiamato getRequest()

Anziché inviare una richiesta al server, questo metodo costruisce la richiesta che avrebbe dovuto essere inviata e poi la restituisce. In questo modo l'utente può esaminare gli elementi della richiesta per verificare che sia corretta.

Ad esempio, se i dati del modulo nella richiesta sono costituiti da molte stringhe concatenate, l'errore potrebbe essere nella funzione che hai creato per generare i dati del modulo. In termini semplici:

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

ti consentirà di ispezionare gli elementi della richiesta.

Log delle richieste e delle risposte

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

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

  2. Aggiungi la seguente funzione 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 nella console, consentendo un debug più semplice.