Guida di riferimento allo schema per il linguaggio di definizione del flusso di lavoro in App per la logica di Azure

Articolo
12/08/2023

Quando si crea un'app per la logica in App per la logica di Azure, l'app per la logica ha una definizione del flusso di lavoro sottostante che descrive la logica effettiva eseguita nell'app per la logica. Tale definizione del flusso di lavoro usa JSON e segue una struttura convalidata dallo schema del linguaggio di definizione del flusso di lavoro. Questo riferimento fornisce una panoramica di questa struttura e del modo in cui lo schema definisce gli attributi nella definizione del flusso di lavoro.

Struttura della definizione del flusso di lavoro

Una definizione del flusso di lavoro include sempre un trigger per creare un'istanza dell'app per la logica, oltre a una o più azioni eseguite dopo l'attivazione del trigger.

Di seguito è riportata la struttura generale di una definizione del flusso di lavoro:

"definition": {
  "$schema": "<workflow-definition-language-schema-version>",
  "actions": { "<workflow-action-definitions>" },
  "contentVersion": "<workflow-definition-version-number>",
  "outputs": { "<workflow-output-definitions>" },
  "parameters": { "<workflow-parameter-definitions>" },
  "staticResults": { "<static-results-definitions>" },
  "triggers": { "<workflow-trigger-definitions>" }
}

Attributo	Richiesto	Descrizione
`definition`	Sì	Elemento iniziale della definizione del flusso di lavoro
`$schema`	Solo quando si fa riferimento esternamente a una definizione del flusso di lavoro	Percorso del file di schema JSON che descrive la versione del linguaggio di definizione del flusso di lavoro, disponibile qui: `https://schema.management.azure.com/providers/Microsoft.Logic/schemas/2016-06-01/workflowdefinition.json`
`actions`	No	Definizioni per una o più azioni da eseguire in fase di esecuzione del flusso di lavoro. Per altre informazioni, vedere Trigger e azioni. Numero massimo di azioni: 250
`contentVersion`	No	Numero di versione della definizione del flusso di lavoro, per impostazione predefinita "1.0.0.0". Specificare un valore da usare per identificare e confermare la definizione corretta durante la distribuzione di un flusso di lavoro.
`outputs`	No	Definizioni per gli output da restituire da un'esecuzione del flusso di lavoro. Per altre informazioni, vedere Output. Numero massimo di output: 10
`parameters`	No	Definizioni per uno o più parametri che passano i valori da usare nel runtime dell'app per la logica. Per altre informazioni, vedere Parametri. Numero massimo di parametri: 50
`staticResults`	No	Le definizioni per uno o più risultati statici restituiti da azioni come output fittizi quando i risultati statici sono abilitati per tali azioni. In ogni definizione di azione l'attributo `runtimeConfiguration.staticResult.name` fa riferimento alla definizione corrispondente all'interno `staticResults`di . Per altre informazioni, vedere Risultati statici.
`triggers`	No	Definizioni di uno o più trigger che creano istanze del flusso di lavoro. È possibile definire più trigger, ma solo con il linguaggio di definizione del flusso di lavoro, non visivamente tramite la finestra di progettazione del flusso di lavoro. Per altre informazioni, vedere Trigger e azioni. Numero massimo di trigger: 10

Trigger e azioni

In una definizione del flusso di lavoro, le sezioni triggers e actions definiscono le chiamate che si verificano durante l'esecuzione del flusso di lavoro. Per la sintassi e altre informazioni su queste sezioni, vedere Trigger e azioni del flusso di lavoro.

Parametri

Il ciclo di vita della distribuzione ha in genere ambienti diversi per lo sviluppo, il test, la gestione temporanea e la produzione. Quando si distribuiscono app per la logica in vari ambienti, è probabile che si vogliano usare valori diversi, ad esempio stringa di connessione, in base alle esigenze di distribuzione. In alternativa, è possibile avere valori che si desidera riutilizzare in tutta l'app per la logica senza hardcoding o che cambiano spesso. Nella sezione della definizione del flusso di parameters lavoro è possibile definire o modificare i parametri per i valori usati dall'app per la logica in fase di esecuzione. È necessario definire questi parametri prima di poter fare riferimento a questi parametri altrove nella definizione del flusso di lavoro.

Di seguito è riportata la struttura generale della definizione di un parametro:

