Gatilhos HTTP e roteamento

Comportamento de gatilho HTTP para funções JavaScript, cobrindo fontes de entrada, parâmetros de caminho, escopos de autenticação, limites de carga e chamada de um gatilho implantado.

Uma função JavaScript que declara um method e um path é exposta como um endpoint HTTP. É isso que torna uma função utilizável como back-end de um aplicativo codificado: o aplicativo chama o ponto de extremidade, e a função contém as credenciais e regras de negócios que nunca devem alcançar o navegador.

export default defineFunction({
  name: "get-order",
  method: "GET",
  path: "/orders/:id",
  input: defineSchema<{ id: string }>(),
  handler: async (input, ctx) => fetchOrder(input.id),
});

Os métodos compatíveis são:

• GET
• POST
• PUT
• PATCH
• DELETE

De onde vem a entrada

Método	Solicitar dados lidos como entrada
GET	A string de consulta
POST, PUT, PATCH, DELETE	O corpo da solicitação JSON

Os parâmetros de caminho também são mesclados, então /orders/:id fornece id junto com o restante da entrada. Cada parâmetro de caminho deve ser declarado no tipo de entrada: o esquema derivados é fechado, então um não declarado é rejeitado como uma propriedade desconhecida.

Os parâmetros de caminho se mesclam abaixo do corpo, então um campo de corpo com o mesmo nome prevalece. Nomes distintos evitam uma substituição silenciosa.

Parâmetros do caminho

Padrão	Correspondências
:param	Exatamente um segmento — /users/:id corresponde a /users/42
:param{regex}	Um segmento, restrito — /users/:id{[0-9]+}
:param?	O segmento, ou nada — /list/:filter? corresponde a /list e /list/open
*	Um genérico à direita, incluindo o prefixo simples

Os valores também estão disponíveis como strings em ctx.params, chaveados por nome. Rotas mais específicas vencem independentemente da ordem da declaração, portanto, uma /users/me literal tem precedência sobre /users/:id. O roteamento comporta-se de forma idêntica em um serve local e quando implantado.

Chamando um gatilho implantado

Depois que a função é publicada e implantada, seu path se torna o campo de dados dinâmico de um gatilho HTTP do Orchestrator, e o gatilho resolve as solicitações de entrada por correspondência de rota. O chamador envia um token de portador; a plataforma passa a identidade do chamador para a função como ctx.user.

Um gatilho implantado é registrado sob um nome prefixado no pacote: uma função chamada get-order no pacote orders-functions é registrada como orders-functions_get-order. Resolver a função por nome requer essa forma prefixada.

A partir de um aplicativo codificado, use Functions serviço no UiPath TypeScript SDK em vez de criar o URL manualmente.

Observação:

Quando uma função é invocada por meio do Functions.invoke() do SDK, os parâmetros de caminho não são substituídos no URL — o campo de dados dinâmico declarado é enviado como escrito e os valores fluem como parâmetros de consulta ou no corpo. O manipulador ainda recebe a entrada correta, mas ctx.params mantém o padrão literal, e um parâmetro restrito a regex não corresponderá. Um caminho resolvido requer a criação do URL no chamador.

Autenticação

Os chamadores autenticam-se com um token de portador de um aplicativo externo. Quais escopos esse token precisa depende de onde o chamador é executado.

Um aplicativo codificado implantado solicita os escopos registrados em seu aplicativo externo — a plataforma os injeta no aplicativo na implantação. Registrar o aplicativo com os escopos do Orchestrator de que os chamadores da função precisam, por exemplo:

uip admin external-apps create "My App" \
  --non-confidential \
  --redirect-uri "https://<org>.uipath.host/my-app" \
  --user-scope "OR.Execution,OR.Folders"

OR.Jobs também é necessário se o aplicativo iniciar trabalhos ou ler seus resultados.

Quando você executa o mesmo aplicativo localmente, sua string de escopo vem de uipath.json , e lá você também pode solicitar OR.Default — o escopo que faz o Orchestrator aplicar as atribuições de pasta e função de tenant do chamador:

openid profile email offline_access OR.Default OR.Execution OR.Folders

Observação:

OR.Default não pode ser adicionado a um registro de Aplicativo externo; a API o rejeita como um escopo desconhecido. Portanto, ele está disponível para um aplicativo executado localmente por meio do uipath.json, mas não para um aplicativo codificado implantado.

Limites de carga

Um gatilho HTTP passa a solicitação como argumentos de trabalho, de modo que a solicitação e a resposta sejam ambas limitadas.

Direction	Limite	Passado o limite
Solicitar	10.000 caracteres de entrada serializada	500, com errorCode 4801 e a mensagem JobArguments length should be less than 10000 characters
Resposta	aproximadamente 512 kB	200 com um corpo vazio e sem erro

A resposta vazia é aquela para projetar: o status diz sucesso e nada relata perda. Quando uma carga puder exceder qualquer limite, invoque a função como um trabalho — um trabalho carrega entradas e saídas grandes como anexos. Consulte Invocação de funções.

Dica:

Retornar uma referência em vez dos próprios dados — um caminho de bucket de armazenamento ou um identificador que o chamador busca separadamente — impede que os limites restrinjam o design.

Próximas Etapas

• Contexto da função — leia a identidade do chamador e a solicitação.
• Acesso a serviços de plataforma — alcance o Orchestrator pelo gerenciador.
• Referência de roteamento — as regras de correspondência completas.