Définition de critères d'achèvement à l'aide de la scrutation

Pour une tâche REST qui appelle une opération d'API REST de longue durée, cochez la case Configurer une condition de scrutation et d'arrêt pour un appel REST sans attente à l'étape Spécifier les critères d'achèvement afin de spécifier la configuration de scrutation pour identifier l'achèvement de l'appel REST.

En plus de la condition de réussite, la configuration de scrutation inclut une URL et une condition REST de scrutation, ainsi que des valeurs d'intervalle de scrutation et de temporisation de scrutation.

Vous pouvez éventuellement spécifier une configuration d'arrêt pour annuler l'opération d'API de longue durée.

Pour utiliser la réponse d'API de l'étape d'exécution dans la configuration de scrutation ou d'arrêt, créez des expressions, puis ajoutez les expressions nommées dans les URL de scrutation et d'arrêt, ainsi que les conditions de scrutation et de réussite.

Avant de configurer la scrutation ou l'arrêt, créez les expressions pour extraire les valeurs de réponse d'API dont vous avez besoin.

Voir aussi Scrutation dans les opérations de longue durée.

Ajout d'expressions à utiliser dans la scrutation

Les expressions permettent d'affecter une valeur ou une expression à une variable que vous pouvez ensuite utiliser lors de la configuration de critères d'achèvement.

Créez des expressions qui utilisent la réponse de l'API à l'étape d'exécution REST. Vous indiquez un nom pour l'expression lorsque vous la créez. Pour inclure l'expression nommée dans l'URL de scrutation ou d'arrêt, ou dans la condition de scrutation ou de réussite, utilisez la syntaxe #{expression_name}.

Par exemple, si la tâche REST appelle l'opération d'API pour créer un projet à l'aide d'un nom de projet spécifique, la demande de scrutation peut vérifier la clé de projet pour déterminer si la scrutation continue ou s'arrête. Pour utiliser la clé de projet en tant que variable dans l'URL de scrutation, créez une expression qui extrait la clé des données utiles de la réponse de l'API et la convertit en valeur de type de données Chaîne ou JSON_TEXT.

Notez qu'une expression que vous créez ici ne peut pas être utilisée comme sortie de tâche REST dans d'autres opérateurs qui sont en aval de la tâche.

Pour ajouter une expression :

  1. Dans la page Configurer les détails de l'API REST, étape Spécifier les critères d'achèvement, cochez la case Configurer une condition de scrutation et d'arrêt pour un appel REST sans attente.
  2. Développez la section Expressions, puis sélectionnez Ajouter une expression.
  3. Dans le panneau Ajouter une expression, section Informations sur l'expression :
    1. Entrez un nom pour l'expression dans le champ Identificateur.
    2. Dans le menu Type de données, sélectionnez un type pour l'expression.
    3. Remplissez les champs de propriété pour le type de données que vous avez sélectionné. Par exemple, entrez une longueur pour le type de données STRING.
  4. Dans la section Générateur d'expressions, vous pouvez construire visuellement une expression en cliquant deux fois sur les sorties, les paramètres ou les fonctions des réponses entrantes ou en les faisant glisser pour les ajouter à l'éditeur pour créer l'expression. Vous pouvez également rédiger manuellement l'expression. Créez une expression qui utilise la sortie de la réponse de la demande REST.
    • Entrant : Vous pouvez utiliser les sorties du système SYS.RESPONSE_PAYLOAD_JSON, SYS.RESPONSE_HEADERS_JSON et SYS.RESPONSE_STATUS.

    • Paramètres : Vous pouvez utiliser tout paramètre défini dans la portée de cette tâche REST. Voir Consultation et gestion des paramètres d'une tâche REST.

    • Fonctions : Vous pouvez utiliser les fonctions de base de type chaîne et opérateur du service d'intégration de données.

    Les fonctions ne sont pas toutes prises en charge lors de la création de l'expression. Voir la liste des fonctions prises en charge.

    Pour extraire les valeurs de propriété JSON du corps de réponse de l'API, utilisez la fonction de chaîne json_path avec la sortie de réponse entrante SYS.RESPONSE_PAYLOAD. Par exemple :

    CAST(json_path(SYS.RESPONSE_PAYLOAD_JSON, '$.key') AS String)
    CAST(json_path(SYS.RESPONSE_PAYLOAD_JSON, '$.emp.ID') AS JSON_TEXT)
  5. Sélectionnez Ajouter.
Modification ou suppression d'expressions dans la scrutation

Vous pouvez modifier et supprimer des expressions que vous avez créées dans la scrutation.

