Crie com a Plataforma Google Maps e a IA

1. Introdução

Visão geral

Onde começa a criação com IA hoje? Tudo começa com uma faísca: uma ideia que vale a pena prototipar. O modo de criação do Google AI Studio transforma essa ideia em realidade com a "vibe coding". Ao aproveitar os modelos do Gemini, você pode projetar, testar e implantar aplicativos da Web de pilha completa totalmente por meio da geração de código conversacional.

Neste codelab, você vai criar o Block Explorer, um jogo geoespacial interativo que combina dados de mapeamento do mundo real com a IA generativa. Você vai usar o AI Studio para gerar o aplicativo e integrá-lo à Plataforma Google Maps e à API Gemini. Em seguida, você vai aprender a implantar o aplicativo concluído diretamente no Cloud Run, disponibilizando-o para outras pessoas testarem.

Atividades deste laboratório

• Use o Google AI Studio para criar um protótipo de um aplicativo da Web interativo de trivia e mapeamento geoespacial.
• Ative e provisione automaticamente uma chave de demonstração da Plataforma Google Maps diretamente no espaço de trabalho do AI Studio.
• Implemente a geocodificação dinâmica de endereços, a descoberta de lugares e os quizzes de curiosidades gerados com IA usando comandos de linguagem natural.
• Aumente a precisão do quiz de curiosidades integrando o Maps Grounding Lite.
• Teste e faça iterações no aplicativo no sandbox de prévia interativa.
• Implante o aplicativo no Cloud Run diretamente da interface do Google AI Studio.

O que você vai aprender

• Como usar o modo de criação do Google AI Studio para prototipar rapidamente um serviço de pilha completa usando linguagem natural.
• Como usar as APIs da Plataforma Google Maps para criar aplicativos com dados geoespaciais.
• Como embasar comandos do LLM com contexto geoespacial do mundo real para gerar testes dinâmicos e insights locais.
• Como implantar seu aplicativo do AI Studio como um contêiner sem servidor no Cloud Run.

Confira uma prévia da pp:

2. Criar o projeto

Antes de iniciar o AI Studio, verifique o status da sua conta, os pré-requisitos e o acesso à API.

Informações da Conta do Google e do nível

1. Se você ainda não tiver uma, crie uma Conta do Google.
   • Dica: use uma Conta do Google pessoal para este laboratório, se possível. As contas de grupo, corporativas ou escolares podem aplicar políticas que desativam recursos experimentais ou integrações na nuvem.
2. Revise os detalhes de faturamento das implantações:
   • Nível Starter do Google Cloud: permite publicar até dois aplicativos full-stack em uma região selecionada sem custo financeiro e sem estabelecer uma conta de faturamento completa do Google Cloud.
   • Implantação padrão: conecta-se a um projeto pago do Google Cloud e aumenta os limites de armazenamento, os recursos de CPU e as APIs.

Chave de demonstração da Plataforma Google Maps

Para simplificar a criação de protótipos, o Google AI Studio se integra de forma nativa à Plataforma Google Maps. Essa é uma maneira simples de testar e criar com as principais APIs da Plataforma Google Maps (como as APIs Maps JavaScript, Geocoding, Places e Routes) diretamente no seu projeto. O AI Studio vai gerar automaticamente uma chave de demonstração da Plataforma Google Maps para você.

Principais benefícios da chave de demonstração:

• Não é necessário cartão de crédito nem configuração de faturamento: você pode prototipar e avaliar imediatamente sem configurar uma conta de faturamento do Google Cloud.
• Cota generosa de prototipagem: inclui até 100 solicitações sem custo financeiro por dia e por API para testes e iteração.
• Integração integrada perfeita: não é necessário navegar até portais externos nem copiar e colar credenciais. O Google AI Studio detecta automaticamente quando seu aplicativo precisa ser integrado à Plataforma Google Maps e faz a configuração para você.

3. Criar o shell do aplicativo no modo de build do AI Studio

Você vai começar criando o shell do aplicativo usando o Google AI Studio.

1. Acesse o painel de apps do Google AI Studio e clique em Novo app ou selecione a guia Criar.
2. Na caixa de entrada de comandos, insira a descrição inicial do seu aplicativo geoespacial. Você também pode clicar no ícone de descoberta da Plataforma Google Maps nas sugestões de comandos:

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. Clique em Build para iniciar o processo de geração do aplicativo.

O AI Studio vai começar a gerar o código do aplicativo. Se for solicitado a escolher um tema de design, selecione o estilo que preferir.

Ativar a Plataforma Google Maps e provisionar uma chave de demonstração

A Plataforma Google Maps oferece a API Geocoding, que converte consultas de endereço legíveis (como "Shibuya" ou "Buenos Aires") em coordenadas geográficas (latitude e longitude) para centralizar mapas e mostrar marcadores.

Quando você envia um comando com intenção geoespacial (como solicitar o Google Maps, um localizador de lojas ou uma exploração local), o AI Studio detecta automaticamente o requisito geoespacial e ajuda no provisionamento de chaves:

1. Cortina de ativação no contexto: um card inline intitulado "Configurar a Plataforma Google Maps" aparece na conversa.
2. Aceitar os termos e ativar:
   • Leia e aceite os Termos de Serviço do projeto de demonstração do Maps e os termos adicionais de serviço do nível Starter, se solicitado.
   • Clique em Ativar o Google Maps.
