API di terza parte

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

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

  • Esecuzione 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.

Recupera i dati con UrlFetchApp

UrlFetchApp fornisce la funzionalità di base necessaria 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 per l'API relativamente semplici.

Fai una richiesta

La documentazione di OpenWeatherMap specifica il formato per la richiesta del 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 si ottiene mediante 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 testo JSON scritto nella finestra di logging degli script Google Ads.

Il passaggio successivo consiste nel convertirlo in un formato utilizzabile all'interno dello script.

Dati JSON

Molte API forniscono risposte in formato JSON. Rappresenta una semplice serializzazione degli 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, di nuovo in un oggetto JavaScript, utilizza il metodo JSON.parse integrato. Continuando 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, che ha una proprietà name.

Consulta la sezione Analizza le risposte per ulteriori dettagli sull'utilizzo delle 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 spesso cambiano spesso e generano valori di risposta imprevisti, ad esempio:

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

Codici di stato HTTP

A causa della possibilità che si verifichino risposte impreviste, devi controllare il codice di stato HTTP. Per impostazione predefinita, UrlFetchApp genera un'eccezione in caso di codice di errore HTTP. Per 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, gli sviluppatori spesso non sono immediatamente a conoscenza delle modifiche che potrebbero influire sui loro script. Ad esempio, se la proprietà name restituita nell'esempio OpenWeatherMap viene modificata in locationName, gli script che utilizzano questa proprietà avranno esito negativo.

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

Dati POST con UrlFetchApp

L'esempio introduttivo con OpenWeatherMap solo ai dati recuperati. In genere, per le chiamate API che non cambiano stato sul server remoto viene usato il metodo HTTP GET.

Il metodo GET è il metodo predefinito per UrlFetchApp. Tuttavia, alcune chiamate API, ad esempio le chiamate a un servizio che invia SMS, richiederanno altri metodi, ad esempio POST o PUT.

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

Configura Slack

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

Come per OpenWeatherMap nell'esempio precedente, è necessario ottenere un token per abilitare l'invio di messaggi. Slack fornisce un URL univoco per consentirti di inviare messaggi al tuo team, chiamato Webhook in entrata.

Configura un webhook in arrivo facendo clic su Aggiungi integrazione webhook in entrata e seguendo le istruzioni. Il processo dovrebbe generare un URL da utilizzare per i messaggi.

Fai una richiesta POST

Dopo aver configurato il webhook in arrivo, 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: questi sono i dati da inviare al server nell'ambito della richiesta POST. In questo esempio, Slack prevede un oggetto serializzato in formato JSON come descritto nella documentazione di Slack. Per farlo, viene utilizzato il metodo 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 il valore minimo per abilitare i messaggi in arrivo in Slack. Un campione esteso illustra la creazione e l'invio di un report sul rendimento delle campagne a un gruppo, nonché alcune opzioni di formattazione e visualizzazione.

Messaggio in arrivo

Per ulteriori dettagli sui messaggi Slack, vedi Formattazione dei messaggi nella documentazione di Slack.

Dati modulo

L'esempio precedente ha mostrato 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 del 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'utilizzo dei dati dei moduli per l'invio di richieste POST, pertanto è utile tenere presente questa conversione automatica da oggetti JavaScript in dati del modulo.

Autenticazione HTTP di base

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

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

Autenticazione HTTP di base

Crea una richiesta

Per produrre una richiesta autenticata sono necessari i seguenti passaggi:

  1. Per creare la passphrase, unisci nome utente e password con i due punti, ad esempio username:password.
  2. Codifica in Base64 la passphrase, ad esempio username:password diventa dXNlcm5hbWU6cGFzc3dvcmQ=.
  3. Allega un'intestazione Authorization alla richiesta nel modulo Authorization: Basic <encoded passphrase>

Lo snippet seguente 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);

Plivo

Plivo è un servizio che facilita l'invio e la ricezione di 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 i valori 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 aggiungere numeri all'account di prova. Aggiungi numeri Sandbox che possono essere utilizzati con l'account di prova.
  6. Aggiungi sia il numero che verrà visualizzato come mittente e il numero del destinatario.
  7. Aggiorna PLIVO_SRC_PHONE_NUMBER nello script con uno dei numeri 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 SMS tramite la propria API. Questo esempio illustra l'invio di messaggi.

  1. Registrati presso 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 i valori visualizzati nella pagina della console dell'account.
  4. Sostituisci TWILIO_SRC_PHONE_NUMBER con il numero della dashboard, che corrisponde al numero autorizzato da Twilio a inviare messaggi.

OAuth 1.0

Molti servizi tra i più diffusi utilizzano OAuth per l'autenticazione. OAuth è disponibile in diversi tipi 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 terze parti di accedere all'account e ai dati di un utente utilizzando credenziali specifiche dell'applicazione di terze parti. Inoltre, anche l'estensione dell'accesso sarà specifica per tale applicazione.

