Variabili

Una variabile è un elemento di integrazione che contiene e trasporta i dati tra le attività, i trigger e i bordi di un'integrazione.

• Le variabili possono essere definite staticamente in fase di progettazione o passate dinamicamente all'integrazione in fase di runtime.
• Le variabili possono fare riferimento ad altre variabili in un'integrazione.
• Le variabili possono essere accessibili a livello globale a tutte le attività o a livello locale a un'attività specifica.

Variabili

In Application Integration, le variabili vengono impostate o inizializzate in varie posizioni:

• Variabili di configurazione: impostate in fase di progettazione per archiviare i dati di configurazione dell'integrazione. Ad esempio, puoi utilizzarlo per impostare un indirizzo email di destinazione per la notifica, anziché codificare l'indirizzo email nell'integrazione.
• Variabili di sistema: generate automaticamente dal sistema per archiviare i dati di configurazione dell'integrazione. Ad esempio, la variabile ExecutionId memorizza l'ID di esecuzione dell'integrazione.
• Variabili di integrazione: impostate in modo esplicito nell'integrazione per tenere traccia dei dati durante l'esecuzione di un'intera integrazione. Ad esempio, puoi impostare una variabile per memorizzare il risultato di un'attività e utilizzarla in un'attività successiva.
• Variabili di attività: impostate implicitamente eseguendo attività specifiche per memorizzare l'output dell'attività. Ad esempio, l'attività Chiama endpoint REST imposta la variabile responseBody per memorizzare il corpo della risposta dell'endpoint REST. Le variabili di attività sono note anche come variabili generate automaticamente. Le variabili generate automaticamente hanno una convenzione di denominazione speciale che prevede l'utilizzo di accenti gravi intorno al nome della variabile.

Variabili di integrazione

Le variabili di integrazione, che includono variabili di input e output, sono simili alle variabili utilizzate in un linguaggio di programmazione. I dati nelle variabili possono essere letti e scritti durante l'esecuzione dell'integrazione.

Le variabili di integrazione possono essere utilizzate nei seguenti modi:

• Acquisite come input per l'integrazione, note anche come variabili di input.
• Restituite come output dell'integrazione, note anche come variabili di output.
• Utilizzato per mantenere lo stato temporaneo durante l'esecuzione di un'integrazione.

Nota: i ruoli delle variabili elencati sopra non si escludono a vicenda. Una determinata variabile può essere una variabile di input, una variabile di output, entrambe o nessuna delle due.

Quando contrassegni una variabile come variabile di input, indichi che il valore della variabile deve essere fornito quando viene attivata l'integrazione. Il valore di una variabile di input può essere modificato durante l'esecuzione dell'integrazione.

Quando contrassegni una variabile come variabile di output, indichi che il valore finale della variabile deve essere restituito come parte della risposta dell'integrazione.

Il valore di una variabile non deve essere definito staticamente nell'integrazione. I valori delle variabili possono essere passati a un'integrazione tramite l'utilizzo di un attivatore. Tuttavia, se una variabile è definita staticamente nell'integrazione e la stessa variabile viene fornita dinamicamente con il trigger, l'assegnazione dinamica del valore sovrascriverà l'assegnazione statica.

Tipi di dati supportati

Per le variabili di integrazione sono supportati i seguenti tipi di dati:

• Stringa e array di stringhe
• Numero intero e array di numeri interi
• Doppio e Dual array
• Booleano e array booleano
• JSON

Variabili dell'attività

Le variabili dell'attività sono variabili predefinite generate automaticamente di un'attività. Se un'attività ha un output, tutti questi output sono disponibili in una variabile dell'attività. Non puoi eliminare o modificare una variabile di attività. Le variabili dell'attività sono note anche come variabili generate automaticamente.

Il nome univoco di una variabile di attività segue una convenzione di denominazione speciale: utilizza gli apici inversi intorno al nome della variabile e include l'ID attività. Il formato è `<Task ID>_<Variable Name>`.

Ad esempio, l'attività Chiamata endpoint REST ha un output per il corpo della risposta. Se questa attività ha un ID Task_5, il nome univoco della variabile dell'attività per il corpo della risposta è `Task_5_responseBody`.

Nel riquadro Variabili, le variabili dell'attività potrebbero essere elencate in base a un nome di output comune, ad esempio responseBody, senza l'ID attività o i backtick. Per visualizzare il nome completo e univoco della variabile richiesto per il riferimento, fai clic sulla variabile nel riquadro e visualizza i relativi dettagli nel riquadro a destra.

Variabili di configurazione

Anteprima

Questo prodotto o funzionalità è soggetto ai "Termini delle offerte pre-GA" nella sezione Termini di servizio generali dei Termini specifici dei servizi. I prodotti e le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per ulteriori informazioni, consulta le descrizioni delle fasi di lancio.

