Documentation Oracle Cloud Infrastructure

Fourniture de critères de fin à l'aide de l'interrogation

Pour une tâche REST qui appelle une opération d'API REST à longue exécution, sélectionnez la case à cocher Configurer une condition d'interrogation et de terminaison pour un appel REST sans attente à l'étape Indiquer des critères de fin afin de spécifier la configuration d'interrogation permettant d'identifier la fin de l'appel REST.

En plus de la condition de réussite, la configuration d'interrogation inclut une condition et une URL REST d'interrogation, ainsi que des valeurs pour l'intervalle d'interrogation et le délai d'expiration d'interrogation.

Vous pouvez éventuellement indiquer une configuration de terminaison pour annuler l'opération d'API à longue durée d'exécution.

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

Avant de configurer l'interrogation ou la terminaison, créez les expressions permettant d'extraire les valeurs de réponse d'API dont vous avez besoin.

Reportez-vous également à Interrogation dans des opérations à longue durée d'exécution.

Ajout d'expressions à utiliser lors de l'interrogation

Les expressions permettent d'affecter une valeur ou une expression à une variable que vous pouvez ensuite utiliser lors de la configuration de l'étape des critères de fin.

Créez des expressions qui utilisent la réponse d'API de l'étape d'exécution REST. Vous indiquez le nom de l'expression lors de sa création. Pour inclure l'expression nommée dans l'URL d'interrogation ou de terminaison, ou la condition d'interrogation 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 avec un nom de projet spécifique, la demande d'interrogation peut vérifier la clé du projet pour déterminer si l'interrogation continue ou s'arrête. Pour utiliser la clé de projet comme variable dans l'URL d'interrogation, créez une expression qui extrait la clé de la réponse de charge utile d'API en la transformant 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 en tant que sortie de tâche REST dans d'autres opérateurs en aval de la tâche.

Pour ajouter une expression, procédez comme suit :

  1. Sur la page Configurer les détails de l'API REST, à l'étape Indiquer des critères de fin, cochez la case Configurer une condition d'interrogation et de terminaison 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, dans la section Informations sur l'expression, procédez comme suit :
    1. Entrez le nom de l'expression dans le champ Utilisateur.
    2. Dans le menu Type de données, sélectionnez un type pour cette expression.
    3. Remplissez les champs de propriété pour le type de données 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 des sorties, paramètres ou fonctions de réponse entrants ou les glisser-déplacer pour les ajouter à l'éditeur afin de créer l'expression. Vous pouvez aussi écrire l'expression vous-même manuellement. Créez une expression qui utilise la sortie de la réponse de la demande REST.

    • Entrant : vous pouvez utiliser les sorties système SYS.RESPONSE_PAYLOAD_JSON, SYS.RESPONSE_HEADERS_JSON et SYS.RESPONSE_STATUS.

    • Paramètres : vous pouvez utiliser n'importe quel paramètre défini dans la portée de la tâche REST. Reportez-vous à Affichage et gestion des paramètres dans une tâche REST.

    • Fonctions : vous pouvez utiliser les fonctions Data Integration de chaînes et d'opérateur de base.

    Toutes les fonctions ne sont pas prises en charge lors de la création de l'expression. Reportez-vous à la liste prise en charge.

    Pour extraire les valeurs de propriété JSON du corps de réponse d'API, utilisez la fonction json_path de chaîne 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 l'interrogation

Vous pouvez modifier et supprimer les expressions que vous avez créées dans l'interrogation.

Pour modifier ou supprimer une expression, procédez comme suit :

  1. Sur la page Configurer les détails de l'API REST, étape Indiquer des critères de fin, développez la section Expressions.
  2. Dans la table 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, apportez les modifications voulus, puis sélectionnez Enregistrer.
    • Dans la boîte Supprimer l'expression, vérifiez que l'expression nommée est celle à supprimer, puis sélectionnez Supprimer.
Configuration de l'URL et de la méthode HTTP d'interrogation

Dans une opération d'API à longue durée d'exécution, définissez la méthode HTTP et l'URL servant à interroger le statut de l'appel REST.

Comme pour l'URL REST lors de l'étape d'exécution, vous pouvez inclure des paramètres dans l'URL d'interrogation à 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 d'interrogation.

