Saltar al contenido
SheetForge

Configuración de Hojas de Google — Cuenta de servicio y clave JSON

SheetForge lee Hojas de Google en dos modos.

  • ExportUrl no necesita credenciales: comparte la hoja por enlace, registra el valor #gid= de cada pestaña, e importa. Es de solo lectura.
  • SheetsApi se autentica como una cuenta de servicio de Google y desbloquea todo lo demás: hojas privadas, escritura de vuelta (reflejo), y Push.

Esta página recorre la configuración de SheetsApi de principio a fin: crear la cuenta de servicio, descargar su clave JSON, compartir tu hoja de cálculo con ella, y apuntar SheetForge hacia la clave. No se asume experiencia previa con Google Cloud. Cada paso ocurre en un navegador web y no cuesta nada.

El flujo completo:

  1. Crea un proyecto de Google Cloud.
  2. Habilita la API de Google Sheets en él.
  3. Crea una cuenta de servicio.
  4. Descarga la clave JSON de la cuenta.
  5. Comparte tu hoja de cálculo con la dirección de correo de la cuenta.
  6. Apunta SheetForge hacia la clave.

1. Crea un proyecto de Google Cloud

  1. Abre console.cloud.google.com e inicia sesión con una cuenta de Google — no necesita ser la que es propietaria de la hoja de cálculo. Una cuenta personal siempre funciona. Algunas organizaciones empresariales de Google Workspace deshabilitan la descarga de claves de cuenta de servicio por política, lo que hace que el paso 4 falle con un error de política de organización (consulta "Si algo falla" más abajo). En la primera visita, acepta el aviso de Términos de Servicio para llegar a la consola.
  2. En la barra superior, haz clic en el selector de proyecto (el menú desplegable junto al logo de Google Cloud), y luego en New project.
  3. Introduce cualquier nombre (por ejemplo, sheetforge-sheets) y haz clic en Create. Deja la organización y la ubicación en sus valores predeterminados.
  4. Cuando aparezca la notificación de "proyecto creado", selecciona el nuevo proyecto en el selector. Todo lo que viene a continuación ocurre dentro de este proyecto, así que asegúrate de que permanezca seleccionado.

Un proyecto es solo un contenedor para los ajustes de la API. Crearlo es gratis, y el uso de la API de Sheets en esta guía no tiene costo.

2. Habilita la API de Google Sheets

  1. Abre el menú de la izquierda (☰) y ve a APIs & Services ▸ Library.
  2. Busca Google Sheets API y abre el resultado.
  3. Haz clic en Enable. Si el botón dice Manage, la API ya está habilitada — no hay nada que hacer.

3. Crea una cuenta de servicio

Una cuenta de servicio es una identidad de máquina con su propia dirección de correo. SheetForge inicia sesión como esta identidad — tu contraseña personal de Google nunca interviene.

  1. Ve a APIs & Services ▸ Credentials.
  2. Haz clic en + Create credentials ▸ Service account.
  3. Introduce un nombre (por ejemplo, sheetforge-reader); el ID de la cuenta se rellena automáticamente. Haz clic en Create and continue.
  4. Los pasos "Grant this service account access to project" y "Grant users access" son opcionales — omite ambos y haz clic en Done. El acceso a tu hoja de cálculo se concede compartiendo la hoja (paso 5), no mediante roles de proyecto.
  5. Si la consola sugiere configurar una OAuth consent screen, ignóralo — las cuentas de servicio no usan una.

4. Descarga la clave JSON

  1. De vuelta en la página de Credentials, haz clic en la cuenta de servicio que acabas de crear (bajo "Service accounts").
  2. Abre la pestaña Keys.
  3. Haz clic en Add key ▸ Create new key, elige JSON, y haz clic en Create.
  4. El navegador descarga un archivo con un nombre como sheetforge-sheets-1a2b3c.json. Esta es la única copia — Google no la conserva para volver a descargarla. Si la pierdes, elimina la clave en la pestaña Keys y crea una nueva.

