Documentazione dell'infrastruttura Oracle Cloud

Fornire criteri di completamento mediante polling

Per un task REST che richiama un'operazione API REST con tempi di esecuzione lunghi, selezionare la casella di controllo Configura una condizione di polling e interruzione per una chiamata REST senza attesa nel passo Specifica criteri di completamento per specificare la configurazione di polling per identificare il completamento del richiamo REST.

Oltre alla condizione di operazione riuscita, la configurazione del polling include un URL e una condizione REST di polling e i valori per un intervallo di polling e un timeout di polling.

Facoltativamente, è possibile specificare una configurazione di interruzione per annullare l'operazione API con tempi di esecuzione lunghi.

Per utilizzare la risposta API dal passo di esecuzione nella configurazione di polling o interruzione, creare le espressioni e quindi includere le espressioni denominate negli URL di polling e interruzione, nonché le condizioni di polling e riuscita.

Prima di configurare il polling o l'interruzione, creare le espressioni per recuperare i valori di risposta API necessari.

Vedere anche Polling in operazioni con tempi di esecuzione lunghi.

Aggiunta di espressioni da utilizzare nel polling

Le espressioni consentono di assegnare un valore o un'espressione a una variabile che può essere quindi utilizzata durante la configurazione del passo dei criteri di completamento.

Crea espressioni che utilizzano la risposta API dal passo di esecuzione REST. Quando si crea un'espressione, viene fornito un nome. Per includere l'espressione denominata nell'URL di polling o interruzione oppure nella condizione di polling o operazione riuscita, utilizzare la sintassi #{expression_name}.

Ad esempio, se il task REST richiama l'operazione API per creare un progetto utilizzando un nome di progetto specifico, la richiesta di polling può controllare la chiave del progetto per determinare se il polling continua o si interrompe. Per utilizzare la chiave progetto come variabile nell'URL di polling, creare un'espressione che estragga la chiave dalla risposta del payload API, convertendola in un valore di tipo dati String o JSON_TEXT.

Si noti che un'espressione creata qui non può essere utilizzata come output di task REST in altri operatori a valle del task.

Per aggiungere un'espressione:

  1. Nella pagina Configura dettagli API REST, nel passo Specifica criteri di completamento, selezionare la casella di controllo Configura una condizione di polling e interruzione per una chiamata REST senza attesa.
  2. Espandere la sezione Espressioni, quindi selezionare Aggiungi espressione.
  3. Nel pannello Aggiungi espressione, sezione Informazioni sull'espressione, effettuare le operazioni riportate di seguito.
    1. Immettere un nome per l'espressione nel campo Identificativo.
    2. Nel menu Tipo di dati selezionare un tipo per questa espressione.
    3. Completare i campi delle proprietà per il tipo di dati selezionato. Ad esempio, immettere una Lunghezza per il tipo di dati STRING.
  4. Nella sezione Costruzione guidata espressione è possibile creare visivamente un'espressione facendo doppio clic o trascinando gli output, i parametri o le funzioni delle risposte in entrata da aggiungere all'editor per creare l'espressione. In alternativa, è possibile scrivere manualmente l'espressione. Crea un'espressione che utilizza l'output della risposta della richiesta REST.

    • In entrata: è possibile utilizzare gli output di sistema SYS.RESPONSE_PAYLOAD_JSON, SYS.RESPONSE_HEADERS_JSON e SYS.RESPONSE_STATUS.

    • Parametri: è possibile utilizzare qualsiasi parametro definito nell'ambito di questo task REST. Vedere Visualizzazione e gestione dei parametri in un task REST.

    • Funzioni: è possibile utilizzare le funzioni di base String e Operator Data Integration.

    Non tutte le funzioni sono supportate durante la creazione dell'espressione. Vedere la lista supportata qui.

    Per estrarre i valori delle proprietà JSON dal corpo della risposta API, utilizzare la funzione String json_path con l'output della risposta in entrata SYS.RESPONSE_PAYLOAD. Ad esempio:

    CAST(json_path(SYS.RESPONSE_PAYLOAD_JSON, '$.key') AS String)
    CAST(json_path(SYS.RESPONSE_PAYLOAD_JSON, '$.emp.ID') AS JSON_TEXT)
  5. Selezionare Aggiungi.
Modifica o eliminazione delle espressioni nel polling

È possibile modificare ed eliminare le espressioni create durante il polling.