Le variabili di configurazione consentono di esternalizzare la configurazione per l'integrazione. Con le variabili di configurazione, puoi configurare aspetti dell'integrazione come i dettagli del connettore, i dettagli di autenticazione o gli endpoint URL in base all'ambiente di sviluppo, ad esempio QA, staging o produzione. Non è necessario aggiornare manualmente l'integrazione prima di caricarla in un nuovo ambiente. L'Application Integration ti consente di inserire i valori per le variabili di configurazione quando pubblichi l'integrazione.

Per visualizzare e modificare le variabili di configurazione definite nell'integrazione, fai clic sulla variable_add Variabile di configurazione dell'integrazione nel riquadro Variabili. Per scoprire come creare variabili di configurazione e utilizzarle, consulta il tutorial Crea CICD per la tua integrazione.

Variabili di sistema

Le variabili di sistema vengono generate automaticamente quando crei un'integrazione. Puoi utilizzare queste variabili nelle attività di integrazione e per gestire gli errori. L'integrazione contiene le seguenti variabili generate dal sistema:

• ErrorInfo: quando l'esecuzione non va a buon fine, puoi accedere ai dettagli dell'errore con la variabile ErrorInfo:

  {
    "ErrorInfo": {
    "message": String,
    "code": Number
    }
  }
  

  Puoi accedere ai messaggi di errore creando una variabile di integrazione denominata ErrorMessage. Tuttavia, ti consigliamo di utilizzare la variabile ErrorInfo.message generata dal sistema per accedere ai messaggi di errore.

• ExecutionMode: la modalità di esecuzione in base al trigger. I valori validi sono SYNC e ASYNC.
• ExecutionId: l'ID esecuzione dell'integrazione.
• IntegrationName: il nome dell'integrazione.
• Region: la regione dell'integrazione.
• ProjectId: l'ID progetto che contiene l'integrazione.

Visualizza variabili

Puoi utilizzare il riquadro Variabili per creare, modificare, visualizzare, duplicare ed eliminare le variabili nell'integrazione. Il riquadro Variabili mostra anche un conteggio dei riferimenti totali alle variabili all'interno dell'integrazione.

Per visualizzare il riquadro Variabili, fai clic su , il pulsante di attivazione/disattivazione del riquadro, nella barra di navigazione del designer.

L'immagine seguente mostra un layout di esempio del riquadro Variabili:

Visualizzare e modificare le variabili di configurazione

Anteprima

Questo prodotto o funzionalità è soggetto ai "Termini delle offerte pre-GA" nella sezione Termini di servizio generali dei Termini specifici dei servizi. I prodotti e le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per ulteriori informazioni, consulta le descrizioni delle fasi di lancio.

Per visualizzare le variabili di configurazione definite nell'integrazione, fai clic su variable_add Variabile di configurazione dell'integrazione nel riquadro Variabili. Viene visualizzato il riquadro Variabili di configurazione, che mostra tutte le variabili di configurazione definite nell'integrazione. Per modificare il valore della variabile di configurazione, è sufficiente fare clic sul campo Valore.

L'immagine seguente mostra un layout di esempio del riquadro Variabili di configurazione:

Creare una variabile

Per creare una variabile, segui questi passaggi:

1. Nella barra di navigazione dell'editor dell'integrazione, fai clic su , il riquadro Attiva/disattiva, per visualizzare il riquadro Variabili.
2. Fai clic su +Crea.
3. Nel riquadro Crea variabile:
   1. Nome:inserisci il nome della variabile.
   2. Tipo di variabile:scegli il tipo di variabile.

   Tipo di dati	Descrizione
   Nessuna	Una variabile locale in un'integrazione.
   Variabile di configurazione per l'integrazione	Una variabile di configurazione in un'integrazione.
   Input per l'integrazione	Durante l'esecuzione, la variabile verrà fornita come input al trigger eseguito.
   Output dell'integrazione	Il valore finale della variabile al termine dell'esecuzione deve essere restituito al chiamante dell'integrazione.
   Input e output dell'integrazione	Durante l'esecuzione, la variabile verrà fornita come input al trigger eseguito e il suo valore finale verrà restituito al chiamante dell'integrazione.

   3. Tipo di dati:scegli il tipo di dati della variabile. Puoi identificare il tipo di dati di una variabile utilizzando l'icona accanto al nome della variabile.

      Tipo di dati	Esempio
      Stringa	Alex
      Numero intero	30
      Doppia	30.5
      Booleano	true
      JSON	{ "employee":{"name":"Alex", "age":30, "city":"Mountain View"} }
      Array di stringhe	Alex, Kai, Raha
      Array di numeri interi	30, 25, 22
      Doppio array	30.5, 25.34, 22.134
      Matrice booleana	true, false, false

      Per informazioni sui tipi di dati supportati, vedi Tipi di dati supportati.

   4. Valore predefinito:inserisci il valore predefinito per la variabile. Questo è un campo facoltativo.
   5. Schema:seleziona lo schema JSON per la variabile.
      • Deduci da un payload JSON di esempio:genera uno schema JSON da un payload JSON di esempio. Il payload di esempio viene eliminato dopo la generazione dello schema. Verrà salvato solo lo schema generato.
      • Inserisci uno schema JSON:inserisci manualmente un intero schema JSON.
      • Deduci dal valore predefinito:genera uno schema JSON utilizzando il valore predefinito fornito.
      • Nessuno:nessun schema JSON.
      Nota:questo campo viene visualizzato solo per le variabili di tipo di dati JSON.
   6. Maschera la variabile nei log (anteprima): seleziona questa opzione per attivare la maschera per la variabile nei log di esecuzione dell'integrazione. Per attivare la maschera per la variabile, devi attivare le variabili di mascheramento per l'integrazione e la regione. Per informazioni su come attivare la maschera per l'integrazione e la regione, vedi Modificare un'integrazione e Modificare le regioni.

      Per informazioni sul mascheramento, vedi Mascherare i dati sensibili nei log.