Trata este archivo como una contraseña:

  • Muévelo a algún lugar fuera de tu proyecto de Unity y tu repositorio, por ejemplo C:/keys/sheetforge.json.
  • Nunca lo pongas bajo Assets/ — todo lo que hay ahí se confirma junto con el proyecto, y una referencia perdida (o una carpeta Resources/StreamingAssets) puede arrastrarlo hacia una build.
  • Si la clave llega a filtrarse, elimínala en la pestaña Keys (esto la revoca de inmediato) y crea una nueva.

5. Comparte la hoja de cálculo con la cuenta de servicio

La clave por sí sola no concede nada. La cuenta de servicio solo puede leer hojas que se hayan compartido explícitamente con ella — exactamente igual que un colaborador humano.

  1. Abre el archivo JSON descargado en cualquier editor de texto y copia el valor de client_email. Se ve así: sheetforge-reader@sheetforge-sheets.iam.gserviceaccount.com.
  2. Abre tu hoja de cálculo en Google Sheets y haz clic en Share.
  3. Pega la dirección y elige un rol:
    • Viewer es suficiente para la importación.
    • Editor se requiere para la escritura de vuelta — el reflejo de creación y Push.
  4. Desactiva "Notify people" (la dirección no tiene bandeja de entrada) y confirma.
  5. Si Google advierte sobre compartir fuera de tu organización, confirma — una cuenta de servicio no pertenece a ninguna organización.

Saltarse este paso es el error de configuración más común — a partir de ahí, cada solicitud falla con un error de permisos, sin importar lo correcta que sea la clave.

6. Apunta SheetForge hacia la clave

  1. En tu asset de ajustes de importación, define el origen como GoogleSheet y el modo de acceso como SheetsApi.
  2. Rellena spreadsheetId con el ID largo de la URL de la hoja: https://docs.google.com/spreadsheets/d/<this part>/edit.
  3. Indícale a SheetForge dónde está el archivo de la clave, de una de estas dos formas:
    • Recomendado — variable de entorno. Define SHEETFORGE_SHEETS_KEY con la ruta absoluta del archivo JSON. Cada desarrollador define la suya propia, ninguna ruta entra jamás al repositorio, y tiene prioridad sobre el campo de ajustes.
      • En Windows: setx SHEETFORGE_SHEETS_KEY "C:\keys\sheetforge.json" en una terminal, y luego reinicia Unity y Unity Hub (los procesos que ya están en ejecución conservan su entorno antiguo).
      • En macOS/Linux: expórtala en el perfil de tu shell e inicia Unity desde ese shell, o usa launchctl setenv en macOS.
    • O — campo de ajustes. Pon la ruta en serviceAccountKeyPath, apuntando fuera del repositorio.
  4. Pulsa ↓ Pull from source en Tools ▸ SheetForge ▸ Data Studio. Un informe exitoso significa que toda la cadena — proyecto, API, cuenta, compartición, clave — está funcionando.

Si algo falla

  • Error de permisos (PERMISSION_DENIED / 403): la hoja no está compartida con la dirección client_email (paso 5) — el ID apunta a una hoja de cálculo real que la cuenta de servicio no puede ver.
  • Requested entity was not found (404): spreadsheetId es incorrecto — copia exactamente el segmento entre /d/ y /edit en la URL de la hoja.
  • "Service account key creation is disabled" / error de política de organización en el paso 4: tu organización de Google Workspace impone iam.disableServiceAccountKeyCreation. Pide a un administrador que permita la creación de claves para este proyecto, o crea el proyecto bajo una cuenta personal de Google. La hoja de cálculo se puede compartir con la cuenta de servicio de ese proyecto sin importar quién sea el propietario de la hoja.
  • "Google Sheets API has not been used in project … or it is disabled": la API no está habilitada en el proyecto que emitió la clave (paso 2) — habilítala ahí, no en algún otro proyecto. Una API recién habilitada puede tardar unos minutos en propagarse.
  • Archivo de clave no encontrado: la ruta tiene un error tipográfico, o Unity se inició antes de que existiera la variable de entorno — define la variable, y luego reinicia Unity y Unity Hub.
  • Clave comprometida o perdida: elimínala en la pestaña Keys de la cuenta de servicio, crea una nueva clave JSON, y reemplaza el archivo. Nada más cambia — la dirección de correo y la compartición de la hoja siguen siendo válidas.

Páginas relacionadas