Ações de fluxo de dados e paginação

  • Versão de lançamento: Washingtondc
  • Atualizado 1 de fev. de 2024
  • 10 min. de leitura

    • Envie solicitações REST, SOAP ou JDBC do Flow Designer para APIs que exibem um fluxo de dados de resposta maior que 10 MB ou que retornam resultados paginados. Analise os dados do fluxo em uma série de saídas de objetos complexos e use as cápsulas de dados em outras ações em um fluxo.

    Por exemplo, crie uma ação Fluxo de dados para importar uma grande quantidade de dados de funcionários de um site de RH de terceiros. A ação Fluxo de dados envia uma solicitação REST para o site de terceiros e processa a resposta para preencher registros na tabela Usuário [sys_user].
    Nota:
    Ações de fluxo de dados requerem uma assinatura IntegrationHub. Para obter mais informações, consulte Programações jurídicas - Visão geral do IntegrationHub.

    Benefícios

    Fluxo de dados As ações do oferecem esses benefícios.

    • Analisar e formatar um fluxo de dados de resposta maior que 10 MB.
    • Envie automaticamente várias solicitações para APIs que paginam resultados, se aplicável.
    • Pode ser usado em IntegrationHub - Importar e para criar uma fonte de dados.
    • Permita que os designers de fluxo processem solicitações grandes sem codificação ou configuração complexa.
    • Habilitar Flow Designers para processe cada objeto em um fluxo de dados usando a lógica de fluxo Para cada. Por exemplo, você pode criar uma ação Fluxo de dados que importe dados de documento de um site de terceiros. Quando você adiciona a ação a um fluxo, Flow Designer adiciona automaticamente a ação a um bloco de lógica de fluxo Para cada, permitindo que os designers de fluxo criem facilmente um registro em ServiceNow para cada objeto no fluxo de dados. Consulte Usar uma ação Fluxo de dados em um fluxo.
    • Permita que os designers de fluxo reutilizem ações Fluxo de dados em vários fluxos, usando a mesma fonte de dados de várias maneiras.

    Executando uma ação de Fluxo de dados

    Existem duas maneiras de executar uma ação Fluxo de dados.

    A partir de um fluxo
    Você pode processe cada objeto em um fluxo de dados usando a lógica de fluxo Para cada. Por exemplo, você pode criar uma ação Fluxo de dados que importe dados de documento de um site de terceiros. Quando você adiciona a ação a um fluxo, Flow Designer adiciona automaticamente a ação a um bloco de lógica de fluxo Para cada, permitindo que os designers de fluxo criem facilmente um registro em ServiceNow para cada objeto no fluxo de dados. Consulte Usar uma ação Fluxo de dados em um fluxo.
    A partir de um script
    Você pode iniciar um Fluxo de dados usando o método executeDataStreamAction() na classe FlowAPI. Para obter mais informações, consulte FlowAPI.

    Esboço de ação

    Fluxo de dados As ações do seguem uma estrutura definida. Siga as instruções para adicionar e remover etapas do contorno da ação. Você não pode adicionar etapas manualmente a uma ação Fluxo de dados.

    Figura 1. Ações de fluxo de dados REST e SOAP
    Ação de fluxo de dados REST e SOAP.
    Figura 2. Ação de fluxo de dados JDBC
    Ação de fluxo de dados JDBC
    Nota:
    Limpar uma opção em uma página de configuração remove a etapa do contorno Fluxo de dados e exclui todos os dados associados à etapa.

    Pré-processamento de ação

    Use a categoria Pré-processamento de ação para recuperar detalhes de conexão e credencial ou para executar um script de pré-processamento.

    Selecione Recuperar informações de conexão para recuperar detalhes de conexão e credencial para usar em sua ação. A seleção desta opção adiciona a etapa Obter informações de conexão como a primeira etapa no pré-processamento da ação. Para obter mais informações, consulte Get Connection Info step.

    Selecione Habilitar script de pré -processamento para executar um script de pré-processamento antes que a ação envie a solicitação de API inicial. Por exemplo, valide entradas de ação ou defina valores padrão. A seleção desta opção adiciona uma etapa de script à ação Fluxo de dados. Para obter mais informações, consulte Script step.

    O pré-processamento é executado uma vez por ação, antes da primeira solicitação de API.

    Este é um componente de ação Fluxo de dados opcional que é executado na instância ou em um MID Server.

    Solicitação

    Use a categoria Solicitação para configurar como a ação envia solicitações de API. A seção Solicitação é executada uma vez por página de resultados. Os componentes de solicitação fornecem essas opções de configuração.

    Etapa de configuração de paginação

    Solicitação resulta em lotes. Depois que uma página de dados é processada, a ação Fluxo de dados executa a seção de solicitação novamente para retornar o próximo conjunto de resultados. Use a etapa de configuração de paginação para configurar as opções de paginação exigidas pela API. Configure a etapa de Configuração de paginação manualmente ou selecione um modelo pré-criado para aplicar configurações comuns. Por exemplo, aplique o modelo Limite/Deslocamento para especificar o número de itens que você deseja retornar por página (limite) e o número inicial do primeiro item (deslocamento). Depois de aplicar um modelo, atualize os valores para garantir que a configuração esteja em conformidade com os requisitos da API.

    Nota:
    Para fins de licenciamento, cada solicitação conta como uma transação, incluindo cada solicitação para a próxima página de resultados.

    O valor da variável getNextPage reservada e somente leitura determina se outra página de resultados deve ser solicitada. Contanto que a variável getNextPage seja verdadeira e a página anterior contenha dados, a ação continuará a enviar solicitações para a próxima página.

    Nota:
    Você deve definir explicitamente o valor como verdadeiro no script ou o padrão será falso.
    Este é um componente de solicitação opcional que é executado somente na instância.
    Nota:
    A paginação não é aplicável à etapa JDBC.
    Etapa de script

    Execute um script antes de cada solicitação para a próxima página de resultados. Use este script para validação e transformação de dados ao chamar uma API paginada. Por exemplo, gere uma carga JSON para a solicitação da próxima página. A seleção desta opção adiciona uma etapa de script à ação Fluxo de dados. Para obter mais informações, consulte Script step.

    Este é um componente de solicitação opcional que é executado na instância ou em um MID Server.

    Etapa REST ou SOAP

    Envie uma solicitação REST ou SOAP para uma API de terceiros. Selecione um formato de dados para adicionar uma etapa associada à ação Fluxo de dados. Para mais informações, consulte Etapa REST e Etapa SOAP.

    Este é um componente Request obrigatório que é executado na instância ou em um MID Server.

    Etapa JDBC

    Envie uma solicitação JDBC para uma API de terceiros. Use o script de transformação para formatar dados e adicionar uma etapa associada à ação Fluxo de dados. Para mais informações, consulte Etapa JDBC e Etapa Testar JDBC. Todos os dados são recuperados e a paginação não é necessária.

    Este é um componente de solicitação obrigatório que é executado em um MID Server.

    Analisando em etapas REST e SOAP

    Use a categoria Análise para configurar como a ação separa elementos de fluxo de dados em objetos de dados complexos. Use a etapa Divisor para identificar e separar itens de um fluxo XML ou JSON e use a etapa Analisador de script para transformar cada item em um objeto complexo. A seção de análise é executada uma vez por item no fluxo. Você pode acessar as saídas das etapas anteriores na ação de fluxo de dados usando o objeto fd_data, excluindo:
    • Saídas de Corpo da resposta, Fluxo ou Mensagem de erro da etapa REST ou SOAP
    • Saídas da etapa do divisor

    Divisão e análise de um fluxo de registros de usuário.

    Para obter mais informações sobre dados complexos, consulte Dados complexos. Os componentes de análise fornecem essas opções de configuração.

    Etapa do divisor

    Identificar o nó primário no fluxo de resposta para mapear para um objeto complexo. Por exemplo, identifique um elemento de usuário em uma carga XML para criar um objeto complexo para cada usuário no fluxo de resposta.

    Selecione um tipo de divisor para identificar e separar itens repetidos em um fluxo de dados XML ou JSON.

    • JSON: identifica objetos de um fluxo de dados JSON. Use uma expressão JSONPath para identificar uma matriz JSON que contém dados repetidos.
    • XML: identifica objetos de um fluxo de dados XML. Use uma expressão XPath para identificar um elemento XML que contém dados repetidos.

    Este é um componente de análise obrigatório que só é executado na instância.

    Etapa de analisador de script

    Usar JavaScript e ServiceNow para mapear itens no fluxo de resposta para uma saída de objeto complexo representada pelo objeto global targetObject. Por exemplo, mapeie os elementos de registro de incidente identificados na etapa do divisor para um objeto complexo que contém campos de incidente. Se o fluxo de dados incluir semelhantes para o item identificado na etapa do divisor que você não deseja mapear para um objeto complexo, inclua condições para excluir esses itens. Você pode ignorar itens no fluxo adicionando outputs.state = 'SKIP' sempre que necessário à seção de script da etapa Analisador de script.

    Este é um componente de análise obrigatório que só é executado na instância.

    Figura 3. Visão geral da ação de fluxo de dados REST e SOAP
    Visão geral da ação de fluxo de dados REST e SOAP.

    Transformar script na etapa JDBC

    A ação de fluxo de dados JDBC não requer paginação. Além disso, as etapas do divisor e do analisador não são necessárias.

    A etapa JDBC gera um objeto complexo para cada registro recuperado. Portanto, o pré-processamento da ação e o script de transformação na ação de fluxo de dados JDBC são opcionais. Ao usar o script de transformação, o designer de ação deve especificar o nome interno das colunas da tabela no script de transformação.
    Figura 4. Visão geral da ação de Fluxo de dados JDBC
    Visão geral da ação de Fluxo de dados JDBC.

    Saídas de fluxo de dados nas etapas SOAP e REST

    Ao projetar uma ação Fluxo de dados, você deve criar uma única saída do tipo Objeto ou Objeto dinâmico. A etapa Analisador de script mapeia itens no fluxo para este objeto usando o objeto global targetObject.

    No tempo de execução, o sistema divide e analisa o fluxo de dados de resposta de acordo com a configuração Fluxo de dados. Cada item no fluxo é mapeado para a estrutura de objeto complexo definida pela etapa Analisador de script e a saída do objeto, resultando em uma grande série de objetos complexos. Para obter mais informações sobre dados complexos, consulte Dados complexos.

    Saídas de fluxo de dados na etapa JDBC

    A saída das etapas JDBC é um fluxo de objetos complexo. Os dados inteiros são recuperados em apenas uma solicitação.
    Nota:
    • Você só pode recuperar dados e não pode atualizar ou excluir registros usando a ação de fluxo de dados JDBC.
    • Os campos Linha máxima e Tamanho máximo da carga (KB) que estão disponíveis na etapa JDBC não estão disponíveis na ação de fluxo de dados JDBC.

    Detalhes de execução nas etapas REST e SOAP

    Exiba os resultados de configuração e tempo de execução para cada item processado por uma ação Fluxo de dados. Selecione um número de registro para ver sua configuração e detalhes de tempo de execução. Por padrão, os detalhes da execução incluem solicitações dos últimos 1.000 itens. Para mudar o número de itens nos detalhes de execução, atualize a propriedade do sistema com.snc.process_flow.reporting.datastream.item.lastn.

    Detalhes de execução para uma ação de Fluxo de dados.

    Resumo do fluxo de dados

    Exiba uma visão geral da execução que inclui essas informações.

    • Contagemde páginas : número de páginas retornadas por uma API paginada.
    • Contagem total de itens: número de itens no fluxo de resposta mapeados para saídas de objeto complexo.
    • Contagemde erros: número de erros encontrados.
    Detalhes da página

    Exiba dados de tempo de execução para cada etapa na ação Fluxo de dados. Selecione uma página para exibir os detalhes do tempo de execução de cada solicitação para uma API paginada. Por padrão, os detalhes da execução incluem solicitações das últimas cinco páginas. Para mudar o número de solicitações nos detalhes de execução, atualize a propriedade do sistema com.snc.process_flow.page.reporting.lastn. Defina o valor como 0 para remover páginas dos detalhes de execução e -1 para incluir todas as páginas.

    Nota:
    Incluir todas as páginas pode afetar o desempenho e não é recomendado.

    Detalhes do tempo de execução

    Detalhes de execução na etapa JDBC

    A construção do esquema de objeto complexo de saída não é necessária para a ação de fluxo de dados JDBC. Você pode testar a consulta e ver o resultado da consulta. Consulte Etapa Testar JDBC para obter mais informações. Configure as propriedades [ MID Servermid.jdbc.datastream.max.record.size e mid.jdbc.datastream.fail.when.attachement.limit.exceeded para recuperar dados de acordo com seus requisitos. Consulte Propriedades do MID Server para obter mais informações.