Guia de referência de esquema para a Linguagem de Definição de Fluxo de trabalho nos Aplicativos Lógicos do Azure

Artigo
06/13/2024

Quando você cria um aplicativo lógico nos Aplicativos Lógicos do Azure, ele tem uma definição de fluxo de trabalho subjacente que descreve a lógica real que é executada no aplicativo. Essa definição de fluxo de trabalho usa JSON e segue uma estrutura validada pelo esquema de Linguagem de Definição de Fluxo de Trabalho. Esta referência fornece uma visão geral sobre essa estrutura e sobre como o esquema define atributos na definição de fluxo de trabalho.

Estrutura da definição de fluxo de trabalho

Uma definição de fluxo de trabalho sempre inclui um gatilho para instanciar o aplicativo lógico, além de uma ou mais ações executadas depois que o gatilho é acionado.

Esta é a estrutura de alto nível de uma definição de fluxo de trabalho:

"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>" }
}

Atributo	Obrigatório	Descrição
`definition`	Sim	O elemento inicial da definição de fluxo de trabalho
`$schema`	Somente ao referenciar uma definição de fluxo de trabalho externamente	O local do arquivo de esquema JSON que descreve a versão da Linguagem de Definição de Fluxo de Trabalho, que você pode encontrar aqui: `https://schema.management.azure.com/providers/Microsoft.Logic/schemas/2016-06-01/workflowdefinition.json`
`actions`	Não	As definições de uma ou mais ações a serem executadas no runtime de fluxo de trabalho. Para saber mais, confira Gatilhos e ações. Máximo de ações: 250
`contentVersion`	Não	O número de versão da definição de fluxo de trabalho, que é "1.0.0.0" por padrão. Para ajudar a identificar e confirmar a definição correta ao implantar um fluxo de trabalho, especifique um valor a ser usado.
`outputs`	Não	As definições das saídas a serem retornadas de uma execução do fluxo de trabalho. Para saber mais, confira Saídas. Máximo de saídas: 10
`parameters`	Não	As definições para um ou mais parâmetros que passam os valores a serem usados no runtime do aplicativo lógico. Para obter mais informações, confira Parâmetros. Máximo de parâmetros: 50
`staticResults`	Não	As definições para um ou mais resultados estáticos retornados por ações como saídas fictícias quando os resultados estáticos são habilitados nessas ações. Em cada definição de ação, o atributo `runtimeConfiguration.staticResult.name` faz referência à definição correspondente dentro de `staticResults`. Para saber mais, confira Resultados estáticos.
`triggers`	Não	As definições de um ou mais gatilhos que criam uma instância do fluxo de trabalho. Você pode definir mais de um gatilho, mas somente com a Linguagem de Definição de Fluxo de Trabalho, não visualmente por meio do designer de fluxo de trabalho. Para saber mais, confira Gatilhos e ações. Máximo da gatilhos: 10

Gatilhos e ações

Em uma definição de fluxo de trabalho, as seções triggers e actions definem as chamadas que ocorrem durante a execução do fluxo de trabalho. Para conhecer a sintaxe e obter mais informações sobre essas seções, confira Gatilhos e ações de fluxo de trabalho.

Parâmetros

O ciclo de vida da implantação geralmente tem ambientes diferentes para desenvolvimento, teste, preparo e produção. Ao implantar aplicativos lógicos em vários ambientes, provavelmente convém usar valores diferentes, como cadeias de conexão, com base nas suas necessidades de implantação. Ou você pode ter valores que deseja reutilizar em todo o seu aplicativo lógico sem hard-coding ou que mudam com frequência. Na seção parameters de sua definição de fluxo de trabalho, você pode definir ou editar parâmetros para os valores que seu aplicativo lógico usa no runtime. Você deve definir esses parâmetros primeiro para poder referenciá-los em outro ugar na sua definição de fluxo de trabalho.

Esta é a estrutura geral de uma definição de parâmetro:

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

Atributo	Obrigatório	Type	Descrição
<parameter-name>	Sim	String	O nome do parâmetro que você deseja definir
<parameter-type>	Sim	int, float, string, bool, matriz, objeto, securestring, secureobject Observação: para todas as senhas, chaves e segredos, use os tipos `securestring` ou `secureobject`, porque a operação `GET` não retorna esses tipos. Para saber mais sobre como proteger os parâmetros, confira Recomendações de segurança para parâmetros de ação e de entrada.	O tipo do parâmetro
<default-parameter-value>	Sim	Mesmo que `type`	O valor de parâmetro padrão a ser usado se nenhum valor for especificado ao criar uma instância do fluxo de trabalho. O atributo `defaultValue` é necessário para que o Designer de Aplicativo Lógico possa mostrar corretamente o parâmetro, mas você pode especificar um valor vazio.
<array-with-permitted-parameter-values>	Não	Array	Uma matriz com valores que o parâmetro pode aceitar
<parameter-description>	Não	Objeto JSON	Quaisquer outros detalhes do parâmetro, como uma descrição para ele

