Referencia de funciones

Tipos de función

El tipo se infiere de la conexión sobre la que construyes. Cada uno se corresponde con una familia de fuente de datos; el constructor muestra los campos que ese tipo necesita (una consulta SQL, una petición HTTP, un filtro de colección, etc.).

• http — una petición REST/HTTP: método, plantilla de URL, query, encabezados y cuerpo, con parámetros vinculados desde los argumentos de la fórmula.
• graphql — una consulta GraphQL con variables contra un endpoint GraphQL.
• database — una consulta SQL parametrizada. El dialecto sigue a la conexión: Postgres, MySQL, SQL Server, Oracle, Azure Synapse o AWS Athena.
• mongo — un find, aggregate o count de MongoDB sobre una colección (filtro, pipeline, orden, límite).
• cosmos — una consulta SQL de Azure Cosmos DB contra un contenedor.
• dynamodb — un get-item o query de AWS DynamoDB por clave de partición/orden.
• lambda — una invocación de AWS Lambda con una carga JSON, leyendo opcionalmente un campo de la respuesta.
• azure_function — una Azure Function disparada por HTTP.
• gcp_function — una Google Cloud Function disparada por HTTP.
• file — lee un archivo remoto (por HTTP(S), S3, SFTP, FTP, Azure Blob o Google Cloud Storage) analizado como CSV, JSON o JSONL.
• kv — una lectura desde una caché clave-valor (get / mget / scan) contra un almacén compatible con Valkey o Redis.

Cuatro de ellos — database, mongo, dynamodb y cosmos — también pueden escribir; ver Operaciones de escritura más abajo.

Formas de salida

La forma decide cómo aterriza el resultado en la cuadrícula.

• single — un valor en la celda que llama (número, cadena, booleano).
• row — un registro a lo largo de una fila de celdas.
• table — filas × columnas que se desbordan en un rango, con encabezados y formatos de número mapeados desde la respuesta.
• json — la respuesta JSON en crudo como texto.
• entity — un tipo de datos vinculado de Excel: un chip de celda cuyas propiedades se convierten en accesores de campo como =A2.Price. Solo async; estos aparecen bajo la pestaña Data types del panel de tareas.

Modelos de ejecución

• sync — calculado localmente en el complemento, sin llamada al agent. Ideal para transformaciones ligeras.
• async — el predeterminado. El agent obtiene los datos mientras Excel muestra #GETTING_DATA; el complemento agrupa muchas llamadas de celda en una sola petición.
• streaming — la celda se actualiza en vivo a medida que llegan nuevos valores. Server-Sent Events en el escritorio, con un respaldo de polling en Excel para la web.

Detalles de streaming

El bloque stream de una función streaming controla exactamente cómo llegan las actualizaciones a la celda:

• Transporte — sse (Server-Sent Events) o polling. SSE solo está disponible cuando la conexión de la función es http — cualquier otro tipo de conexión transmite por polling, y Excel para la web siempre recurre a polling, ya que las conexiones SSE de larga duración no son fiables en todos los sandboxes de navegador. El polling lleva su propio intervalo, en segundos; SSE no tiene ninguno — el agent reenvía los eventos a medida que llegan.
• emitOnChangeOnly — cuando está activo, el agent solo empuja un valor nuevo a la celda cuando realmente cambió, en lugar de reemitir el mismo valor en cada tick.
• cancelUpstream — activo por defecto. Cuando se borra la celda o el usuario navega a otro sitio, el agent da de baja su suscripción upstream en lugar de seguir haciendo polling o mantener una conexión abierta para nadie.

Operaciones de escritura

Cuatro tipos envían datos en el otro sentido. La operación se elige en el constructor, y una función tiene exactamente una.

La vía SQL nunca ensambla una sentencia a partir de texto libre: el nombre de la tabla y cada nombre de columna deben ser un identificador simple — una letra o _ seguida de letras, dígitos y _ — y los valores viajan como parámetros vinculados. Un encabezado del libro no puede colar SQL en una sentencia.

Las subidas son seguras de reintentar por construcción. Cada trozo de una misma subida lleva la misma identidad (las variables ${upload.*} de más abajo): el insert SQL estampa _upload_id y _chunk en cada fila y reemplaza ese trozo dentro de una única transacción, Cosmos deriva sus ids de documento de la identidad de la subida y DynamoDB sobrescribe por la clave de la tabla. Volver a hacer clic tras un fallo parcial reemplaza por tanto lo ya escrito en lugar de duplicarlo.

Indicadores de función

Tres interruptores independientes, disponibles sea cual sea el tipo:

Variables de plantilla

En cualquier texto libre de una función que se envíe a la fuente de datos — la ruta de un endpoint HTTP, valores de cabeceras o de query, la plantilla del body, una sentencia SQL o el valor predeterminado de un parámetro — puedes referenciar variables predefinidas con ${...}. El agent las resuelve en cada llamada, del lado del servidor; el workbook nunca ve ni aporta los valores, así que no se pueden falsificar desde una celda. Una referencia ${...} desconocida se deja intacta en lugar de vaciarse.

Integradas — siempre disponibles

El usuario con sesión iniciada — ${auth.*}

Se resuelven desde el token de inicio de sesión validado del usuario final. Cada una es una cadena vacía cuando nadie ha iniciado sesión — combínalas con una conexión user_token o con control de acceso cuando el valor deba estar presente.

Identidad de la subida — ${upload.*}

Solo tienen valor cuando la llamada procede de un bloque Upload range del taskpane; en cualquier otro caso son cadenas vacías. Las subidas grandes se envían por trozos, y un clic reintentado reenvía la misma identidad — así tu API puede deduplicar por (id, chunk) en lugar de almacenar duplicados.

Los valores se escapan según el contexto donde aterrizan (una sentencia SQL escapa distinto que un body JSON), de modo que un nombre con comillas no puede romper la petición.