Estrutura de Aplicativos Lógicos do Azure para conectores primários

  • Artigo

Estamos construindo uma estrutura que permitirá que parceiros e provedores de soluções criem conectores e os integrem à solução Microsoft Sustainability Manager. Este artigo fornece detalhes sobre o primeiro grupo de conectores que criamos usando os Aplicativos Lógicos do Azure em colaboração com a equipe de parceiros. Este artigo fornece orientação sobre como criar um conector de Aplicativos Lógicos para o Microsoft Sustainability Manager e compartilhar os dados necessários para calcular a pegada de carbono e sustentabilidade para os clientes.

Termos-chave

Você precisará conhecer as seguintes definições usadas neste artigo:

Provedor: um provedor é um parceiro que oferece um ou mais serviços que permitem uma conexão enriquecida e pré-configurada com uma solução de dados. As organizações selecionam os provedores que se aplicam aos seus negócios conectando-se a eles. Depois de se conectarem, uma instância desse provedor é criada e pode incluir mais de uma solução de provedor. Os clientes podem estabelecer uma conexão com cada solução de provedor para trazer seus dados para o Microsoft Sustainability Manager.

Conector: um conector é um software integrado ao produto ou fornecido como um módulo separado que permite ao usuário ingerir (ou importar) dados para o Microsoft Sustainability Manager. Os provedores podem ter um ou mais conectores para cada uma de suas soluções às quais um usuário se conecta.

Aplicativos lógicos: os Aplicativos Lógicos do Azure são uma plataforma de nuvem onde você pode criar e executar fluxos de trabalho automatizados com pouco ou nenhum código. Usando o designer visual e selecionando operações predefinidas, você pode criar rapidamente um fluxo de trabalho que integra e gerencia aplicativos, dados, serviços e sistemas.

A tabela a seguir define de forma sucinta a terminologia e os conceitos principais nos Aplicativos Lógicos do Azure.

Termo Description
Logic App O recurso do Azure que você cria quando quer desenvolver um fluxo de trabalho. Existem vários tipos de recursos de aplicativos lógicos executados em diferentes ambientes.
Workflow Uma série de etapas que definem uma tarefa, processo de negócios ou carga de trabalho. Cada fluxo de trabalho começa com um único gatilho, após o qual é necessário adicionar uma ou mais ações.
Gatilho Sempre a primeira etapa em qualquer fluxo de trabalho e especifica a condição para executar quaisquer outras etapas nele. Por exemplo, neste artigo, usaremos um gatilho HTTP para desencadear os aplicativos lógicos e passar os parâmetros do gatilho como conteúdo do corpo.
Para As etapas subsequentes em um fluxo de trabalho que seguem o gatilho. Cada ação executa alguma operação em um fluxo de trabalho.
Modelo do Azure Resource Manager (ARM) Um modelo do ARM é um arquivo JavaScript Object Notation (JSON) que define a infraestrutura e a configuração do projeto. O modelo usa sintaxe declarativa. Na sintaxe declarativa, você descreve a implantação pretendida sem escrever a sequência de comandos de programação para criar a implantação.

Requisitos da solução do provedor

A Microsoft Cloud for Sustainability e seus parceiros criarão conectores para a solução Microsoft Sustainability Manager a fim de obter conjuntos de dados completos para uma ou mais emissões de carbono e categorias de sustentabilidade. Os conectores devem atender aos seguintes requisitos:

  • Estar disponível em todas as regiões e atender a diferentes tipos de setores de clientes e tamanhos operacionais.

  • Permita a separação de usuários para credenciais de conexão (administrador do sistema de destino) e configuração de conexão (usuário do Microsoft Sustainability Manager).

  • Forneça ferramentas para desenvolvedores, área restrita e documentação de suporte para criar POC, se necessário.

Além disso, cada conector deve fornecer os seguintes itens:

  • Dados de atividade, dados de referência ou emissões pré-calculadas essenciais para definir o direito de carbono e sustentabilidade

  • Capacidade de recuperar dados da solução do parceiro autenticando por meio de credenciais do usuário

  • Capacidade de automatizar o mapeamento de dados de entidades e atributos

