API di terza parte

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

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

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

Includiamo anche esempi per una serie di API popolari che illustrano questi concetti.

Recupera i dati con UrlFetchApp

UrlFetchApp fornisce la funzionalità di base necessaria per interagire con 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 si ottiene tramite la registrazione.

Dopo la registrazione, è possibile inviare una richiesta utilizzando la chiave come segue:

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 logging negli script Google Ads.

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

Dati JSON

Molte API forniscono risposte in formato JSON. Rappresenta una 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 integrato JSON.parse. Continuando con 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.

Per ulteriori dettagli sull'utilizzo delle risposte dell'API in formati diversi, consulta la sezione Analizza le risposte.

Gestione degli errori

La gestione degli errori è un aspetto importante da considerare quando utilizzi API di terze parti nei tuoi script, perché queste API 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

A causa della possibilità di risposte impreviste, devi ispezionare il codice di stato HTTP. Per impostazione predefinita, UrlFetchApp genera un'eccezione se viene rilevato un 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, potresti non essere immediatamente a conoscenza di modifiche che potrebbero influire sui tuoi script. Ad esempio, se la proprietà name restituita nell'esempio di OpenWeatherMap viene modificata in locationName, gli script che utilizzano questa proprietà non funzioneranno.

Per questo motivo, può essere utile verificare se la struttura restituita è quella prevista, 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 ha recuperato 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 quelle a un servizio che invia SMS, richiedono altri metodi, come POST o PUT.

Per illustrare l'utilizzo delle chiamate POST con UrlFetchApp, l'esempio seguente mostra 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à creato 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 entrata facendo clic su Aggiungi integrazione webhook in entrata e seguendo le istruzioni. Il processo dovrebbe generare un URL da utilizzare per la messaggistica.

Invia una richiesta POST

Dopo aver configurato il webhook in entrata, per effettuare una richiesta POST è necessario 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: 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. A questo scopo, viene utilizzato il metodo [JSON.stringify][json-stringify-url] 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 precedente mostra il codice minimo necessario per abilitare i messaggi in arrivo in Slack. Un esempio esteso 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 Slack, consulta la sezione sulla formattazione dei messaggi nella documentazione di Slack.

Dati modulo

L'esempio precedente mostrava 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 della 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!
    

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

Alcune API richiedono l'utilizzo di dati dei moduli per l'invio di richieste POST, quindi è utile tenere presente questa conversione automatica da oggetti JavaScript a dati dei moduli.

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 allegando 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. Crea la passphrase unendo il nome utente e la password con i due punti, ad esempio username:password.
  2. Codifica la passphrase in Base64, ad esempio username:password diventa dXNlcm5hbWU6cGFzc3dvcmQ=.
  3. Collega un'intestazione Authorization alla richiesta, nel formato 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

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 SMS con la relativa 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 sia il numero del destinatario.
  7. Aggiorna PLIVO_SRC_PHONE_NUMBER nello script con uno dei numeri di sandbox appena registrati. Deve includere il prefisso 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 con la sua API. Questo esempio illustra l'invio di messaggi.

  1. Registrati con 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 mostrati nella pagina della console dell'account.
  4. Sostituisci TWILIO_SRC_PHONE_NUMBER con il numero della 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 alle applicazioni di terze parti di accedere all'account e ai dati di un utente utilizzando credenziali specifiche per l'applicazione di terze parti. Inoltre, l'estensione dell'accesso sarà specifica per l'applicazione.

Per informazioni di base su OAuth 1.0, consulta la guida di OAuth Core. In particolare, consulta la sezione 6. Autenticazione con OAuth. In OAuth 1.0 a tre vie completo, il processo è il 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 una richiesta firmata.

Affinché i servizi di terze parti utilizzino OAuth 1.0 senza interazione dell'utente (ad esempio, come richiesto dagli 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 è noto come OAuth 1.0 a una gamba.

OAuth1

OAuth 1.0 negli script Google Ads

Per gli script Google Ads, ogni script viene solitamente interpretato come un'applicazione. Tramite la console o la pagina delle impostazioni di amministrazione del servizio, di solito è necessario:

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

OAuth 2.0

OAuth 2.0 viene 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. I vantaggi sono che il proprietario:

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

Per utilizzare i servizi abilitati per OAuth 2.0 negli script Google Ads, segui questi passaggi:

Al di fuori dello script

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

Specifica i diritti di accesso da concedere all'applicazione degli script Google Ads, a cui di solito viene assegnato un ID cliente. In questo modo, tramite OAuth 2.0, puoi controllare quali applicazioni hanno accesso ai tuoi dati nel servizio di terze parti e quali aspetti di questi dati possono visualizzare o modificare.

Nello script

