Referência de funções

Tipos de função

O tipo é inferido a partir da ligação sobre a qual constróis. Cada um mapeia para uma família de fonte de dados; o construtor mostra os campos de que esse tipo precisa (uma consulta SQL, um pedido HTTP, um filtro de coleção, e por aí fora).

• http — um pedido REST/HTTP: método, template de URL, query, cabeçalhos e corpo, com parâmetros vinculados a partir dos argumentos da fórmula.
• graphql — uma consulta GraphQL com variáveis contra um endpoint GraphQL.
• database — uma consulta SQL parametrizada. O dialeto segue a ligação: Postgres, MySQL, SQL Server, Oracle, Azure Synapse ou AWS Athena.
• mongo — um find, aggregate ou count de MongoDB sobre uma coleção (filtro, pipeline, ordenação, limite).
• cosmos — uma consulta SQL de Azure Cosmos DB contra um contentor.
• dynamodb — um get-item ou query de AWS DynamoDB por chave de partição/ordenação.
• lambda — uma invocação de AWS Lambda com um payload JSON, opcionalmente lendo um campo da resposta.
• azure_function — uma Azure Function acionada por HTTP.
• gcp_function — uma Google Cloud Function acionada por HTTP.
• file — lê um ficheiro remoto (por HTTP(S), S3, SFTP, FTP, Azure Blob ou Google Cloud Storage) analisado como CSV, JSON ou JSONL.
• kv — uma leitura de uma cache chave-valor (get / mget / scan) contra um armazém compatível com Valkey ou Redis.

Quatro deles — database, mongo, dynamodb e cosmos — também sabem escrever; ver Operações de escrita mais abaixo.

Formas do resultado

A forma decide como o resultado chega à grelha.

• single — um valor na célula que chama (número, string, booleano).
• row — um registo ao longo de uma linha de células.
• table — linhas × colunas que derramam para um intervalo, com cabeçalhos e formatos numéricos mapeados a partir da resposta.
• json — a resposta JSON em bruto como texto.
• entity — um tipo de dados ligado de Excel: um chip de célula cujas propriedades se tornam acessores de campo como =A2.Price. Apenas async; estes aparecem sob o separador Tipos de dados do painel de tarefas.

Modelos de execução

• sync — calculado localmente no suplemento, sem chamada ao agent. Melhor para transformações leves.
• async — o padrão. O agent obtém enquanto o Excel mostra #GETTING_DATA; o suplemento agrupa muitas chamadas de célula num só pedido.
• streaming — a célula atualiza-se ao vivo à medida que chegam novos valores. Server-Sent Events no desktop, com um recurso a polling no Excel para a web.

Detalhes do streaming

O bloco stream de uma função streaming controla exatamente como as atualizações chegam à célula:

• Transporte — sse (Server-Sent Events) ou polling. SSE só está disponível quando a ligação da função é http — qualquer outro tipo de ligação transmite por polling, e o Excel para a web recorre sempre a polling, já que ligações SSE de longa duração não são fiáveis em todas as sandboxes de navegador. O polling tem o seu próprio intervalo, em segundos; o SSE não tem nenhum — o agent reencaminha os eventos à medida que chegam.
• emitOnChangeOnly — quando ativo, o agent só envia um valor novo para a célula quando este realmente mudou, em vez de reemitir o mesmo valor a cada tick.
• cancelUpstream — ativo por predefinição. Quando a célula é apagada ou o utilizador navega para outro sítio, o agent termina a sua subscrição upstream em vez de continuar a fazer polling ou a manter uma ligação aberta para ninguém.

Operações de escrita

Quatro tipos enviam dados no sentido inverso. A operação escolhe-se no construtor, e uma função tem exatamente uma.

O caminho SQL nunca monta uma instrução a partir de texto livre: o nome da tabela e cada nome de coluna têm de ser um identificador simples — uma letra ou _ seguida de letras, dígitos e _ — e os valores viajam como parâmetros vinculados. Um cabeçalho do livro não consegue infiltrar SQL numa instrução.

Os carregamentos são seguros de repetir por construção. Cada bloco de um mesmo carregamento leva a mesma identidade (as variáveis ${upload.*} mais abaixo): o insert SQL carimba _upload_id e _chunk em cada linha e substitui esse bloco dentro de uma única transação, o Cosmos deriva os seus ids de documento da identidade do carregamento, e o DynamoDB sobrescreve pela chave da tabela. Voltar a clicar depois de uma falha parcial substitui, portanto, o que já tinha sido escrito em vez de o duplicar.

Sinalizadores de função

Três interruptores independentes, disponíveis seja qual for o tipo:

Variáveis de modelo

Em qualquer texto livre de uma função que seja enviado à fonte de dados — o caminho de um endpoint HTTP, valores de cabeçalhos ou de query, o modelo do body, uma instrução SQL ou o valor predefinido de um parâmetro — podes referenciar variáveis predefinidas com ${...}. O agent resolve-as em cada chamada, do lado do servidor; o workbook nunca vê nem fornece os valores, pelo que não podem ser falsificados a partir de uma célula. Uma referência ${...} desconhecida fica intacta em vez de ser esvaziada.

Integradas — sempre disponíveis

O utilizador com sessão iniciada — ${auth.*}

Resolvidas a partir do token de início de sessão validado do utilizador final. Cada uma é uma cadeia vazia quando ninguém tem sessão iniciada — combina-as com uma ligação user_token ou com o controlo de acesso quando o valor tiver de estar presente.

Identidade do carregamento — ${upload.*}

Preenchidas apenas quando a chamada vem de um bloco Upload range do taskpane; cadeias vazias caso contrário. Os carregamentos grandes são enviados em blocos, e um clique repetido reenvia a mesma identidade — assim a tua API pode desduplicar por (id, chunk) em vez de armazenar duplicados.

Os valores são escapados conforme o contexto onde aterram (uma instrução SQL escapa de forma diferente de um body JSON), pelo que um nome com aspas não consegue quebrar o pedido.