Construire des fonctions JavaScript

L’anatomie d’une fonction JavaScript, couvrant le point de terminaison HTTP et les formes de tâche, les contrats saisis, les assistants de réponse, la gestion des erreurs et la journalisation.

Chaque fonction est un module qui exporte par défaut un objet defineFunction(...). La CLI le découvrez via la carte functions dans 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) => { /* ... */ },
});

Les deux formes

Une seule paire de champs décide de la façon dont une fonction est invoquée.

Forme	Déclaration	Invoqué par
Point de terminaison HTTP	method et path sont définis	Une application ou tout client HTTP, via l'URL du déclencheur de la fonction
Job	method et path omis	Une tâche de service Maestro, une activité Exécuter une tâche, l'API Orchestrator ou un déclencheur de tâche

Les deux formes sont empaquetées et déployées de la même manière. Une fonction HTTP est ce qui assure une application codée; une fonction de tâche est une étape d'une automatisation plus importante. Voir Déclencheurs et routage HTTP pour le premier et Fonctions d'appel pour le second.

Contrats saisis

defineSchema<T>() transforme une interface TypeScript en schéma JSON qui entraîne la liaison de variables sur chaque surface d'invocation. L'interface est la source unique de vérité - elle type le gestionnaire et déclare le contrat:

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

Les propriétés facultatives deviennent facultatives dans le schéma, et une balise JSdoc @default porte la valeur par défaut à travers. Dans les projets JavaScript, transmettez un littéral d'objet Schéma JSON à la place de defineSchema<T>().

Les schémas sont extraits de la source sans l’exécuter, écrivez-les donc sous forme de littéraux. Une valeur référencée via une variable (une limite numérique ou un objet de schéma partagé) peut être supprimée du schéma extrait, laissant la fonction sans contrat pour lier.

La déclaration de output est facultative. Lorsqu'elle est présente, la valeur de retour du gestionnaire est validée par rapport à elle avant de quitter la fonction.

Retour des résultats

Renvoyez un objet simple pour envoyer 200 avec cet objet comme corps:

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

Pour tout le reste, renvoyez un objet de réponse ou utilisez un assistant:

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 } };

Avertissement :

Étant donné que { status, body } est la forme de la réponse, un champ de sortie vous concernant status contenant un numéro est lu comme un code de statut. Le statut déclaré est envoyé avec un corps vide et le reste de votre charge utile est déposé, sans erreur. Donnez un autre nom au champ, par exemple httpStatus.

Erreurs (Errors)

Générez FunctionError pour échouer avec un statut et un message spécifiques:

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

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

Une erreur non détectée devient une erreur 500. Lorsque la fonction s'exécute en tant que tâche, une erreur générée échoue dans la tâche et le message atteint le résultat de la tâche.

Journalisation

Utilisez l’enregistreur SDK afin que la sortie soit attribuée à l’exécution et atteigne les journaux de tâche Orchestrator:

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

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

La sortie console.* n’est pas transférée. Les valeurs secrètes ne doivent jamais être journalisées.

Prochaines étapes

• Déclencheurs et routage HTTP
• Contexte de la fonction — identité, coordonnées de la plateforme et données de la demande.
• defineFunction référence — chaque champ et ses valeurs par défaut.