Pour configurer la méthode et l'URL d'interrogation, procédez comme suit :

  1. Sur la page Configurer les détails de l'API REST, à l'étape Indiquer des critères de fin, cochez la case Configurer une condition d'interrogation et de terminaison pour un appel REST sans attente.
  2. Dans l'onglet Interrogation, sélectionnez la méthode HTTP à utiliser pour l'URL d'interrogation.
  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 transformées en paramètres d'URL pour la tâche REST.

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

    Si vous modifiez l'URL à un moment donné en ajoutant ou en supprimant la 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, reportez-vous à Configuration des paramètres d'URL.
  5. Pour afficher ou masquer l'URL d'interrogation avec la valeur par défaut de paramètre que vous avez configurée, sélectionnez Afficher l'URL d'aperçu ou Masquer l'URL d'aperçu.
  6. Pour ajouter un en-tête, reportez-vous à Ajout et gestion d'un en-tête.
  7. Si un corps de demande est requis, reportez-vous à Fourniture d'un corps de demande.
Spécification de la condition d'interrogation

La configuration d'interrogation inclut une condition d'interrogation, ainsi que des valeurs pour l'intervalle d'interrogation et le délai d'expiration d'interrogation.

La condition d'interrogation est une expression qui détermine si l'interrogation s'arrête ou se poursuit. Lorsque l'expression renvoie la valeur False, l'interrogation s'arrête.

Data Integration émet un appel d'interrogation répété à l'intervalle d'interrogation spécifié jusqu'à ce que la valeur du délai d'expiration d'interrogation spécifiée soit atteinte ou jusqu'à ce que la condition d'interrogation renvoie la valeur False, selon l'événement qui survient en premier.