Pour modifier ou supprimer une expression :

  1. Dans la page Configurer les détails de l'API REST, étape Indiquer les critères d'achèvement, développez la section Expressions.
  2. Dans le tableau Expressions, recherchez l'expression à modifier ou à supprimer.
  3. Dans le menu Actions (Menu Actions) de l'expression, sélectionnez Modifier ou Supprimer.
    • Dans le panneau Modifier l'expression, effectuez les modifications, puis sélectionnez Enregistrer.
    • Dans la boîte de dialogue Supprimer l'expression, vérifiez que l'expression nommée est celle que vous voulez supprimer, puis sélectionnez Supprimer.
Configuration de la méthode HTTP et de l'URL de scrutation

Dans une opération d'API de longue durée, définissez la méthode HTTP et l'URL pour sonder le statut de l'appel REST.

Comme pour l'URL REST à l'étape d'exécution, vous pouvez inclure des paramètres dans l'URL de scrutation à l'aide de la syntaxe ${parameter_name}.

En outre, vous pouvez inclure des expressions nommées à l'aide de la syntaxe #{expression_name}. Créez les expressions dont vous avez besoin avant de configurer l'URL de scrutation.

Pour configurer la méthode et l'URL de scrutation :

  1. Dans la page Configurer les détails de l'API REST, étape Spécifier les critères d'achèvement, cochez la case Configurer une condition de scrutation et d'arrêt pour un appel REST sans attente.
  2. Dans l'onglet Scrutation, sélectionnez la méthode HTTP à utiliser pour l'URL de scrutation.
  3. Dans le champ URL, entrez l'URL complète, puis appuyez sur Entrée.

    Si la syntaxe de paramètre ${} est utilisée pour des parties de l'URL, ces parties sont converties en paramètres d'URL pour la tâche REST.

    Le tableau de l'onglet Paramètres d'URL sous le champ URL est mis à jour avec les parties paramétrées. Par défaut, chaque paramètre d'URL est de type chaîne.

    Si vous modifiez l'URL à tout moment en ajoutant ou en supprimant une syntaxe de paramètre, la table des paramètres d'URL est mise à jour en conséquence.

  4. Pour affecter une valeur par défaut à un paramètre, voir Configuration des paramètres d'URL.
  5. Pour afficher ou masquer l'URL de consultation à l'aide des valeurs de paramètre par défaut que vous avez configurées, sélectionnez Afficher l'URL de consultation ou Masquer l'URL de consultation.
  6. Pour ajouter un en-tête, voir Ajout et gestion d'un en-tête.
  7. Si un corps de demande est requis, voir Définition d'un corps de demande.
Spécification de la condition de scrutation

La configuration de scrutation comprend une condition de scrutation, une valeur d'intervalle de scrutation et une valeur de temporisation de scrutation.

La condition de scrutation est une expression qui détermine si la scrutation s'arrête ou continue. Lorsque l'expression retourne la valeur Faux, la scrutation s'arrête.

Le service d'intégration de données émet un appel de sondage de façon répétée selon l'intervalle de sondage spécifié jusqu'à ce que la valeur de temporisation de sondage spécifiée soit atteinte, ou jusqu'à ce que la condition de sondage retourne la valeur Faux, selon ce qui se produit en premier.

Pour configurer la condition de scrutation :

  1. Dans la page Configurer les détails de l'API REST, étape Spécifier les critères d'achèvement, cochez la case Configurer une condition de scrutation et d'arrêt pour un appel REST sans attente.
  2. Dans l'onglet Scrutation, section Conditions, effectuez les opérations suivantes :
    1. À côté de Condition de scrutation, sélectionnez Créer.
    2. Dans le panneau Créer une condition de sondage, entrez une expression qui utilise la sortie de la réponse à la demande REST.

      L'expression de condition peut inclure les éléments suivants :

      • Entrant : Sorties de réponse entrante (par exemple, SYS.RESPONSE_PAYLOAD_JSON, SYS.RESPONSE_HEADERS_JSON, SYS.RESPONSE_STATUS).

      • Paramètres : Paramètres définis dans la portée de cette tâche REST. Voir Consultation et gestion des paramètres d'une tâche REST.

      • Fonctions : Fonctions de base d'intégration de données de chaîne et d'opérateur. La fonction json_path (Chaîne) vous permet d'extraire les valeurs de propriété de la réponse à l'aide d'éléments de syntaxe JSONPath au format : json_path(json_string, json_filter_path)

      Par exemple : CAST(json_path(SYS.RESPONSE_PAYLOAD, '$.name') AS String) != 'My_Project'

  3. Dans la section Conditions, sous Condition de programmation, entrez une valeur et sélectionnez une unité de mesure pour Intervalle de programmation et Temporisation de programmation.
    • Temporisation de scrutation : Temps maximal autorisé pour qu'une scrutation répétée ait lieu selon l'intervalle spécifié. La valeur de temporisation doit être supérieure ou égale à 120 secondes mais inférieure ou égale à 30 jours.
    • Intervalle de sondage : Durée d'attente avant l'envoi de la demande de sondage suivante. La valeur d'intervalle doit être supérieure ou égale à 60 secondes et inférieure à la valeur de temporisation spécifiée.
  4. Pour affecter un paramètre de tâche à la condition, sélectionnez Affecter un paramètre. Voir Paramétrage de la condition de scrutation.