Design de alto nível de Conectores de Aplicativos Lógicos

O design de alto nível a seguir dos conectores de Aplicativos Lógicos inclui uma breve descrição do fluxo de ingestão da perspectiva do usuário. Essas etapas não são as que você seguiria para criar um conector, mas uma visão geral de como o conector é usado.

  1. Seleção do conector:

    1. O usuário receberá uma mensagem com o tipo de dados que gostaria de ingerir junto com o escopo e a categoria.
    2. Na próxima etapa, uma lista exibe conectores personalizados e Power Query que oferecem suporte ao tipo de dados, escopo e categoria que o usuário selecionou.

  2. Seleção de credenciais:

    1. Para criar uma credencial para um conector de Aplicativos Lógicos, os usuários precisam especificar as credenciais.
    2. O Microsoft Sustainability Manager valida as credenciais usando o protocolo especificado pelo parceiro e envia a solicitação de conexão ao back-end.

  3. Criação de conexão e gatilho:

    1. Para atender à solicitação de conexão, a Microsoft implanta uma instância de Aplicativos Lógicos usando o modelo do ARM especificado pelo parceiro. O modelo do ARM deve seguir o paradigma do conector descrito posteriormente nesse artigo.
    2. Depois que a instância de Aplicativos Lógicos é implantada, ela é desencadeada uma vez e o usuário pode agendá-la para execuções diárias. A criação da conexão já está concluída.
    3. Opcionalmente, o usuário pode desencadear a própria instância de Aplicativos Lógicos na interface do usuário.

  4. Ingestão no Dataverse:

    1. Cada execução de fluxo de trabalho de Aplicativos Lógicos (seja desencadeada manualmente ou agendada) envia os dados transformados em partes por chamada HTTPS para o microsserviço de Sustentabilidade. Em seguida, os dados seriam validados e ingeridos no ambiente do cliente.

  5. Exclusão de conexão:

    1. A exclusão da conexão é tratada pela estrutura dos Aplicativos Lógicos. Quando um usuário exclui uma conexão de Aplicativos Lógicos, desprovisionamos a instância de Aplicativos Lógicos para a conexão especificada e, depois, excluímos a própria conexão.
    2. A exclusão da entidade de conexão também excluiria em cascata as IDs de atualização da conexão.

Construir um conector de Aplicativos Lógicos

Para criar um conector primário no Microsoft Sustainability Manager, siga estas etapas para compilar a definição do conector, a definição do provedor, o modelo do ARM de Aplicativos Lógicos e a configuração de credenciais. Adicione esses arquivos a um repositório GitHub privado e adicione nossa equipe como colaborador: mcfsconnectors@microsoft.com.

Etapa 1: revisão dos dados

A primeira etapa na criação de um conector inclui a revisão do tipo de dados disponível na solução do parceiro e o aplicativo no Microsoft Sustainability Manager. Esses tipos de dados podem incluir dados de atividades, dados de referência ou emissões pré-calculadas, todos os quais são fundamentais para definir direitos de carbono e sustentabilidade.

Etapa 2: definir conector e provedor ou parceiro

A próxima etapa para criar o conector inclui a coleta de informações adicionais sobre a solução que está sendo integrada ao Microsoft Sustainability Manager.

  • Definição do provedor:

    Informações Description
    Name Nome da empresa.
    Description Uma breve descrição da empresa.
    Logotipo Logotipo da empresa em formato SVG.
    URL URL da empresa.

  • Definição do conector:

    Informações Description
    Name Nome de exibição do conector.
    Description Uma breve descrição de duas frases sobre o conector.
    Logotipo Ícone do conector no formato SVG.
    Tipo de dados O tipo de dados que esse conector ingere para o usuário. Por exemplo: dados de atividade, escopo 1, categoria 2. Para obter mais informações sobre tipos de dados, acesse Registro.

Esta imagem fornece um exemplo de como um conector seria exibido. Este exemplo mostra o logotipo de amostra. Conector de dados de distribuição é o nome de exibição, Johnnie McConnel é o nome do provedor e Nossos dados internos é a descrição.

Exemplo de exibição de um conector de Aplicativos Lógicos.