3. Provisionamento automático de chaves e injeção de secrets: o AI Studio provisiona automaticamente uma chave de demonstração da Plataforma Google Maps na infraestrutura do Google Hosted Project (GHP) e a injeta diretamente nos secrets do seu projeto com o nome GOOGLE_MAPS_PLATFORM_KEY.
4. Prévia instantânea: o sandbox de prévia do aplicativo é atualizado imediatamente com um mapa interativo do Google em tempo real e totalmente funcional.

> Você também pode ativar proativamente a Plataforma Google Maps em Configurações (ícone de engrenagem) > guia Integrações > Plataforma Google Maps ou fornecer sua própria chave de API em Configurações > Secrets se já tiver um projeto ativo do Google Cloud. Como alternativa, o agente pode pedir uma chave de API diretamente na janela de conversa.

Teste o aplicativo no sandbox de prévia inserindo um novo local ou selecionando um dos botões de local predefinidos.

4. Adicionar insights locais com a API Gemini

Em seguida, você vai integrar a API Gemini para gerar insights avançados e localizados sobre lugares enquanto os usuários exploram o mapa.

1. Envie o seguinte comando para o assistente de IA na janela de 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. Verifique no painel de visualização se a seleção ou pesquisa de um local mostra curiosidades dinâmicas geradas pelo Gemini.

O AI Studio vai atualizar o aplicativo, e a seção "Insights locais" vai aparecer na parte de baixo da tela.

5. Crie o teste de curiosidades gerado por IA

Agora que seu aplicativo recupera coordenadas de local e insights localizados, combine esses recursos para gerar jogos de perguntas e respostas interativos com base no destino selecionado.

1. Envie o comando de geração de teste para o 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. Faça o teste gerado na janela de prévia para testar o gerenciamento de estado, a seleção de respostas e a renderização de pontuação.

6. Integrar o Grounding Lite do Maps

Por padrão, o Gemini gera fatos e testes usando o conhecimento dos dados de treinamento. Para melhorar a precisão e aproveitar os dados espaciais em tempo real, integre o Maps Grounding Lite. Esse serviço conecta o Gemini a dados em tempo real diretamente da Plataforma Google Maps.

1. Envie o seguinte comando no 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. Teste a opção Modo hiperlocal na janela de prévia para verificar a geração de testes fundamentados.

Os LLMs podem alucinar horários de funcionamento específicos, aberturas recentes ou IDs de lugar exatos. O Maps Grounding Lite embasa as respostas com entidades e atribuições reais do Google Maps Places, melhorando significativamente a precisão factual das perguntas de curiosidades.

7. Implantar no Cloud Run

Quando o protótipo estiver totalmente funcional, implante-o como um contêiner público sem servidor no Cloud Run diretamente do AI Studio.

1. No canto superior direito do Google AI Studio, clique no botão Publicar para iniciar o assistente de implantação.
2. Clique em Começar para configurar seu projeto na nuvem do Google Cloud.
   • Verifique se o menu suspenso Projeto do Google Cloud de destino corresponde ao projeto de implantação pretendido.
   • O AI Studio vai gerar automaticamente um identificador de serviço exclusivo para a instância do Cloud Run.
3. Clique em Publicar app.
4. A criação, o registro e a implantação do serviço de contêiner serão executados em segundo plano. Esse processo normalmente leva de 2 a 4 minutos.
5. Quando a implantação terminar, copie o URL do aplicativo gerado e acesse o link do aplicativo ativo em uma guia do navegador.

8. Revisar as práticas recomendadas de segurança e produção

Ao fazer a transição desse app de um protótipo para um ambiente de produção, lembre-se destes pilares de segurança:

1. Restrições da API Google Maps

Nunca deixe chaves de API Google Maps de produção sem restrições. No console do Google Cloud:

• Restrições de API:restrinja a chave para que ela só possa chamar APIs específicas (API Maps JavaScript, API Geocoding, API Places).
• Restrições de aplicativo:restrinja a chave usando Referenciadores HTTP (por exemplo, https://yourgame.com/*) para evitar o uso não autorizado em sites de terceiros.

2. Como proteger a chave da API Gemini

A chave de API Gemini nunca deve ser exposta em JavaScript do lado do cliente.

• Arquitetura de produção:crie um serviço de back-end leve (por exemplo, Cloud Run ou Cloud Functions) para atuar como um proxy. O front-end chama o back-end (/api/get-fun-facts), e o back-end se comunica com segurança com o Google AI Studio usando uma variável de ambiente (GEMINI_API_KEY).

9. Limpar recursos

Para evitar cobranças inesperadas ou limpar os recursos do seu espaço de trabalho:

1. No Google AI Studio, acesse a página de apps.
2. Encontre o aplicativo na grade ou lista.
3. Clique no ícone da lixeira para excluir o estado do app e cancelar a publicação do serviço no Cloud Run.
4. Se você fez a implantação usando um projeto padrão e quer desligar todos os recursos completamente, acesse as Configurações do projeto do console do Google Cloud e exclua o projeto subjacente.

10. Conclusão

Parabéns! Você projetou, desenvolveu e implantou um aplicativo da Web geoespacial com tecnologia de IA no Google AI Studio. Você usou as APIs da Plataforma Google Maps para criar um jogo interativo com dados do mundo real.

Acesse este link para reivindicar o selo Jornada do Builder concluída.

Para continuar sua jornada, acesse goo.gle/builders e faça o próximo laboratório.

Saiba mais

• Documentação da Plataforma Google Maps
• Documentação do Cloud Run
• Criar apps no Google AI Studio