Autorizza con il server remoto. A seconda del grant type consentito dal server, sarà necessario seguire una serie di passaggi diversi, nota come flusso, ma tutti porteranno infine all'emissione di un token di accesso che verrà utilizzato per la sessione per tutte le richieste successive.

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

Flussi di autorizzazione

Ogni grant type 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 un'applicazione deve essere eseguita in background senza la presenza di un utente.

I provider di API decideranno quali grant type accettare e questo guiderà il modo in cui l'utente procede con l'integrazione della propria API.

Implementazione

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

Una libreria di esempio, che illustra come eseguire l'autenticazione per ogni tipo di flusso. Ognuno di questi metodi restituisce un oggetto che ottiene e archivia il token di accesso e facilita 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][client-credentials-rfc] è 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

Concessione del token di aggiornamento

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

Token di aggiornamento

Ottieni un token di aggiornamento

La differenza con la concessione del token di aggiornamento è che, mentre i dettagli richiesti per una 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 una [concessione del codice di autorizzazione][authorization-code-rfc], che richiederà l'interazione dell'utente:

Codice di autorizzazione

Utilizzo di OAuth Playground per ottenere un token di aggiornamento

OAuth2 Playground fornisce un'interfaccia utente che consente all'utente di eseguire i passaggi della 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: credenziali per l'applicazione.

    OAuth Playground

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:

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 il Riferimento API Search Ads 360.

Crea lo script
  1. Crea un nuovo progetto nella console Google Cloud e ottieni un ID client, un client secret e un token di aggiornamento seguendo la procedura descritta nella guida di Search Ads 360, assicurandoti di attivare l'API Search Ads 360.
  2. Incolla lo [script di esempio][search-ads-360-example] in un nuovo script in Google Ads.
  3. Incolla la [libreria OAuth2 di esempio][oauth20-library-example] 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 puoi chiamare Apps Script dagli script Google Ads.

Crea uno script Apps Script

Crea un nuovo script. L'esempio seguente elenca 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 della piattaforma Cloud.
  3. Fai clic sul nome del progetto per accedere alla console Google Cloud.
  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 del menu.
  7. Torna allo script e pubblicalo per l'esecuzione da Pubblica > Esegui il deployment come eseguibile API.
Crea 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][oauth20-library-example] sotto l'elenco di codici.
  3. Modifica lo script in modo che contenga i valori corretti per ID client, client secret e token di aggiornamento.

Service account

Un'alternativa ai grant type è il concetto di service account.

I service account differiscono dai grant type in quanto non vengono utilizzati per accedere ai dati utente: dopo l'autenticazione, le richieste vengono effettuate dal service account per conto dell'applicazione, non come l'utente che potrebbe essere proprietario del progetto. Ad esempio, se il service account dovesse utilizzare l'API Drive per creare un file, questo apparterrebbe al service account e, per impostazione predefinita, non sarebbe accessibile al proprietario del progetto.

Esempio di API Google Natural Language

L'[API Natural Language][natural-language-api-docs] fornisce [analisi del sentiment][sentiment-analysis-api-docs] e [analisi delle entità][entity-analysis-api-docs] per il testo.

Questo esempio illustra il calcolo del [sentiment][sentiment-api-docs] per il testo dell'annuncio, inclusi il titolo o la descrizione. In questo modo, viene fornita una misura della positività e della portata del messaggio: qual è il migliore tra Vendiamo torte o Vendiamo le migliori torte di Londra? Acquista oggi stesso.

Configura lo script
  1. Crea un nuovo progetto nella console Google Cloud.
  2. Abilita l'[API Natural Language][natural-language-api].
  3. Abilita la fatturazione per il progetto.
  4. [Crea un service account][create-service-account]. Scarica il file JSON delle credenziali.
  5. Incolla lo [script di esempio][natural-language-example] in un nuovo script in Google Ads.
  6. Inoltre, incolla la [libreria OAuth2 di esempio][oauth20-library-example] sotto l'elenco di codici.
  7. Sostituisci i valori necessari:
    • serviceAccount: l'indirizzo email del service account, ad esempio xxxxx@yyyy.iam.gserviceaccount.com.
    • key: la chiave del file JSON scaricato durante la creazione del service account. Inizia il giorno -----BEGIN PRIVATE KEY... e termina il giorno ...END PRIVATE KEY-----\n.

Risposte dell'API

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

JSON

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

Convalida della risposta

Dopo aver ricevuto una risposta positiva dalla chiamata all'API, il passaggio successivo tipico è utilizzare JSON.parse per convertire la stringa JSON in un oggetto JavaScript. A questo punto, è opportuno gestire il caso in cui l'analisi non vada 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 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