Etapa 3: defina uma fonte de dados

Antes de criar um aplicativo lógico, você precisa definir a fonte de dados e como ela pode ser acessada usando credenciais de usuário. Consulte alguns exemplos:

  • REST HTTP: você pode expor um HTTP API REST para expor dados ao aplicativo lógico. É possível usar mecanismos de autenticação HTTP para acessar esses dados a partir do nosso aplicativo lógico.

  • Azure Data Lake Storage: <https://<adlsname>.blob.core.windows.net/<nome da pasta>/<nome do arquivo>>, nesse caso, o aplicativo lógico precisaria de acesso relevante a essa URL com o token SAS apropriado.

  • Tabela MySQL: <jdbc:mysql:replication//myUser:myPassword@[address=(host=myHost1)(port=1111)(key1=value1)]> Os dados podem ser armazenados em um banco de dados. Nesse caso, o aplicativo lógico pode exigir o ponto de extremidade do banco de dados junto com uma ID de usuário e senha válidos. Também pode exigir o nome da tabela onde os dados a serem ingeridos são armazenados. Para obter mais informações sobre como se conectar a um banco de dados SQL, acesse Conecte-se a um banco de dados SQL de fluxos de trabalho nos Aplicativos Lógicos do Azure.

  • AWS S3: <s3.Region.amazonaws.com> Os dados podem ser armazenados em um bucket do S3 ou em um armazenamento de arquivo semelhante. O controle de acesso relevante seria exigido pela instância de Aplicativos Lógicos para acessar esse bucket de armazenamento.

Etapa 4: obter informações de credenciais

Depois de definir a fonte de dados e os detalhes de acesso, é necessário fornecer as informações de credenciais que devem ser coletadas do usuário para autenticação nos dados de origem.

Para conectores primários, o Microsoft Sustainability Manager atualmente não oferece suporte a SSO. As credenciais serão coletadas e armazenadas no ambiente Dataverse do cliente.

Quando os usuários criam uma conexão de Aplicativos Lógicos do Microsoft Sustainability Manager, eles visualizarão uma página semelhante à imagem a seguir para inserir detalhes de conexão relevantes entre o aplicativo lógico hospedado do Microsoft Sustainability Manager e o parceiro.

Captura de tela de uma página Adicionar credenciais.

Observação

A página Adicionar credenciais é uma página dinâmica que pode variar de acordo com o conector do parceiro. Esses campos são definidos por um arquivo JSON e podem ser diferentes para cada conector, conforme definido pelo parceiro. Uma verificação de validação é realizada para garantir que essas credenciais sejam válidas antes de serem salvas.

A Microsoft criará o arquivo JSON para a página de credenciais. Você só precisa responder às seguintes perguntas para gerarmos o arquivo.

Pergunta Exemplo
De quais informações de credencial do usuário você precisaria? Nome de usuário, senha, segredos, chave API, etc.
Quais são os vários tipos de campo? Oferecemos suporte a todos os tipos de entrada HTML, como caixa de texto, caixa de seleção, menu suspenso, botão de opção, etc. Nome de usuário: caixa de texto, Senha: caixa de texto, Região: menu suspenso.
Insira o nome dos campos que precisam ser mascarados. Senha, segredo.
Insira a URL com cabeçalhos e corpo onde podemos fazer uma chamada HTTP com as credenciais para validá-la. Adicione também uma resposta com o conteúdo e o código de status. POST: https:api.partner.com/token
Corpo:
{
“username”:”xyz”, “password”:”test”
}
Resposta:
“status”:
“message”:
“type”:
}

Etapa 5: criar o aplicativo lógico

A próxima etapa inclui a criação de um aplicativo lógico. A Microsoft fornecerá um modelo do ARM de amostra que você pode carregar na assinatura do Azure e começar a usá-lo para desenvolver um aplicativo lógico que executa as seguintes ações:

  • Use as credenciais do usuário para autenticar o sistema e obter dados da fonte de dados de forma paginada.

  • Aplique transformações e mapeie os dados para o modelo de dados de sustentabilidade ou modelo de dados de água.

  • Adicione os dados transformados em uma matriz JSON.

