Stream Connect guia de início rápido

Este guia de início rápido fornece uma visão geral de como configurar e usar cada um dos seis produtores e consumidores do Stream Connect para trocar dados entre o. ServiceNow E um ambiente Kafka.

O Stream Connect tem dois produtores que enviam dados de ServiceNow Para um ambiente Kafka.

• O produtor Kafka entra em ação Workflow Studio
• API do ProducerV2

O Stream Connect também tem quatro consumidores que recuperam dados de um ambiente Kafka.

• Gatilho de mensagem do Kafka em Workflow Studio
• Extract Transform Load (ETL) consumidor
• Consumidor do mapa de transformação
• Consumidor de script

Para vincular seu ServiceNow Para um ambiente Kafka, o Stream Connect usa o. Serviço de envio de mensagens Hermes. O diagrama a seguir mostra cada um dos produtores e consumidores e como eles se conectam ao seu ambiente Kafka, mostrado aqui como local do cliente , Por Hermes.

Figura 1. Stream Connect produtores e consumidores

Para obter mais informações, consulte Usando Stream Connect para Apache Kafka e o. .

Introdução

Para representar o local do cliente, este guia usa Apache Kafka as ferramentas de linha de comando são executadas em seu computador. Os parâmetros de configuração usados com esta ferramenta podem ser usados para configurar qualquer conexão de cliente com o gateway do Controlador de entrega de aplicações, versão 2 (ADCv2) usando o protocolo Kafka.

Todos os comandos fornecidos são testados com a versão OpenSSL (LibreSSL 2,8.3) e. Apache Kafka versão da distribuição binária kafka_2,13-3,4.0.tgz. No entanto, todos os comandos devem funcionar com qualquer versão que você tenha em seu ambiente local.

Etapas de início rápido

Este guia de início rápido tem cinco etapas. As etapas 1 e 2 abordam como configurar e testar uma conexão com o Hermes. As etapas 3 a 5 mostram como configurar e usar cada um dos produtores e consumidores do Stream Connect para enviar e receber dados.

1. O gateway ADCv2 usa autenticação mútua para autenticar solicitações, portanto, a primeira etapa é criar um armazenamento de chaves e um armazenamento confiável para usar com seu cliente Kafka favorito. A página a seguir mostra como criar os certificados necessários: Configurar uma conexão segura com o Serviço de envio de mensagens Hermes.
2. Depois de configurar uma conexão segura com Hermes, verifique se o armazenamento de chaves e o armazenamento confiável foram gerados corretamente por Testando a conexão com Hermes por meio do gateway ADCv2 .
3. Agora você pode Use o gatilho Mensagem Kafka e o consumidor de script para consumir mensagens. A primeira parte desta página mostra como usar o gatilho Mensagem do Kafka no Workflow Studio Para recuperar mensagens do Kafka. A segunda parte mostra como usar o consumidor de script para recuperar mensagens.
4. E. Use os consumidores de ETL e Mapa de transformação para importar dados. As definições de ETL e os mapas de transformação especificam a lógica de transformação a ser usada ao extrair dados por meio de importações agendadas. Você pode usar as mesmas definições de ETL e mapas de transformação para transformar os eventos recebidos por meio do Kafka.
   Nota:

   Para usar o consumidor de ETL, você precisa de um transformador de conjunto de importação robusto . Da mesma forma, para usar o consumidor Mapa de transformação, você precisa de mapa de transformação .
5. Por fim, você pode Use a etapa do produtor Kafka e a API do ProducerV2 para publicar mensagens. Esta página mostra como usar a etapa Produtor Kafka em Workflow Studio E a API ProducerV2 para enviar mensagens por push para o Kafka.

Configurar uma conexão segura com o Serviço de envio de mensagens Hermes

Proteja os tópicos do Kafka gerando um certificado assinado pela instância ServiceNow®.

Antes de Iniciar

Configurar o Serviço de envio de mensagens Hermes requer coordenação com o administrador da rede e com o administrador do Kafka. Trabalhe com o administrador da rede para obter os certificados de segurança e abrir as portas necessárias. Trabalhe com o administrador do Kafka para garantir que o ambiente do Kafka esteja configurado corretamente e que as aplicações possam se conectar ao Serviço de envio de mensagens Hermes usando o protocolo padrão do Kafka.

