Codificar, decodificar ou gerar esquemas para arquivos simples no Aplicativos Lógicos do Azure

Aplica-se a: Aplicativos Lógicos do Azure (Consumo + Padrão)

Para fluxos de trabalho de integração entre empresas (B2B), você geralmente precisa converter dados entre formatos de arquivo simples e XML antes de poder trocar esses dados com parceiros comerciais.

Este guia mostra como usar as ações internas do conector Flat File para codificar ou decodificar XML e gerar esquemas de arquivo simples compatíveis com o BizTalk a partir de dados de exemplo.

Referência técnica do conector

O conector Flat File inclui as seguintes ações de codificação, decodificação e geração de esquema:

Para obter mais informações, consulte conectores integrados da conta de integração.

Pré-requisitos

• Uma conta e uma assinatura do Azure. Obtenha uma conta gratuita do Azure.

• O recurso de aplicativo lógico e o fluxo de trabalho onde você deseja usar as operações Flat File.

  As operações de Arquivo Simples não incluem gatilhos. Seu fluxo de trabalho pode começar com qualquer gatilho ou usar qualquer ação para trazer o XML de origem.

  Os exemplos neste artigo usam o gatilho de solicitação chamado Quando uma solicitação HTTP é recebida.

  Para obter mais informações, consulte:

  • Criar um fluxo de trabalho de aplicativo lógico de consumo usando o portal do Azure

  • Criar um fluxo de trabalho do aplicativo lógico Standard usando o portal do Azure

• Um recurso de conta de integração para definir e armazenar artefatos para integração empresarial e fluxos de trabalho B2B.

  • Sua conta de integração e o recurso de aplicativo lógico devem existir na mesma assinatura do Azure e na região do Azure.

  • Antes de começar a trabalhar com as operações de Arquivo Simples, você deve vincular seu aplicativo lógico de Consumo ou Padrão à conta de integração para trabalhar com artefatos, como parceiros comerciais e acordos. Você pode vincular uma conta de integração a vários recursos do aplicativo lógico de Consumo ou Padrão para compartilhar os mesmos artefatos.

  Dica

  Se você não estiver trabalhando com artefatos B2B, como parceiros comerciais e contratos em fluxos de trabalho Standard, talvez não precise de uma conta de integração. Em vez disso, você pode carregar esquemas diretamente no recurso de aplicativo lógico Standard. É possível usar o mesmo esquema em todos os fluxos de trabalho secundários no mesmo recurso de aplicativo lógico. Para usar o mesmo esquema em vários recursos de aplicativo lógico, você deve usar e vincular uma conta de integração.

• Um esquema de arquivo simples que especifica como codificar ou decodificar conteúdo XML.

  Em fluxos de trabalho Padrão, as operações de Arquivo Simples permitem selecionar um esquema de uma conta de integração vinculada ou que foi carregado anteriormente no aplicativo lógico, mas não ambos.

  Para obter mais informações, consulte Adicionar esquemas a contas de integração.

• Instale ou use uma ferramenta que possa enviar solicitações HTTP para testar sua solução, por exemplo:

  • Visual Studio Code com uma extensão do Visual Studio Marketplace
  • Invoke-RestMethod do PowerShell
  • Microsoft Edge – ferramenta Console de Rede
  • Bruno
  • curl

  Atenção

  Para cenários em que você tem dados confidenciais, como credenciais, segredos, tokens de acesso, chaves de API e outras informações semelhantes, use uma ferramenta que proteja seus dados com os recursos de segurança necessários. A ferramenta deve funcionar offline ou localmente e não exigir entrar em uma conta online ou sincronizar dados com a nuvem. Ao usar uma ferramenta com essas características, você reduz o risco de expor dados confidenciais ao público.

Limitações

• O conteúdo XML que você deseja decodificar precisa ser codificado no formato UTF-8.

• No esquema de arquivo simples, os grupos XML contidos não devem ter números excessivos da propriedade max count definidos com um valor maior que 1. Evite aninhar um grupo XML com um valor de propriedade max count maior que 1 dentro de outro grupo XML com uma propriedade max count maior que 1.

• Quando os Aplicativos Lógicos do Azure analisam o esquema de arquivo simples e quando o esquema permite a escolha do próximo fragmento, os Aplicativos Lógicos do Azure geram um símbolo e uma previsão para esse fragmento. Se o esquema permitir muitos constructos, por exemplo, mais de 100.000, a expansão do esquema se tornará muito grande, o que consome muitos recursos e muito tempo.

