Minilección · Español

Cómo mantener las claves de API fuera del frontend

Usa el ejemplo con servidor para mantener la clave del proveedor fuera del navegador y verificar peticiones permitidas y rechazadas.

Comenzar la lección interactivaLeer los apuntes

¿Para quién es esta lección?

Para quienes conectan un sitio con IA u otro servicio privilegiado. El asistente puede conectar el proyecto; necesitas entender dónde usar el secreto, no programar el servidor.

Antes de empezar

Necesitas tu acceso API Google AI Studio y un proyecto separado de funciones Netlify. Usa el taller completo y un asistente para el entorno privado. Confirma modelo, límites de cuenta y posibles cargos antes de llamar. El laboratorio usa otro código bajo control del propietario; no es un servicio público listo.

Tiempo estimado: 20–32 min

Estimaciones con los archivos iniciales y las cuentas y herramientas necesarias ya listas. La configuración, las colas de publicación y las esperas de correo o DNS requieren tiempo adicional. Configurar el proveedor y la cuenta puede llevar más tiempo. El uso está sujeto a las condiciones y cuota actuales de tu cuenta.

Qué aprenderás

  • Pon el secreto solo en el entorno privado del servidor.
  • Ejecuta la acción sin exponer la clave a visitantes.
  • Comprueba accesos correctos y rechazados.

Archivos del taller

Paso 1

Identifica qué valor debe quedar privado

El navegador debe usar la función sin recibir el secreto del proveedor.

Abre el proyecto con el asistente. Identifica la clave como dato privado y el código de práctica independiente como control del propietario para este laboratorio pequeño.

Llamar .env al archivo no basta si una compilación copia su valor a scripts públicos. Pide examinar los archivos reales del visitante.

Un ejemplo concreto

Un campo oculto sigue perteneciendo al navegador y no esconde una clave.

Abre el taller de claves API y guía run-locally.txt. Mantén clave y modelo en servidor y usa un código de acceso de práctica separado. No pongas secretos en archivos públicos ni pidas pegarlos en mensajes compartidos. Ayúdame a examinar lo que recibe el navegador y probar permisos y rechazos. Explica la evidencia observable en vez de exigirme implementar el endpoint.

Archivos de este paso

Start hereArchivos del taller

Open or download the files below. When saving a project, keep the folder paths shown in the filenames.

How it works (optional)

Mantén las claves privilegiadas fuera del navegador

El navegador del visitante puede examinar cada archivo que le envías.

Un secreto de proveedor puede autorizar gastos u operaciones privilegiadas. Ponerlo en JavaScript público, un campo oculto o una variable sustituida durante la compilación del frontend sigue enviándolo al navegador.

El ejemplo plantea a Gemini una pregunta educativa fija a través de tu función de servidor. El navegador recibe la respuesta; la clave del proveedor permanece en el entorno del servidor. No todas las claves son secretas: las claves publicables de Supabase están diseñadas para usarse en el navegador junto con políticas de acceso, mientras que sus claves secretas no lo están.

Ejemplo resuelto

Abre insecure-example.txt. El valor falso es visible porque está en código entregado. Minificarlo dificultaría leerlo, pero no cambiaría quién lo recibe.

Extra implementation exercise

Una clave se guarda en .env y después se inserta en el JavaScript público durante la compilación. ¿Es privada frente a los visitantes?

Mostrar una solución desarrollada

No. Su ubicación original no importa después de insertarla en un paquete público. Traslada la operación privilegiada a una función de servidor y mantén allí el valor.

  • Sigue la clave hasta el paquete entregado.
  • Distingue el entorno de servidor de la sustitución del frontend.

Paso 2

Inicia la acción protegida

Deja configurar al asistente la ruta servidor existente.

Sigue run-locally.txt y server-env.example.txt con el asistente. Confirma cuenta/modelo y condiciones, configura la clave privada en servidor y genera otro código de práctica. Ejecuta el proyecto completo y abre su URL. Estos controles son obligatorios; escribir la función es opcional.

