Conectar-se a um servidor do IBM MQ a partir de um fluxo de trabalho dos Aplicativos Lógicos do Azure

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

Este artigo mostra como acessar um servidor MQ hospedado no Azure ou local de um fluxo de trabalho nos Aplicativos Lógicos do Azure usando o conector MQ. Em seguida, você pode criar fluxos de trabalho que recebem e enviam mensagens armazenadas no servidor MQ. Por exemplo, seu fluxo de trabalho pode procurar uma só mensagem em uma fila e executar outras ações.

O conector MQ fornece um wrapper em torno de um cliente Microsoft MQ, que inclui todos os recursos de mensagens para se comunicar com um servidor MQ remoto através de uma rede TCP/IP. Esse conector define as conexões, operações e parâmetros para chamar o cliente MQ.

Versões compatíveis do IBM WebSphere MQ

• MQ 7.5
• MQ 8.0
• MQ 9.0, 9.1, 9.2 e 9.3

Referência técnica do conector

O conector do MQ tem versões diferentes, com base no tipo de aplicativo lógico e no ambiente do host.

Autenticação com criptografia TLS (SSL)

Com base no fato de você usar o conector gerenciado MQ (fluxos de trabalho Consumo ou Padrão) ou o conector interno MQ (somente fluxos de trabalho Padrão), o conector MQ suporta uma ou ambas as seguintes direções de autenticação:

Observações sobre certificados de chave privada e chave pública

• O certificado que requer validação é sempre um certificado de chave privada. O certificado usado para executar a validação é sempre um certificado de chave pública.

• Um certificado de chave privada publicamente confiável é emitido por uma Autoridade de Certificação reconhecida. Um certificado de chave privada não publicamente confiável inclui CA privada autoassinada e certificados semelhantes.

• Para validar um certificado de chave privada enviado do servidor MQ, o conector MQ usa certificados de chave pública que geralmente existem no host da máquina virtual do aplicativo lógico no Armazenamento de Autoridades de Certificação (CA) Raiz Confiáveis do host.

  No entanto, se o host não tiver todos os certificados de chave pública necessários ou se o servidor MQ enviar um certificado de chave privada não publicamente confiável, você precisará executar etapas extras. Para obter mais informações, veja Pré-requisitos.

• Para validar o certificado de chave privada de um cliente enviado do aplicativo lógico padrão, o servidor MQ usa certificados de chave pública que existem no armazenamento de certificados do servidor MQ. Para adicionar um certificado de chave privada para seu aplicativo lógico usar como um certificado de cliente, consulte Adicionar um certificado de chave privada.

Limitações

• Autenticação com criptografia TLS (SSL)

  Conector MQ	Direção de autenticação suportada
  Gerenciado	Somente servidor (unidirecional)
  Interno	- Servidor-cliente (bidirecional) - Somente servidor (unidirecional)

• Validação de certificado do servidor

  O conector MQ interno não valida a data de expiração do certificado do servidor nem a cadeia de certificados.

• Conversões de conjunto de caracteres

  • O conector gerenciado MQ não faz conversões de conjunto de caracteres nem usa o campo Formato da mensagem. O conector apenas copia os dados que aparecem no campo de mensagem e envia a mensagem junto.

  • O conector MQ integrado pode fazer conversões de conjunto de caracteres, mas somente quando o formato de dados é uma cadeia de caracteres. Se você fornecer uma ID de conjunto de caracteres diferente (página de código), o conector tentará converter os dados para a nova página de código.

• O conector MQ não dá suporte a mensagens segmentadas.

Para obter mais informações, veja a referência do conector gerenciado do MQ ou a referência do conector interno do MQ.

Pré-requisitos

• Uma conta e uma assinatura do Azure. Se você não tiver uma assinatura do Azure, inscreva-se em uma conta gratuita do Azure.