Carregar esquema

Depois de criar seu esquema, carregue o esquema com base no fluxo de trabalho:

• Consumo: Adicionar esquemas a contas de integração para fluxos de trabalho de Consumo

• Padrão: adicionar esquemas a contas de integração para fluxos de trabalho Standard

Adicionar uma ação de codificação de arquivo simples

1. Abra o recurso de aplicativo lógico no portal do Azure.

2. Na ferramenta designer, abra o fluxo de trabalho.

   Se o fluxo de trabalho não tiver um gatilho ou outras ações necessárias, adicione essas operações primeiro.

   Este exemplo usa o gatilho de solicitação chamado Quando uma solicitação HTTP é recebida. Para adicionar um gatilho, consulte Adicionar um gatilho para iniciar seu fluxo de trabalho.

3. No designer, siga estas etapas gerais para adicionar a ação interna chamada Codificação de Arquivo Simples.

   O painel de informações de ação é aberto com a guia Parâmetros selecionada.

4. No parâmetro Conteúdo da ação, forneça o conteúdo XML para codificar, que é a saída do gatilho ou de uma ação anterior, seguindo estas etapas:

   1. Selecione dentro da caixa Conteúdo e, em seguida, selecione o ícone relâmpago para abrir a lista de conteúdo dinâmico.

   2. Na lista de conteúdo dinâmico, selecione o conteúdo XML a ser codificado.

   O exemplo a seguir mostra a lista de conteúdo dinâmico aberto, a saída do gatilho Quando uma solicitação HTTP é recebida e o conteúdo do Corpo selecionado da saída do gatilho.

   

   Observação

   Se Body não aparecer na lista de conteúdo dinâmico, ao lado do rótulo Quando uma solicitação HTTP é recebida, selecione Mostrar mais. Você também pode inserir diretamente o conteúdo para codificação na caixa Conteúdo.

5. Na lista Nome do esquema, selecione o esquema.

   

   Observação

   Se a lista de esquemas estiver vazia, a causa poderá ser:

   • O recurso de aplicativo lógico não está vinculado a uma conta de integração.
   • A conta de integração vinculada não contém nenhum arquivo de esquema.
   • O recurso de aplicativo lógico não contém nenhum arquivo de esquema. Esse motivo se aplica apenas aos aplicativos lógicos Standard.

6. Para adicionar outros parâmetros opcionais à ação, selecione esses parâmetros na lista de parâmetros Avançados .

   Parâmetro	Valor	Descrição
   Modo de geração de nó vazio	ForcedDisabled ou HonorSchemaNodeProperty ou ForcedEnabled	O modo a ser usado para geração de nós vazios com a codificação de arquivo simples. Para BizTalk, o esquema de arquivo simples tem uma propriedade que controla a geração de nós vazios. Você pode seguir o comportamento da propriedade de geração de nós vazios para o esquema de arquivos simples. Como alternativa, você pode usar essa configuração para que os Aplicativos Lógicos do Azure gerem ou omita nós vazios. Para obter mais informações, confira Marcas para elementos vazios.
   Normalização de XML	Sim ou Não	A configuração para habilitar ou desabilitar a normalização de XML na codificação de arquivo simples. Para obter mais informações, confira XmlTextReader.Normalization.

7. Salve seu fluxo de trabalho. Selecione Salvar na barra de ferramentas do designer.

Adicionar uma ação de decodificação de arquivo simples

1. Abra o recurso de aplicativo lógico no portal do Azure.

2. Na ferramenta designer, abra o fluxo de trabalho.

   Se o fluxo de trabalho não tiver um gatilho ou outras ações necessárias, adicione essas operações primeiro.

   Este exemplo usa o gatilho de solicitação chamado Quando uma solicitação HTTP é recebida. Para adicionar um gatilho, consulte Adicionar um gatilho para iniciar seu fluxo de trabalho.

3. No designer, siga estas etapas gerais para adicionar a ação interna chamada Decodificação de Arquivo Simples.

