Paginação e ações de fluxo de dados

Versão de lançamento: Zurich

Atualizado 31 de jul. de 2025

11 min. de leitura

Envie solicitações REST, SOAP ou JDBC do Workflow Studio 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 um Fluxo de dadosAção para importar uma grande quantidade de dados do funcionário de um site de RH de terceiros. . Fluxo de dadosA ação 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 Cronogramas jurídicos - IntegrationHub visão geral .

Benefícios

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

Analise e formate 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 crie uma fonte de dados .
Permita que os designers de fluxo processem solicitações grandes sem codificação ou configuração complexas.
Habilitar designers de fluxo 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, Workflow Studio 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 Use um Fluxo de dadosação em um fluxo.
Permita que os designers de fluxo reutilizem Fluxo de dadosações em vários fluxos, usando a mesma fonte de dados de várias maneiras.

Executando uma ação de Fluxo de dados

Há duas maneiras de executar um Fluxo de dadosação.

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, Workflow Studio 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 Use um Fluxo de dadosação em um fluxo.
De um script: Você pode iniciar um Fluxo de dadosUsando o método executeDataStreamAction() na classe FlowAPI. Para obter mais informações, consulte FlowAPI .

Descrição da ação

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

Ação de fluxo de dados REST e SOAP. — Figura 1. Ações de fluxo de dados REST e SOAP

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.

Avaliação de erro de ação

Usar avaliação de erro para detectar erros de etapa e especificar o comportamento de erro de cada etapa adicionada a uma ação de fluxo de dados. Você também pode criar suas próprias condições de erro especificando quando uma ação retorna um estado de erro, bem como os códigos de status e as mensagens retornadas.

Pré-processamento de ação

Use a categoria Pré-processamento de ação para recuperar detalhes de conexão e credencial ou 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. Selecionar esta 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.

Opcional Fluxo de dadoscomponente de ação 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 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 do reservado, somente leitura ObterPróxima Página a variável 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 ele será falso por padrão.

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 próxima solicitação de 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 ao Fluxo de dadosação. Para obter mais informações, consulte Etapa REST e Etapa SOAP.

Este é um componente de solicitação 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 ao Fluxo de dadosação. Para obter mais informações, consulte Etapa JDBC e Etapa JDBC de teste. 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.

Análise 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 Análise é executada uma vez por item no fluxo. Você pode acessar saídas de etapas anteriores em sua ação de fluxo de dados usando fd_data objeto, excluindo:

Corpo de resposta da etapa REST ou SOAP, Fluxo ou Saída de mensagem de erro
Saídas de etapa do divisor

Dividir e analisar 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 é executado somente na instância.

Etapa do 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: "IGNORAR" Sempre que necessário para a seção de script da etapa Analisador de scripts.

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

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

Gere a fase de análise para ações de fluxo de dados baseadas EM REST

Você pode configurar automaticamente a etapa do divisor, a etapa do analisador de script e as saídas para ações de fluxo de dados baseadas EM REST. A funcionalidade da etapa Testar REST em Ações de fluxo de dados baseadas em REST executa uma solicitação para o endpoint REST configurado, analisa a carga de resposta e configura automaticamente os componentes de análise e saída.

Quando uma etapa REST é adicionada à seção Solicitação de uma ação de Fluxo de dados, você pode usar as etapas REST Etapa REST de teste botão para Gerar automaticamente a seção Análise e as saídas . A seção Análise inclui a etapa do divisor e a etapa do analisador. A geração automática também coloca a saída de objetos complexos na seção Saídas.

Script de transformação na etapa JDBC

A ação de fluxo de dados JDBC não requer paginação. As etapas do divisor e do analisador não são necessárias.

A etapa JDBC gera um objeto complexo para cada um dos registros recuperados. 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.

Visão geral da ação de Fluxo de dados JDBC. — Figura 4. Visão geral da ação de Fluxo de dados JDBC

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

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

Em tempo de execução, o sistema divide e analisa o fluxo de dados de resposta de acordo com Fluxo de dadosconfiguração. Cada item no fluxo é mapeado para a estrutura de objeto complexa definida pela etapa Analisador de scripts e pela 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. 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 da execução nas etapas REST e SOAP

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

Detalhes da execução de 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.

Contagem de 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 objetos complexos.
Contagem de erros Número de erros encontrados.

Detalhes da página

Exiba dados de tempo de execução de cada etapa no Fluxo de dadosação. 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 para as últimas cinco páginas. Para mudar o número de solicitações nos detalhes da execução, atualize com.snc.process_flow.page.reporting.lastnpropriedade do sistema. 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 da 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. Para obter mais informações, consulte Etapa JDBC de teste. Configure o. MID Server propriedades mid.jdbc.datastream.max.record.sizee. mid.jdbc.datastream.fail.when.attachement.limit.exceededpara recuperar dados de acordo com sua necessidade. Consulte Propriedades do MID Server para obter mais informações.