El navegador debe llamar a tu servidor y este al proveedor en privado. Si fallan configuración, acceso o cuota, indica esa etapa sin inventar respuesta.

Un ejemplo concreto

El código del formulario no es la clave de Google.

Gemini: API generateContent · Gemini: claves de API · Gemini: ID y capacidades actuales de modelos · Node.js: estado de soporte de versiones

Archivos de este paso

Start hereArchivos del taller

Open or download the files below. When saving a project, keep the folder paths shown in the filenames.

How it works (optional)

Pon la llamada del proveedor detrás de tu endpoint

Configura el servidor y envía solo la pequeña solicitud que necesita la función.

Lee netlify/functions/mini-explain.mjs, despliega el proyecto separado y establece GEMINI_API_KEY, GEMINI_MODEL y LAB_TOKEN en el servidor. Elige un modelo de texto con soporte en tu cuenta en vez de copiar un nombre antiguo de tutorial.

Introduce el código independiente de práctica en el formulario. El navegador llama a /.netlify/functions/mini-explain; la función llama al endpoint HTTPS fijo de Google con x-goog-api-key. El código restringe el laboratorio al propietario; no es la credencial Gemini ni un sistema completo de cuotas públicas.

GEMINI_MODEL es el ID exacto disponible en tu cuenta API, no una etiqueta de captura. generate es una función auxiliar del mismo archivo de servidor. Ni la clave ni esa función pertenecen a public/. Una solicitud válida aún puede fallar si el proveedor no tiene cuota o está caído.

Para la secuencia local completa, abre run-locally.txt: prepara el entorno privado de la raíz, vincula solo el proyecto de práctica e inicia el proxy de funciones de Netlify. server-env.example.txt enumera variables sin secretos reales. Abrir solo el HTML no ejecuta el servidor.

Utiliza la guía actual siguiente o ejecuta list-text-models.mjs desde la raíz privada del taller con tu entorno. Enumera candidatos generateContent visibles para la cuenta sin imprimir la clave. Elige un modelo de texto con soporte, comprueba condiciones y cuota y copia su ID exacto en GEMINI_MODEL del servidor.

Antes de la primera solicitud, ejecuta la herramienta de modelos y elige uno actual que admita los campos generateContent usados aquí, incluido systemInstruction. La lista identifica candidatos, no cuota ni todas sus capacidades. Todo netlify/functions/mini-explain.mjs se ejecuta en el servidor; public/app.js se entrega a cada visitante. Comprueba también el tiempo máximo de funciones del plan: el límite de 20 segundos del proveedor no puede ampliar un límite menor del alojamiento.

Ejemplo resuelto

La instrucción del proveedor es fija en el servidor, así que quien llama no puede convertir la ruta en instrucciones arbitrarias enormes. La función limita también la salida y espera como máximo 20 segundos al proveedor.

Gemini: API generateContent · Gemini: claves de API · Gemini: ID y capacidades actuales de modelos · Node.js: estado de soporte de versiones

Extra implementation exercise

¿Qué dos solicitudes deben existir y cuál no debe aparecer en Network del navegador?

Mostrar una solución desarrollada

El navegador muestra su llamada a tu función y la respuesta. El servidor solicita al proveedor; la llamada Google con credenciales no debe aparecer como solicitud del navegador.

  • Ve la solicitud del navegador a la función del propio sitio.
  • Mantiene la solicitud autenticada de Google en el servidor.

Paso 3

Comprueba privacidad y fallo juntos

Una respuesta útil no justifica una clave expuesta.

Pide revisar archivos públicos entregados y peticiones buscando el secreto sin mostrarlo en registros compartidos. Prueba código incorrecto y configuración ausente en el proyecto desechable.

La clave real no debe aparecer en archivos/peticiones del navegador. Los rechazos o indisponibilidad deben seguir siendo fallos con una vía útil para reintentar.

Un ejemplo concreto

Una respuesta convincente con la clave en app.js sigue siendo una tarea incompleta.

Archivos de este paso

Start hereArchivos del taller

Open or download the files below. When saving a project, keep the folder paths shown in the filenames.

How it works (optional)