• Para se conectar a um servidor MQ local, você deve instalar o gateway de dados local em um servidor dentro da rede. Para que o conector do MQ funcione, o servidor com o gateway de dados local também precisa ter o .NET Framework 4.6 instalado.

  Após instalar o gateway, você ainda precisa criar um recurso de gateway de dados no Azure. O conector do MQ usa esse recurso para acessar o servidor MQ. Para mais informações, confira Configurar a conexão do gateway de dados.

  Observação

  Você não precisará do gateway nos seguintes cenários:

  • O servidor MQ está disponível publicamente ou no Azure.
  • Você vai usar o conector interno do MQ, não o conector gerenciado.

• O recurso de aplicativo lógico e o fluxo de trabalho onde você deseja acessar seu servidor MQ.

  • Para usar o conector gerenciado MQ com o gateway de dados local, seu recurso de aplicativo lógico deve usar o mesmo local que seu recurso de gateway no Azure.

  • Para usar o conector gerenciado MQ, que não fornece gatilhos, certifique-se de que seu fluxo de trabalho comece com um gatilho ou que você primeiro adicione um gatilho ao seu fluxo de trabalho. É possível, por exemplo, usar o Gatilho de recorrência.

  • Para usar um gatilho do conector interno MQ, certifique-se de começar com um fluxo de trabalho em branco.

• Requisitos de certificado para autenticação com criptografia TLS (SSL)

  • Conector gerenciado MQ

    Servidor MQ	Requisitos
    Servidor MQ hospedado no Azure	O servidor MQ deve enviar um certificado de chave privada emitido por uma autoridade de certificação confiável ao cliente de aplicativo lógico para validação.
    Servidor MQ local usando gateway de dados local	Para enviar um certificado de chave privada não publicamente confiável, como um certificado de autoridade de certificação autoassinado ou privado, você precisa adicionar o certificado ao armazenamento de autoridades de certificação (CA) raiz confiáveis no computador local com a instalação do gateway de dados local. Para essa tarefa, você pode usar o Gerenciador de Certificados do Windows (certmgr.exe).

  • Conector MQ integrado

    Os aplicativos lógicos padrão usam o Serviço de Aplicativo do Azure como a plataforma de host e para manipular certificados. Para aplicativos lógicos padrão em qualquer plano WS*, você pode adicionar certificados públicos, privados, personalizados ou autoassinados ao repositório de certificados do computador local. No entanto, se você precisar adicionar certificados ao Repositório de CA Raiz Confiável no host da máquina virtual em que seu aplicativo lógico padrão é executado, o Serviço de Aplicativo exigirá que seu aplicativo lógico seja executado em um ASE (Ambiente de Serviço de Aplicativo v3) isolado com um plano somente para Windows e um plano de Serviço de Aplicativo baseado em ASE. Para obter mais informações, consulte Certificados e o ambiente do Serviço de Aplicativo.

    • Autenticação do servidor MQ

      A tabela a seguir descreve os pré-requisitos do certificado, com base no seu cenário:

      Certificado do servidor MQ de entrada	Requisitos
      Certificado de chave privada publicamente confiável emitido por uma autoridade de certificação confiável	Normalmente, seu aplicativo lógico não precisa de nenhuma outra configuração porque o host de máquina virtual do aplicativo lógico geralmente tem os certificados de chave pública necessários para validar o certificado de chave privada do servidor MQ de entrada. Para verificar se esses certificados de chave pública existem, siga as etapas para Exibir e confirmar impressões digitais para certificados de chave pública existentes. Se o host da máquina virtual não tiver todos os certificados de chave pública necessários para validar o certificado de chave privada do servidor MQ de entrada e quaisquer certificados de encadeamento, conclua as seguintes etapas: 1. Recrie seu aplicativo lógico padrão usando um ASE (Ambiente do Serviço de Aplicativo do Azure) com um plano de Serviço de Aplicativo somente para Windows e baseado em ASE. 2. Adicione manualmente os certificados de chave pública necessários ao Armazenamento de CA Raiz Confiável do host.
      Certificado de chave privada não publicamente confiável, como um certificado de CA autoassinado ou privado	O host da máquina virtual do aplicativo lógico não terá os certificados de chave pública necessários no Armazenamento de CA Raiz Confiável do host para validar a cadeia de certificados do servidor MQ. Nesse caso, conclua as seguintes etapas: 1. Recrie seu aplicativo lógico padrão usando um ASE (Ambiente do Serviço de Aplicativo do Azure) com um plano de Serviço de Aplicativo somente para Windows e baseado em ASE. 2. Adicione manualmente os certificados de chave pública necessários ao Armazenamento de CA Raiz Confiável do host. Para obter mais informações, consulte a seguinte documentação: - Associações de certificado e o Ambiente do Serviço de Aplicativo - Adicionar e gerenciar certificados TLS/SSL no Serviço de Aplicativo do Azure

    • Autenticação de cliente de aplicativo lógico

      Você pode adicionar um certificado de chave privada para enviar como o certificado do cliente e, em seguida, especificar o valor da impressão digital do certificado nos detalhes da conexão para o conector interno MQ. Para obter mais informações, consulte Adicionar um certificado de chave privada.

    Recomendação: Atualize para o servidor MQ 9.0 ou posterior. Além disso, em seu servidor MQ, certifique-se de configurar o canal de conexão do servidor com um conjunto de codificação que corresponda à especificação de codificação usada pela conexão do cliente, por exemplo, ANY_TLS12_OR_HIGHER. Para obter mais informações, consulte o próximo item sobre os requisitos de codificação.