Para implantar automaticamente um modelo de aplicativo lógico no Azure, você pode selecionar o seguinte botão Implantar no Azure, que o conecta ao portal do Azure e solicita a ID da assinatura e o nome do grupo de recursos onde esse aplicativo lógico será implantado.

Implantar no Azure

Este aplicativo lógico de exemplo é um ponto de partida para o conector primário. As entradas para esse conector são enviadas por meio do gatilho HTTPS da instância do Microsoft Sustainability Manager do cliente. Esse gatilho HTTP contém detalhes fornecidos durante a configuração do conector (incluindo ponto de extremidade personalizado e credenciais).

Depois de implantar o aplicativo lógico, você pode exibi-lo e editá-lo no designer de aplicativos:

Captura de tela do designer de aplicativo.

Breve descrição das ações:

  1. Gatilho: o Microsoft Sustainability Manager desencadeará o aplicativo lógico de parceiro para ser executado por meio de um gatilho HTTP passando os detalhes de conexão fornecidos pelo cliente na Etapa 4: obter informações de credencial. Os aplicativos lógicos de parceiros usarão um subconjunto dos seguintes parâmetros de gatilho:

    Captura de tela dos parâmetros do gatilho.

    • ID e segredo do cliente: credenciais que o usuário insere na página de credenciais do Microsoft Sustainability Manager. Esses parâmetros podem variar dependendo de como você autentica a fonte de dados. Por exemplo, em vez de ID e segredo do cliente, você pode usar nome de usuário, senha ou chave de API. Substitua-os pelas credenciais identificadas na etapa anterior.

    • Hora da última atualização: este parâmetro é um carimbo de data/hora no fuso horário UTC e é usado para atualizações incrementais. O aplicativo lógico só deve extrair e processar dados onde dataCreateTime>= lastRefreshTime.

  2. InitializeContinuationToken: esta ação inicializa a variável ContinuationToken como nula. Essa variável será usada para sair do "until loop", que extrai dados de forma paginada.

  3. Try: qualquer lógica para extrair e transformar dados deve estar dentro do bloco try. Se alguma etapa dentro do bloco try falhar, o fluxo de execução será pulado para o bloco catch, onde a equipe da Microsoft adicionará lógica para lidar com cenários de erro. A imagem a seguir mostra as ações dentro do bloco try.

    Captura de tela do bloco try.

A ação obter token usa as credenciais do usuário para obter o token de acesso e usá-lo para chamar o ponto de extremidade do parceiro e conectar-se à fonte de dados para obter os dados do usuário. Dependendo do tamanho dos dados, os dados da fonte de dados devem ser acessados de forma paginada para evitar tempos limite. A próxima etapa mapeará os dados para o modelo de dados do Microsoft Sustainability Manager.

Captura de tela do mapeamento de dados para o modelo de dados do Microsoft Sustainability Manager.

Este modelo usa a entidade Purchased Electricity como um exemplo para demonstrar a lógica de mapeamento, mas será necessário mapear os dados para a entidade compatível com o conector. Depois que os dados forem mapeados, você armazenará a matriz de dados em uma variável e enviará os dados para o Microsoft Sustainability Manager em uma solicitação POST. PostDataToMSM é um exemplo de como a solicitação HTTP deve ser construída.

Você pode enviar dados para o Microsoft Sustainability Manager em vários lotes fazendo várias solicitações POST ou de uma só vez, dependendo do tamanho dos dados. A ação Ingestão Completa mostra como deve ser a última solicitação para o Microsoft Sustainability Manager. A Microsoft chama o mesmo ponto de extremidade e define a variável isIngestionComplete como true. Após esta solicitação, o Microsoft Sustainability Manager iniciará o processamento dos dados para ingeri-los no ambiente do cliente.

A imagem a seguir fornece um exemplo de como os registros de dados devem ser estruturados:

Captura de tela de como os registros de dados devem ser estruturados.

Etapa 6: enviar os arquivos do conector