Certifique-se de que a seguinte configuração esteja em vigor:

• O Serviço de envio de mensagens Hermes está ativado. Consulte .
• O plug-in da Estrutura de gestão de chaves (com.glide.kmf.global) está ativado.
• A tabela Certificados [sys_kmf_certificate] contém um certificado de autoridade de certificação raiz da instância ServiceNow.
• A instância não está configurada com uma URL personalizada. URLs personalizadas não são compatíveis com o Gerador de certificados de PKI da instância.

Função necessária: hermes_admin, sn_kmf.cryptographic_manager ou admin

Para obter detalhes sobre como atribuir funções do KMF, consulte .

Procedimento

1. Navegar até Tudo > Gerador de certificados > Gerador de certificados PKI da instância.
2. Opcional: Controle o acesso a tópicos configurando listas de controle de acesso (ACLs) no namespace ou no nível de tópico.

   Opção	Descrição
   Aplicar ACLs a namespaces	Selecione Configurar ACLs. Na caixa de diálogo ACLs de Tópico, selecione Namespaces. Insira um namespace que você deseja configurar. Defina o nível de permissão selecionando Somente Leitura ou Leitura/Gravação. Selecione Adicionar.
   Aplicar ACLs a tópicos definidos	Selecione Configurar ACLs. Na caixa de diálogo ACLs de Tópico, selecione Tópicos definidos. Insira um tópico existente que você deseja configurar. Defina o nível de permissão selecionando Somente Leitura ou Leitura/Gravação. Selecione Adicionar.

   O portador do certificado recebe acesso de leitura ou leitura/gravação aos tópicos no namespace ou ao tópico existente que você selecionou.
3. Configure a segurança para o Serviço de envio de mensagens Hermes.
   1. Navegue de volta para a página Gerador de Certificado PKI de Instância.
   2. Insira uma senha de armazenamento de chaves no campo Senha do Certificado.
   3. Selecione Gerar.
   O sistema gera um certificado assinado pela instância na tabela Certificados [sys_kmf_certificate], cria um armazenamento de chaves e um repositório de confiança.

   Se o acesso restrito do solicitante não for permitido para o Gerador de certificados IPKI, um erro de acesso entre escopos será exibido. Contato Suporte e atendimento ao cliente Para obter assistência com a permissão de acesso restrito do solicitante. Para resolver este problema, Suporte e atendimento ao cliente Pode fazer referência a source_scope

4. Salve uma cópia do armazenamento de chaves selecionando Download de Armazenamento de Chaves.
5. Salve uma cópia do repositório de confiança selecionando Download de Repositório de Confiança.
6. Copie os arquivos de armazenamento de chaves e de repositório de confiança para cada produtor e cliente consumidor que se conectem ao Serviço de envio de mensagens Hermes.

Resultado

Agora você pode criar uma conexão segura com o Serviço de envio de mensagens Hermes.

Nota:

Você deve usar o armazenamento de chaves gerado usando o Gerador de Certificado PKI de Instância para se conectar a Hermes. Os armazenamentos de chaves gerados de forma personalizada que não são criados de acordo com a documentação de ServiceNow não são compatíveis.

Teste a conexão com Hermes por meio do gateway ADCv2

Verifique se o armazenamento de chaves e o armazenamento confiável foram gerados corretamente testando a conexão com o Hermes por meio do gateway ADCv2.

Antes de Iniciar

• Função necessária: Integration_hub_admin

Procedimento

1. Baixe e instale o Apache Kafka.
   1. Baixe o. Apache Kafka binários.
   2. Descompacte o pacote Kafka executando o seguinte comando:

      tar -zxvf kafka_2.13-3.1.2.tgz

2. Navegue até o diretório Kafka executando o seguinte comando:

   cd kafka_2.13-3.1.2