4. No parâmetro Conteúdo da ação, forneça o conteúdo XML a ser decodificado, como saída do gatilho ou de uma ação anterior seguindo estas etapas:

   1. Selecione dentro da caixa Conteúdo e, em seguida, selecione o ícone relâmpago para abrir a lista de conteúdo dinâmico.

   2. Na lista de conteúdo dinâmico, selecione o conteúdo XML a ser decodificado.

   O exemplo a seguir mostra a lista de conteúdo dinâmico aberto, a saída do gatilho Quando uma solicitação HTTP é recebida e o conteúdo do Corpo selecionado da saída do gatilho.

   

   Observação

   Se você não vir Corpo na lista de conteúdo dinâmico, selecione Ver mais ao lado do rótulo da seção Quando uma solicitação HTTP é recebida. Você também pode inserir diretamente o conteúdo para decodificação na caixa Conteúdo.

5. Na lista Nome do esquema, selecione o esquema.

   

   Observação

   Se a lista de esquemas estiver vazia, a causa poderá ser:

   • O recurso de aplicativo lógico não está vinculado a uma conta de integração.
   • A conta de integração vinculada não contém nenhum arquivo de esquema.
   • O recurso de aplicativo lógico não contém nenhum arquivo de esquema. Esse motivo se aplica apenas aos aplicativos lógicos Standard.

6. Salve seu fluxo de trabalho. Selecione Salvar na barra de ferramentas do designer.

Agora, você concluiu a configuração de sua ação de decodificação de arquivo simples. Em um aplicativo real, convém armazenar os dados decodificados em um aplicativo LOB (linha de negócios), como o Salesforce. Ou, você pode enviar os dados decodificados para um parceiro comercial. Para enviar a saída da ação de decodificação para o Salesforce ou para seu parceiro comercial, use os outros conectores disponíveis nos Aplicativos Lógicos do Azure:

• Conectores gerenciados nos Aplicativos Lógicos do Azure
• Conectores integrados em Aplicativos Lógicos do Azure

Adicionar uma ação de geração de esquema de arquivo simples

A ação Geração de Esquema de Arquivo Simples gera um esquema de arquivo simples XSD em runtime a partir do conteúdo de arquivo simples de exemplo que você fornece como entrada. O esquema gerado é compatível com anotações de arquivo simples biztalk, como b:schemaInfo, b:recordInfoe b:fieldInfo.

1. Abra o recurso de aplicativo lógico no portal do Azure.

2. Na ferramenta designer, abra o fluxo de trabalho.

   Se o fluxo de trabalho não tiver um gatilho ou outras ações necessárias, adicione essas operações primeiro.

   Este exemplo usa o gatilho de solicitação chamado Quando uma solicitação HTTP é recebida. Para adicionar um gatilho, consulte Adicionar um gatilho para iniciar seu fluxo de trabalho.

3. No designer, siga estas etapas gerais para adicionar a ação interna chamada Geração de Esquema de Arquivo Simples.

4. No parâmetro Conteúdo da ação, forneça o conteúdo de exemplo de arquivo simples.

   Você pode usar o conteúdo da saída do gatilho ou de uma ação anterior:

   1. Selecione dentro da caixa Conteúdo e, em seguida, selecione o ícone relâmpago para abrir a lista de conteúdo dinâmico.

   2. Na lista de conteúdo dinâmico, selecione o conteúdo de arquivo simples de exemplo.

5. Defina o parâmetro estrutura de registro como Delimitado ou Posicional.

   O designer usa parâmetros dinâmicos (getFlatFileSchemaGenerationParameters) para mostrar o conjunto de parâmetros correto, com base no valor selecionado recordStructure .

   O exemplo a seguir mostra os parâmetros de configuração para a estrutura de registro delimitada :

   

   O exemplo a seguir mostra os parâmetros de configuração para a estrutura de registro posicional :

   