"parameters": {
   "<parameter-name>": {
      "type": "<parameter-type>",
      "defaultValue": <default-parameter-value>,
      "allowedValues": [ <array-with-permitted-parameter-values> ],
      "metadata": {
         "description": "<parameter-description>"
      }
   }
},

Attributo	Richiesto	Digita	Descrizione
<parameter-name>	Sì	Stringa	Nome del parametro che si desidera definire
<tipo di parametro>	Sì	int, float, string, bool, array, object, securestring, secureobject Nota: per tutte le password, le chiavi e i segreti, usare i `securestring` tipi o `secureobject` perché l'operazione `GET` non restituisce questi tipi. Per altre informazioni sulla protezione dei parametri, vedere Raccomandazioni sulla sicurezza per i parametri di azione e di input.	Tipo di parametro
<default-parameter-value>	Sì	Uguale a `type`	Valore del parametro predefinito da utilizzare se non viene specificato alcun valore quando viene creata un'istanza del flusso di lavoro. L'attributo `defaultValue` è obbligatorio in modo che Progettazione app per la logica possa visualizzare correttamente il parametro, ma è possibile specificare un valore vuoto.
<array-with-permitted-parameter-values>	No	Matrice	Matrice con valori che il parametro può accettare
<parameter-description>	No	Oggetto JSON	Qualsiasi altro dettaglio del parametro, ad esempio una descrizione per il parametro

Creare quindi un modello di Azure Resource Manager per la definizione del flusso di lavoro, definire i parametri del modello che accettano i valori da distribuire, sostituire i valori hardcoded con riferimenti ai parametri di definizione del modello o del flusso di lavoro in base alle esigenze e archiviare i valori da usare nella distribuzione in un file di parametri separato. In questo modo, è possibile modificare questi valori più facilmente tramite il file di parametri senza dover aggiornare e ridistribuire l'app per la logica. Per informazioni sensibili o che devono essere protette, ad esempio nomi utente, password e segreti, è possibile archiviare tali valori in Azure Key Vault e recuperare tali valori dall'insieme di credenziali delle chiavi. Per altre informazioni ed esempi sulla definizione dei parametri a livello di modello e definizione del flusso di lavoro, vedere Panoramica: Automatizzare la distribuzione per le app per la logica con i modelli di Azure Resource Manager.

Risultati statici

Nell'attributo staticResults definire la simulazione outputs di un'azione e status che l'azione restituisce quando l'impostazione del risultato statico dell'azione è attivata. Nella definizione dell'azione, l'attributo runtimeConfiguration.staticResult.name fa riferimento al nome per la definizione del risultato statico all'interno staticResultsdi . Informazioni su come testare i flussi di lavoro delle app per la logica con dati fittizi configurando i risultati statici.

"definition": {
   "$schema": "<...>",
   "actions": { "<...>" },
   "contentVersion": "<...>",
   "outputs": { "<...>" },
   "parameters": { "<...>" },
   "staticResults": {
      "<static-result-definition-name>": {
         "outputs": {
            <output-attributes-and-values-returned>,
            "headers": { <header-values> },
            "statusCode": "<status-code-returned>"
         },
         "status": "<action-status>"
      }
   },
   "triggers": { "<...>" }
}

Attributo	Richiesto	Digita	Descrizione
<static-result-definition-name>	Sì	Stringa	Nome per una definizione di risultato statico a cui può fare riferimento una definizione di azione tramite un `runtimeConfiguration.staticResult` oggetto . Per altre informazioni vedere Impostazioni di configurazione di runtime. È possibile usare qualsiasi nome univoco desiderato. Per impostazione predefinita, questo nome univoco viene aggiunto con un numero, che viene incrementato in base alle esigenze.
<output-attributes-and-values-returned>	Sì	Variabile	I requisiti per questi attributi variano in base a condizioni diverse. Ad esempio, quando `status` è `Succeeded`, l'attributo `outputs` include attributi e valori restituiti come output fittizi dall'azione. `status` Se è `Failed`, l'attributo include l'attributo `errorsoutputs` , ovvero una matrice con uno o più oggetti errore `message` con informazioni sull'errore.
<header-values>	No	JSON	Qualsiasi valore di intestazione restituito dall'azione
<status-code-returned>	Sì	Stringa	Codice di stato restituito dall'azione
<action-status>	Sì	Stringa	Stato dell'azione, ad esempio o `SucceededFailed`

