Como criar funções do JavaScript

Anatomia de uma função JavaScript, cobrindo o ponto de extremidade HTTP e formas de trabalho, contratos digitados, auxiliares de resposta, tratamento de erros e registro em log.

Cada função é um módulo que exporta por padrão um objeto defineFunction(...). A CLI o descobri por meio do mapa functions em uipath.json.

import { defineFunction, defineSchema } from "@uipath/coded-functions-js-sdk";

export default defineFunction({
  name: "process-order",
  input: defineSchema<Input>(),
  output: defineSchema<Output>(),
  handler: async (input, ctx) => { /* ... */ },
});

As duas formas

Um único par de campos decide como uma função é invocada.

Formato	Declaração	Invocado por
Ponto de extremidade HTTP	method e path estão definidos	Um aplicativo ou qualquer cliente HTTP, por meio do URL do gatilho da função
Tarefa	method e path omitido	Uma tarefa de serviço do Maestro, uma atividade Run Job, a API do Orchestrator ou um gatilho de trabalho

Ambas as formas são empacotadas e implantadas da mesma maneira. Uma função HTTP é o que suporta um aplicativo codificado; uma função de trabalho é uma etapa dentro de uma automação maior. Consulte Gatilhos HTTP e roteamento para o primeiro e Invocação de funções para o segundo.

Contratos digitados

defineSchema<T>() transforma uma interface TypeScript no Esquema JSON que direciona a associação de variáveis em cada superfície de invocação. A interface é a única fonte de verdade — ela digita o manipulador e declara o contrato:

interface CreateOrderInput {
  /** Customer reference. */
  customerId: string;
  /** @default 1 */
  quantity?: number;
}

As propriedades opcionais tornam-se opcionais no esquema, e uma tag JSDoc @default carrega o valor padrão. Em projetos JavaScript, passe um literal de objeto de Esquema JSON no lugar de defineSchema<T>().

Os esquemas são extraídos da origem sem executá-la. Portanto, escreva-os como literais. Um valor referenciado por meio de uma variável — um limite numérico ou um objeto de esquema compartilhado — pode ser retirado do esquema extraído, deixando a função sem contrato para vincular.

A declaração é opcional.output Quando presente, o valor de retorno do manipulador é validado antes que ele saia da função.

Retornando resultados

Retorne um objeto simples para enviar 200 com esse objeto como o corpo:

handler: async (input) => ({ orderId: input.customerId, processed: true }),

Para qualquer outra coisa, retorne um objeto de resposta ou use um auxiliar:

import { ok, created, notFound } from "@uipath/coded-functions-js-sdk";

return created({ id: "new-id" });          // 201
return notFound("No such order");          // 404
return { status: 202, body: { queued: true } };

AVISO:

Como { status, body } é a forma de resposta, um campo de saída seu próprio chamado status contendo um número é lido como um código de status. O status declarado é enviado com um corpo vazio e o restante da sua carga é descartado, sem erro. Nomeie o campo de outra maneira, como httpStatus.

Erros

Gere FunctionError para falhar com um status e mensagem específicos:

import { FunctionError } from "@uipath/coded-functions-js-sdk";

if (!input.customerId) {
  throw new FunctionError("customerId is required", 400);
}

Um erro não detectado torna-se um 500. Quando a função é executada como um trabalho, um erro gerado falha o trabalho e a mensagem chega ao resultado do trabalho.

Geração de logs

Use o logger do SDK para que a saída seja atribuída à execução e atinja os logs de trabalho do Orchestrator:

import { logger } from "@uipath/coded-functions-js-sdk";

logger.info(`Processed order ${input.orderId}`);

A saída console.* não é encaminhada. Os valores do segredo nunca devem ser registrados.

Próximas Etapas

• Gatilhos HTTP e roteamento
• Contexto da função — identidade, coordenadas de plataforma e dados de solicitação.
• ReferênciadefineFunction — cada campo e seus padrões.