6. Para a estrutura de registros selecionada, defina os parâmetros obrigatórios e opcionais.

   Parâmetros comuns (delimitados e posicionais)

   Parâmetro	Tipo	Obrigatório	Descrição
   content	Any	Yes	Conteúdo de dados de exemplo de arquivo simples (cadeia de caracteres ou binário).
   recordStructure	String	Yes	Delimited ou Positional.
   hasHeader	booleano	Yes	Se true, trata a primeira linha de registro como o cabeçalho e usa esses valores como os nomes de campo gerados.
   recordDelimiter	String	No	Delimitador de registro (linha). A análise usa esse valor literalmente (sem decodificação hex). Use caracteres reais, como \r\n ou \n. Para usar a divisão de linha padrão, omita esse valor. O XSD gerado pode emitir um valor hex (0x0D0A) em anotações de esquema.
   recordDelimiterOrder	String	No	Posicionamento do delimitador: Infix (padrão) Prefixou Postfix.
   rootElementName	String	No	Nome do elemento raiz para o XSD. Padrão: Root.
   targetNamespace	String	No	Namespace de destino do esquema. Padrão: http://schemas.microsoft.com/FlatFile/{RootElementName}
   recordName	String	No	Nome do elemento de registro filho recorrente. Padrão: {RootElementName}_Record

   Parâmetros específicos delimitados

   Parâmetro	Tipo	Obrigatório	Descrição
   fieldDelimiter	String	Yes	Os caracteres delimitadores de campo, como vírgula, ponto e vírgula, guia, Fornecer caracteres reais, como ,, ;ou \t. A análise sintática usa comparação literal de cadeias de caracteres (sem decodificação hexadecimal).
   fieldDelimiterOrder	String	Yes	Posicionamento do delimitador: Infix (padrão) Prefixou Postfix.
   escapeCharacter	String	No	O caractere de escape para delimitadores incorporados em valores de campo. Forneça o caractere real, como \ ou ". A análise usa correspondência literal (sem decodificação hex).

   Parâmetros específicos de posição

   Parâmetro	Tipo	Obrigatório	Descrição
   countPositionsByByte	booleano	Yes	Mede os comprimentos do campo em bytes (true) ou caracteres (false). Relevante para codificações de vários bytes.
   fieldPositions	Array	Yes	Matriz de objetos de posição de campo, cada um com length e justification.
   fieldPositions[].length	Integer	Yes	Largura fixa do campo.
   fieldPositions[].justification	String	Yes	Controla o alinhamento do padding. Insira manualmente o valor Left ou Right (não diferencia maiúsculas de minúsculas). Observação: o designer atual não fornece uma lista para você selecionar um valor.

7. Antes de executar o fluxo de trabalho, examine o delimitador e o comportamento do caractere de escape:

   Comportamento do delimitador de registro

   Aspecto	Behavior
   Análise (divisão de linhas)	options.RecordDelimiter (valor bruto do usuário) passa diretamente para String.Split(). Nenhuma decodificação hexadecimal.
   Saída XSD	GetRecordDelimiterForSchema() converte da seguinte maneira: - Se for precedido pelo prefixo 0x, deixe passar. - Se estiver vazio, o padrão será 0x0D0A. - Caso contrário, converta caracteres literais em bytes hexadecimais.
   Entrada hex	Não para análise sintática. Se você fornecer 0x0D0A, a análise tentará dividir com base no texto literal 0x0D0A.
   O que fornecer	Use os caracteres literais: \r\n, \n ou omita inteiramente, o que, por padrão, divide com base em \r\n/\n/\r.

   Comportamento do delimitador de campo

   Aspecto	Behavior
   Análise (divisão de campos)	options.FieldDelimiter é passado diretamente para SplitDelimitedRecord() como uma comparação literal de string. Sem decodificação hexadecimal.
   Saída XSD	Se o valor começar com 0x, emitirá child_delimiter_type="hex"; caso contrário, "char".
   Entrada hex	Não para análise sintática. 0x09 corresponde ao texto literal 0x09, não a uma tabulação.
   O que fornecer	Use caracteres reais): ,, ;, , \te |assim por diante.

   Comportamento do caractere de escape

   Aspecto	Behavior
   Análise (escape)	options.EscapeCharacter é comparado literalmente. Quando há correspondência, o caractere seguinte é consumido como está. Sem decodificação hexadecimal.
   Saída XSD	Se o valor começar com 0x, emitirá escape_char_type="hex"; caso contrário, "char".
   Entrada hex	Não para análise sintática. Mesmo comportamento de correspondência literal.
   O que fornecer	Use o caractere real, por exemplo, \ ou ".

8. Salve seu fluxo de trabalho. Selecione Salvar na barra de ferramentas do designer.

9. Para usar a saída de esquema gerada para decodificar ou codificar ações, salve manualmente essa saída como um .xsd arquivo.

10. Carregue o arquivo .xsd para sua conta de integração. Ou, para fluxos de trabalho Standard, carregue o arquivo na pasta artefatos do recurso de aplicativo lógico. Você também pode usar a API REST para fazer upload do artefato do esquema.

    O esquema gerado é retornado no corpo das saídas da ação como uma cadeia de caracteres:

    @body('Flat_File_Schema_Generation')
    