• Requisitos de especificação de codificação

  O servidor MQ requer que você defina a especificação de codificação para conexões que usam criptografia TLS (SSL). Essa especificação de codificação deve corresponder aos conjuntos de codificação que são suportados, escolhidos e usados pelo sistema operacional onde o servidor MQ é executado. Em última análise, a especificação de codificação usada pela conexão do cliente deve corresponder aos conjuntos de codificação configurados no canal de conexão do servidor no servidor MQ.

  Para saber mais, confira Problemas de conexão e autenticação.

Adicionar um gatilho do MQ (somente aplicativo lógico Standard)

As etapas a seguir só se aplicam aos fluxos de trabalho do aplicativo lógico Standard, que podem usar gatilhos fornecidos pelo conector interno do MQ. O conector gerenciado do MQ não inclui nenhum gatilho.

Estas etapas usam o portal do Azure, mas com a extensão apropriada dos Aplicativos Lógicos do Azure, você também pode usar o Visual Studio Code para criar um fluxo de trabalho do aplicativo lógico Standard.

1. No portal do Azure, abra o fluxo de trabalho do aplicativo de lógica vazio no designer.

2. Siga estas etapas gerais para adicionar o gatilho interno MQ desejado. Para obter mais informações, consulte Gatilhos de conector internos do MQ.

3. Forneça as informações necessárias para autenticar sua conexão. Quando terminar, selecione Criar.

4. Quando a caixa de informações do gatilho for exibida, forneça as informações necessárias para o gatilho.

5. Quando terminar, salve o fluxo de trabalho. Selecione Salvar na barra de ferramentas do designer.

Adicionar uma ação do MQ

Um fluxo de trabalho de aplicativo lógico de Consumo só pode usar o conector gerenciado do MQ. No entanto, um fluxo de trabalho de aplicativo lógico Standard pode usar o conector gerenciado do MQ e o conector interno do MQ. Cada versão tem várias ações. Por exemplo, as versões dos conectores gerenciado e interno têm ações próprias para navegar por uma mensagem.

• Ações do conector gerenciado: essas ações são executadas em um fluxo de trabalho de aplicativo lógico do tipo Consumo ou Padrão.

• Ações do conector interno: essas ações são executadas somente em um fluxo de trabalho de aplicativo lógico Padrão.

As seguintes etapas usam o portal do Azure, mas com a extensão de Aplicativos Lógicos do Azure apropriada, você também pode usar as seguintes ferramentas para criar fluxos de trabalho do aplicativo lógico:

• Fluxos de trabalho do aplicativo lógico de consumo: Visual Studio ou Visual Studio Code

• Fluxos de trabalho de aplicativo lógico padrão: Visual Studio Code

Testar seu fluxo de trabalho

Para verificar se o fluxo de trabalho retorna os resultados esperados, execute o fluxo de trabalho e examine as saídas do histórico de execução do fluxo de trabalho.

1. Executar seu fluxo de trabalho.

   • Aplicativo lógico de Consumo: na barra de ferramentas do designer de fluxo de trabalho, selecione Executar Gatilho>Execução.

   • Aplicativo lógico Standard: no menu de recursos do fluxo de trabalho, selecione Visão geral. Na barra de ferramentas do painel Visão geral, selecione Executar Gatilho>Executar.

   Após a conclusão da execução, o designer mostra o histórico de execuções do fluxo de trabalho, acompanhado do status de cada etapa.

2. Para examinar as entradas e saídas de cada etapa executada (não ignorada), expanda ou selecione a etapa.

   • Para examinar mais detalhes de entrada, selecione Mostrar entradas brutas.

   • Para examinar mais detalhes de saída, selecione Mostrar saídas brutas. Se você definir IncludeInfo como true, será adicionada uma quantidade maior à saída.

Exibir e adicionar certificados para autenticação com criptografia TLS (SSL)

As informações a seguir se aplicam somente aos fluxos de trabalho de aplicativo lógico padrão para o conector interno MQ usando autenticação somente servidor ou servidor-cliente com criptografia TLS (SSL).

Exibir e confirmar impressões digitais para certificados de chave pública existentes

Para verificar se as impressões digitais dos certificados de chave pública necessários existem no host da máquina virtual do aplicativo lógico padrão no Repositório de CA raiz confiável, siga estas etapas para executar o cert script do PowerShell no menu de recursos do aplicativo lógico padrão.

1. No portal do Azure, abra seu recurso de aplicativo lógico Padrão. No menu de recursos do aplicativo lógico, em Ferramentas de Desenvolvimento, selecione Ferramentas>Avançadas.

2. No menu do console do Kudu Debug, selecione PowerShell.

3. Depois que a janela do PowerShell for exibida, no prompt de comando do PowerShell, execute o seguinte script:

   dir cert:\localmachine\root

   A janela do PowerShell lista as impressões digitais e descrições existentes, por exemplo:

   

Adicionar um certificado de chave pública

Para adicionar um certificado de chave pública ao Armazenamento de CA Raiz Confiável no host de máquina virtual em que seu aplicativo lógico padrão é executado, siga estas etapas:

1. No portal do Azure, abra seu recurso de aplicativo lógico Padrão. No menu de recursos do aplicativo lógico, em Configurações, selecione Configurações de TLS/SSL (clássico).

2. Na página Configurações de TLS/SSL (clássico), selecione a guia Certificados de Chave Pública (.cer) e selecione Carregar Certificado de Chave Pública.

3. No painel Adicionar Certificado de Chave Pública (.cer) que é aberto, insira um nome para descrever o certificado. Localize e selecione o arquivo de certificado de chave pública (.cer). Ao concluir, selecione Carregar.

4. Depois de adicionar o certificado, na coluna Impressão digital, copie o valor da impressão digital do certificado.

   

5. No menu de recursos do aplicativo lógico, selecione Configuração.

6. Na guia Configurações de aplicativo, selecione Novas configurações de aplicativo. Adicione uma nova configuração de aplicativo chamada WEBSITE_LOAD_ROOT_CERTIFICATES e insira o valor da impressão digital do certificado que você copiou anteriormente. Se você tiver vários valores de impressão digital de certificado, certifique-se de separar cada valor com uma vírgula (,).

   Para obter mais informações, consulte Editar configurações de host e aplicativo para aplicativos lógicos padrão em aplicativos lógicos do Azure de locatário único.

   Observação

   Se você especificar uma impressão digital para um certificado de autoridade de certificação privada, o conector interno MQ não executará nenhuma validação de certificado, como verificar a data de expiração ou a origem do certificado. Se a validação SSL padrão do .NET falhar, o conector só comparará qualquer valor de impressão digital que tenha sido passado em relação ao valor na configuração WEBSITE_LOAD_ROOT_CERTIFICATES.

