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 localmente 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 utilizzarle 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à Call REST Endpoint 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 apici inversi intorno al nome della variabile.

Variabili di integrazione

Variabili di integrazione, che includono le 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 dell'integrazione, note anche come variabili di input.
• Restituite come output dell'integrazione, note anche come variabili di output.
• Utilizzate 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 un trigger. Tuttavia, se una variabile è definita staticamente nell'integrazione e la stessa variabile viene fornita dinamicamente con il trigger, l'assegnazione del valore dinamico 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 array di numeri doppi
• Valore booleano e array di valori booleani
• JSON

Variabili di attività

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

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

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

Nel riquadro Variabili , le variabili di attività potrebbero essere elencate con un nome di output comune, ad esempio responseBody, senza l'ID attività o gli apici inversi. Per visualizzare il nome completo e univoco della variabile necessario per il riferimento, fai clic sulla variabile nel riquadro e visualizzane i dettagli nel riquadro a destra.

Variabili di configurazione

Anteprima : connettore BigQuery

Questa funzionalità è soggetta ai "Termini delle offerte pre-GA" nella sezione Termini di servizio generali dei Termini specifici del servizio. Le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per ulteriori informazioni, consulta le descrizioni della fase 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 devi aggiornare manualmente l'integrazione prima di caricarla in un nuovo ambiente. 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 su variable_add Variabile di configurazione dell'integrazione nel riquadro Variabili. Per scoprire come creare e utilizzare le variabili di configurazione, consulta il tutorial Creare CI/CD per l'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 riesce, 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 di esecuzione dell'integrazione.
• IntegrationName: il nome dell'integrazione.
• Region: la regione dell'integrazione.
• ProjectId: l'ID progetto che contiene l'integrazione.

Visualizzare le 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 Attiva/disattiva 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 : connettore BigQuery

Questa funzionalità è soggetta ai "Termini delle offerte pre-GA" nella sezione Termini di servizio generali dei Termini specifici del servizio. Le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per ulteriori informazioni, consulta le descrizioni della fase 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. Puoi semplicemente fare clic sul campo Valore per modificare il valore della variabile di configurazione.

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

Creare una variabile

Per creare una variabile:

1. Nella barra di navigazione dell'editor di integrazione, fai clic su , il pulsante Attiva/disattiva riquadro, 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 dall'integrazione	Il valore finale della variabile alla fine 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
      Doppio	30.5
      Valore booleano	true
      JSON	{ "employee":{"name":"Alex", "age":30, "city":"Mountain View"} }
      Array di stringhe	Alex, Kai, Raha
      Array di numeri interi	30, 25, 22
      Array di numeri doppi	30.5, 25.34, 22.134
      Array di valori booleani	true, false, false

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

   4. Valore predefinito:inserisci il valore predefinito della 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 sulla maschera, 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 che sono dichiarate per l'integrazione o l'attività. Una volta avviata l'esecuzione, i dati di input vengono convertiti in un oggetto in memoria chiamato un 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. Man mano che l'integrazione viene eseguita, 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.	Impostata in fase di progettazione e modificabile quando pubblichi l'integrazione.	Un indirizzo email di destinazione per la notifica.
Variabile di sistema	Generata automaticamente dal sistema.	Di sola lettura e non modificabile.	La variabile ExecutionId.
Variabile di integrazione	Tiene traccia dei dati durante l'esecuzione di un'intera integrazione.	Impostata in modo esplicito nell'integrazione e modificabile durante l'esecuzione dell'integrazione.	Una variabile per memorizzare il risultato di un'attività.
Variabile di attività	Memorizza l'output di un'attività specifica.	Impostata implicitamente eseguendo un'attività e non modificabile.	La variabile responseBody dell'attività Call REST Endpoint.

Riferimenti alle variabili

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

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

Ad esempio:

• Una condizione di bordo 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 numero intero.

• Puoi creare una notifica via email per la registrazione di un nuovo utente all'interno di un flusso di lavoro di Application Integration. Supponiamo di avere due variabili:
  • $userName$: contiene il nome del nuovo utente (ad es. "Alex").
  • $orderID$: contiene un identificatore di ordine univoco (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 di bordo

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

Quote e limiti

Per informazioni su quote e limiti, vedi 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