
Minilição 15 de 30 · Contas e acesso
Saiba qual valor deve permanecer privado
Para quem é esta lição?
Para quem conecta um site a uma IA ou outro serviço privilegiado. Um assistente de programação pode conectar o projeto pronto; você precisa entender onde seu segredo pode ser usado, não escrever código de servidor.
O navegador deve usar sua funcionalidade sem receber o segredo do provedor.
Objetivo desta lição
- Coloque o segredo do provedor apenas no ambiente privado do servidor.
- Execute a ação fornecida sem expor a chave aos visitantes.
- Verifique tentativas de acesso bem-sucedidas e rejeitadas.
Explicação, exemplo resolvido e prática
Antes de começar
Você precisa de acesso próprio à API do Google AI Studio e de um projeto Netlify Functions separado. Use o material completo e a configuração privada com um assistente. Antes de fazer solicitações, confirme limites do modelo e da conta, incluindo possíveis cobranças. O laboratório usa um código separado mantido pelo responsável; não é um serviço público de IA pronto.
Confira os conhecimentos iniciais
São habilidades úteis, não cursos obrigatórios bloqueados. Se já as domina, comece aqui; caso contrário, abra a preparação. Os arquivos fornecidos dispensam um site pessoal anterior.
- Como publicar seu site pelo GitHub
Conecte um repositório de prática à hospedagem.
Tempo estimado: 20–32 min
Estimativas com os arquivos iniciais e as contas e ferramentas necessárias já prontas. Configuração, filas de publicação e esperas de e-mail ou DNS exigem tempo adicional. Configurar provedor e conta pode levar mais tempo. O uso depende dos termos e da cota atuais da sua conta.
Entenda a ideia
Abra o projeto fornecido com seu assistente. Identifique a chave do provedor como um valor privado da conta e o código de prática separado como controle de acesso do proprietário para este pequeno laboratório.
Um arquivo chamado .env não basta se uma compilação copiar seu valor para scripts públicos. Peça ao assistente para examinar os arquivos reais entregues ao visitante.
Um exemplo concreto
Um campo oculto de formulário ainda pertence ao navegador e não pode esconder uma chave do provedor.
Abra esta oficina pronta de chave de API e oriente sua configuração em run-locally.txt. Mantenha a chave do provedor e a escolha do modelo no servidor e use um código de acesso de prática separado. Não coloque segredos em arquivos públicos nem peça que eu os cole em mensagens compartilhadas. Ajude a examinar o que o navegador recebe e a testar solicitações permitidas e rejeitadas. Explique as provas observáveis em vez de exigir que eu implemente o endpoint.Arquivos desta etapa
Comece aquiArquivos da oficina
Abra ou baixe os arquivos abaixo. Ao salvar o projeto, mantenha as pastas indicadas nos nomes dos arquivos.
Experimente
Qual valor deve ficar fora da página do visitante e que prova você pedirá ao assistente para examinar?
Mostrar uma solução comentada
Plano ilustrativo de privacidade: “GEMINI_API_KEY é a credencial privada do provedor. LAB_TOKEN é um código separado de prática, não outro nome dessa chave. O assistente inspecionará os scripts públicos entregues e as solicitações do navegador em busca de exposição acidental.”
Um nome de arquivo privado não basta: o build ainda pode copiar seu conteúdo para a saída pública. Vou manter os valores reais fora de capturas e notas compartilhadas.
O que uma boa resposta inclui
- Identifica a chave do provedor como secreta e o código de prática como uma fronteira separada do laboratório.
- Aponta arquivos públicos e solicitações do navegador como locais a inspecionar em busca de vazamento da chave.
Como funciona (opcional)
Mantenha chaves privilegiadas fora do código de navegador
O navegador do visitante consegue examinar todos os arquivos que você envia.
Um segredo de provedor pode autorizar gastos ou operações privilegiadas. Colocá-lo em JavaScript público, campo oculto ou variável substituída na compilação do frontend ainda o envia ao navegador.
O exemplo faz ao Gemini uma pergunta educativa fixa pela sua função de servidor. O navegador recebe a resposta; a chave permanece no ambiente do servidor. Nem toda chave é secreta: chaves publicáveis do Supabase foram feitas para o navegador com políticas de acesso, ao contrário das chaves secretas.
Exemplo resolvido
Abra insecure-example.txt. O valor falso é visível porque está no código entregue. Minificar a mesma linha reduz a legibilidade, mas não muda quem a recebe.
Exercício técnico complementar
Uma chave é guardada em .env e depois inserida no JavaScript público durante a compilação. Ela é privada para os visitantes?
Mostrar uma solução comentada
Não. O local original não importa depois de a chave ser inserida em um pacote público. Mova a operação privilegiada para uma função de servidor e mantenha o valor ali.
- Acompanha a chave até o pacote entregue.
- Distingue ambiente de servidor de substituição no frontend.