7. Se o certificado adicionado não aparecer na lista de certificados de chave pública, na barra de ferramentas, selecione Atualizar.

Adicionar um certificado de chave privada

Para adicionar um certificado de chave privada ao Armazenamento de CA Raiz Confiável no host da máquina virtual onde seu aplicativo lógico padrão é executado, siga estas etapas:

1. Abra o recurso de aplicativo lógico no portal do Azure. No menu de recursos do aplicativo lógico, em Configurações, selecione Configurações de TLS/SSL (clássico).

2. Na página Configurações de TLS/SSL (clássico), selecione a guia Certificados de Chave Privada (.pfx) e selecione Carregar Certificado.

3. No painel Adicionar Certificado de Chave Privada (.pfx) que é aberto, localize e selecione o arquivo de certificado de chave privada (.pfx) e insira a senha do certificado. Ao concluir, selecione Carregar.

4. Depois de adicionar o certificado, na coluna Impressão digital, copie o valor da impressão digital do certificado.

   

5. No menu de recursos do aplicativo lógico, selecione Configuração.

6. Na guia Configurações de aplicativo, selecione Novas configurações de aplicativo. Adicione uma nova configuração de aplicativo chamada WEBSITE_LOAD_CERTIFICATES e insira o valor da impressão digital do certificado que você copiou anteriormente.

   Para obter mais informações, consulte Editar configurações de host e aplicativo para aplicativos lógicos padrão em aplicativos lógicos do Azure de locatário único.

7. Se o certificado adicionado não aparecer na lista de certificados de chave privada, na barra de ferramentas, selecione Atualizar.

8. Ao criar uma conexão usando o conector interno MQ, na caixa de informações de conexão, selecione Usar TLS.

9. Na propriedade Client Cert Thumbprint, insira o valor de impressão digital copiado anteriormente para o certificado de chave privada, que habilita a autenticação servidor-cliente (bidirecional). Se você não inserir um valor de impressão digital, o conector usará autenticação somente de servidor (unidirecional).

   

Solução de problemas

Falhas em ações de procura ou recebimento

Se você executar uma ação de navegação ou recebimento em uma fila vazia, a ação falhará com as seguintes saídas de cabeçalho:

Problemas de conexão e autenticação

Quando seu fluxo de trabalho usa o conector gerenciado MQ para se conectar ao servidor MQ local, você pode obter o seguinte erro:

"MQ: Could not Connect the Queue Manager '<queue-manager-name>': The Server was expecting an SSL connection."

• O servidor MQ precisa fornecer um certificado emitido por uma autoridade de certificação confiável.

• O servidor MQ requer que você defina a especificação de criptografia que deseja usar para conexões TSL. No entanto, para fins de segurança e para incluir os melhores conjuntos de segurança, o sistema operacional Windows envia um conjunto de especificações de criptografia com suporte.

  O sistema operacional em que o servidor MQ é executado escolhe os conjuntos a usar. Para fazer a correspondência de configuração, você precisa alterar a configuração do servidor MQ para que a especificação de criptografia corresponda à opção escolhida na negociação de TLS.

  Quando você tenta conectar, o servidor MQ registra uma mensagem de evento que indica que a conexão falhou porque a outra extremidade usou a especificação de criptografia incorreta. A mensagem de evento contém a especificação de criptografia que o servidor MQ escolheu na lista. Na configuração do canal de conexão do servidor, atualize a especificação de codificação para corresponder à especificação de codificação na mensagem de evento.

Próximas etapas

• Conectores gerenciados nos Aplicativos Lógicos do Azure
• Conectores internos nos Aplicativos Lógicos do Azure