Adicione todos os arquivos criados nas etapas anteriores em um repositório GitHub privado e inclua a equipe da Microsoft como colaborador. A pasta raiz do repositório deve ser um número de versão (por exemplo, v1.0) e os seguintes arquivos devem estar na pasta:

  • logic_apps_armtemplate.json
  • credentials_info.csv
  • connector_definition.csv
  • provider_definition.csv
  • company_logo.svg
  • connector_logo.svg

A equipe da Microsoft iniciará o processo de validação do aplicativo lógico e adicionará mais ações para concluir o processo de ingestão. Após a etapa de validação, a Microsoft criará um ambiente do Microsoft Sustainability Manager com o conector operacional para o parceiro testar a funcionalidade. A Microsoft também realizará os próprios testes funcionais antes de lançar o recurso para os usuários em visualização ou disponibilidade geral.

Requisitos de suporte do provedor ou parceiro

O parceiro é responsável pela manutenção e operação da fonte de dados. Exigimos uma pessoa de contato com um contrato de nível de serviço (SLA) que a equipe da Microsoft possa contatar durante interrupções e erros relacionados à solução. Os cenários a seguir são exemplos que exigirão suporte do parceiro:

  • Alteração do modelo de dados: uma das etapas mais críticas na construção da integração com o Microsoft Sustainability Manager é mapear o modelo de dados da solução do parceiro com o modelo de dados de sustentabilidade. Se o modelo de dados da solução do parceiro for alterado, o parceiro precisará trabalhar com a equipe do Microsoft Sustainability Manager para remapear o modelo de dados ou fornecer um modelo do ARM atualizado e garantir que os atributos de dados necessários possam ser obtidos da solução.

  • Gerenciamento de credenciais: o principal mecanismo para acessar a solução do parceiro dentro do Microsoft Sustainability Manager é por meio das credenciais da solução do parceiro. Se os usuários não conseguirem autenticar as credenciais no Microsoft Sustainability Manager, o parceiro fornecerá suporte para autenticar e atualizar as credenciais do usuário.

  • Solução não operacional: o parceiro também precisará ajudar o Microsoft Sustainability Manager e seus usuários em situações em que a solução não estiver operacional ou funcional. O Microsoft Sustainability Manager trabalhará com o parceiro para determinar a causa e os cronogramas de resolução para que ele possa se comunicar com seus usuários finais.

  • Atualizações da solução: o parceiro deve fornecer notificação antes de qualquer atualização importante, juntamente com o possível impacto no acesso do usuário no Microsoft Sustainability Manager. Antes de integrar uma solução no Microsoft Sustainability Manager, o parceiro fornecerá cronogramas provisórios para a cadência de atualização da solução, juntamente com a documentação de suporte sobre como isso estenderá o suporte ao Microsoft Sustainability Manager e aos seus usuários caso não consigam acessar a solução do provedor e importar dados.

  • Ambiente de teste: o parceiro deve fornecer um ambiente de teste para o Microsoft Sustainability Manager testar os recursos antes de distribuí-los aos clientes.

Cenários de atualização

Para atualizações no aplicativo lógico ou na configuração do conector, o parceiro deve criar uma nova pasta na raiz do repositório com o novo número de versão (por exemplo, v2.0) e adicionar todos os arquivos nessa pasta. O parceiro também deve incluir um arquivo readme.md na pasta com uma breve explicação do que foi atualizado. Depois que a Microsoft receber os arquivos atualizados, seguiremos o mesmo processo de publicação da primeira versão do conector. Depois que o aplicativo lógico atualizado for lançado para o usuário final, os aplicativos lógicos para conexões existentes serão desprovisionados e a versão mais recente será implantada. Esse processo é tratado pelo nosso sistema, comparando os números de versão no modelo do ARM.

Requisitos de conformidade

Os recursos e serviços de produtos da Microsoft devem passar por análises de privacidade, segurança e conformidade antes de serem colocados em produção. A equipe da Microsoft será proprietária e gerenciará esse processo, mas exigirá coordenação com a equipe do parceiro para coletar as informações necessárias sobre a integração da solução com o Microsoft Sustainability Manager.

Confira também

Importar dados
Documentação dos Aplicativos Lógicos do Azure
Microsoft Sustainability Manager
Modelo de dados da Microsoft Cloud for Sustainability