In questa definizione di azione HTTP, ad esempio, l'attributo runtimeConfiguration.staticResult.name fa HTTP0 riferimento all'interno dell'attributo staticResults in cui vengono definiti gli output fittizi per l'azione. L'attributo runtimeConfiguration.staticResult.staticResultOptions specifica che l'impostazione del risultato statico si trova Enabled nell'azione HTTP.

"actions": {
   "HTTP": {
      "inputs": {
         "method": "GET",
         "uri": "https://www.microsoft.com"
      },
      "runAfter": {},
      "runtimeConfiguration": {
         "staticResult": {
            "name": "HTTP0",
            "staticResultOptions": "Enabled"
         }
      },
      "type": "Http"
   }
},

L'azione HTTP restituisce gli output nella HTTP0 definizione all'interno staticResultsdi . In questo esempio, per il codice di stato, l'output fittizio è OK. Per i valori di intestazione, l'output fittizio è "Content-Type": "application/JSON". Per lo stato dell'azione, l'output fittizio è Succeeded.

"definition": {
   "$schema": "<...>",
   "actions": { "<...>" },
   "contentVersion": "<...>",
   "outputs": { "<...>" },
   "parameters": { "<...>" },
   "staticResults": {
      "HTTP0": {
         "outputs": {
            "headers": {
               "Content-Type": "application/JSON"
            },
            "statusCode": "OK"
         },
         "status": "Succeeded"
      }
   },
   "triggers": { "<...>" }
},

Espressioni

Con JSON è possibile avere valori letterali già esistenti in fase di progettazione, ad esempio:

"customerName": "Sophia Owen",
"rainbowColors": ["red", "orange", "yellow", "green", "blue", "indigo", "violet"],
"rainbowColorsCount": 7

È anche possibile avere valori che non esistono fino all'esecuzione. Per rappresentare questi valori è possibile usare espressioni che vengono valutate in fase di esecuzione. Un'espressione è una sequenza che può contenere una o più funzioni, operatori, variabili, valori espliciti o costanti. Nella definizione del flusso di lavoro è possibile usare un'espressione in qualsiasi punto di un valore stringa JSON aggiungendo all'espressione il prefisso @. Quando si valuta un'espressione che rappresenta un valore JSON, il corpo dell'espressione viene estratto rimuovendo il carattere @ e si ottiene sempre un altro valore JSON.

Ad esempio, per la proprietà customerName definita in precedenza è possibile ottenere il valore usando la funzione parameters() in un'espressione e assegnare tale valore alla proprietà accountName:

"customerName": "Sophia Owen",
"accountName": "@parameters('customerName')"

Anche l'interpolazione delle stringhe consente di usare più espressioni all'interno delle stringhe, racchiuse dal carattere @ e da parentesi graffe ({}): La sintassi è la seguente:

@{ "<expression1>", "<expression2>" }

Il risultato è sempre una stringa, rendendo questa funzionalità simile alla funzione concat(), ad esempio:

"customerName": "First name: @{parameters('firstName')} Last name: @{parameters('lastName')}"

In presenza di una stringa letterale che inizia con il carattere @, prefissare il carattere @ con un altro carattere @ come carattere di escape: @@

Questi esempi mostrano come vengono valutate le espressioni:

Valore JSON	Result
"Sophia Owen"	Restituisce questi caratteri: 'Sophia Owen'
"array[1]"	Restituisce questi caratteri: 'array[1]'
"@@"	Restituisce questi caratteri come stringa di un solo carattere: \'\@\'
" @"	Restituisce questi caratteri come stringa di due caratteri: \' \@\'

Per questi esempi si supponga di definire "myBirthMonth" uguale a "January" e "myAge" uguale al numero 42:

"myBirthMonth": "January",
"myAge": 42

Questi esempi mostrano come vengono valutate le espressioni seguenti:

Espressione JSON	Result
"@parameters('myBirthMonth')"	Restituisce la stringa: "January"
"@{parameters('myBirthMonth')}"	Restituisce la stringa: "January"
"@parameters('myAge')"	Restituisce il numero: 42
"@{parameters('myAge')}"	Restituisce questo numero come stringa: "42"
"My age is @{parameters('myAge')}"	Restituisce la stringa: "My age is 42"
"@concat('My age is ', string(parameters('myAge')))"	Restituisce la stringa: "My age is 42"
"My age is @@{parameters('myAge')}"	Restituisce questa stringa, che include l'espressione: "My age is @{parameters('myAge')}`