Etapa 1 · Como manter chaves de API fora do frontend
Inicie a ação protegida fornecida
Deixe o assistente configurar o caminho de servidor existente.
Explicação, exemplo resolvido e prática
Entenda a ideia
Siga run-locally.txt e server-env.example.txt com o assistente. Confirme conta/modelo e condições de uso, configure a chave privada no servidor e gere um código separado. Inicie o projeto inteiro e abra a URL local. Essa preparação é obrigatória; escrever o código da função é opcional.
O navegador deve falar com sua funcionalidade de servidor enquanto o servidor chama o provedor em privado. Se configuração, acesso ou cota falharem, relate essa etapa em vez de inventar uma resposta.
Um exemplo concreto
O código de prática do formulário não é a chave do provedor Google.
Arquivos desta etapa
Comece aquiArquivos da oficina
Abra ou baixe os arquivos abaixo. Ao salvar o projeto, mantenha as pastas indicadas nos nomes dos arquivos.
Experimente
A ação executou e qual etapa de configuração privada ou provedor ainda está bloqueada?
Mostrar uma solução comentada
Resultado ilustrativo de preparação: “O projeto completo abriu na URL do proxy local. Com o código de prática, a ação do servidor retornou uma breve explicação de um servidor web. Credenciais e modelo ficaram no ambiente privado.”
Um exemplo bloqueado é “A aplicação roda, mas o provedor informa cota indisponível; nenhuma resposta bem-sucedida foi observada”. Confira modelos permitidos, limites e cobranças antes de repetir; esta aula não promete chamadas gratuitas ou ilimitadas.
O que uma boa resposta inclui
- Registra o endereço local real e uma ação permitida ou o bloqueio exato de configuração/provedor.
- Mantém credencial/modelo no servidor e verifica as condições da conta antes do uso.
Como funciona (opcional)
Coloque a chamada ao provedor atrás do seu endpoint
Configure o servidor e envie apenas a pequena solicitação necessária ao recurso.
Leia netlify/functions/mini-explain.mjs, implante o projeto separado e defina GEMINI_API_KEY, GEMINI_MODEL e LAB_TOKEN no servidor. Escolha um modelo de texto com suporte na sua conta em vez de copiar um nome antigo de tutorial.
Digite o código independente de prática no formulário. O navegador chama /.netlify/functions/mini-explain; a função chama o endpoint HTTPS fixo do Google com x-goog-api-key. O código restringe o laboratório ao proprietário; não é a credencial Gemini nem um sistema completo de cotas públicas.
GEMINI_MODEL é o ID exato disponível na sua conta de API, não um rótulo copiado de captura. generate é uma função auxiliar no mesmo arquivo de servidor. Nem a chave nem a função pertencem a public/. Uma solicitação válida ainda pode falhar quando o provedor não tem cota ou está indisponível.
Para a sequência local completa, abra run-locally.txt: prepare o ambiente privado da raiz, vincule apenas o projeto de prática e inicie o proxy de funções do Netlify. server-env.example.txt lista nomes de variáveis sem segredos reais. Abrir apenas o HTML não executa o servidor.
Use o guia atual abaixo ou execute list-text-models.mjs na raiz privada da oficina com seu ambiente. Ele lista candidatos generateContent visíveis à conta sem imprimir a chave. Escolha um modelo de texto com suporte, confira termos e cota e copie seu ID exato para GEMINI_MODEL no servidor.
Antes da primeira solicitação, execute a lista de modelos e selecione um modelo atual de texto que aceite os campos generateContent usados aqui, incluindo systemInstruction. A lista identifica candidatos, não cota nem toda capacidade. Todo netlify/functions/mini-explain.mjs roda no servidor; public/app.js é entregue a cada visitante. Confira também o tempo limite da função na hospedagem: os 20 segundos do provedor não estendem um limite menor do host.
Exemplo resolvido
A instrução do provedor é fixa no servidor, então quem chama não consegue transformar a rota em instruções arbitrariamente grandes. A função também limita a saída e espera no máximo 20 segundos pela solicitação ao provedor.
Gemini: API generateContent · Gemini: chaves de API · Gemini: IDs e capacidades atuais dos modelos · Node.js: estado de suporte das versões
Exercício técnico complementar
Quais duas solicitações devem existir e qual deve estar ausente de Network no navegador?
Mostrar uma solução comentada
O navegador mostra sua chamada à função e a resposta. O servidor faz a solicitação ao provedor; a chamada ao Google com credenciais não deve aparecer como solicitação do navegador.
- Vê a solicitação do navegador à função do próprio site.
- Mantém a solicitação autenticada ao Google no servidor.