Verifica tanto el límite como la respuesta

Una respuesta correcta no demuestra por sí sola que la clave siguiera privada.

Busca la clave real en HTML y scripts públicos desplegados sin pegarla en capturas ni registros compartidos. Examina solicitudes del navegador: el código de práctica puede ser visible al propietario, pero la clave Gemini no.

Prueba un código incorrecto y configuración de proveedor ausente en el proyecto desechable. Un fallo debe seguir siendo fallo. Un 429 puede indicar límites de cuota o frecuencia; 401 o 403 pueden indicar acceso o configuración. No los conviertas todos en una respuesta de IA inventada.

Ejemplo resuelto

Un código correcto y ajustes válidos deben devolver una respuesta real. El mismo endpoint con código incorrecto debe rechazar antes de solicitar al proveedor.

Extra implementation exercise

La respuesta funciona, pero la clave también aparece en public/app.js. ¿Está terminada la tarea?

Mostrar una solución desarrollada

No. Elimina la clave de archivos públicos, rótala porque fue expuesta, actualiza el servidor y comprueba el nuevo despliegue y el historial en busca de exposición restante.

  • No acepta una salida correcta como prueba suficiente.
  • Elimina la filtración y rota la clave expuesta.

Paso 4

Haz un cambio limitado de forma segura

Conserva el límite del secreto al cambiar la función.

Pide adaptar la operación fija para explicar DNS brevemente. Conserva modelo/clave en servidor y acceso de práctica solo del propietario.

Repite respuesta prevista y código inválido. Antes de abrir al público, decide autenticación real, controles duraderos de uso y supervisión del presupuesto.

Un ejemplo concreto

Cambiar el tema no debe trasladar datos privados a la página.

Archivos de este paso

Start hereArchivos del taller

Open or download the files below. When saving a project, keep the folder paths shown in the filenames.

How it works (optional)

Tu tarea: trasladar una segunda operación fija

Al cambiar la operación, conserva deliberadamente las mismas restricciones de acceso y ejecución, sin ampliarlas por accidente.

Cambia la instrucción fija del servidor para explicar DNS en dos frases. Mantén credenciales, elección de modelo y límite de salida en el servidor; el navegador debe seguir sin conocer la clave.

Registra el resultado con códigos válidos e inválidos. Explica qué añadirías antes del acceso público: usuarios autenticados u otro límite significativo, límites persistentes de uso y monitorización del presupuesto del proveedor.

Ejemplo resuelto

Cambiar una instrucción fija demuestra que entiendes dónde se controla el proveedor. Aceptar modelos, endpoints o límites de salida arbitrarios del navegador anularía ese control.

Encontrarás el desarrollo completo de referencia en reference/assignment-walkthrough.txt. Compara sus pasos con tu resultado; rellena el registro de pruebas con observaciones de tu propio proyecto.

Extra implementation exercise

Entrega la versión DNS y un registro breve de pruebas del límite.

Mostrar una solución desarrollada

En mini-explain, exclusiva del servidor, sustituye la pregunta fija sobre un servidor web por 'Explain DNS in two sentences for a beginner.' (explica DNS en dos frases para principiantes). Conserva clave y modelo en variables del servidor; la función completa de referencia muestra el cambio exacto.

Examina scripts entregados y solicitudes Network. El navegador envía su solicitud a tu función; no debe enviar GEMINI_API_KEY a Google. El código de laboratorio introducido por el propietario es distinto de la clave del proveedor.

Prueba un código incorrecto: debe rechazarse antes de llamar al proveedor. Un fallo de cuota o red debe seguir siendo un fallo honesto, no una respuesta correcta predefinida. Si expusiste un secreto real, elimínalo y rótalo; ignorar después el archivo no revoca la exposición.

  • No se entrega ningún secreto del proveedor al navegador.
  • Se rechaza el acceso incorrecto y se muestra honestamente el fallo del proveedor.

¿Te resultó útil esta lección?

Deja un me gusta o compártela con alguien a quien pueda servirle.

Sigue aprendiendo

Explora las otras lecciones