Référence des fonctions

Genres de fonctions

Le genre est déduit de la connexion sur laquelle vous construisez. Chacun correspond à une famille de source de données ; le générateur affiche les champs dont ce genre a besoin (une requête SQL, une requête HTTP, un filtre de collection, et ainsi de suite).

• http — une requête REST/HTTP : méthode, modèle d'URL, requête, en-têtes et corps, avec des paramètres liés aux arguments de la formule.
• graphql — une requête GraphQL avec des variables contre un point de terminaison GraphQL.
• database — une requête SQL paramétrée. Le dialecte suit la connexion : Postgres, MySQL, SQL Server, Oracle, Azure Synapse ou AWS Athena.
• mongo — un find, aggregate ou count MongoDB sur une collection (filtre, pipeline, tri, limite).
• cosmos — une requête SQL Azure Cosmos DB contre un conteneur.
• dynamodb — un get-item ou une requête AWS DynamoDB par clé de partition/de tri.
• lambda — une invocation AWS Lambda avec une charge utile JSON, lisant éventuellement un champ de la réponse.
• azure_function — une Azure Function déclenchée par HTTP.
• gcp_function — une Google Cloud Function déclenchée par HTTP.
• file — lit un fichier distant (en HTTP(S), S3, SFTP, FTP, Azure Blob ou Google Cloud Storage) analysé en CSV, JSON ou JSONL.
• kv — une lecture depuis un cache clé-valeur (get / mget / scan) contre un magasin compatible Valkey ou Redis.

Quatre d'entre eux — database, mongo, dynamodb et cosmos — savent aussi écrire ; voir Opérations d'écriture plus bas.

Formes de sortie

La forme décide de la manière dont le résultat atterrit dans la grille.

• single — une valeur dans la cellule appelante (nombre, chaîne, booléen).
• row — un enregistrement sur une ligne de cellules.
• table — lignes × colonnes qui se répandent dans une plage, avec des en-têtes et des formats de nombre mappés depuis la réponse.
• json — la réponse JSON brute sous forme de texte.
• entity — un type de données lié Excel : une puce de cellule dont les propriétés deviennent des accesseurs de champ comme =A2.Price. Async uniquement ; celles-ci apparaissent sous l'onglet Types de données du volet Office.

Modèles d'exécution

• sync — calculé localement dans le complément, sans appel à l'agent. Idéal pour les transformations légères.
• async — par défaut. L'agent récupère les données pendant qu'Excel affiche #GETTING_DATA ; le complément regroupe de nombreux appels de cellules en une seule requête.
• streaming — la cellule se met à jour en direct à mesure que de nouvelles valeurs arrivent. Server-Sent Events sur le bureau, avec une solution de repli par interrogation sur Excel pour le web.

Détails du streaming

Le bloc stream d'une fonction streaming contrôle exactement comment les mises à jour atteignent la cellule :

• Transport — sse (Server-Sent Events) ou polling. SSE n'est disponible que lorsque la connexion de la fonction est http — tout autre genre de connexion diffuse par polling, et Excel pour le web bascule toujours vers le polling, les connexions SSE longue durée n'étant pas fiables dans tous les bacs à sable de navigateur. Le polling porte son propre intervalle, en secondes ; SSE n'en a aucun — l'agent transmet les événements à mesure qu'ils arrivent.
• emitOnChangeOnly — lorsqu'il est activé, l'agent ne pousse une nouvelle valeur dans la cellule que lorsqu'elle a réellement changé, au lieu de réémettre la même valeur à chaque tick.
• cancelUpstream — actif par défaut. Quand la cellule est supprimée ou que l'utilisateur navigue ailleurs, l'agent résilie son abonnement en amont au lieu de continuer à faire du polling ou de garder une connexion ouverte pour personne.

Opérations d'écriture

Quatre genres envoient des données dans l'autre sens. L'opération se choisit dans le générateur, et une fonction en porte exactement une.

La voie SQL n'assemble jamais une instruction à partir de texte libre : le nom de la table et chaque nom de colonne doivent être un identifiant simple — une lettre ou _ suivie de lettres, de chiffres et de _ — et les valeurs voyagent en paramètres liés. Un en-tête de classeur ne peut pas glisser du SQL dans une instruction.

Les téléversements sont sûrs à réessayer par construction. Chaque bloc d'un même téléversement porte la même identité (les variables ${upload.*} plus bas) : l'insert SQL estampille _upload_id et _chunk sur chaque ligne et remplace ce bloc dans une seule transaction, Cosmos dérive ses ids de document de l'identité du téléversement, et DynamoDB écrase par clé de table. Recliquer après un échec partiel remplace donc ce qui était déjà écrit au lieu de le dupliquer.

Indicateurs de fonction

Trois interrupteurs indépendants, disponibles quel que soit le genre :

Variables de modèle

Partout où la définition d'une fonction accepte du texte libre envoyé à la source de données — le chemin d'un endpoint HTTP, des valeurs d'en-têtes ou de query, le modèle de body, une instruction SQL ou la valeur par défaut d'un paramètre — vous pouvez référencer des variables prédéfinies avec ${...}. L'agent les résout à chaque appel, côté serveur ; le workbook ne voit ni ne fournit jamais les valeurs, elles ne peuvent donc pas être falsifiées depuis une cellule. Une référence ${...} inconnue est laissée telle quelle plutôt que vidée.

Intégrées — toujours disponibles

L'utilisateur connecté — ${auth.*}

Résolues à partir du jeton de connexion validé de l'utilisateur final. Chacune est une chaîne vide quand personne n'est connecté — combinez-les avec une connexion user_token ou le contrôle d'accès quand la valeur doit être présente.

Identité du téléversement — ${upload.*}

Renseignées uniquement quand l'appel provient d'un bloc Upload range du taskpane ; chaînes vides sinon. Les gros téléversements sont envoyés par blocs, et un clic réessayé renvoie la même identité — votre API peut donc dédupliquer par (id, chunk) au lieu de stocker des doublons.

Les valeurs sont échappées selon le contexte où elles atterrissent (une instruction SQL s'échappe différemment d'un body JSON), de sorte qu'un nom contenant une apostrophe ne peut pas casser la requête.