Etapa 2 · Como manter chaves de API fora do frontend
Verifique privacidade e falha juntas
Uma resposta útil não justifica uma chave exposta.
Explicação, exemplo resolvido e prática
Entenda a ideia
Peça ao assistente para ajudar a examinar arquivos públicos entregues e solicitações do navegador em busca do segredo do provedor sem exibi-lo em registros compartilhados. Experimente um código de prática errado e um caso de configuração ausente no projeto descartável.
A chave real não deve aparecer em arquivos ou solicitações do navegador. Solicitações rejeitadas ou indisponíveis devem continuar sendo falhas, com um caminho utilizável para tentar novamente.
Um exemplo concreto
Uma resposta convincente com uma chave exposta em app.js ainda é uma tarefa incompleta.
Arquivos desta etapa
Comece aquiArquivos da oficina
Abra ou baixe os arquivos abaixo. Ao salvar o projeto, mantenha as pastas indicadas nos nomes dos arquivos.
Experimente
O que a verificação de saída pública e a tentativa rejeitada realmente mostraram?
Mostrar uma solução comentada
Registro ilustrativo de privacidade/erro: “O assistente inspecionou a saída pública e a solicitação do navegador ao meu servidor; a chave não estava lá. Um código errado foi rejeitado. Ao remover a configuração privada do provedor no projeto descartável, a ação falhou em vez de exibir uma explicação inventada.”
Isso registra a fronteira inspecionada, não uma auditoria completa. Se uma chave aparecer na saída pública, pare de compartilhar esse build e substitua a credencial exposta no provedor antes de usá-la de novo.
O que uma boa resposta inclui
- Informa quais saídas/solicitações públicas foram inspecionadas sem reproduzir o segredo do provedor.
- Registra como falhas uma tentativa de acesso rejeitada e outra sem configuração disponível.
Como funciona (opcional)
Verifique o limite e a resposta
Uma resposta bem-sucedida sozinha não prova que a chave continuou privada.
Procure a chave real no HTML e scripts públicos implantados sem colar em capturas nem logs compartilhados. Examine as solicitações: o código de prática pode ser visível ao proprietário, mas a chave Gemini não.
Teste um código errado e configuração ausente do provedor no projeto descartável. Uma falha deve continuar sendo falha. Status 429 pode indicar limites de cota ou frequência; 401 ou 403 podem indicar acesso ou configuração. Não transforme todos em uma resposta de IA fabricada.
Exemplo resolvido
Um código correto com configurações válidas deve retornar uma resposta real. O mesmo endpoint com código errado deve rejeitar antes de solicitar ao provedor.
Exercício técnico complementar
A resposta funciona, mas a chave também aparece em public/app.js. A tarefa está concluída?
Mostrar uma solução comentada
Não. Remova a chave dos arquivos públicos, faça a rotação porque foi exposta, atualize o servidor e confira a nova implantação e o histórico em busca de exposição restante.
- Não aceita saída bem-sucedida como evidência suficiente.
- Remove o vazamento e faz a rotação da chave exposta.

