Google Sheets — Find row

Tipo: googlesheets-find-row · Paquete: Google Sheets Activities v1.0.5 · Salida: Dictionary<string,object>

Encuentra la primera fila donde una columna coincide con un valor, y la devuelve completa como diccionario. Es el equivalente a un BUSCARV (VLOOKUP): localizar el registro de un cliente, un pedido o una factura por su identificador y leer el resto de sus datos.

Cómo funciona

Lee el range (por defecto A:Z) de la hoja sheet y busca value en la columna column, fila por fila. Devuelve la primera fila que coincide.

column admite una letra (A, B, AA) o un número (1, 2). Se cuenta desde la primera columna de range: con range = "C:H", la columna A (o 1) es la C de la hoja.
La comparación ignora mayúsculas y los espacios al inicio y al final, y se hace contra el texto que se ve en la celda.
Con has-headers = true (por defecto), la primera fila del rango son los encabezados: no se busca en ella y da las claves del diccionario.
Solo se leen las columnas de range: con el valor por defecto, las columnas después de Z no aparecen en el resultado.

Parámetros requeridos

Parámetro	Tipo	Por defecto	Descripción
`column`	`string`	—	Columna donde buscar: letra (`A`, `B`) o número (`1`, `2`), contada desde el inicio de `range`.
`value`	`object`	—	Valor a buscar; se compara como texto, sin distinguir mayúsculas ni espacios de los extremos.

Parámetros opcionales

Parámetro	Tipo	Por defecto	Descripción
`session`	`ZoanGoogleSheetsSession`	—	Sesión de Google Sheets — Open. Dentro del `body` de Open se hereda y puedes omitirla.
`sheet`	`string`	—	Hoja donde buscar. Si se omite, se usa la primera hoja.
`range`	`string`	`A:Z`	Rango de búsqueda en notación A1.
`has-headers`	`bool`	`true`	Usar la primera fila del rango como claves del diccionario. Si es `false`, las claves son `Column1`, `Column2`, …

Salida

Devuelve un Dictionary con la fila encontrada, o nulo si ninguna fila coincide (o si el rango está vacío):

Con has-headers = true: una clave por cada encabezado, con el texto exacto de la fila 1 (fila["Cliente"], fila["Total"]). Si la fila encontrada es más corta que los encabezados, las claves que faltan valen nulo.
Con has-headers = false: claves Column1, Column2, … hasta la última celda con datos de esa fila.
Siempre incluye la clave __row__ (int): el número de la fila encontrada, contado desde la primera fila de range e incluyendo la de encabezados. Con el range por defecto coincide con el número de fila de la hoja, así que sirve para escribir en esa misma fila.

Los valores son texto tal como se ven en la hoja.

Errores comunes

Mensaje	Causa y solución
`'column' es obligatorio.`	`column` quedó vacío o su expresión dio nulo.
`No hay una sesión de Google Sheets disponible. Indica 'session' desde una actividad googlesheets-open o coloca esta actividad dentro del cuerpo de la actividad Open …`	La actividad está fuera del `body` de Open y no recibió `session`. Colócala dentro del `body` o pasa la sesión guardada.
`The service sheets has thrown an exception. HttpStatusCode is …`	Google rechazó la llamada: hoja o rango inexistente, sin acceso, token vencido o cuota superada. Ver errores de la API de Google.

No encontrar la fila no es un error: la salida es nula.

Ejemplo

Buscar un cliente por NIT y actualizar su estado en la misma fila:

Google Sheets — Find row   session = hoja   sheet = "Clientes"   column = "A"   value = nit   → output: cliente
If   condition = !isNull(cliente)
 └─ then:
      Log   message = "Cliente: " + str(cliente["Nombre"]) + " (fila " + cliente["__row__"] + ")"
      Google Sheets — Write cell   session = hoja   sheet = "Clientes"
                                   cell = "E" + cliente["__row__"]   value = "Actualizado"

Actividades relacionadas

Find cell — encontrar una celda concreta.
Read sheet — leer todo y filtrar varias filas a la vez.