Paramétrage de la condition de scrutation

Après avoir ajouté une condition de scrutation, vous pouvez affecter un paramètre de tâche à la condition.

Pour paramétrer la condition de scrutation dans une tâche REST :

  1. Dans la page Configurer les détails de l'API REST, allez à l'étape Spécifier les critères d'achèvement.
  2. Dans le bloc Conditions, à côté de Condition de scrutation, sélectionnez Affecter un paramètre.
  3. Dans le panneau Ajouter un paramètre, entrez un nom pour le paramètre dans le champ Identificateur ou utilisez la valeur par défaut.

    Le nom du paramètre doit être unique dans la tâche REST. Pour obtenir la liste courante des paramètres de la tâche, voir Consultation de tous les paramètres d'une tâche REST.

  4. (Facultatif) Entrez une description pour aider les autres utilisateurs à identifier la fonction du paramètre.
  5. Le type du paramètre est Expression, et ne peut pas être modifié.
  6. Dans le générateur de conditions, définissez l'expression de condition par défaut pour ce paramètre. Cette condition par défaut est utilisée lors de l'exécution, à moins que vous ne modifiiez la valeur plus tard (au moment de la conception ou de l'exécution).

    L'expression de condition peut inclure les éléments suivants :

    • Entrant : Sorties de réponse entrante (par exemple, SYS.RESPONSE_PAYLOAD_JSON, SYS.RESPONSE_HEADERS_JSON, SYS.RESPONSE_STATUS).

    • Paramètres : Paramètres définis dans la portée de cette tâche REST. Voir Consultation et gestion des paramètres d'une tâche REST.

    • Fonctions : Fonctions de base d'intégration de données de chaîne et d'opérateur. La fonction json_path (Chaîne) vous permet d'extraire les valeurs de propriété de la réponse à l'aide d'éléments de syntaxe JSONPath au format : json_path(json_string, json_filter_path)

    Par exemple : CAST(json_path(SYS.RESPONSE_PAYLOAD, '$.name') AS String) != 'My_Project'

  7. Sélectionnez Ajouter.
    Le nom du paramètre est ajouté à côté de la condition de scrutation.
Modification du paramètre de condition de scrutation

Vous pouvez modifier la description et la valeur par défaut du paramètre de tâche de la condition de scrutation.

Pour modifier la condition de scrutation paramétrée :

  1. Dans la page Configurer les détails de l'API REST, allez à l'étape Spécifier les critères d'achèvement.
  2. Dans le bloc Conditions, sélectionnez Modifier le paramètre.
  3. Dans le panneau Modifier le paramètre, vous pouvez modifier uniquement la description et l'expression de la condition de scrutation. Vous ne pouvez pas modifier l'identificateur (nom) et le type de données.
  4. Sélectionnez Enregistrer les modifications.
Suppression du paramètre de condition de scrutation

La suppression du paramètre de condition supprime uniquement l'association du paramètre à la condition de scrutation spécifiée pour la tâche REST.

Pour annuler l'affectation du paramètre à la condition de scrutation :

  1. Dans la page Configurer les détails de l'API REST, allez à l'étape Spécifier les critères d'achèvement.
  2. Dans le bloc Conditions, sélectionnez Supprimer le paramètre.
  3. Dans la boîte de dialogue Supprimer le paramètre, sélectionnez Supprimer.

    L'affectation du paramètre à la condition de scrutation est annulée. L'expression de condition affectée au paramètre devient la condition de scrutation par défaut pour la tâche REST.

    Note

    Le paramètre n'est pas supprimé de la tâche REST. Pour supprimer le paramètre, voir Suppression d'un paramètre de tâche REST.
Configuration de la méthode HTTP et de l'URL d'arrêt

Pour une tâche REST qui appelle une opération d'API REST de longue durée, vous pouvez spécifier les détails de l'API REST pour mettre fin à l'opération de longue durée.

Dans l'onglet Arrêt, définissez la méthode HTTP et l'URL pour mettre fin à l'appel REST.

Comme pour l'URL de scrutation, vous pouvez inclure des paramètres et des expressions dans l'URL d'arrêt à l'aide de la syntaxe ${parameter_name} et #{expression_name}. Créez les expressions dont vous avez besoin avant de configurer l'URL d'arrêt.

Pour configurer la méthode d'arrêt et l'URL :

  1. Dans la page Configurer les détails de l'API REST, étape Spécifier les critères d'achèvement, cochez la case Configurer une condition de scrutation et d'arrêt pour un appel REST sans attente.
  2. Dans l'onglet Arrêt, sélectionnez la méthode HTTP à utiliser pour l'URL.
  3. Dans le champ URL, entrez l'URL complète, puis appuyez sur Entrée.

    Si la syntaxe de paramètre ${} est utilisée pour des parties de l'URL, ces parties sont converties en paramètres d'URL pour la tâche REST.

    Le tableau de l'onglet Paramètres d'URL sous le champ URL est mis à jour avec les parties paramétrées. Par défaut, chaque paramètre d'URL est de type chaîne.

    Si vous modifiez l'URL à tout moment en ajoutant ou en supprimant une syntaxe de paramètre, la table des paramètres d'URL est mise à jour en conséquence.

  4. Pour affecter une valeur par défaut à un paramètre, voir Configuration des paramètres d'URL.
  5. Pour afficher ou masquer l'URL à l'aide des valeurs de paramètre par défaut que vous avez configurées, sélectionnez Afficher l'URL de prévisualisation ou Masquer l'URL de prévisualisation.
  6. Pour ajouter un en-tête, voir Ajout et gestion d'un en-tête.
  7. Si un corps de demande est requis, voir Définition d'un corps de demande.
Définition des critères d'achèvement (condition de réussite)

La condition de réussite d'une tâche REST est une expression qui détermine l'achèvement réussi de l'appel d'API REST. La scrutation s'arrête lorsque la condition de réussite est satisfaite.

Par défaut, le service d'intégration de données fournit une condition de réussite pour une tâche REST. La condition de réussite par défaut est un code de statut HTTP de 200 ou supérieur, mais inférieur à 300. Elle est exprimée par l'expression suivante :

SYS.RESPONSE_STATUS >= 200 AND SYS.RESPONSE_STATUS < 300

L'expression de la condition de réussite référence la sortie de la réponse JSON à la demande REST définie à l'étape d'exécution.

Vous pouvez utiliser la condition de réussite par défaut ou écrire une expression de condition à l'aide des sorties du système ou extraire des valeurs de propriété JSON de la réponse.

Pour modifier la condition de réussite :

  1. Dans la page Configurer les détails de l'API REST, allez à l'étape Spécifier les critères d'achèvement.
  2. Si l'API REST appelle une opération de longue durée, cochez la case Configurer une condition de scrutation et d'arrêt pour un appel REST sans attente.
  3. Dans le bloc Conditions, à côté de condition de réussite, sélectionnez Modifier.
  4. Dans le panneau Modifier la condition de réussite, entrez une expression qui utilise la sortie de la réponse à la demande REST.

    L'expression de condition peut inclure les éléments suivants :

    • Entrant : Vous pouvez utiliser les sorties de réponse entrante (par exemple, SYS.RESPONSE_PAYLOAD_JSON, SYS.RESPONSE_HEADERS_JSON, SYS.RESPONSE_STATUS).

    • Paramètres : Vous pouvez utiliser tout paramètre défini dans la portée de cette tâche REST. Voir Consultation et gestion des paramètres d'une tâche REST.

    • Fonctions : Vous pouvez utiliser les fonctions de base de type chaîne et opérateur du service d'intégration de données. La fonction json_path (Chaîne) vous permet d'extraire les valeurs de propriété de la réponse à l'aide d'éléments de syntaxe JSONPath au format : json_path(json_string, json_filter_path)

      Par exemple : json_path(SYS.RESPONSE_PAYLOAD, '$.@STATUS')

    Toutes les fonctions ne sont pas prises en charge dans une expression de condition de réussite. Voir la liste des fonctions prises en charge.

    (Pour les opérations de longue durée) Si vous avez coché la case Configurer une condition de scrutation et d'arrêt pour un appel REST sans attente, la condition de réussite est une expression écrite dans la réponse à la demande de scrutation. Vous pouvez créer des expressions qui utilisent la réponse d'API de l'étape d'exécution, puis inclure les expressions nommées pour créer la condition de réussite.

  5. Pour affecter un paramètre de tâche à la condition de réussite, sélectionnez Affecter un paramètre. Voir Paramétrage de la condition de réussite.