Pour configurer la condition d'interrogation, procédez comme suit :

  1. Sur la page Configurer les détails de l'API REST, à l'étape Indiquer des critères de fin, cochez la case Configurer une condition d'interrogation et de terminaison pour un appel REST sans attente.
  2. Dans l'onglet Interrogation, dans la section Conditions, procédez comme suit :
    1. En regard de Condition d'interrogation, sélectionnez Créer.
    2. Dans le panneau Créer une condition d'interrogation, entrez une expression qui utilise la sortie de la réponse de la demande REST.

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

      • Entrantes : sorties de réponse entrantes (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. Reportez-vous à Affichage et gestion des paramètres dans une tâche REST.

      • Fonctions : fonctions d'intégration de chaînes et de données d'opérateur de base. La fonction json_path, qui se trouve sous Chaîne, permet d'extraire les valeurs de propriété de la réponse à l'aide des éléments de syntaxe JSONPath au format suivant : 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 Conditions d'interrogation, entrez une valeur et choisissez une unité de mesure pour l'intervalle d'interrogation et le expiration d'interrogation.
    • expiration de l'interrogation : durée maximale autorisée pour la réalisation d'interrogations répétées à la fréquence d'intervalle spécifiée. La valeur du délai d'expiration doit être supérieure ou égale à 120 secondes, mais inférieure ou égale à 30 jours.
    • Intervalle d'interrogation : durée d'attente avant l'envoi de la demande d'interrogation suivante. La valeur de l'intervalle doit être supérieure ou égale à 60 secondes, et inférieure à la valeur de délai d'expiration spécifiée.
  4. Pour affecter un paramètre de tâche à la condition, sélectionnez Affecter le paramètre. Reportez-vous à Paramétrage de la condition d'interrogation.
Paramétrage de la condition d'interrogation

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

Pour paramétrer la condition d'interrogation dans une tâche REST, procédez comme suit :

  1. Sur la page Configurer les détails de l'API REST, accédez à l'étape Indiquer des critères de fin.
  2. Dans le bloc Conditions, en regard de Condition d'interrogation, sélectionnez Affecter le paramètre.
  3. Dans le panneau Ajouter un paramètre, entrez le nom du 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 des paramètres en cours dans la tâche, reportez-vous à Affichage de tous les paramètres d'une tâche REST.

  4. (Facultatif) Entrez une description afin d'identifier l'objectif du paramètre pour les autres utilisateurs.
  5. Le type du paramètre est Expression, et vous ne pouvez pas le modifier.
  6. Dans le générateur de condition, 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, sauf si vous modifiez la valeur ultérieurement (au moment de la conception ou de l'exécution).

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

    • Entrantes : sorties de réponse entrantes (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. Reportez-vous à Affichage et gestion des paramètres dans une tâche REST.

    • Fonctions : fonctions d'intégration de chaînes et de données d'opérateur de base. La fonction json_path, qui se trouve sous Chaîne, permet d'extraire les valeurs de propriété de la réponse à l'aide des éléments de syntaxe JSONPath au format suivant : 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é en regard de la condition d'interrogation.
Modification du paramètre de condition d'interrogation

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

Pour modifier la condition d'interrogation paramétrée, procédez comme suit :

  1. Sur la page Configurer les détails de l'API REST, accédez à l'étape Indiquer des critères de fin.
  2. Dans le bloc Conditions, sélectionnez Modifier le paramètre.
  3. Dans le panneau Modifier le paramètre, vous pouvez uniquement modifier la description et l'expression de la condition d'interrogation. 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 d'interrogation

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

Pour annuler l'affectation du paramètre à la condition d'interrogation, procédez comme suit :

  1. Sur la page Configurer les détails de l'API REST, accédez à l'étape Indiquer des critères de fin.
  2. Dans le bloc Conditions, sélectionnez Enlever le paramètre.
  3. Dans la boîte de dialogue Enlever le paramètre, sélectionnez Enlever.

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

    Remarque

    Le paramètre n'est pas supprimé de la tâche REST. Pour supprimer le paramètre, reportez-vous à Suppression d'un paramètre de tâche REST.
Configuration de l'URL et de la méthode HTTP de terminaison

Pour une tâche REST qui appelle une opération d'API REST à longue durée d'exécution, vous pouvez indiquer les détails de l'API REST pour la terminaison de l'opération à longue durée d'exécution.

Dans l'onglet Terminaison, définissez la méthode HTTP et l'URL servant à mettre fin à l'appel REST.

Comme pour l'URL d'interrogation, vous pouvez inclure des paramètres et des expressions dans l'URL de terminaison en utilisant la syntaxe ${parameter_name} et #{expression_name}. Créez les expressions dont vous avez besoin avant de configurer l'URL de terminaison.

Pour configurer la méthode et l'URL de terminaison, procédez comme suit :

  1. Sur la page Configurer les détails de l'API REST, à l'étape Indiquer des critères de fin, cochez la case Configurer une condition d'interrogation et de terminaison pour un appel REST sans attente.
  2. Dans l'onglet Fin de contrat, 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 transformées en paramètres d'URL pour la tâche REST.

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

    Si vous modifiez l'URL à un moment donné en ajoutant ou en supprimant la 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, reportez-vous à Configuration des paramètres d'URL.
  5. Pour afficher ou masquer l'URL avec la valeur par défaut de paramètre que vous avez configurée, sélectionnez Afficher l'URL d'aperçu ou Masquer l'URL d'aperçu.
  6. Pour ajouter un en-tête, reportez-vous à Ajout et gestion d'un en-tête.
  7. Si un corps de demande est requis, reportez-vous à Fourniture d'un corps de demande.
Spécification des critères de fin (condition de réussite)

La condition de réussite d'une tâche REST est une expression qui détermine la réussite de l'appel d'API REST. L'interrogation s'arrête lorsque la condition de réussite est remplie.

Par défaut, Data Integration 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 supérieur ou égal à 200, mais inférieur à 300, écrit sous la forme de l'expression suivante :

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

L'expression de condition de réussite référence la sortie dans la réponse JSON reçue de la demande REST définie dans 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 système ou des valeurs de propriété JSON extraites de la réponse.

Pour modifier la condition de réussite, procédez comme suit :

  1. Sur la page Configurer les détails de l'API REST, accédez à l'étape Indiquer des critères de fin.
  2. Si l'API REST appelle une opération à longue durée d'exécution, cochez la case Configurer une condition d'interrogation et de terminaison pour un appel REST sans attente.
  3. Dans le bloc Conditions, en regard de Conditions 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 de la demande REST.

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

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

    • Paramètres : vous pouvez utiliser n'importe quel paramètre défini dans la portée de la tâche REST. Reportez-vous à Affichage et gestion des paramètres dans une tâche REST.

    • Fonctions : vous pouvez utiliser les fonctions Data Integration de chaînes et d'opérateur de base. La fonction json_path, qui se trouve sous Chaîne, permet d'extraire les valeurs de propriété de la réponse à l'aide des éléments de syntaxe JSONPath au format suivant : 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. Reportez-vous à la liste prise en charge.

    (Pour les opérations à longue durée d'exécution) Si vous avez coché la case Configurer une condition d'interrogation et de terminaison pour un appel REST sans attente, la condition de réussite est une expression écrite sur la réponse de la demande d'interrogation. 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 le paramètre. Reportez-vous à Paramétrage de la condition de réussite.