3. Configure um produtor.
   1. Abra o. config/producer.properties arquivo.
   2. Configure as seguintes propriedades de SSL:

      security.protocol=SSL
      
      ssl.truststore.password=<truststore password>
      
      ssl.truststore.location=<path to truststore.p12>
      
      ssl.truststore.type=PKCS12
      
      ssl.keystore.password=<keystore password>
      
      ssl.keystore.location=<path to keystore.p12>
      
      ssl.keystore.type=PKCS12
      
      ssl.key.password=<keystore password>

      Substitua as seguintes variáveis de espaço reservado:

      • <truststore password> com sua senha do truststore.
      • caminho para truststore.p12> com o caminho para o arquivo do truststore.
      • <keystore password> com a senha do armazenamento de chaves.
      • caminho para keystore.p12> com o caminho para o arquivo de armazenamento de chaves.
   Depois de seguir as etapas 1 a 3, você deve ter baixado Apache Kafka e configurou o producer.properties corretamente. Todos os comandos fornecidos nas próximas etapas devem ser executados no Apache Kafka diretório inicial.
4. Copie o arquivo config/producer.properties para config/bootcamp.properties.
   Este exemplo usa bootcamp como um nome genérico.

   cp config/producer.properties config/bootcamp.properties

5. Use o comando a seguir para listar os tópicos.

   bin/kafka-topics.sh --list --command-config config/bootcamp.properties  --bootstrap-server <instance name>.service-now.com:4000,<instance name>.service-now.com:4001,<instance name>.service-now.com:4002,<instance name>.service-now.com:4003

   Substitua <instance name> com o nome da sua instância.
   Se houver tópicos na instância, eles devem ser listados aqui.

Use o gatilho Mensagem Kafka e o consumidor de script para consumir mensagens

Recupere mensagens do Hermes com o gatilho Mensagem Kafka em Workflow Studio E o consumidor de script.

Antes de Iniciar

• Função necessária: Integration_hub_admin
• A primeira parte desta seção mostra como usar o gatilho Mensagem do Kafka no Workflow Studio para consumir mensagens. Para obter mais informações sobre o gatilho, consulte .
• A segunda parte desta seção mostra como usar o consumidor de script para consumir mensagens. Para obter mais informações, consulte Configure um consumidor de script.

Procedimento

1. Crie um tópico para consumir mensagens.
   1. Use o comando a seguir para criar um tópico no Hermes.

      bin/kafka-topics.sh --create --command-config config/bootcamp.properties  --bootstrap-server <instance name>.service-now.com:4000,<instance name>.service-now.com:4001,<instance name>.service-now.com:4002, <instance name>.service-now.com:4003 --topic snc.<instance name>.topic1

      Substitua <instance name> com o nome da sua instância.
   2. Para exibir o tópico, faça login na instância e navegue até Tudo > IntegrationHub > Conexão de fluxo > Tópicos.
      Nota:

      A criação de um tópico leva aproximadamente 10 minutos.
2. Crie um gatilho de fluxo para consumir mensagens do tópico.
   1. Navegar até Tudo > Automação de Processo > Flow Designer.
   2. Selecionar Criar novo > Fluxo.
   3. No formulário Propriedades de fluxo, insira um nome para o fluxo e insira Enviar .
      Este exemplo usa o nome Consumidor do Topic1 .
   4. Na seção do gatilho, selecione Adicione um gatilho , em seguida, selecione Mensagem do Kafka como o tipo de gatilho.

      

   5. Selecione o tópico Topic1.

      

      Você pode usar o ícone de lupa para ver a lista de tópicos disponíveis.

   6. Na seção Ações do fluxo, navegue até Adicionar uma Ação, Lógica de Fluxo ou Subfluxo > Lógica de fluxo > Para cada.
   7. Arraste o. Mensagens cápsula de dados para Itens e selecione Concluído .
   8. Na seção Ações do fluxo, navegue até Adicionar uma Ação, Lógica de Fluxo ou Subfluxo > Ação > ServiceNow Core > Log.
   9. Arraste o. Carga cápsula de dados para Mensagem e selecione Concluído .

      

   10. Salvar o gatilho de fluxo.
   11. Vá para a tabela Configurações [sys_flow_execution_setting] para habilitar a emissão de relatórios para este fluxo.
   12. Crie uma nova entrada e habilite a emissão de relatórios para o fluxo criado acima.

       

   13. Navegue de volta para seu fluxo e selecione Ativar .
   14. Para exibir sua assinatura de tópico, navegue até Tudo > IntegrationHub > Conexão de fluxo > Assinaturas.

       

