Crea con Google Maps Platform e l'AI

1. Introduzione

Panoramica

Da dove si inizia oggi a creare con l'AI? Tutto inizia con una scintilla: un'idea che vale la pena prototipare. La modalità di creazione di Google AI Studio trasforma quella scintilla in realtà attraverso il "vibe coding". Sfruttando i modelli Gemini, puoi progettare, testare ed eseguire il deployment di applicazioni web full-stack interamente tramite la generazione di codice conversazionale.

In questo codelab, creerai Block Explorer, un gioco geospaziale interattivo che combina dati di mappatura del mondo reale con l'AI generativa. Utilizzerai AI Studio per generare l'applicazione e integrarla con Google Maps Platform e l'API Gemini. Dopodiché, imparerai a eseguire il deployment dell'applicazione completata direttamente in Cloud Run, rendendola disponibile per gli altri.

In questo lab proverai a:

• Utilizza Google AI Studio per prototipare un'applicazione web interattiva di mappatura e curiosità geospaziali.
• Attiva e esegui il provisioning automatico di una chiave demo di Google Maps Platform direttamente nello spazio di lavoro di AI Studio.
• Implementa il geocoding dinamico degli indirizzi, la scoperta di luoghi e quiz di curiosità creati con l'AI utilizzando prompt in linguaggio naturale.
• Migliora l'accuratezza del quiz di curiosità integrando Maps Grounding Lite.
• Testa l'applicazione e apporta modifiche iterative nella sandbox di anteprima interattiva.
• Esegui il deployment dell'applicazione su Cloud Run direttamente dall'interfaccia utente di Google AI Studio.

Obiettivi didattici

• Come utilizzare la modalità Build di Google AI Studio per creare rapidamente un prototipo di servizio full-stack utilizzando il linguaggio naturale.
• Come utilizzare le API di Google Maps Platform per creare applicazioni con dati geospaziali.
• Come basare i prompt LLM su un contesto geospaziale reale per generare quiz dinamici e approfondimenti locali.
• Come eseguire il deployment dell'applicazione AI Studio come container serverless su Cloud Run.

Ecco un'anteprima della pp:

2. Configura il progetto

Prima di lanciare AI Studio, verifica lo stato dell'account, i prerequisiti e l'accesso all'API.

Informazioni sull'Account Google e sul livello

1. Se non hai ancora un Account Google, creane uno.
   • Suggerimento: se possibile, utilizza un Account Google personale per questo lab. Gli account di gruppo, aziendali o scolastici potrebbero applicare criteri che disattivano le funzionalità sperimentali o le integrazioni cloud.
2. Esamina i dettagli di fatturazione per i deployment:
   • Google Cloud Starter Tier: consente di pubblicare fino a due applicazioni full-stack in una regione selezionata senza costi, senza creare un account di fatturazione Google Cloud completo.
   • Deployment standard: si connette a un progetto Google Cloud a pagamento esistente ed espande i limiti di archiviazione, le risorse CPU e le API.

Chiave demo di Google Maps Platform

Per semplificare la prototipazione, Google AI Studio si integra in modo nativo con Google Maps Platform. In questo modo, puoi testare e creare con le API principali di Google Maps Platform (come l'API Maps JavaScript, l'API Geocoding, l'API Places e l'API Routes) direttamente nel tuo progetto. AI Studio genererà automaticamente una chiave demo di Google Maps Platform per te.

Vantaggi principali della chiave demo:

• Nessuna carta di credito o configurazione di fatturazione richiesta: puoi creare prototipi e valutare immediatamente senza configurare un account di fatturazione Google Cloud.
• Quota di prototipazione generosa: include fino a 100 richieste senza costi al giorno per API per test e iterazioni.
• Integrazione integrata perfetta: non devi accedere a portali esterni o copiare e incollare le credenziali. Google AI Studio rileva automaticamente quando la tua applicazione deve integrarsi con Google Maps Platform e configura tutto per te.

3. Crea la shell dell'applicazione in modalità di creazione di AI Studio

Inizierai creando la shell dell'applicazione utilizzando Google AI Studio.

1. Vai al riquadro App di Google AI Studio e fai clic su Nuova app (o seleziona la scheda Crea).
2. Nella casella di immissione del prompt, inserisci la descrizione iniziale dell'applicazione geospaziale. Puoi anche fare clic sul chip di scoperta Google Maps Platform nei suggerimenti per i prompt:

Build a highly polished, responsive, split-screen application. This application should be called "Block Explorer". It is meant to be a geospatial exploration app. It will use Google Maps Platform.

Key Features & Functionality:

-   Split-Screen Layout: On desktop, a 1/3-width left-side editorial control panel and a 2/3-width right-side full-height map.
-   Include a search bar where users can type a location such as a city or neighborhood. Submitting should issue a Geocoding request to the Google Geocoding V4 API REST endpoint (https://geocode.googleapis.com/v4/geocode/address/). Then pan the map to the geocoded location.
-   Interactive Google Map: Render the Map inside an interactive container allowing users to pan, drag, and zoom freely. Place customized markers representing the currently selected/geocoded location.
-   Also include five buttons for presets the users can click on: Buenos Aires, Shibuya, Copacabana, Cologne, and Lima. Clicking on this should geocode the location and pan the map there.
-   Make sure to also include a mechanism to clearly show error messages when they occur so users can easily troubleshoot.

3. Fai clic su Crea per avviare il processo di generazione dell'applicazione.

AI Studio inizierà a generare il codice dell'applicazione. Se ti viene chiesto di scegliere un tema di design, seleziona lo stile che preferisci.

Abilitare Google Maps Platform e fornire la chiave demo

Google Maps Platform fornisce l'API Geocoding, che converte le query di indirizzi leggibili (ad esempio "Shibuya" o "Buenos Aires") in coordinate geografiche (latitudine e longitudine) per centrare le mappe e visualizzare i marker.

Quando invii un prompt con intento geospaziale (ad esempio richiedendo Google Maps, un localizzatore di negozi o l'esplorazione locale), AI Studio rileva automaticamente il requisito geospaziale e assiste con il provisioning delle chiavi:

1. Tendina di attivazione contestuale: nella conversazione viene visualizzata una scheda in linea intitolata "Configura Google Maps Platform".
2. Accetta i termini e attiva:
   • Leggi e accetta i Termini di servizio del progetto demo di Maps (e i Termini di servizio aggiuntivi di Starter Tier, se richiesto).
   • Fai clic su Attiva Google Maps.
3. Provisioning automatico delle chiavi e inserimento dei secret: AI Studio esegue automaticamente il provisioning di una chiave demo di Google Maps Platform nell'infrastruttura di Google Hosted Project (GHP) e la inserisce direttamente nei secret del tuo progetto con il nome GOOGLE_MAPS_PLATFORM_KEY.
4. Anteprima live istantanea: il sandbox di anteprima dell'applicazione viene aggiornato immediatamente con una mappa di Google interattiva, live e completamente funzionante.

Puoi anche attivare in modo proattivo Google Maps Platform tramite Impostazioni (icona a forma di ingranaggio) > scheda Integrazioni > Google Maps Platform oppure fornire la tua chiave API in Impostazioni > Secret se hai già un progetto cloud Google Cloud attivo. In alternativa, l'agente potrebbe chiederti una chiave API direttamente nella finestra di chat.

Prova l'applicazione nella sandbox di anteprima inserendo una nuova posizione o selezionando uno dei pulsanti delle posizioni preimpostate.

4. Aggiungere approfondimenti locali con l'API Gemini

Successivamente, integrerai l'API Gemini per generare approfondimenti ricchi e localizzati sui luoghi mentre gli utenti esplorano la mappa.

1. Invia il seguente prompt all'assistente AI nella finestra della chat:

Now, let's bring in the AI using the Gemini API.
1.  Once geocoding successfully identifies the City and State (e.g., "Miami, Florida"), trigger a call to the Gemini API (using the gemini-3.8-flash model).
2.  Use the following prompt template for the AI:
   "You are a local tour guide for [City, State]. Give me exactly 3 short, highly engaging, and unusual or surprising fun facts about this place. Keep each fact under 2 sentences. Format the response as a clean HTML unordered list (<ul>) so I can inject it directly."
3.  Display these fun facts in a beautiful "Local Insights" banner on the bottom portion of the map screen. Add a subtle loading spinner while the AI is thinking.
4.  Make sure to make this handling robust. If an API request fails, display a user-friendly error notification in the UI.

2. Verifica nel riquadro di anteprima che la selezione o la ricerca di una località mostri curiosità dinamiche generate da Gemini.

AI Studio aggiornerà l'applicazione e nella parte inferiore dello schermo verrà visualizzata la sezione "Approfondimenti locali".

5. Crea il quiz di cultura generale creato con l'AI

Ora che la tua applicazione recupera le coordinate della posizione e gli approfondimenti localizzati, combina queste funzionalità per generare quiz interattivi basati sulla destinazione selezionata.

1. Invia il prompt di generazione del quiz all'agente:

Now let's build the actual game! We will have Gemini generate a 3-question quiz based on the real places we just got information about.

After the local insights are generated, show the user a button to "Test their local knowledge". Once clicked, offer them 3 options to choose from:
-   Local cuisine
-   Art and culture
-   Local history

Once selected, generate a 3-question quiz based on the category and the place. The quiz should be multiple choice. Once the user submits the quiz show them their score and the correct answer.

2. Riproduci il quiz generato nella finestra di anteprima per testare la gestione dello stato, la selezione delle risposte e il rendering del punteggio.

6. Integrare Maps Grounding Lite

Per impostazione predefinita, Gemini genera fatti e quiz utilizzando le conoscenze dei dati di addestramento. Per migliorare l'accuratezza e sfruttare i dati spaziali in tempo reale, integra Maps Grounding Lite. Questo servizio collega Gemini ai dati in tempo reale direttamente da Google Maps Platform.

1. Invia il seguente prompt in AI Studio:

Add a toggle to make the quiz more difficult. Call this "Hyperlocal mode". When enabled, use the Google Maps Grounding Lite service with the Gemini API to fetch more local data, making the quiz more difficult.

Add information for the user so they know that Hyperlocal Mode is more difficult and how it works.

2. Prova il pulsante di attivazione/disattivazione della modalità iperlocale nella finestra di anteprima per verificare la generazione di quiz basati su dati reali.

I LLM possono avere allucinazioni su orari di apertura specifici, aperture recenti o ID luogo esatti. Maps Grounding Lite basa le risposte su entità e attribuzioni reali di Google Maps Places, migliorando significativamente l'accuratezza delle domande di cultura generale.

7. Esegui il deployment in Cloud Run

Una volta che il prototipo è completamente funzionante, esegui il deployment come contenitore serverless pubblico su Cloud Run direttamente da AI Studio.

1. Nell'angolo in alto a destra di Google AI Studio, fai clic sul pulsante Pubblica per avviare la procedura guidata per il deployment.
2. Fai clic su Inizia per configurare il progetto Google Cloud.
   • Verifica che il menu a discesa Progetto Google Cloud di destinazione corrisponda al progetto di deployment previsto.
   • AI Studio genererà automaticamente un identificatore di servizio univoco per l'istanza Cloud Run.
3. Fai clic su Pubblica app.
4. La creazione, la registrazione e il deployment del servizio del container verranno eseguiti in background. In genere, questa procedura viene completata in 2-4 minuti.
5. Al termine del deployment, copia l'URL dell'app generato e visita il link dell'applicazione live in una scheda del browser.

8. Rivedere le best practice per la sicurezza e la produzione

Quando esegui la transizione di questa app da un prototipo a un ambiente di produzione, tieni presente questi pilastri della sicurezza:

1. Limitazioni relative alle chiavi API di Google Maps

Non lasciare mai le chiavi API di Google Maps di produzione senza restrizioni. Nella console Google Cloud:

• Limitazioni API:limita la chiave in modo che possa chiamare solo API specifiche (API Maps JavaScript, API Geocoding, API Places).
• Restrizioni delle applicazioni:limita la chiave utilizzando i referrer HTTP (ad es. https://yourgame.com/*) per impedire l'utilizzo non autorizzato su siti di terze parti.

2. Protezione della chiave API Gemini

La chiave API Gemini non deve mai essere esposta in JavaScript lato client.

• Architettura di produzione:crea un servizio di backend leggero (ad es. Cloud Run o Cloud Functions) che funga da proxy. Il frontend chiama il backend (/api/get-fun-facts) e il backend comunica in modo sicuro con Google AI Studio utilizzando una variabile di ambiente (GEMINI_API_KEY).

9. Libera spazio

Per evitare addebiti imprevisti o liberare spazio nelle risorse dello spazio di lavoro:

1. In Google AI Studio, vai alla pagina App.
2. Trova la tua applicazione nella griglia o nell'elenco.
3. Fai clic sull'icona del cestino per eliminare lo stato dell'app e annullare la pubblicazione del servizio da Cloud Run.
4. Se hai eseguito il deployment utilizzando un progetto standard e vuoi arrestare completamente tutte le risorse, vai alle impostazioni del progetto Google Cloud Console ed elimina il progetto sottostante.

10. Conclusione

Complimenti! Hai progettato, sviluppato ed eseguito il deployment di un'applicazione web geospaziale basata sull'AI da Google AI Studio. Hai utilizzato correttamente le API di Google Maps Platform per creare un gioco interattivo basato su dati del mondo reale.

Visita questo link per ottenere il badge Percorso del Builder completato.

Per continuare il tuo percorso, vai alla pagina goo.gle/builders per il prossimo lab.

Scopri di più

• Documentazione di Google Maps Platform
• Documenti di Cloud Run
• Creare app in Google AI Studio