Etapa 3 · Como manter chaves de API fora do frontend
Faça uma alteração delimitada com segurança
Mantenha a mesma fronteira de segredo ao alterar a funcionalidade.
Explicação, exemplo resolvido e prática
Entenda a ideia
Peça ao assistente para adaptar a operação fixa fornecida para explicar DNS brevemente. Preserve as configurações de modelo e chave no servidor e a fronteira de prática exclusiva do proprietário.
Teste novamente a resposta pretendida e um código de acesso inválido. Antes do uso público, decida sobre autenticação real, controles duráveis de uso e monitoramento do orçamento no provedor.
Um exemplo concreto
Alterar o assunto da resposta não deve mover valores privados da conta para a página.
Arquivos desta etapa
Comece aquiArquivos da oficina
Abra ou baixe os arquivos abaixo. Ao salvar o projeto, mantenha as pastas indicadas nos nomes dos arquivos.
Experimente
Apresente a ação alterada e as verificações de privacidade, validade e rejeição que realmente executou.
O que entregar: Um registro com dados sensíveis ocultados da fronteira da chave e de solicitações válidas e inválidas da ação fornecida.
Mostrar uma solução comentada
Registro ilustrativo de alteração: “A operação fixa agora explica DNS em duas frases. Uma chamada permitida retornou esse tema; um código errado foi rejeitado; a inspeção pública continuou sem encontrar chave do provedor.”
“Antes de abrir para desconhecidos, ainda preciso de autenticação real, limites duráveis de uso e monitoramento do orçamento.” O código compartilhado é uma pequena fronteira de laboratório, não prova de um serviço público completo.
O que uma boa resposta inclui
- Muda o tema fixo da resposta para DNS, preservando chave/modelo somente no servidor.
- Repete chamadas permitidas e rejeitadas e identifica os controles de custo/acesso ainda necessários para uso público.
Como funciona (opcional)
Sua tarefa: mover uma segunda operação fixa
Ao mudar a operação, mantenha deliberadamente os mesmos limites de acesso e execução, sem ampliá-los por acidente.
Mude a instrução fixa do servidor para explicar DNS em duas frases. Mantenha credenciais, escolha de modelo e limite de saída no servidor; o navegador deve continuar sem conhecer a chave.
Registre o resultado com códigos válidos e inválidos. Explique o que acrescentaria antes de acesso público: usuários autenticados ou outro limite significativo, limites duradouros de uso e monitoramento do orçamento do provedor.
Exemplo resolvido
Alterar uma instrução fixa prova que você entende onde o comportamento é controlado. Aceitar modelos, endpoints ou limites arbitrários do navegador desfaria esse controle.
O roteiro completo de referência está em reference/assignment-walkthrough.txt. Compare as etapas com seu resultado; preencha o registro de teste com observações do seu próprio projeto.
Exercício técnico complementar
Produza a versão DNS e um breve registro de teste do limite.
Mostrar uma solução comentada
Na função mini-explain, exclusiva do servidor, substitua a pergunta fixa sobre servidor web por 'Explain DNS in two sentences for a beginner.' (explique DNS em duas frases para iniciantes). Mantenha chave e modelo nas variáveis do servidor; a função completa de referência mostra a alteração exata.
Examine scripts entregues e solicitações Network. O navegador envia sua solicitação à sua função; não deve enviar GEMINI_API_KEY ao Google. O código de laboratório digitado pelo proprietário é separado da chave do provedor.
Tente um código errado: espere rejeição antes de qualquer chamada ao provedor. Uma falha de cota ou rede deve continuar honesta, não virar uma resposta pronta de sucesso. Se um segredo real foi exposto, remova e faça a rotação; ignorar o arquivo depois não revoga a exposição.
- Nenhum segredo do provedor é entregue ao navegador.
- O acesso errado é rejeitado e uma falha real do provedor fica visível.
Esta lição foi útil?
Deixe uma curtida ou compartilhe com alguém que possa aproveitar.