
Minilição · Português
Como manter chaves de API fora do frontend
Use um exemplo fornecido com servidor para manter uma chave de provedor fora do navegador do visitante e verificar solicitações permitidas e rejeitadas.
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.
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.
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.
O que você vai aprender
- 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.
Etapa 1
Saiba qual valor deve permanecer privado
O navegador deve usar sua funcionalidade sem receber o segredo do provedor.
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
Open or download the files below. When saving a project, keep the folder paths shown in the filenames.
How it works (optional)
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.
Extra implementation exercise
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.
Erro comum
Tratar toda variável chamada SECRET como privada, independentemente de onde é enviada.
Etapa 2
Inicie a ação protegida fornecida
Deixe o assistente configurar o caminho de servidor existente.
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.
Gemini: API generateContent · Gemini: chaves de API · Gemini: IDs e capacidades atuais dos modelos · Node.js: estado de suporte das versões
Experimente
A ação executou e qual etapa de configuração privada ou provedor ainda está bloqueada?
Converse com o tutor sobre sua resposta
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.
- 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.
Arquivos desta etapa
Open or download the files below. When saving a project, keep the folder paths shown in the filenames.
How it works (optional)
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
Extra implementation exercise
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.
Erro comum
Copiar a função auxiliar de servidor para public/ para corrigir um caminho.
Etapa 3
Verifique privacidade e falha juntas
Uma resposta útil não justifica uma chave exposta.
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.
Experimente
O que a verificação de saída pública e a tentativa rejeitada realmente mostraram?
Converse com o tutor sobre sua resposta
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.
- 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.
Arquivos desta etapa
Open or download the files below. When saving a project, keep the folder paths shown in the filenames.
How it works (optional)
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.
Extra implementation exercise
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.
Erro comum
Esconder um valor vazado na interface enquanto permanece em um script baixável.
Etapa 4
Faça uma alteração delimitada com segurança
Mantenha a mesma fronteira de segredo ao alterar a funcionalidade.
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.
Experimente
Materiais para começar
Os arquivos e conteúdos de teste estão incluídos. A verificação real exige sua própria conta, caixa de entrada ou domínio conforme os pré-requisitos. É possível inspecionar localmente; marque etapas reais não executadas como não testadas.
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.
Converse com o tutor sobre sua resposta
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.
- 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.
Arquivos desta etapa
Open or download the files below. When saving a project, keep the folder paths shown in the filenames.
How it works (optional)
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.
Extra implementation exercise
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.
Erro comum
Chamar a oficina restrita de serviço público de IA pronto para produção.
Esta lição foi útil?
Deixe uma curtida ou compartilhe com alguém que possa aproveitar.
Continue aprendendo
- Como criar seu primeiro site pessoal
- Como publicar seu site pelo GitHub
- Como conectar um domínio próprio ao seu site
- Como configurar e-mail no seu próprio domínio
- Como tornar seu site utilizável em celulares
- Como acelerar o carregamento das imagens do seu site
- Como receber os comentários do seu site na sua caixa de entrada
- Como adicionar assinaturas por e-mail ao seu site
- Como enviar e-mails automáticos pelo seu site
- Como salvar envios de formulário em um banco de dados
- Como permitir que as pessoas entrem no seu site
- Como manter uma página privada
- Como permitir que usuários editem as informações do perfil
- Como permitir que usuários enviem imagens
- Como mostrar dados de uma API externa no seu site
- Como adicionar um chatbot de IA ao seu site
- Como fazer um chatbot responder com base no seu conteúdo
- Como adicionar um blog ao seu site
- Como adicionar busca ao seu site
- Como adicionar outro idioma ao seu site
- Como ajudar o Google a encontrar seu site
- Como corrigir a prévia do seu site ao compartilhar um link
- Como medir visitas e ações úteis no seu site
- Como permitir que visitantes agendem um horário
- Como aceitar um pagamento no seu site
- Como visualizar mudanças do site antes de publicar
- Como desfazer uma implantação com falha do seu site
- Como fazer backup e restaurar os dados do seu site
- Como encontrar e corrigir erros no seu site no ar