Per modificare o eliminare un'espressione:

  1. Nella pagina Configura dettagli API REST, nel passo Specifica criteri di completamento, espandere la sezione Espressioni.
  2. Nella tabella Espressioni, individuare l'espressione che si desidera modificare o eliminare.
  3. Nel menu Azioni (Menu Azioni) dell'espressione, selezionare Modifica o Elimina.
    • Nel pannello Modifica espressione apportare le modifiche desiderate, quindi selezionare Salva.
    • Nella finestra di dialogo Elimina espressione confermare che l'espressione denominata è quella che si desidera eliminare, quindi selezionare Elimina.
Configurazione del metodo e dell'URL HTTP di polling

In un'operazione API con tempi di esecuzione lunghi, definire il metodo HTTP e l'URL per eseguire il polling dello stato della chiamata REST.

Analogamente all'URL REST nel passo di esecuzione, è possibile includere i parametri nell'URL di polling utilizzando la sintassi ${parameter_name}.

È inoltre possibile includere espressioni denominate utilizzando la sintassi #{expression_name}. Creare le espressioni necessarie prima di configurare l'URL di polling.

Per configurare il metodo e l'URL di polling, procedere come segue.

  1. Nella pagina Configura dettagli API REST, nel passo Specifica criteri di completamento, selezionare la casella di controllo Configura una condizione di polling e interruzione per una chiamata REST senza attesa.
  2. Nella scheda Polling, selezionare il metodo HTTP da utilizzare per l'URL di polling.
  3. Nel campo URL, immettere l'URL completo, quindi premere Invio.

    Se si utilizza la sintassi del parametro ${} per parti dell'URL, tali parti vengono convertite in parametri URL per il task REST.

    La tabella nella scheda Parametri URL sotto il campo URL viene aggiornata con le parti con parametri. Il tipo di dati predefinito per ogni parametro URL è String.

    Se si modifica l'URL in qualsiasi momento aggiungendo o rimuovendo la sintassi dei parametri, la tabella dei parametri URL viene aggiornata di conseguenza.

  4. Per assegnare un valore predefinito a un parametro, vedere Configurazione dei parametri URL.
  5. Per mostrare o nascondere l'URL di polling utilizzando i valori predefiniti dei parametri configurati, selezionare Mostra URL anteprima o Nascondi URL anteprima.
  6. Per aggiungere un'intestazione, vedere Aggiunta e gestione di un'intestazione.
  7. Se è necessario un corpo della richiesta, vedere Fornitura di un corpo della richiesta.
Specifica della condizione di polling

La configurazione del polling include una condizione di polling e i valori per un intervallo di polling e un timeout di polling.

La condizione di polling è un'espressione che determina se il polling si arresta o continua. Quando l'espressione restituisce false, il polling viene interrotto.

Integrazione dei dati genera ripetutamente una chiamata di polling all'intervallo di polling specificato fino al raggiungimento del valore per il timeout di polling specificato o fino a quando la condizione di polling non restituisce false, a seconda di quale delle due condizioni si verifica per prima.

Per configurare la condizione di polling, effettuare le operazioni riportate di seguito.

  1. Nella pagina Configura dettagli API REST, nel passo Specifica criteri di completamento, selezionare la casella di controllo Configura una condizione di polling e interruzione per una chiamata REST senza attesa.
  2. Nella scheda Polling, sezione Condizioni, effettuare le operazioni riportate di seguito.
    1. Accanto a Condizione di polling, selezionare Crea.
    2. Nel pannello Crea condizione di polling, immettere un'espressione che utilizza l'output della risposta della richiesta REST.

      L'espressione della condizione può includere i seguenti elementi:

      • In entrata: output di risposta in entrata (ad esempio, SYS.RESPONSE_PAYLOAD_JSON, SYS.RESPONSE_HEADERS_JSON, SYS.RESPONSE_STATUS).

      • Parametri: parametri definiti nell'ambito di questo task REST. Vedere Visualizzazione e gestione dei parametri in un task REST.

      • Funzioni: funzioni Basic String e Operator Data Integration. La funzione json_path, disponibile in String, consente di estrarre i valori delle proprietà dalla risposta utilizzando gli elementi della sintassi JSONPath nel formato: json_path(json_string, json_filter_path)

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

  3. Nella sezione Condizioni, sotto Condizione di polling, immettere un valore e scegliere un'unità di misura per Intervallo di polling e Timeout di polling.
    • Timeout di polling: il periodo di tempo massimo consentito per il polling ripetuto alla frequenza di intervallo specificata. Il valore di timeout deve essere maggiore o uguale a 120 secondi, ma minore o uguale a 30 giorni.
    • Intervallo di polling: il periodo di tempo di attesa prima dell'invio della richiesta di polling successiva. Il valore dell'intervallo deve essere maggiore o uguale a 60 secondi e minore del valore di timeout specificato.
  4. Per assegnare un parametro task alla condizione, selezionare Assegna parametro. Vedere Parametrizzazione della condizione di polling.