Per informazioni su OAuth 1.0, consulta la guida OAuth Core. In particolare, vedi 6. Autenticazione con OAuth. Nel protocollo OAuth 1.0 a tre vie completo, il processo è il seguente:

  1. L'applicazione ("Consumer") riceve 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 successive richieste di risorse, 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 perché 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 andare direttamente al passaggio 4. Questo protocollo è noto come OAuth 1.0 a una vie.

OAuth1

OAuth 1.0 negli script Google Ads

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

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

OAuth 2.0

OAuth 2.0 è utilizzato nelle API più diffuse per fornire l'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. Il vantaggio è che il proprietario:

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

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

Al di fuori dello script

Concedi agli script Google Ads l'autorizzazione ad accedere ai dati utente tramite l'API di terze parti. Nella maggior parte dei casi, questa operazione comporta la configurazione di un'applicazione nella console del servizio di terze parti. Questa applicazione rappresenta il tuo script Google Ads.

Sei tu a specificare i diritti di accesso che deve ricevere l'applicazione Google Ads Script e in genere gli viene 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 dei dati possono essere visualizzati o modificati.

Nel tuo script

Autorizza con il server remoto. A seconda del tipo di autorizzazione consentito dal server, sarà necessario seguire una serie di passaggi diversa, nota come flusso, ma la procedura comporterà l'emissione di un token di accesso che verrà utilizzato per la sessione in questione per tutte le richieste successive.

Effettua richieste API. Passare il token di accesso per ogni richiesta.

Flussi di autorizzazione

Ogni tipo di autorizzazione e il flusso corrispondente si rivolgono a diversi scenari di utilizzo. Ad esempio, viene utilizzato un flusso diverso quando un utente partecipa a una sessione interattiva, a differenza di uno scenario in cui un'applicazione deve essere eseguita in background in assenza di un utente.

I provider di API decideranno quali tipi di concessioni accettare e questo indicherà il modo in cui l'utente procede con l'integrazione dell'API.

Implementazione

Per tutti i diversi flussi OAuth, l'obiettivo è ottenere un token di accesso che possa essere utilizzato per il resto della sessione per autenticare le richieste.

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

Lo schema di utilizzo generale è il seguente:

// 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 di flusso OAuth2, in cui l'applicazione scambia un ID e un 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 client, in quanto una semplice richiesta al server restituisce 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, come la concessione del codice di autorizzazione, che richiede l'interazione dell'utente:

Codice di autorizzazione

Utilizzare OAuth Playground per ottenere un token di aggiornamento

L'ambiente OAuth2 fornisce una UI che consente all'utente di eseguire la concessione del codice di autorizzazione per ottenere un token di aggiornamento.

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

  • Endpoint di autorizzazione: utilizzato come avvio del flusso per l'autorizzazione.
  • Endpoint del token: utilizzato con il token di aggiornamento per ottenere un token di accesso.
  • client ID and secret: le 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 nell'esempio di generazione di token di aggiornamento.

Aggiorna utilizzo dei token

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. Per informazioni dettagliate sulle altre azioni che possono essere eseguite, consulta la documentazione di riferimento sull'API Search Ads 360.

Crea lo script
  1. Crea un nuovo progetto nella console API e recupera un ID client, un client secret e un token di aggiornamento seguendo la procedura nella guida di DoubleClick, assicurandoti di abilitare 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 l'elenco di codici.
  4. Modifica lo script in modo che contenga i valori corretti per ID client, client secret e 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 è possibile chiamare Apps Script da Google Ads Script.

Creare uno script Apps Script

Crea un nuovo script. Il seguente esempio elencherà 10 file di 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 Apps Script per l'esecuzione
  1. Salva lo script.
  2. Fai clic su Risorse > Progetto Cloud Platform.
  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 Apps Script Execution.
  6. Crea le credenziali OAuth dalla voce Credenziali nel menu.
  7. Torna allo script, pubblica lo script per l'esecuzione da Pubblica > Implementa come eseguibile API.
Creare lo script Google Ads
  1. Incolla lo script di esempio in un nuovo script in Google Ads.
  2. Inoltre, incolla la libreria OAuth2 di esempio sotto l'elenco dei codici.
  3. Modifica lo script in modo che contenga i valori corretti per ID client, client secret e token di aggiornamento.

Account di servizio

Un'alternativa ai tipi di concessioni precedenti è il concetto degli account di servizio.

Gli account di servizio differiscono da quelli precedenti in quanto non vengono utilizzati per accedere ai dati utente: dopo l'autenticazione, le richieste vengono effettuate dall'account di servizio per conto dell'applicazione e non come utente che potrebbe essere proprietario del progetto. Ad esempio, se l'account di servizio utilizzasse l'API Drive per creare un file, quest'ultimo apparerebbe all'account di servizio e, per impostazione predefinita, non sarebbe accessibile al proprietario del progetto.

Esempio di API Natural Language di Google

L'API Natural Language fornisce analisi del sentiment e analisi delle entità per il testo.

Questo esempio illustra il calcolo del sentimento per il testo dell'annuncio, inclusi il titolo o la descrizione. Ciò consente di misurare il livello di positività del messaggio e l'entità del messaggio: "Vendiamo torte di più", Vendiamo torte o Vendiamo le migliori torte di Londra. Acquista oggi!?

