Usar políticas para conversão de dados
Os modelos de política podem ser usados para converter dados de uma estrutura para outra. Esse processo normalmente é feito para simplificar a tarefa do criador usando um conector personalizado para fornecer dados às ações ou trabalhar com os dados de resposta dos resultados da ação. Por exemplo, a API pode fornecer uma lista separada por vírgulas de usuários que têm acesso ao registro. A conversão dessa lista em uma matriz facilita o uso da lista em um aplicativo ou fluxo. Os seguintes modelos de política oferecem suporte à conversão de estruturas de dados:
Converter uma matriz em um objeto
Converter um objeto em uma matriz
Converter cadeia de caracteres delimitada em matriz de objetos
Cada política pode ser executada na solicitação (dados de entrada) ou na resposta (dados de saída) de uma ou mais ações. Ao executar uma política na solicitação, você molda os dados fornecidos pelo criador para determinar como a API deseja vê-la. Por exemplo, o conector do Microsoft Planner usa a matriz Converter para um objeto na ação Atualizar detalhes da tarefa. Esta ação permite que o usuário forneça uma matriz de links de referência externos e os associe à tarefa. Ao permitir que o criador os especifique como uma matriz, os usuários são apresentados com uma interface amigável que permite adicionar vários links selecionando Adicionar novo item.
Se você usar o recurso de espiada na etapa de ação, poderá ver como os dados são estruturados e serão apresentados à API, caso nenhuma transformação tenha sido feita pelos modelos de política no conector.
Se você olhar os documentos da API do Microsoft Planner para esta operação, observe que ela deseja que os dados sejam estruturados como o exemplo a seguir.
Para converter o que foi fornecido pela ação de fluxo para o que é esperado pela API, o conector é configurado para vários modelos de política para transformar os dados. Os modelos de política são usados da seguinte maneira:
Definir Propriedade: para definir o campo previewPriority como "!"
Definir Propriedade: para definir a expressão @odata.type
Converter matriz em objeto: para remodelar a matriz e incluir tipo e alias como propriedades
A política Converter matriz em objeto seria semelhante ao exemplo a seguir.
Os modelos de política executados na resposta permitem que a remodelação da saída da API. Por exemplo, a resposta da Contoso Invoicing da ação Obter fatura inclui uma lista de marcas separadas por ponto e vírgula como parte do objeto de fatura. Os dados retornados da API se assemelham à captura de tela a seguir.
Uma cadeia de caracteres com vários valores é mais difícil para os aplicativos e os fluxos trabalharem do que uma matriz. Para melhorar a usabilidade, é possível usar o modelo de política Converter cadeia de caracteres delimitada na resposta. O exemplo a seguir mostra o modelo de política que você configuraria.
Essa ação resultaria em uma nova matriz chamada lista de marcas adicionada à resposta, conforme mostrado na imagem a seguir.
Agora que você explorou alguns exemplos de modelos de política em uso, pode revisar alguns detalhes importantes de configuração. O parâmetro Executar política em decide se a política se aplica à solicitação ou resposta. Se você precisar de ambos, será necessário configurar dois modelos de política.
Cada modelo de política de conversão tem um objeto de destino ou um parâmetro de coleção. Esse fator fornece o ponto de partida para onde a lógica da política fará com que os dados sejam transformados. O ponto de partida mais comum é usar a expressão @body(), que aponta para o corpo da solicitação ou resposta. No exemplo a seguir, a expressão @body() é um objeto e tem uma propriedade chamada marcas.
Como alternativa, se a resposta era um objeto com uma propriedade chamada faturas que era uma matriz de objetos de fatura, cada qual com uma propriedade marcas, a configuração seria semelhante à imagem a seguir.
Ao configurar políticas, certifique-se de aplicá-las somente às ações com dados de solicitação/resposta que correspondam a essas configurações. Por exemplo, a ação Obter fatura, que retorna um único objeto de fatura, precisaria de modelos de política diferentes aplicados à ação Listar fatura, que retorna uma matriz de objetos de fatura. Se você estiver adicionando modelos de política a um conector existente com todas as ações habilitadas, certifique-se de testar todas as ações e gatilhos para garantir que funcionem com a nova política.
Após configurar os modelos de política de resposta, certifique-se de reimportar os dados de exemplo na resposta de ação. Essa etapa é necessária para que os aplicativos e os fluxos possam ter visibilidade para os dados transformados.
Se a configuração de um modelo de política gerar um erro, você normalmente o verá no testador como um status HTTP de 500 ou não conseguirá fazer qualquer processamento. Embora não seja possível desabilitar uma política, você pode remover uma ação da lista de operações para permitir o teste para isolar se a política está causando problemas. A imagem a seguir mostra apenas duas operações selecionadas.
Converter modelos de política oferece uma abordagem focada na configuração para transformar dados de e para a API subjacente. Elas podem ser usadas para facilitar o uso de ações de conector.