Desencadenadores HTTP y enrutamiento

Comportamiento del desencadenador HTTP para funciones JavaScript, que abarca fuentes de entrada, parámetros de ruta, ámbitos de autenticación, límites de carga útil y llamada a un desencadenador implementado.

Una función JavaScript que declara un method y un path se expone como un punto final HTTP. Esto es lo que hace que una función se pueda utilizar como backend de una aplicación codificada: la aplicación llama al punto final y la función contiene las credenciales y las reglas empresariales que nunca deben llegar al navegador.

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

Los métodos compatibles son:

• GET
• POST
• PUT
• PATCH
• DELETE

De dónde proviene la entrada

Método	Solicitar lectura de datos como entrada
GET	La cadena de consulta
POST, PUT, PATCH, DELETE	El cuerpo de la solicitud JSON

Los parámetros de ruta también se fusionan, por lo que /orders/:id proporciona id junto con el resto de la entrada. Cada parámetro de ruta debe declararse en el tipo de entrada: el esquema derivado está cerrado, por lo que uno no declarado se rechaza como propiedad desconocida.

Los parámetros de ruta se fusionan debajo del cuerpo, por lo que gana un campo de cuerpo del mismo nombre. Los nombres distintos evitan una anulación silenciosa.

Parámetros de ruta

Patrón	Coincidencias
:param	Exactamente un segmento: /users/:id coincide con /users/42
:param{regex}	Un segmento, restringido: /users/:id{[0-9]+}
:param?	El segmento, o nada: /list/:filter? coincide con /list y /list/open
*	Un final general, incluido el prefijo simple

Los valores también están disponibles como cadenas en ctx.params, tecleadas por nombre. Las rutas más específicas ganan independientemente del orden de declaración, por lo que un literal /users/me tiene prioridad sobre /users/:id. El enrutamiento se comporta de forma idéntica en un serve local y cuando se implementa.

Llamar a un desencadenador implementado

Una vez publicada e implementada la función, su path se convierte en el slug de un desencadenador HTTP de Orchestrator, y el desencadenador resuelve las solicitudes entrantes por coincidencia de rutas. La persona que llama envía un token al portador; la plataforma pasa la identidad de la persona que llama a la función como ctx.user.

Un desencadenador implementado se registra bajo un nombre con prefijo de paquete: una función llamada get-order en el paquete orders-functions se registra como orders-functions_get-order. Resolver la función por nombre requiere esa forma prefijada.

Desde una aplicación codificada, utiliza el servicio Functions en el SDK de TypeScript de UiPath en lugar de crear la URL a mano.

Nota:

Cuando se invoca una función a través del Functions.invoke()SDK, los parámetros de ruta no se sustituyen en la URL: el slug declarado se envía tal como está escrito y los valores viajan como parámetros de consulta o en el cuerpo. El controlador sigue recibiendo la entrada correcta, pero ctx.params mantiene el patrón literal y un parámetro restringido por regex no coincidirá. Una ruta resuelta requiere crear la URL en la persona que llama.

Autenticación

Las personas que llaman se autentican con un token al portador desde una aplicación externa. Los ámbitos que necesita ese token dependen de dónde se ejecute la persona que llama.

Una aplicación codificada implementada solicita los ámbitos registrados en su aplicación externa: la plataforma los inyecta en la aplicación en el momento de la implementación. Registra la aplicación con los ámbitos de Orchestrator que necesitan las personas que llaman a la función, por ejemplo:

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 también es necesario si la aplicación inicia trabajos o lee sus resultados.

Cuando ejecutas la misma aplicación localmente, su cadena de ámbito proviene de uipath.json , y allí también puedes solicitar OR.Default , el ámbito que hace que Orchestrator aplique las asignaciones de carpetas y roles de tenant de la persona que llama:

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

Nota:

OR.Default no se puede añadir a un registro de aplicación externa; la API lo rechaza como un ámbito desconocido. Por lo tanto, está disponible para una aplicación ejecutada localmente a través de uipath.json, pero no para una aplicación codificada implementada.

Límites de carga útil

Un desencadenador HTTP pasa la solicitud como argumentos de trabajo, por lo que la solicitud y la respuesta están limitadas.

Dirección	Límite	Más allá del límite
Solicitud	10 000 caracteres de entrada serializada	500, con errorCode 4801 y el mensaje JobArguments length should be less than 10000 characters
Respuesta	Aproximadamente 512 KB	200 con un cuerpo vacío y sin error

La respuesta vacía es contra la que se debe diseñar: el estado dice éxito y nada informa de la pérdida. Cuando una carga útil puede superar cualquier límite, invoca la función como un trabajo en su lugar: un trabajo lleva entradas y salidas grandes como archivos adjuntos. Consulta Invocar funciones.

Consejo:

Devolver una referencia en lugar de los datos en sí (una ruta de depósito de almacenamiento o un identificador que la persona que llama obtiene por separado) evita que los límites restrinjan el diseño.

Próximos pasos

• Contexto de la función : lee la identidad de la persona que llama y la solicitud.
• Acceder a los servicios de la plataforma : accede a Orchestrator desde el controlador.
• Referencia de enrutamiento : las reglas de coincidencia completas.