3. Publique mensagens no tópico usando a ferramenta de linha de comando Kafka.
   1. Execute o comando a seguir para publicar mensagens no tópico.

      bin/kafka-console-producer.sh --topic snc.<instance name>.topic1  --producer.config  config/bootcamp.properties  --bootstrap-server <instance name>.service-now.com:4000,<instance name>.service-now.com:4001,<instance name>.service-now.com:4002,<instance name>.service-now.com:4003

      Substitua <instance name> com o nome da sua instância.

      Este comando solicita mensagens. Adicione algumas mensagens de amostra. Este exemplo usa as seguintes mensagens.

      • mensagem de teste 1
      • Mensagem de teste 2
      • Mensagem de teste 3

      Você deve receber as mensagens em cerca de um minuto.
   2. Navegue de volta para o fluxo e selecione Execuções .

      

   3. Abra a execução de fluxo.

      

   4. Para exibir as estatísticas desta assinatura, navegue até Tudo > IntegrationHub > Conexão de fluxo > Assinaturas, abra a assinatura e vá para a exibição de estatísticas.

      

4. Crie um consumidor de script para consumir mensagens do tópico.
   1. Navegar até IntegrationHub > clientees > Consumidores de script.
   2. Selecione Novo.
   3. Em Nome insira um nome para o consumidor de script.
      Este exemplo usa Consumidor do Topic1 .
   4. Defina o script para registrar a mensagem adicionando a seguinte lógica na caixa de script.

      for (var i = 0; i < messages.length; i++) {
            gs.info('Received message ' + JSON.stringify(messages[i].message));
       }
      

      

   5. Salve o formulário.
   6. Na seção Links relacionados, selecione Novo Para adicionar um fluxo Kafka para consumir as mensagens.
   7. No formulário Fluxo Kafka, defina os seguintes valores de campo.
      • Nome para Fluxo do Topic1 .
      • Tópico para o tópico criado anteriormente, tópico 1.
      • Simultaneidade máxima para 1 .
      • Comece a consumir para Todas as mensagens armazenadas no tópico . Esta opção permite que você leia as mensagens já publicadas neste tópico.
      • Tratamento de mensagens para Otimizar automaticamente .

      

   8. Selecione Ativar Link em Links relacionados.
      Você deve ser capaz de ver a assinatura ativada.
   9. Para exibir as mensagens, navegue até Tudo > Logs do sistema > Log do sistema E filtrar mensagens que começam com mensagem recebida.

      

   10. Todas as mensagens serão exibidas após 1 minuto.

Use os consumidores de ETL e Mapa de transformação para importar dados

Use definições de ETL e mapas de transformação para processar eventos Kafka. As definições de ETL e os mapas de transformação especificam a lógica de transformação a ser usada ao extrair dados por meio de importações agendadas. Você pode usar as mesmas definições de ETL e mapas de transformação para transformar os eventos recebidos por meio do Kafka.

Antes de Iniciar

• Função necessária: Integration_hub_admin
• A primeira parte desta seção mostra como usar o consumidor de ETL para consumir mensagens. Para usar o consumidor de ETL, você precisa de um transformador de conjunto de importação robusto .
• A segunda parte desta seção mostra como usar um consumidor de mapa de transformação para consumir mensagens. Para usar o Consumidor do mapa de transformação, você precisa de um mapa de transformação .

Procedimento

1. Crie um tópico para consumir ETL e transformar mensagens do consumidor do mapa.
   1. Use o comando a seguir para criar um tópico no Hermes.
      Neste exemplo, o nome do tópico é topic2.

      bin/kafka-topics.sh --create --command-config config/bootcamp.properties  --bootstrap-server <instance name>.service-now.com:4000,<instance name>.service-now.com:4001,<instance name>.service-now.com:4002, <instance name>.service-now.com:4003 --topic snc.<instance name>.topic2

      Substitua <instance name> com o nome da sua instância.
   2. Para exibir o tópico, faça login na instância e navegue até Tudo > IntegrationHub > Conexão de fluxo > Tópicos.
      Nota:

      A criação de um tópico leva aproximadamente 10 minutos.
