Google Sheets

1. Visión General

El componente Google Sheets (google-sheets) permite crear planillas, leer, actualizar, agregar y limpiar datos en una planilla de Google Sheets.

Úsalo cuando el flujo necesita grabar o consultar datos en una planilla compartida. Solo funciona como acción de salida.

2. Prerrequisitos

• Una aplicación OAuth 2.0 configurada a nivel de plataforma (clientId, clientSecret, applicationName — configurados globalmente, no en el step).
• Un accessToken y refreshToken válidos de la cuenta de Google con acceso a la planilla.
• El ID de la planilla (spreadsheetId) a usar.

3. Autenticación y Conexión

Campo	Obligatorio	Tipo	Descripción	Ejemplo
accessToken	Sí	Texto	Token de acceso OAuth de Google.	Un token OAuth
refreshToken	Sí	Texto	Token de actualización OAuth de Google.	Un refresh token OAuth

A CONFIRMAR: clientId, clientSecret y applicationName de este componente vienen exclusivamente de una configuración global de la aplicación (no pueden definirse por flujo), a diferencia del componente Google Calendar, que acepta esos campos también en el step.

4. Configuración / Operaciones Soportadas

Campo	Obligatorio	Tipo	Descripción	Ejemplo
operation	Sí	Texto: CREATE, CLEAR, UPDATE, APPEND, READ	Operación a ejecutar en la planilla.	"APPEND"
spreadsheetId	Sí, excepto en CREATE	Texto	ID de la planilla (se encuentra en la URL de la planilla de Google).	"1AbCdEfGhIjKlMnOpQrStUvWxYz"
range	No	Texto	Intervalo de celdas a considerar.	"Sheet1!A1:C10"
valueInput	No	Texto	Cómo interpreta Google Sheets los valores enviados. Valor por defecto: "USER_ENTERED" (como si los hubiera escrito un usuario, aplicando formato/fórmulas).	"RAW"
payload	Sí, en APPEND y UPDATE	Texto (JSON, matriz de filas)	Los datos a insertar o actualizar, en formato de lista de filas, cada fila una lista de valores.	[["Maria", "maria@ejemplo.com"]]

5. Ejemplos Prácticos

Ejemplo simple: agregar una nueva fila con datos de un cliente en una planilla.

Entrada:

{
  "cliente": { "nome": "Maria Silva", "email": "maria@ejemplo.com" }
}

Configuración del componente:

{
  "componentName": "google-sheets",
  "configurations": {
    "operation": "APPEND",
    "accessToken": "{$.secrets.googleAccessToken}",
    "refreshToken": "{$.secrets.googleRefreshToken}",
    "spreadsheetId": "1AbCdEfGhIjKlMnOpQrStUvWxYz",
    "range": "Clientes!A1",
    "payload": "[[\"{$.body.cliente.nome}\", \"{$.body.cliente.email}\"]]"
  }
}

Respuesta:

{
  "spreadsheetId": "1AbCdEfGhIjKlMnOpQrStUvWxYz",
  "updates": { "updatedRange": "Clientes!A5:B5", "updatedRows": 1 }
}

Ejemplo avanzado: leer un intervalo de datos de una planilla para procesarlo en el flujo.

Configuración del componente:

{
  "componentName": "google-sheets",
  "configurations": {
    "operation": "READ",
    "accessToken": "{$.secrets.googleAccessToken}",
    "refreshToken": "{$.secrets.googleRefreshToken}",
    "spreadsheetId": "1AbCdEfGhIjKlMnOpQrStUvWxYz",
    "range": "Clientes!A1:B10"
  }
}

Respuesta:

{
  "range": "Clientes!A1:B10",
  "values": [
    ["Maria Silva", "maria@ejemplo.com"],
    ["João Souza", "joao@ejemplo.com"]
  ]
}

6. Errores Comunes y Troubleshooting

Error / Síntoma	Causa probable	Cómo resolverlo
"Missing required environment variables for Google Sheets configuration: ..."	Las credenciales globales (clientId/clientSecret/applicationName) no están configuradas en la plataforma.	Configurar las credenciales OAuth a nivel de aplicación.
"Operation not specified or invalid."	El campo operation no fue completado o no es reconocido.	Completar operation con uno de los valores soportados.
"Spreadsheet ID is empty."	El campo spreadsheetId no fue completado.	Completar spreadsheetId con el ID de la planilla.
"Payload is empty."	Se usaron las operaciones APPEND/UPDATE sin el campo payload.	Completar payload con la matriz de valores a insertar/actualizar.
"Failed to parse payload: ..."	El texto de payload no es un JSON válido en el formato esperado.	Revisar el formato del JSON en payload (debe ser una lista de listas).
"Request to Google Sheets failed: ..."	Error de comunicación con la API de Google Sheets (permiso, token expirado, planilla inexistente).	Revisar los permisos de la cuenta y la validez de los tokens.