Em seguida, crie um modelo do Azure Resource Manager para sua definição de fluxo de trabalho, defina os parâmetros de modelo que aceitam os valores desejados na implantação, substitua os valores codificados por referências aos parâmetros de definição de modelo ou de fluxo de trabalho, conforme apropriado, e armazene os valores a serem usados na implantação em um arquivo de parâmetroseparado. Dessa forma, você poderá alterar esses valores com mais facilidade, sem precisar atualizar e reimplantar o aplicativo lógico. Para informações confidenciais ou que devem ser protegidas, como nomes de usuários, senhas e segredos, você pode armazenar esses valores no Azure Key Vault e fazer com que o arquivo de parâmetros recupere esses valores do seu cofre de chaves. Para obter mais informações e exemplos sobre como definir parâmetros nos níveis de definição de modelo e de fluxo de trabalho, confira Visão geral: automatizar a implantação para aplicativos lógicos com modelos do Azure Resource Manager.

Resultados estáticos

No atributo staticResults, defina outputs e status fictícios de uma ação, que esta retornará quando a configuração de resultado estático dela for ativada. Na definição da ação, o atributo runtimeConfiguration.staticResult.name faz referência ao nome da definição de resultado estático dentro de staticResults. Saiba como você pode testar fluxos de trabalho de aplicativos lógicos com dados fictícios configurando resultados estáticos.

"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": { "<...>" }
}

Atributo	Obrigatório	Type	Descrição
<static-result-definition-name>	Sim	String	O nome de uma definição de resultado estático que uma definição de ação pode referenciar por meio de um objeto `runtimeConfiguration.staticResult`. Para obter mais informações, consulte Configurações de runtime. Você pode usar qualquer nome exclusivo que desejar. Por padrão, um número é acrescentado a esse nome exclusivo e incrementado conforme necessário.
<output-attributes-and-values-returned>	Sim	Varia	Os requisitos para esses atributos variam de acordo com diferentes condições. Por exemplo, quando o `status` for `Succeeded`, o atributo `outputs` incluirá atributos e valores retornados como saídas fictícias pela ação. Se `status` for `Failed`, o atributo `outputs` incluirá o atributo `errors`, que é uma matriz com um ou mais objetos `message` de erro que têm informações de erro.
<header-values>	Não	JSON	Qualquer valor de cabeçalho retornado pela ação
<status-code-returned>	Sim	String	O código de status retornado pela ação
<action-status>	Sim	String	O status da ação, por exemplo, `Succeeded` ou `Failed`

Por exemplo, nessa definição de ação HTTP, o atributo runtimeConfiguration.staticResult.name faz referência a HTTP0 dentro do atributo staticResults, onde as saídas fictícias para a ação são definidas. O atributo runtimeConfiguration.staticResult.staticResultOptions especifica que a configuração de resultado estático é Enabled na ação HTTP.

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

A ação HTTP retorna as saídas na definição HTTP0 dentro de staticResults. Neste exemplo, para o código de status, a saída fictícia é OK. Para valores de cabeçalho, a saída fictícia é "Content-Type": "application/JSON". Para o status da ação, a saída fictícia é Succeeded.

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

Expressões

Com JSON, é possível ter valores literais existentes no tempo de design, por exemplo:

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

Também é possível ter valores que não existem até o tempo de execução. Para representar esses valores, é possível usar expressões, que são avaliadas em tempo de execução. Uma expressão é uma sequência que pode conter uma ou mais funções, operadores, variáveis, valores explícitos ou constantes. Em sua definição de fluxo de trabalho, você pode usar uma expressão em qualquer lugar de um valor de cadeia de caracteres JSON prefixando a expressão com uma arroba (@). Quando uma expressão que representa um valor JSON é avaliada, o corpo da expressão é extraído removendo o caractere @ e ela sempre resulta em outro valor JSON.

Por exemplo, para a propriedade customerName definida anteriormente, você pode obter o valor da propriedade usando a função parameters() em uma expressão de função e pode atribuir esse valor à propriedade accountName:

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

A interpolação de cadeias de caracteres também permite usar várias expressões dentro de cadeias de caracteres que são encapsuladas pelo caractere @ e por chaves ({}). Esta é a sintaxe:

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

O resultado sempre é uma cadeia de caracteres, tornando essa funcionalidade semelhante à função concat(), por exemplo:

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

Se você tiver uma cadeia de caracteres literal iniciada pelo caractere @, prefixe esse caractere com outro @, que funcionará como caractere de escape: @@

Estes exemplos mostram como as expressões são avaliadas:

Valor JSON	Result
"Sophia Owen"	Retornar estes caracteres: 'Sophia Owen'
"array[1]"	Retornar estes caracteres: 'array[1]'
"@@"	Retornar estes caracteres como uma cadeia de caracteres com um caractere: \'\@\'
" @"	Retornar estes caracteres como uma cadeia de caracteres com dois caracteres: \' \@\'