Parametrizzazione della condizione di polling

Dopo aver aggiunto una condizione di polling, è possibile assegnare un parametro di task alla condizione.

Per parametrizzare la condizione di polling in un task REST:

  1. Nella pagina Configura dettagli API REST, andare al passo Specifica criteri di completamento.
  2. Nel blocco Condizioni, accanto a Condizione di polling, selezionare Assegna parametro.
  3. Nel pannello Aggiungi parametro, immettere un nome per il parametro nel campo Identificativo oppure utilizzare il valore predefinito.

    Il nome del parametro deve essere univoco nel task REST. Per un elenco corrente dei parametri nel task, vedere Visualizzazione di tutti i parametri in un task REST.

  4. (Facoltativo) Immettere una descrizione per facilitare l'identificazione dello scopo del parametro per gli altri utenti.
  5. Il tipo del parametro è Espressione, che non è possibile modificare.
  6. In Condition builder, impostare l'espressione di condizione predefinita per questo parametro. Questa condizione predefinita viene utilizzata in runtime, a meno che non si modifichi il valore in un secondo momento (in fase di progettazione o in runtime).

    L'espressione della condizione può includere i seguenti elementi:

    • In entrata: output di risposta in entrata (ad esempio, SYS.RESPONSE_PAYLOAD_JSON, SYS.RESPONSE_HEADERS_JSON, SYS.RESPONSE_STATUS).

    • Parametri: parametri definiti nell'ambito di questo task REST. Vedere Visualizzazione e gestione dei parametri in un task REST.

    • Funzioni: funzioni Basic String e Operator Data Integration. La funzione json_path, disponibile in String, consente di estrarre i valori delle proprietà dalla risposta utilizzando gli elementi della sintassi JSONPath nel formato: json_path(json_string, json_filter_path)

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

  7. Selezionare Aggiungi.
    Il nome del parametro viene aggiunto accanto alla condizione di polling.
Modifica del parametro della condizione di polling

È possibile modificare la descrizione e il valore predefinito del parametro del task per la condizione di polling.

Per modificare la condizione di polling con parametri:

  1. Nella pagina Configura dettagli API REST, andare al passo Specifica criteri di completamento.
  2. Nel blocco Condizioni selezionare Modifica parametro.
  3. Nel pannello Modifica parametro è possibile modificare solo la descrizione e l'espressione per la condizione di polling. Non è possibile modificare l'identificativo (nome) e il tipo di dati.
  4. Selezionare Salva modifiche.
Rimozione del parametro della condizione di polling

La rimozione del parametro di condizione rimuove solo l'associazione del parametro alla condizione di polling specificata per il task REST.

Per annullare l'assegnazione del parametro dalla condizione di polling, effettuare le operazioni riportate di seguito.

  1. Nella pagina Configura dettagli API REST, andare al passo Specifica criteri di completamento.
  2. Nel blocco Condizioni selezionare Rimuovi parametro.
  3. Nella finestra di dialogo Rimuovi parametro selezionare Rimuovi.

    L'assegnazione del parametro alla condizione di polling è stata annullata. L'espressione di condizione assegnata al parametro diventa la condizione di polling predefinita per il task REST.

    Nota

    Il parametro non viene eliminato dal task REST. Per eliminare il parametro, vedere Eliminazione di un parametro di task REST.
Configurazione del metodo e dell'URL HTTP di cessazione

Per un task REST che richiama un'operazione API REST con tempi di esecuzione lunghi, è possibile specificare i dettagli dell'API REST per terminare l'operazione con tempi di esecuzione lunghi.

Nella scheda Cessazione definire il metodo HTTP e l'URL per terminare la chiamata REST.

Analogamente all'URL di polling, è possibile includere parametri ed espressioni nell'URL di interruzione utilizzando la sintassi ${parameter_name} e #{expression_name}. Creare le espressioni necessarie prima di configurare l'URL di interruzione.