2. Crie um consumidor de ETL para consumir dados do tópico.
   1. Navegar até Tudo > IntegrationHub > clientees > Consumidor de ETL.
   2. Selecione Novo.
   3. No formulário Consumidor Kafka, insira um nome no Nome campo.
      Este exemplo usa o nome Importação de membro.
   4. Para Transformador de conjunto de importação robusto Arquivo, selecione um transformador de conjunto de importação robusto existente.
      Para o transformador de conjunto de importação robusto, selecione um que não esteja usando a opção para armazenar dados em uma única coluna. Para poder ver as mensagens, certifique-se de que o transformador do conjunto de importação robusto tenha o. Detalhado opção habilitada.
   5. Desmarque Dados em coluna única opção.
      Esta opção só deve ser selecionada para tabelas de conjuntos de importação com dados em uma única coluna.
   6. Defina o. Mapeamento de coluna para Rótulo .

      Isso significa que as chaves JSON da mensagem de entrada são mapeadas para os rótulos de coluna da tabela Conjunto de importação.

      

   7. Salve o formulário.
   8. Crie um fluxo Kafka para o consumidor.
   9. No formulário Fluxo Kafka, defina os seguintes valores de campo.
      • Nome para Fluxo de Topic2 .
      • Tópico para o tópico criado anteriormente, tópico 2.
      • Simultaneidade máxima para 1 .
      • Comece a consumir para Mensagens recebidas após a primeira ativação .
      • Tratamento de mensagens para Otimizar automaticamente .
   10. Selecione Ativar Link em Links relacionados.

       Você deve ser capaz de ver a assinatura ativada.

       

3. Publique mensagens no tópico 2.
   1. Execute o comando a seguir para publicar mensagens no tópico 2.

      bin/kafka-console-producer.sh --topic snc.<instance name>.topic2  --producer.config  config/bootcamp.properties  --bootstrap-server <instance name>.service-now.com:4000,<instance name>.service-now.com:4001,<instance name>.service-now.com:4002,<instance name>.service-now.com:4003

      Substitua <instance name> com o nome da sua instância.

      Este comando solicita mensagens.

   2. Envie a seguinte mensagem JSON.

      {"city":"San Diego","name":"Jhon","id":"SN001","state":"California"}

      Você pode enviar esta mensagem com qualquer valor, mas a chave de mensagem JSON deve corresponder aos rótulos da tabela Conjunto de importação.
   3. Volte para o consumidor de ETL que você criou.

      Após cerca de um minuto, os dados devem ter sido importados por meio do conjunto de importação.

      

   4. Para exibir informações detalhadas sobre o conjunto de importação, selecione o número do conjunto de importação.

      

   5. Para exibir informações detalhadas sobre uma linha de conjunto de importação, selecione o número da linha do conjunto de importação.

      

4. Crie um Consumidor de mapa de transformação para consumir dados.
   1. Navegar até Tudo > IntegrationHub > clientees > Consumidor de mapa de transformação.
   2. Selecione Novo.
   3. No formulário Consumidor do mapa de transformação, insira um nome em Nome campo.
   4. Para Mapa de transformação selecione um mapa de transformação existente.

      

   5. Salve o formulário.
   6. Crie um fluxo Kafka para o consumidor.
   7. No formulário Fluxo Kafka, defina os seguintes valores de campo.
      • Nome para Fluxo do mapa de transformação .
      • Tópico para o tópico criado anteriormente, tópico 2.
      • Simultaneidade máxima para 1 .
      • Comece a consumir para Mensagens recebidas após a primeira ativação .
      • Tratamento de mensagens para Otimizar automaticamente .
   8. Selecione Ativar Link em Links relacionados.

      Você deve ser capaz de ver a assinatura ativada.

      