Quando si lavora visivamente nella finestra di progettazione del flusso di lavoro, è possibile creare espressioni usando l'editor di espressioni, ad esempio:

Screenshot shows workflow designer and expression editor.

Al termine viene visualizzata l'espressione per la proprietà corrispondente nella definizione del flusso di lavoro, ad esempio la proprietà searchQuery:

"Search_tweets": {
  "inputs": {
    "host": {
      "connection": {
        "name": "@parameters('$connections')['twitter']['connectionId']"
      }
    }
  },
  "method": "get",
  "path": "/searchtweets",
  "queries": {
    "maxResults": 20,
    "searchQuery": "Azure @{concat('firstName','', 'LastName')}"
  }
},

Output

Nella sezione outputs definire i dati che il flusso di lavoro può restituire al termine dell'esecuzione. Ad esempio, per tenere traccia di uno stato o di un valore specifico per ogni esecuzione, specificare che l'output del flusso di lavoro restituisca tali dati.

Nota

Quando si risponde alle richieste in ingresso dall'API REST di un servizio, non usare outputs. ma il tipo di azione Response. Per altre informazioni, vedere Trigger e azioni dei flussi di lavoro.

Di seguito è riportata la struttura generale della definizione di un output:

"outputs": {
  "<key-name>": {
    "type": "<key-type>",
    "value": "<key-value>"
  }
}

Attributo	Richiesto	Digita	Descrizione
<key-name>	Sì	Stringa	Valore chiave del valore di output restituito
<key-type>	Sì	int, float, string, securestring, bool, array, JSON object	Tipo di valore di output restituito
<key-value>	Sì	Uguale al <tipo di chiave>	Valore di output restituito

Per ottenere l'output da un'esecuzione del flusso di lavoro, esaminare la cronologia di esecuzione dell'app per la logica e i dettagli nella portale di Azure o usare l'API REST del flusso di lavoro. È anche possibile passare l'output a sistemi esterni, ad esempio Power BI, per creare dashboard.

Operatori

Nelle espressioni e nelle funzioni, gli operatori eseguono attività specifiche, ad esempio fanno riferimento a una proprietà o un valore in una matrice.

Operatore	Attività
`'`	Per usare un valore letterale di stringa come input o in espressioni e funzioni, racchiudere la stringa solo tra virgolette singole, ad esempio `'<myString>'`. Non usare virgolette doppie (`""`), che sono in conflitto con la formattazione JSON intorno a un'intera espressione. Ad esempio: Sì: length('Hello') No: length("Hello") Quando si passano matrici o numeri, non è necessario il wrapping della punteggiatura. Ad esempio: Sì: length([1, 2, 3]) No: length("[1, 2, 3]")
`[]`	Per fare riferimento a un valore in una posizione specifica (indice) in una matrice o all'interno di un oggetto JSON, usare parentesi quadre, ad esempio: - Per ottenere il secondo elemento in una matrice: `myArray[1]` - Per accedere alle proprietà all'interno di un oggetto JSON: Esempio 1: `setProperty(<object>, '<parent-property>', addProperty(<object>['<parent-property>'], '<child-property>', <value>)` Esempio 2: `lastIndexOf(triggerBody()?['subject'],'some string')`
`.`	Per fare riferimento a una proprietà in un oggetto, usare l'operatore punto. Ad esempio, per ottenere la `name` proprietà per un `customer` oggetto JSON: `"@parameters('customer').name"`
`?`	Per fare riferimento alle proprietà Null di un oggetto senza un errore di runtime, usare l'operatore punto interrogativo. Ad esempio, per gestire gli output Null da un trigger, è possibile usare questa espressione: `@coalesce(trigger().outputs?.body?.<someProperty>, '<property-default-value>')`

Funzioni

Alcune espressioni ottengono i valori dalle azioni di runtime che potrebbero non esistere ancora quando la definizione del flusso di lavoro inizia a essere eseguita. Per usare questi valori o farvi riferimento nelle espressioni, è possibile usare le funzioni fornite dal Linguaggio di definizione del flusso di lavoro.

Passaggi successivi

Vedere Azioni e trigger del linguaggio di definizione del flusso di lavoro
Informazioni sulla creazione e la gestione di app per la logica a livello di codice con l'API REST del flusso di lavoro