Para esses exemplos, suponha que você defina "myBirthMonth" como "January" e "myAge" igual ao número 42:

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

Estes exemplos mostram como as expressões a seguir são avaliadas:

Expressão JSON	Resultado
"@parameters('myBirthMonth')"	Retornar esta cadeia de caracteres: "January"
"@{parameters('myBirthMonth')}"	Retornar esta cadeia de caracteres: "January"
"@parameters('myAge')"	Retornar este número: 42
"@{parameters('myAge')}"	Retornar este número como uma cadeia de caracteres: "42"
"My age is @{parameters('myAge')}"	Retornar esta cadeia de caracteres: My age is 42"
"@concat('My age is ', string(parameters('myAge')))"	Retornar esta cadeia de caracteres: My age is 42"
"My age is @@{parameters('myAge')}"	Retornar esta cadeia de caracteres, que inclui a expressão: "My age is @{parameters('myAge')}`

Quando você estiver trabalhando visualmente no designer de fluxo de trabalho, poderá criar expressões usando o editor de expressões, por exemplo:

A captura de tela mostra o designer de fluxo de trabalho e o editor de expressão.

Quando você terminar, a expressão será exibida para a propriedade correspondente em sua definição de fluxo de trabalho, por exemplo, a propriedade searchQuery aqui:

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

Saídas

Na seção outputs, defina os dados que o fluxo de trabalho pode retornar quando terminar sua execução. Por exemplo, para rastrear um valor ou status específico em cada execução, especifique que a saída do fluxo de trabalho retorne esses dados.

Observação

Ao responder a solicitações de entrada da API REST de um serviço, não use outputso . Em vez disso, use o tipo de ação Response. Para obter mais informações, consulte Gatilhos e ações de fluxo de trabalho.

Esta é a estrutura geral de uma definição de saída:

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

Atributo	Obrigatório	Type	Descrição
<key-name>	Sim	String	O nome da chave do valor retornado da saída
<key-type>	Sim	int, float, string, securestring, bool, array, objeto JSON	O tipo do valor retornado da saída
<key-value>	Sim	Mesmo que <key-type>	O valor retornado da saída

Para obter a saída da execução de um fluxo de trabalho, examine os detalhes e o histórico de execuções do seu aplicativo lógico no portal do Azure ou use a API REST de fluxo de trabalho. Você também pode passar a saída para sistemas externos, por exemplo, o Power BI para que você possa criar painéis.

Operadores

No caso de expressões e funções, os operadores desempenham tarefas específicas, como referenciar uma propriedade ou um valor em uma matriz.

Operador	Tarefa
`'`	Para usar um literal de cadeia de caracteres como entrada ou em expressões e funções, encapsule a cadeia de caracteres somente com aspas simples, por exemplo, `'<myString>'`. Não use aspas duplas (`""`), que entram em conflito com a formatação JSON ao redor de uma expressão inteira. Por exemplo: Sim: length('Hello') Não: length("Hello") Quando passa matrizes ou números, você não precisa de pontuação de encapsulamento. Por exemplo: Sim: length([1, 2, 3]) No: length("[1, 2, 3]")
`[]`	Para fazer referência a um valor em uma posição específica (índice) em uma matriz ou dentro de um objeto JSON, use colchetes, por exemplo: - Para obter o segundo item em uma matriz: `myArray[1]` - Para acessar as propriedades dentro de um objeto JSON: Exemplo 1: `setProperty(<object>, '<parent-property>', addProperty(<object>['<parent-property>'], '<child-property>', <value>)` Exemplo 2: `lastIndexOf(triggerBody()?['subject'],'some string')`
`.`	Para referenciar uma propriedade em um objeto, use o operador de ponto. Por exemplo, para obter a `name` propriedade de um `customer` objeto JSON: `"parameters('customer').name"`
`?`	Para fazer referência a propriedades nulas em um objeto sem um erro de tempo de execução, use o operador null-ignore (?). Por exemplo, para manipular saídas nulas de um gatilho, você pode usar a seguinte expressão: `coalesce(trigger().outputs?.body?['<someProperty>'], '<property-default-value>')`

Funções

Algumas expressões obtêm seus valores de ações de runtime que podem ainda não existir quando sua definição de fluxo de trabalho começa a ser executada. Para referenciar ou trabalhar com esses valores em expressões, você pode usar as funções fornecidas pela linguagem de definição de fluxo de trabalho.

Próximas etapas

Saiba mais sobre Workflow Definition Language actions and triggers (Ações e gatilhos da Linguagem de Definição de Fluxo de Trabalho)
Saiba mais sobre como criar e gerenciar Aplicativos Lógicos de forma programática com a API REST de fluxo de trabalho

Compartilhar via