4. Fai clic su Crea.

Come funzionano le variabili nelle integrazioni

Durante l'esecuzione di un'integrazione, i dati di runtime vengono passati come variabili dichiarate per l'integrazione o l'attività. Una volta iniziata l'esecuzione, i dati di input vengono convertiti in un oggetto in memoria chiamato Evento.

Dopo aver creato l'oggetto Evento, viene creato un grafico in memoria delle attività utilizzando la definizione di integrazione. I valori delle variabili in entrata vengono passati alle attività in base alla configurazione. Durante l'esecuzione dell'integrazione, le attività leggono e scrivono i dati nell'oggetto Evento,che verranno utilizzati dalle attività successive o per formare i dati di output dell'integrazione.

La seguente tabella riassume i diversi tipi di variabili e il loro comportamento:

Tipo di variabile	Descrizione	Comportamento	Esempio
Variabile di configurazione	Memorizza i dati di configurazione dell'integrazione.	Impostato in fase di progettazione e modificabile quando pubblichi l'integrazione.	Un indirizzo email di destinazione per la notifica.
Variabile di sistema	Generato automaticamente dal sistema.	Di sola lettura e non può essere modificato.	La variabile ExecutionId.
Variabile di integrazione	Tiene traccia dei dati durante l'esecuzione di un'intera integrazione.	Impostato in modo esplicito nell'integrazione e può essere modificato durante l'esecuzione dell'integrazione.	Una variabile per archiviare il risultato di un'attività.
Variabile attività	Archivia l'output di un'attività specifica.	Impostato implicitamente eseguendo un'attività e non può essere modificato.	La variabile responseBody dell'attività Chiama endpoint REST.

Riferimenti alle variabili

Le attività, gli attivatori e i bordi di un'integrazione leggono e scrivono nelle variabili utilizzando i riferimenti alle variabili. Un riferimento a una variabile ha il formato $paramKey$, dove paramKey è il nome della variabile.

$isNameUnique$ = true AND $numAccounts$ >= 1

Ad esempio:

• Una condizione limite potrebbe avere il seguente aspetto:

  $isNameUnique$ = true AND $numAccounts$ >= 1

  In questo esempio, isNameUnique è una variabile di tipo di dati booleano e numAccounts è un parametro di tipo di dati intero.

• Puoi creare una notifica via email per la registrazione di un nuovo utente all'interno di un flusso di lavoro di integrazione delle applicazioni. Supponiamo di avere due variabili:
  • $userName$: Contiene il nome del nuovo utente (ad es. "Alex").
  • $orderID$: contiene un identificatore univoco dell'ordine (ad es. "ORD-12345").

  Il modello per il corpo dell'email potrebbe essere:

  Hello $userName$, thank you for your order! Your order ID is $orderID$.

  Quando questo messaggio viene inviato, il sistema sostituisce i riferimenti alle variabili con i valori corrispondenti. Il messaggio finale sarà:

  Hello Alex, thank you for your order! Your order ID is ORD-12345.

Puoi utilizzare i riferimenti alle variabili nelle seguenti posizioni:

• Parametri attività
• Parametri trigger
• Condizioni limite

Quando fai riferimento a una variabile generata automaticamente o di attività, devi utilizzare il suo nome completo e univoco, che include i backtick e l'ID attività, all'interno dei delimitatori del segno del dollaro. Ad esempio, per fare riferimento all'output responseBody di un'attività Chiama endpoint REST con ID Task_5, devi utilizzare $`Task_5_responseBody`$.

Quote e limiti

Per informazioni su quote e limiti, consulta Quote e limiti.

Passaggi successivi

• Scopri come creare CI/CD per l'integrazione.
• Scopri come mascherare i dati sensibili nei log.
• Aggiungere e configurare un'attività di mappatura dei dati