Configura lo script
  1. Crea un nuovo progetto nella console API
  2. Abilita l'API Natural Language.
  3. Abilitare 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. Inoltre, incolla la libreria OAuth2 di esempio sotto l'elenco dei 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 dati in diversi formati. I più importanti sono XML e JSON.

JSON

Di solito, JSON è più semplice rispetto a XML e utilizzalo come formato di risposta. Tuttavia, possono comunque presentarsi alcuni problemi.

Convalida della risposta

Dopo aver ottenuto una risposta riuscita dalla chiamata all'API, il passaggio successivo in genere è utilizzare JSON.parse per convertire la stringa JSON in un oggetto JavaScript. A questo punto, è opportuno gestire il caso in cui l'analisi non riesce:

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 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. La risposta di una chiamata API può 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.
}

Anche se XmlService.parse rileva errori nel file XML e genera le eccezioni di conseguenza, non offre la possibilità di convalidare il codice XML in base a uno schema.

Elemento radice

Se il documento XML viene analizzato correttamente, l'elemento radice viene ottenuto con il metodo getRootElement():

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

Spazi dei nomi

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

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

Nota come lo spazio dei nomi è specificato nell'elemento principale. Per questo è necessario:

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

Il seguente esempio mostra come accedere all'elemento <matches> nello snippet 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 l'esempio 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 vengono concatenati quando sono presenti più elementi secondari di testo di un elemento. Prendi in considerazione l'uso di getChildren() e l'iterazione per ciascun bambino nei casi in cui è probabile che ci siano più bambini con testo.

Esempio di Sportradar

Questo esempio di Sportradar completo illustra il recupero dei dettagli delle partite di calcio, in particolare quelle della Premier League inglese. L'API Soccer è uno dei numerosi feed sportivi offerti da Sportradar.

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

Sportradar separa sport diversi in diverse API. Ad esempio, puoi acquistare l'accesso all'API Soccer, ma non all'API Tennis. A ogni applicazione che crei possono essere associati diversi sport e chiavi diverse.

  1. In Applicazioni, fai clic su Create a new Application (Crea una nuova applicazione). Assegna all'applicazione un nome e una descrizione e ignora il campo del sito web.
  2. Seleziona solo l'opzione Rilascia una nuova chiave per Soccer Trial Europe v2.
  3. Fai clic su Registra domanda.

Se l'operazione va a buon fine, dovrebbe apparire 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 nell'elenco con la chiave ottenuta in precedenza e modifica il campo dell'indirizzo email.

Risolvere i problemi

Lavorando con API di terze parti, gli errori possono verificarsi 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 incontrato.
  • Client che utilizzano token o chiavi non validi oppure valori lasciati come segnaposto.
  • Client che raggiungono i limiti di utilizzo.
  • Client che forniscono parametri non validi.

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

Analizza le risposte

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

Per evitare questo comportamento e per 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 un successo. Se la risposta non contiene i dati previsti, tieni presente che:

    • Alcune API consentono di specificare i campi e/o il formato di risposta da utilizzare. Per ulteriori dettagli, consulta la documentazione dell'API.
    • Un'API può avere più risorse che è possibile chiamare. Consulta la documentazione per determinare se un'altra risorsa potrebbe essere più appropriata da usare e restituirà 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 indica in genere che qualcosa non è corretto nella formattazione o nella struttura della richiesta inviata al server. Ispeziona la richiesta e confrontala con le specifiche dell'API per assicurarti che sia conforme alle aspettative. Per ulteriori dettagli su come esaminare le richieste, consulta Controllo delle richieste.

  • 401 Unauthorized di solito significa 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 venga creata e fornita nella richiesta.
    • Se l'API utilizza OAuth 2.0, assicurati che il token di accesso sia stato ottenuto e che venga fornito come token Bearer.
    • 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 concedendo all'utente l'accesso a un file in una richiesta basata su file.

  • 404 Not Found significa 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 fai riferimento esista (ad esempio, se il file esiste per un'API basata su file).

Esaminare le richieste

L'ispezione delle richieste è utile quando le risposte dell'API indicano che la richiesta non è formattata correttamente, ad esempio con un codice di stato 400. Per semplificare l'esame delle richieste, UrlFetchApp ha un metodo complementare al metodo fetch(), chiamato getRequest()

Anziché inviare una richiesta al server, questo metodo crea la richiesta che sarebbe stata inviata e poi la restituisce. Ciò consente all'utente di controllare gli elementi della richiesta per assicurarsi che sembri corretta.

Ad esempio, se i dati del modulo nella richiesta sono costituiti da molte stringhe concatenate, l'errore potrebbe risiedere nella funzione creata per generare i dati del modulo. Nel modo più semplice:

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

ti consentirà di esaminare gli elementi della richiesta.

Registra richieste e risposte

Per facilitare l'intero processo di ispezione delle richieste e delle risposte a un'API di terze parti, la seguente funzione helper può essere utilizzata come sostituzione diretta di UrlFetchApp.fetch(), per registrare sia le richieste che 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 risposte vengono registrati nella console, consentendo il debug più semplice.