Per configurare il metodo di interruzione e l'URL, effettuare le operazioni riportate di seguito.

  1. Nella pagina Configura dettagli API REST, nel passo Specifica criteri di completamento, selezionare la casella di controllo Configura una condizione di polling e interruzione per una chiamata REST senza attesa.
  2. Nella scheda Cessazione selezionare il metodo HTTP da utilizzare per l'URL.
  3. Nel campo URL, immettere l'URL completo, quindi premere Invio.

    Se si utilizza la sintassi del parametro ${} per parti dell'URL, tali parti vengono convertite in parametri URL per il task REST.

    La tabella nella scheda Parametri URL sotto il campo URL viene aggiornata con le parti con parametri. Il tipo di dati predefinito per ogni parametro URL è String.

    Se si modifica l'URL in qualsiasi momento aggiungendo o rimuovendo la sintassi dei parametri, la tabella dei parametri URL viene aggiornata di conseguenza.

  4. Per assegnare un valore predefinito a un parametro, vedere Configurazione dei parametri URL.
  5. Per mostrare o nascondere l'URL utilizzando i valori predefiniti dei parametri configurati, selezionare Mostra URL anteprima o Nascondi URL anteprima.
  6. Per aggiungere un'intestazione, vedere Aggiunta e gestione di un'intestazione.
  7. Se è necessario un corpo della richiesta, vedere Fornitura di un corpo della richiesta.
Specifica dei criteri di completamento (condizione riuscita)

La condizione di operazione riuscita in un task REST è un'espressione che determina il completamento riuscito della chiamata dell'API REST. Il polling si interrompe quando viene soddisfatta la condizione di operazione riuscita.

Per impostazione predefinita, Data Integration fornisce una condizione di operazione riuscita per un task REST. La condizione di operazione riuscita predefinita è un codice di stato HTTP uguale o superiore a 200 ma inferiore a 300, scritto come espressione riportata di seguito.

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

L'espressione della condizione di operazione riuscita fa riferimento all'output nella risposta JSON ricevuta dalla richiesta REST definita nel passo di esecuzione.

È possibile utilizzare la condizione di operazione riuscita predefinita oppure scrivere un'espressione di condizione utilizzando output di sistema o valori di proprietà JSON estratti dalla risposta.

Per modificare la condizione di operazione riuscita:

  1. Nella pagina Configura dettagli API REST, andare al passo Specifica criteri di completamento.
  2. Se l'API REST richiama un'operazione con tempi di esecuzione lunghi, selezionare la casella di controllo Configura una condizione di polling e interruzione per una chiamata REST senza attesa.
  3. Nel blocco Condizioni, accanto a Condizione riuscita, selezionare Modifica.
  4. Nel pannello Modifica condizione riuscita, immettere un'espressione che utilizza l'output della risposta della richiesta REST.

    L'espressione della condizione può includere i seguenti elementi:

    • In entrata: è possibile utilizzare gli output delle risposte in entrata (ad esempio, SYS.RESPONSE_PAYLOAD_JSON, SYS.RESPONSE_HEADERS_JSON, SYS.RESPONSE_STATUS).

    • Parametri: è possibile utilizzare qualsiasi parametro definito nell'ambito di questo task REST. Vedere Visualizzazione e gestione dei parametri in un task REST.

    • Funzioni: è possibile utilizzare le funzioni di base String e Operator Data Integration. La funzione json_path, disponibile in String, consente di estrarre i valori delle proprietà dalla risposta utilizzando gli elementi della sintassi JSONPath nel formato: json_path(json_string, json_filter_path)

      Ad esempio: json_path(SYS.RESPONSE_PAYLOAD, '$.@STATUS')

    Non tutte le funzioni sono supportate in un'espressione di condizione di operazione riuscita. Vedere la lista supportata qui.

    (Per le operazioni con tempi di esecuzione lunghi) Se è stata selezionata la casella di controllo Configura una condizione di polling e interruzione per una chiamata REST senza attesa, la condizione di operazione riuscita è un'espressione scritta nella risposta della richiesta di polling. È possibile creare espressioni che utilizzano la risposta API dal passo di esecuzione, quindi includere le espressioni denominate per creare la condizione di operazione riuscita.

  5. Per assegnare un parametro task alla condizione di operazione riuscita, selezionare Assegna parametro. Vedere Parametrizzazione della condizione di operazione riuscita.