Prima di mettere l’AI nel tuo foglio: imparare a chiamare un’API con UrlFetchApp

Il modo in cui le aziende italiane si stanno avvicinando all’AI sui fogli di lavoro è quasi sempre lo stesso: “come faccio a usare ChatGPT direttamente in Google Sheets?”. La risposta tecnica è in tre lettere: API. La risposta operativa è in una funzione di Apps Script che si chiama UrlFetchApp.fetch(). Capire come funziona è il prerequisito che apre la porta non solo all’AI, ma a qualsiasi servizio esterno: cambi valuta, geolocalizzazione, screenshot, invio SMS, anagrafiche IVA, meteo.

È più semplice di quanto sembri.

Il concetto in una frase

UrlFetchApp è la libreria di Apps Script che permette al tuo foglio di parlare con qualunque servizio web. Da Sheets parte una chiamata HTTP a un URL, il servizio risponde con dei dati (di solito JSON), tu li leggi e li scrivi nel foglio. Tutto qui. Una funzione, tre passaggi.

Esempio minimo: tassi di cambio in tempo reale

Partiamo da un’API gratuita e senza autenticazione: exchangerate.host. Restituisce i tassi di cambio. Una richiesta del tipo https://api.exchangerate.host/latest?base=EUR&symbols=USD ti torna la quotazione del dollaro contro l’euro.

In Apps Script diventa:

function cambioEurUsd() {
  const url = 'https://api.exchangerate.host/latest?base=EUR&symbols=USD';
  const risposta = UrlFetchApp.fetch(url);
  const dati = JSON.parse(risposta.getContentText());
  return dati.rates.USD;
}

Salvi la funzione, torni nel foglio, in una cella scrivi =cambioEurUsd(). La cella mostra il valore. Da quel momento puoi usarlo in qualsiasi formula come fosse un numero qualsiasi.

Tre righe di codice. Una funzione personalizzata che chiama un’API e restituisce un risultato.

I tre concetti che ti devono entrare in testa

1. La risposta è una stringa, non un oggetto. UrlFetchApp.fetch() restituisce un oggetto risposta. Il contenuto vero lo prendi con .getContentText() e ti torna una stringa. Per usarla come oggetto strutturato la passi a JSON.parse(). Questo è il pattern: fetch → getContentText → JSON.parse. Lo ripeterai sempre.

2. Gli scope OAuth. La prima volta che esegui una funzione che usa UrlFetchApp, Google ti chiede l’autorizzazione a fare chiamate esterne. È normale, devi accettare. In appsscript.json comparirà:

"oauthScopes": [
  "https://www.googleapis.com/auth/script.external_request"
]

Se condividi lo script con altri utenti, ognuno dovrà dare la stessa autorizzazione la prima volta.

3. Le quote. Apps Script permette 20.000 chiamate UrlFetchApp al giorno (50.000 su Workspace). Sembrano tante, ma se metti =cambioEurUsd() in 1000 celle e il foglio si ricalcola spesso, ci arrivi prima di pranzo. Per questo le funzioni personalizzate che chiamano API esterne vanno usate con criterio: meglio una chiamata in una cella, e poi usare quel valore con riferimenti, che non mille chiamate in mille celle.

Salire di livello: API con autenticazione

Le API più potenti chiedono una chiave (API key). Il pattern resta lo stesso, cambia solo che alla chiamata fetch aggiungi delle opzioni:

function chiamataConChiave() {
  const url = 'https://api.servizio-x.com/endpoint';
  const opzioni = {
    method: 'get',
    headers: {
      'Authorization': 'Bearer LA_TUA_CHIAVE_API',
      'Content-Type': 'application/json'
    },
    muteHttpExceptions: true
  };
  const risposta = UrlFetchApp.fetch(url, opzioni);
  return JSON.parse(risposta.getContentText());
}

Due dettagli importanti:

• non scrivere la chiave nel codice se condividi il foglio. Salvala con PropertiesService.getScriptProperties().setProperty('API_KEY', '...') e la rileggi con getProperty(). La chiave resta protetta, lo script funziona;
• muteHttpExceptions: true serve a evitare che lo script si interrompa al primo errore HTTP. Senza, una chiamata che torna 401 o 500 blocca l’esecuzione e perdi tutto il resto. Con muteHttpExceptions puoi leggere il codice di risposta con risposta.getResponseCode() e decidere cosa fare.

E adesso, l’AI

Una volta che UrlFetchApp ti è chiaro, chiamare OpenAI, Claude o Gemini è semplicemente una chiamata HTTP in più. Il pattern non cambia:

function chiediAClaude(prompt) {
  const apiKey = PropertiesService.getScriptProperties().getProperty('CLAUDE_KEY');
  const opzioni = {
    method: 'post',
    headers: {
      'x-api-key': apiKey,
      'anthropic-version': '2023-06-01',
      'Content-Type': 'application/json'
    },
    payload: JSON.stringify({
      model: 'claude-sonnet-4-6',
      max_tokens: 1024,
      messages: [{ role: 'user', content: prompt }]
    }),
    muteHttpExceptions: true
  };
  const risposta = UrlFetchApp.fetch('https://api.anthropic.com/v1/messages', opzioni);
  const dati = JSON.parse(risposta.getContentText());
  return dati.content[0].text;
}

In una cella: =chiediAClaude(A2). Nella colonna A le tue domande, nella colonna delle formule le risposte di Claude. Funziona davvero, ed è esattamente la stessa identica struttura del tasso di cambio.

Il punto da portare a casa

L’AI in Google Sheets non è una tecnologia a sé. È un caso particolare di una capacità più generale: chiamare un servizio web e usare la risposta nel foglio. Imparata quella, il giorno in cui esce un nuovo modello, un nuovo servizio, una nuova API, il codice è quasi pronto: cambi l’URL e i parametri.

UrlFetchApp è la chiave universale. L’AI è una delle stanze che apre, non l’unica.

Fausto Pitzalis

Blogger dal 2001, Nativo Digitale, Developer.
Da 15 anni mi occupo di IT per una grande Azienda.
Lavoro per abbattere il Digital Divide.
Visita i miei altri progetti
sardiniamobility.com
www.cyberness.it