11. Opcionalmente, use os seguintes exemplos de definição:

    Exemplo delimitado

    {
       "Flat_File_Schema_Generation": {
          "type": "FlatFileSchemaGeneration",
          "runAfter": {},
          "inputs": {
             "content": "@triggerBody()",
             "recordStructure": "Delimited",
             "fieldDelimiter": ";",
             "fieldDelimiterOrder": "Infix",
             "recordDelimiter": "\\r\\n",
             "hasHeader": true,
             "rootElementName": "MerchantOrders",
             "targetNamespace": "http://schemas.contoso.com/FlatFile/MerchantOrders",
             "recordName": "MerchantOrder",
             "escapeCharacter": "\\"
          }
       }
    }
    

    Exemplo posicional

    {
       "Flat_File_Schema_Generation": {
          "type": "FlatFileSchemaGeneration",
          "runAfter": {},
          "inputs": {
             "content": "@triggerBody()",
             "recordStructure": "Positional",
             "fieldPositions": [
                { "length": 6, "justification": "Left" },
                { "length": 5, "justification": "Left" },
                { "length": 3, "justification": "Left" }
             ],
             "countPositionsByByte": false,
             "hasHeader": false,
             "rootElementName": "Ledger",
             "targetNamespace": "http://schemas.contoso.com/FlatFile/Ledger"
          }
       }
    }
    

    Passe o esquema gerado para a próxima ação:

    {
       "Next_Action": {
          "inputs": {
             "schema": "@body('Flat_File_Schema_Generation')"
          },
          "runAfter": {
             "Flat_File_Schema_Generation": [ "Succeeded" ]
          }
       }
    }
    

12. Examine a saída, as regras de inferência e os problemas conhecidos:

    Saída:

    Propriedade	Tipo	Descrição
    body	String	Esquema XSD compatível com BizTalk gerado como uma cadeia de caracteres XML.

    Conteúdo XSD gerado em alto nível:

    • b:schemaInfo anotação com standard="Flat File", root_referencee codepage="65001" (UTF-8)
    • Anotações por registro b:recordInfo com structure, child_delimiter, child_delimiter_type, child_order e escape_char e escape_char_type opcionais
    • b:fieldInfo anotações por campo com justification e, para esquemas posicionais, pos_offset e pos_length
    • Inferência do tipo de dados a partir de dados de exemplo: xs:string, xs:integer, xs:decimal, xs:boolean, xs:date, xs:dateTime

    Inferência de tipo de dados do primeiro registro de dados não vazio:

    Valor de amostra	Tipo XSD inferido
    true ou false	xs:boolean
    12345	xs:integer
    19.99	xs:decimal
    2025-01-15	xs:date
    2025-01-15T10:30:00	xs:dateTime
    Qualquer outro valor	xs:string

    Ordem filho (posicionamento do delimitador):

    Pedido	Meaning	Exemplo (;)
    Infix	Delimitador entre campos	A;B;C
    Prefix	Delimitador antes de cada campo	;A;B;C
    Postfix	Delimitador após cada campo	A;B;C;

    Gerenciamento de cabeçalhos:

    • Quando hasHeader é true, a primeira linha é tratada como nomes de campo, não dados.
    • Os valores de cabeçalho são convertidos em nomes de elementos XML válidos. Caracteres especiais se tornam _, e os dígitos principais obtêm um _ prefixo.
    • Se houver apenas uma linha de cabeçalho e nenhum registro de dados existir, os campos serão padrão para xs:string.
    • Se um campo de cabeçalho estiver em branco, o nome do campo gerado retornará para Field{N}.
    • Quando hasHeader éfalse, os campos são nomeados Field1automaticamente, Field2Field3e assim por diante.

Limitações e problemas conhecidos

Solucionar problemas

Testar seu fluxo de trabalho

Para disparar seu fluxo de trabalho, siga estas etapas:

1. No disparador Solicitação, encontre o parâmetro URL de HTTP POST e copie a URL.

2. Abra sua ferramenta de solicitação HTTP e use suas instruções para enviar uma solicitação HTTP para a URL copiada, incluindo o método esperado pelo gatilho de Solicitação.

   Esse exemplo usa o método POST com o URL.

3. Inclua o conteúdo XML que você quer codificar ou decodificar no corpo da solicitação.

4. Depois que o fluxo de trabalho terminar de ser executado, vá para o histórico de execução do fluxo de trabalho e examine as entradas e saídas da ação Flat File.

Conteúdo relacionado

• Processar mensagens XML e arquivos simples nos Aplicativos Lógicos do Azure