5. Publique mensagens no tópico 2.
   1. Execute o comando a seguir para publicar mensagens no tópico 2.

      bin/kafka-console-producer.sh --topic snc.<instance name>.topic2  --producer.config  config/bootcamp.properties  --bootstrap-server <instance name>.service-now.com:4000,<instance name>.service-now.com:4001,<instance name>.service-now.com:4002,<instance name>.service-now.com:4003

      Substitua <instance name> com o nome da sua instância.

      Este comando solicita mensagens.

   2. Envie a seguinte mensagem JSON.

      {"city":"San Diego","name":"Jhon","id":"SN001","state":"California"}

      Você pode enviar esta mensagem com qualquer valor, mas a chave de mensagem JSON deve corresponder aos rótulos da tabela Conjunto de importação.
   3. Vá para o Consumidor do mapa de transformação que você criou.
      Após cerca de um minuto, os dados devem ter sido importados por meio do conjunto de importação.
   4. Para exibir informações detalhadas sobre o conjunto de importação, selecione o número do conjunto de importação como na etapa 3d acima.

Use a etapa do produtor Kafka e a API do ProducerV2 para publicar mensagens

Enviar dados de ServiceNow Para Hermes para que os consumidores Kafka possam lê-los.

Antes de Iniciar

• Função necessária: Integration_hub_admin
• A primeira parte desta seção mostra como usar a etapa Produtor Kafka em Workflow Studio Para publicar mensagens para Hermes. Para obter mais informações sobre a etapa, consulte .
• A segunda parte desta seção mostra como usar a API ProducerV2 para publicar mensagens. Para obter mais informações, consulte API do ProducerV2 .
• Para receber todas as mensagens, você precisa executar dois consumidores para datacenters diferentes. Consulte para obter detalhes.

Procedimento

1. Inicie dois consumidores para receber mensagens.
   1. Execute os seguintes comandos na linha de comando para receber as mensagens.

      bin/kafka-console-consumer.sh --consumer.config config/bootcamp.properties --topic snc.<instance name>.topic1 --group snc.<instance name>.consumer_group1 --from-beginning --bootstrap-server <instance name>.service-now.com:4100,<instance name>.service-now.com:4101,<instance name>.service-now.com:4102,<instance name>.service-now.com:4103

      bin/kafka-console-consumer.sh --consumer.config config/bootcamp.properties --topic snc.<instance name>.topic1 --group snc.<instance name>.consumer_group1 --from-beginning --bootstrap-server <instance name>.service-now.com:4200, <instance name>.service-now.com:4201, <instance name>.service-now.com:4202, <instance name>.service-now.com:4203

      Substitua <instance name> com o nome da sua instância.
2. Publique mensagens da instância usando uma etapa de fluxo.
   1. Navegar até Tudo > Automação de Processo > Flow Designer.
   2. Selecione uma nova ação Criar novo > Ação.
   3. No formulário Propriedades da ação, atribua um nome à ação e selecione Enviar .
      Este exemplo usa o nome Fornecedor de mensagens.
   4. Adicione um Kafka produtor etapa para a ação.

      Para adicionar uma etapa de ação, selecione o sinal de mais entre Entradas e. Avaliação de erro Na Descrição da ação.

      

   5. Na etapa, defina Tópico campo para tópico 1 .
   6. Em Mensagem , insira uma mensagem.

      Você não precisa mudar nenhum outro campo.

      

   7. Selecione Salvar para salvar a ação.
   8. Selecione Teste botão para testar a ação.
      Testar a ação publica a mensagem no tópico.
   9. Para exibir a mensagem, vá para os consoles de linha de comando criados na etapa 1.
      A mensagem deve estar presente em um dos terminais.
3. Publique mensagens da instância usando um script.
   1. Execute o script a seguir usando o plano de fundo de scripts para publicar mensagens para este tópico da instância.

      var producer = new sn_ih_kafka.ProducerV2();
      producer.send('<sys id of the topic record>', gs.generateGUID(), 'Test message from ServiceNow', false, null);
      

      Substitua sys id do registro de tópico> com o sys_id do registro de tópico.
   2. Para exibir a mensagem, vá para os consoles de linha de comando criados na etapa 1.
      A mensagem deve estar presente em um dos terminais.