XmlService consente agli script di analizzare ed estrarre i dati dai corpi delle risposte XML.

Convalida

XML è ancora un formato molto utilizzato per la creazione di API. Una risposta da una chiamata API può essere analizzata utilizzando il metodo parse di XmlService:

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 file XML e generi eccezioni di conseguenza, non offre la possibilità di convalidare il file XML rispetto a uno schema.

Elemento root

Se l'analisi del documento XML va a buon fine, l'elemento root 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 di calcio per le partite selezionate. La risposta XML ha il seguente formato:

<schedule_schedules xmlns="http://schemas.sportradar.com/sportsapi/soccer/v4">
  <schedule>
     ...
  </schedule>
</schedule_schedules>

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

  • 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 <schedule> e cercare i relativi elementi secondari <sport_event> nello snippet di documento precedente:

const document = XmlService.parse(xmlText);
const rootElement = document.getRootElement();
// The namespace is required for accessing child elements in the schema.
const namespace = rootElement.getNamespace();
const scheduleElement = rootElement.getChild('schedule', namespace);
const sportEvents = scheduleElement.getChildren('sport_event', namespace);

Ottieni valori

Considerando l'esempio del programma di calcio:

<sport_event_status status="..." ... />

Gli attributi possono essere recuperati, ad esempio:

const statusElement = sportEventElement.getChild('sport_event_status', namespace);
const status = statusElement.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 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 un account di prova.
  3. Dopo aver effettuato la registrazione, accedi al tuo account.
  4. Una volta eseguito l'accesso, vai a Il mio account.

Sportradar separa i diversi 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 e chiavi diversi associati.

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

Se l'operazione va a buon fine, dovrebbe essere visualizzata 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 la chiave appena emessa e modifica il campo dell'indirizzo email.

Risoluzione dei problemi

Quando si lavora con API di terze parti, possono verificarsi errori per una serie di 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.
  • Client 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 di stato pari o superiore a 400) verrà generata dal motore degli script Google Ads.

Per evitare 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 che l'operazione è riuscita. Se la risposta non contiene i dati previsti, tieni presente che:

    • Alcune API consentono di specificare quali campi, formato di risposta o entrambi utilizzare. Per maggiori dettagli, consulta la documentazione dell'API.
    • Un'API può avere più risorse che possono essere chiamate. Consulta la documentazione per determinare se è più appropriato utilizzare una risorsa diversa che restituisca i dati richiesti.
    • L'API potrebbe essere cambiata da quando è stato scritto il codice. Per chiarimenti, consulta la documentazione o rivolgiti allo sviluppatore.
  • 400 Bad Request in genere indica che qualcosa non va nella formattazione o nella struttura della richiesta inviata al server. Esamina la richiesta e confrontala con le specifiche dell'API per assicurarti che sia conforme alle aspettative. Per informazioni dettagliate su come esaminare le richieste, consulta Esamina le 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 venga fornito come token di connessione.
    • 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 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 viene fatto 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 è formattata correttamente, ad esempio un codice di stato 400. Per facilitare l'esame delle richieste, UrlFetchApp ha un metodo complementare al metodo fetch(), chiamato getRequest(url, params)

Anziché inviare una richiesta al server, questo metodo crea la richiesta che sarebbe stata inviata e la restituisce. In questo modo l'utente può ispezionare gli elementi della richiesta per assicurarsi che sia corretta.

Ad esempio, se i dati del modulo nella richiesta sono costituiti da molte stringhe concatenate, l'errore potrebbe risiedere nella funzione che hai creato per generare i dati del modulo. Nella sua forma più semplice:

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.

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 sostituto diretto 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 le risposte vengono registrati nella console, semplificando il debug.

[json-stringify-url]: //developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify [client-credentials-rfc]: //datatracker.ietf.org/doc/html/rfc6749#section-4.4 [authorization-code-rfc]: //datatracker.ietf.org/doc/html/rfc6749#section-1.3.1 [oauth20-library-example]: /google-ads/scripts/docs/examples/oauth20-library [search-ads-360-example]: /google-ads/scripts/docs/examples/search-ads-360 [natural-language-api]: //console.developers.google.com/apis/api/language.googleapis.com/overview [create-service-account]: //console.developers.google.com/apis/credentials/serviceaccountkey [natural-language-example]: /google-ads/scripts/docs/examples/natural-language [natural-language-api-docs]: //cloud.google.com/natural-language/docs/ [sentiment-api-docs]: //cloud.google.com/natural-language/docs/reference/rest/v1beta2/Sentiment [sentiment-analysis-api-docs]: //cloud.google.com/natural-language/docs/analyzing-sentiment [entity-analysis-api-docs]: //cloud.google.com/natural-language/docs/analyzing-entities