Configuração da ingestão de dados para seus dados do ServiceNow¶

Modificação da ingestão de dados usando o Snowsight¶

Para modificar as tabelas do ServiceNow a serem ingeridas ou o cronograma de sincronização para as tabelas, faça o seguinte:

1. Entre em Snowsight como um usuário com a função ACCOUNTADMIN.

2. Na navegação da esquerda, selecione Marketplace.

3. Procure o conector do Snowflake para ServiceNow, depois selecione o bloco para o conector.

4. Na página do Snowflake Connector for ServiceNow, selecione Edit.

5. Modifique as tabelas que você deseja ingerir:

   1. Procure a tabela que você deseja ingerir.

   2. Selecione a caixa de seleção na coluna Status ao lado da tabela que você deseja selecionar ou desmarcar.

   3. Em Synch Schedule, selecione com que frequência você deseja sincronizar a tabela entre Snowflake e ServiceNow.

6. Selecione Update.

Especificação do cronograma de sincronização¶

O conector Snowflake para ServiceNow sincroniza os dados de todas as tabelas do ServiceNow no Snowflake em um horário especificado. Por padrão, todas as tabelas são sincronizadas uma vez por hora (1h).

Para alterar o cronograma padrão de sincronização de todas as tabelas, chame o procedimento armazenado CONFIGURE_CONNECTOR com os seguintes argumentos:

CALL CONFIGURE_CONNECTOR('data_ingestion_schedule', '<schedule>');

Onde:

data_ingestion_schedule (o literal de cadeia de caracteres)

Especifica que você deseja configurar o cronograma para sincronização.

schedule

Especifica a freqüência da sincronização. Você pode especificar um dos seguintes valores da cadeia de caracteres:

• '30m'

• '1h'

• '3h'

• '6h'

• '12h'

• '1d'

O conector também permite especificar um cronograma diferente para cada tabela que é habilitada para sincronização. Para alterar o cronograma de sincronização de um conjunto selecionado de tabelas, chame o procedimento armazenado CONFIGURE_TABLES_SCHEDULE com os seguintes argumentos:

CALL CONFIGURE_TABLES_SCHEDULE(<table_names>, <schedule>);

Onde:

table_names

Especifica uma matriz de nomes de tabelas para os quais você deseja configurar o cronograma de sincronização.

schedule

Especifica a freqüência da sincronização. Você pode especificar um dos seguintes valores JSON:

• { 'type': 'interval', 'value': '<valor_interno>' }, onde interval_value é um dos seguintes valores de cadeia de caracteres:

  • '30m'

  • '1h'

  • '3h'

  • '6h'

  • '12h'

  • '1d'

• { 'type': 'custom', 'value': { 'hour': <hora>, 'dayOfWeek': '<dia_da_semana>' } }, em que hour especifica a hora no fuso horário UTC em que a ingestão deve começar e day_of_week especifica o dia da semana em que a ingestão deve ser realizada. É possível usar expressões especiais como dia da semana:

  • '*' para executar a ingestão todos os dias.

  • '1-3' para executar a ingestão de segunda a quarta-feira.

  • '0,5,6' para executar a ingestão na sexta, sábado e domingo.

  Os valores possíveis que podem ser usados na expressão para configuração day_of_week são:

  • '0' - Domingo

  • '1' - Segunda-feira

  • '2' - Terça-feira

  • '3' - Quarta-feira

  • '4' - Quinta-feira

  • '5' - Sexta-feira

  • '6' - Sábado

  Outros valores que não sejam dígitos, como '5L' que indica a última sexta-feira de um mês ou 'FRI-SUN' que indica o intervalo de sexta a domingo, não são suportados.

Por exemplo, para ingerir tabelas table_1 e table_2 todos os sábados e domingos às 11:00 PM UTC, chame o seguinte procedimento armazenado:

CALL CONFIGURE_TABLES_SCHEDULE(['table_1', 'table_2'], { 'type': 'custom', 'value': { 'hour': 23, 'dayOfWeek': '0,6' } });

Copy

Por padrão, o conector tenta iniciar a ingestão em 3 horas a partir do horário de início agendado. Se não for possível iniciar a ingestão dentro desse período, por exemplo, quando o conector estiver ingerindo outras tabelas, a execução programada atual não será executada. O conector tenta executar a ingestão no próximo período programado. É possível alterar a duração do período chamando o procedimento de armazenamento CONFIGURE_CONNECTOR:

CALL CONFIGURE_CONNECTOR('custom_schedule_start_ingestion_window', <window_length>);

Copy

onde window_length é o comprimento da janela no formato de duração ISO 8601. A duração deve ser arredondada para uma hora inteira e deve durar pelo menos 1 hora. Por exemplo, o valor 'PT12H' especifica uma janela que dura 12 horas e 'P2D' especifica uma janela que dura 2 dias.

Se você ativar apenas tabelas com cronogramas personalizados, essa configuração afetará apenas o tempo necessário para criar e atualizar exibições niveladas para as tabelas configuradas. As exibições niveladas são criadas no primeiro ciclo de ingestão após as seguintes condições serem atendidas:

• A ingestão de tabelas de metadados foi concluída

• A ingestão da tabela configurada foi iniciada.

Se os alertas por e-mail estiverem ativados, a Snowflake recomenda alterar a frequência do alerta para Once per day ao usar o cronograma personalizado.

Além disso, o conector expõe o procedimento armazenado CONFIGURE_CONNECTOR_TABLES obsoleto com os seguintes argumentos:

CALL CONFIGURE_CONNECTOR_TABLES('schedule_interval', '<schedule>', '<table_names>');

Onde:

schedule

Especifica a freqüência da sincronização. Você pode especificar um dos seguintes valores da cadeia de caracteres:

• '30m'

• '1h'

• '3h'

• '6h'

• '12h'

• '1d'

table_names

Especifica uma lista delimitada por vírgulas dos nomes das tabelas.

Para estas tabelas, o cronograma que você especifica no parâmetro schedule substitui a cronograma padrão que você define ao chamar o procedimento armazenado CONFIGURE_CONNECTOR('data_ingestion_schedule', 'schedule').

Especificação da hora de início do intervalo de dados¶

Por padrão, o conector Snowflake para ServiceNow sincroniza todos os registros nas tabelas ServiceNow correspondentes. Para as tabelas com: colunas sys_updated_on ou sys_created_on (doravante chamadas colunas de tempo) presentes, é possível restringir o intervalo de dados sincronizados definindo um horário de início do intervalo de dados - ou seja, limite inferior para o valor correspondente da coluna de tempo dos registros.

Com essa configuração, os registros com o valor de coluna de tempo correspondente mais antigo que o carimbo de data/hora de início do intervalo de dados não são ingeridos. A coluna de tempo correspondente usada por este procedimento é determinada da mesma maneira que para as atualizações incrementais.

Para alterar o valor do horário de início do intervalo de dados, chame o procedimento armazenado CONFIGURE_TABLES_RANGE_START com os seguintes argumentos:

CALL CONFIGURE_TABLES_RANGE_START(<table_names>, <range_start>);

Copy

Onde:

table_names

Especifica uma matriz de nomes de tabelas para as quais você deseja configurar a hora de início do intervalo de dados.

range_start

Carimbo de data/hora especificando o hora de início do intervalo de dados no formato TIMESTAMP_TZ ou NULL para cancelar a definição do valor atual.

• Se a ingestão da tabela ainda não tiver sido iniciada, o valor hora de início do intervalo de dados será levado em consideração na primeira ingestão.

• Se a ingestão da tabela já tiver sido iniciada (por exemplo, um recarregamento está em andamento), o valor hora de início do intervalo de dados será ignorado e (outro) recarregamento da(s) tabela(s) será necessário para filtrar os registros com valores de coluna de tempo correspondentes muito antigos.

Portanto, é recomendável definir o horário de início do intervalo de dados antes de iniciar a primeira ingestão de uma tabela (portanto, também antes de ativá-la).

Por exemplo, se as tabelas table1 e table2 tiverem as coluna(s) de tempo necessárias, para definir a hora de início do intervalo de dados como 2022-11-23 07:00:00 UTC para essas duas tabelas, execute o seguinte comando:

CALL CONFIGURE_TABLES_RANGE_START(['table1', 'table2'], TO_TIMESTAMP_TZ('2022-11-23 07:00:00 +00:00'));

Copy

Então:

• para a tabela table1, por exemplo, se sua ingestão ainda não tiver sido iniciada, todos os registros com valor de coluna de tempo correspondente antes de 2022-11-23 07:00:00 não serão ingeridos.

• para a tabela table2, por exemplo, se sua ingestão já tiver sido iniciada, o valor hora de início do intervalo de dados será ignorado em todas as sincronizações de dados até recarregar esta tabela. Durante a recarga, todos os registros com valor de coluna de tempo correspondente antes de 2022-11-23 07:00:00 não serem ingeridos.

Também é possível cancelar a hora de início do intervalo de dados. Por exemplo, para cancelar a configuração da tabela table1, execute o seguinte comando:

CALL CONFIGURE_TABLES_RANGE_START(['table1'], NULL);

Copy

Novamente, se uma ingestão da tabela table1 já tiver sido iniciada, será necessário recarregar esta tabela para ingerir todos os registros de ServiceNow.

Ativação ou desativação da sincronização de uma tabela¶

Para ativar a sincronização de dados para uma tabela específica no ServiceNow, chame o procedimento armazenado ENABLE_TABLES com os seguintes argumentos:

CALL ENABLE_TABLES(<tables_to_enable>);

Copy

Onde:

tables_to_enable

Especifica uma matriz de nomes de tabela do ServiceNow.

Use o nome da tabela, não a etiqueta exibida na UI do ServiceNow. Você pode encontrar o nome da tabela nas tabelas do dicionário de dados no ServiceNow. Na UI do ServiceNow, vá para System Definition » Tables. A coluna Name exibe o nome da tabela.

Por exemplo, para permitir a sincronização das tabelas chamadas table1, table2 e table3, execute o seguinte comando:

CALL ENABLE_TABLES(['table1', 'table2', 'table3']);

Copy

Para desativar a sincronização de dados para uma tabela específica no ServiceNow, chame o procedimento armazenado DISABLE_TABLES com os seguintes argumentos:

CALL DISABLE_TABLES(<tables_to_disable>);

Copy

Onde:

tables_to_disable

Especifica uma matriz de nomes de tabela do ServiceNow.

Use o nome da tabela, não a etiqueta exibida na UI do ServiceNow. Você pode encontrar o nome da tabela nas tabelas do dicionário de dados no ServiceNow. Na UI do ServiceNow, vá para System Definition » Tables. A coluna Name exibe o nome da tabela.

Por exemplo, para desativar a sincronização das tabelas chamadas table1 e table2, e execute o seguinte comando:

CALL DISABLE_TABLES(['table1', 'table2']);

Copy

A desativação da tabela interrompe sua sincronização. Quando a sincronização da tabela é reativada, a ingestão recomeça de onde foi feita a pausa.

O conector expõe a versão obsoleta do procedimento ENABLE_TABLES que recebe dois argumentos:

CALL ENABLE_TABLES('<tables_to_configure>', <enable>);

Copy

Onde:

tables_to_configure

Especifica uma lista delimitada por vírgulas dos nomes das tabelas do ServiceNow.

enable

Especifica se a sincronização deve ser ativada ou desativada para essas tabelas. Especifique TRUE para ativar ou FALSE para desativar.

Este procedimento está obsoleto e deverá ser removido em uma versão futura do conector. Recomendamos usar ENABLE_TABLES e DISABLE_TABLES com um único argumento.

Os procedimentos ENABLE_TABLES e DISABLE_TABLES adicionam os nomes de tabela especificados à exibição ENABLED_TABLES.

Se você quiser adicionar todas as tabelas disponíveis no ServiceNow à exibição ENABLED_TABLES, chame o procedimento armazenado PREFILL_CONFIG_TABLE.

Para chamar este procedimento, execute o seguinte comando:

CALL PREFILL_CONFIG_TABLE();

Este procedimento adiciona todas as tabelas do ServiceNow à visualização ENABLED_TABLES e desabilita as tabelas para ingestão por padrão.

Para habilitar estas tabelas recém-adicionadas para sincronização:

1. Execute os seguintes comandos para produzir uma lista delimitada por vírgula das tabelas na exibição ENABLED_TABLES:

   SELECT LISTAGG(TABLE_NAME, ',') FROM ENABLED_TABLES;
   

   Copy

2. Na lista retornada por este comando, remova as tabelas que não devem ser sincronizadas.

3. Chame o procedimento armazenado ENABLE_TABLES e passe nesta lista.

Se novas tabelas foram adicionadas recentemente ao ServiceNow, você pode identificar as novas tabelas e habilitar essas tabelas para sincronização usando esta mesma abordagem (ou seja, gerar a lista de tabelas, editar a lista e passar a lista para o procedimento armazenado ENABLE_TABLES).

Ativação da sincronização de uma tabela com filtragem de coluna¶

Se você não precisar de todas as colunas de uma tabela ServiceNow no Snowflake, você poderá ignorá-las. Por exemplo, talvez você queira pular as colunas se uma única linha exceder o tamanho máximo de linha de 10 MB.

Para ativar a ingestão de tabelas com colunas especificadas, execute o seguinte comando:

CALL ENABLE_TABLE_WITH_COLUMNS('<table_to_enable>', <include_columns>, <exclude_columns>);

Copy

Onde:

table_to_enable

Especifica um nome de tabela ServiceNow.

include_columns

Especifica uma matriz de nomes de colunas a serem ingeridas. Se sys_id, sys_created_on e sys_updated_on existirem, eles sempre são incluídos, mesmo que não sejam mencionados nesta matriz.

exclude_columns

Especifica uma matriz de nomes de coluna a serem excluídos da ingestão. Você não pode excluir as colunas sys_id, sys_created_on ou sys_updated_on, pois o conector as usa no processo de ingestão.

Por exemplo, ter uma tabela ServiceNow chamada u_table com colunas sys_id, sys_updated_on, col_1 e col_2 e executar:

CALL ENABLE_TABLE_WITH_COLUMNS('u_table', ['sys_id', 'sys_updated_on'], []);

Copy

irá ingerir apenas as colunas sys_id e sys_updated_on para a tabela fornecida, mas chamando:

CALL ENABLE_TABLE_WITH_COLUMNS('u_table', [], ['col_1']);

Copy

irá ingerir sys_id, sys_updated_on e também col_2.

O conector valida as colunas fornecidas e rejeita a solicitação de ativação se alguma das colunas não estiver disponível no ServiceNow. Como a API do ServiceNow oferece suporte apenas ao modo de inclusão, o conector transforma matrizes de colunas fornecidas em lista de colunas incluídas e as envia com cada solicitação para o ServiceNow. O URL com colunas incluídas pode ser muito longo para o ServiceNow. O conector valida essa limitação quando ENABLE_TABLE_WITH_COLUMNS é invocado.

A configuração das colunas incluídas para cada tabela pode ser encontrada na coluna INCLUDED_COLUMNS da exibição ENABLED_TABLES. Para modificar a lista de colunas ingeridas, primeiro você precisa desativar a tabela específica. Se a filtragem de coluna estiver configurada para uma tabela, você poderá ativar as colunas apenas usando o procedimento ENABLE_TABLE_WITH_COLUMNS. Você não pode usar o ENABLE_TABLES nesse caso.

A alteração de configuração não afeta os dados já ingeridos. A filtragem de coluna se aplica apenas aos registros recém-ingeridos.

As exibições niveladas incluem apenas as colunas especificadas quando a tabela foi ativada. Elas são atualizadas sempre que a lista de colunas incluídas é alterada. Se nenhuma filtragem de coluna estiver configurada, uma exibição consistirá em todas as colunas disponíveis.

Recarregamento de dados em uma tabela¶

Para recarregar dados em uma tabela específica, chame o procedimento armazenado RELOAD_TABLE:

CALL RELOAD_TABLE('<table_name>');

Onde:

table_name

Especifica o nome da tabela a ser recarregada.

Quando você chama o procedimento armazenado RELOAD_TABLE, o conector executa o seguinte exemplo:

1. O conector suspende temporariamente a ingestão da tabela original.

   Nota

   Enquanto a tabela está sendo recarregada, não é possível reativar a tabela para ingestão.

2. O conector cria uma tabela temporária separada para ingestão.

3. O conector faz a ingestão dos dados nesta nova tabela temporária. Esta tabela é visível na exibição CONNECTOR_STATS como uma tabela com um sufixo __tmp.

   Nota

   Cada recarga leva em consideração o valor da hora de início do intervalo de dados, o que pode restringir quais registros são ingeridos.

4. Depois de ingeridos os dados, o conector substitui os dados da tabela original pelos dados da tabela temporária.

5. O conector apaga a tabela temporária.

6. O conector reativa a tabela original para ingestão.

Durante este processo, você pode continuar a consultar os dados existentes na tabela original. No entanto, as mudanças nos dados da tabela do ServiceNow não serão refletidas na tabela do Snowflake até que o processo de ingestão esteja concluído.

Para evitar sobrecarregar sua instância do ServiceNow, recarregue apenas uma tabela de cada vez.

Cancelamento da recarga da tabela¶

Para cancelar o processo de recarga dos dados em uma tabela, use o procedimento armazenado CANCEL_RELOAD_TABLE, como mostrado no exemplo a seguir:

CALL CANCEL_RELOAD_TABLE('<table_name>');

Onde:

table_name

Especifica o nome da tabela cuja recarga você deseja cancelar.

Quando você cancela a recarga, o conector descarta todos os objetos temporários criados durante a recarga. A tabela fica então disponível para ingestão como parte do cronograma normal de sincronização.

Configuração do tamanho de uma busca de página única para uma tabela¶

O conector obtém dados de uma tabela dividindo-os em partes menores chamadas páginas. Cada solicitação da API para ServiceNow busca uma página. Devido às limitações do Snowflake e das ServiceNow REST APIs, o tamanho da resposta da API do ServiceNow não pode exceder 10 MB e a resposta deve ser retornada em menos de um minuto.

Para levar isso em conta, o conector limita o número de linhas obtidas em uma única solicitação de API. Esse limite é o tamanho da página.

O conector usa o seguinte processo para determinar o tamanho da página:

1. Inicialmente, o tamanho da página padrão é definido como 10.000 linhas.

2. Se a solicitação de busca falhar durante a ingestão porque o tamanho da resposta foi excedido, o tamanho da página será gradualmente reduzido em 1.000, 100, 10 e 1 até que a solicitação seja bem-sucedida ou o tamanho final da página seja definido como 1.

3. O tamanho da página bem-sucedido é salvo no estado do conector e esse valor é usado pelas solicitações subsequentes.

O tamanho atual da página de uma tabela está disponível na exibição ENABLED_TABLES. Para ver o tamanho da página, execute o seguinte comando:

SELECT PAGE_SIZE FROM ENABLED_TABLES WHERE TABLE_NAME = '<table_name>';

Onde:

table_name

Especifica o nome da tabela do ServiceNow que está sendo ingerida.

O processo que o conector usa para determinar o tamanho da página pode levar a ineficiências. Este processo reduz apenas o tamanho da página. Ele não aumenta o tamanho da página. Isto pode acontecer em situações em que uma tabela tem uma única linha grande que faz com que o tamanho da página seja definido com um valor menor.

Para evitar esta situação, você pode definir manualmente o tamanho da página chamando o procedimento armazenado RESET_PAGE_SIZE, como mostrado no exemplo a seguir:

CALL RESET_PAGE_SIZE('<table_name>');

Onde:

table_name

Especifica o nome da tabela do ServiceNow que está sendo ingerida.

Execução de ingestão¶

As execuções de ingestão para uma determinada tabela são acionadas de acordo com o cronograma configurado. Uma execução baixa todas as linhas relevantes divididas em páginas mencionadas no parágrafo anterior da tabela de origem em um loop.

Carregamento inicial e atualizações

Assim que uma página de dados é obtida, ela é inserida na tabela de log de eventos correspondente. Neste estágio, as alterações recém-buscadas ainda não estão disponíveis na tabela de sincronização ou por meio de exibições niveladas. Quando isso for feito, a próxima solicitação com critérios atualizados será emitida, desde que algum dado seja retornado. Quando a execução de ingestão for concluída e não houver mais dados para buscar na tabela de origem, uma tarefa de mesclagem assíncrona será acionada, que pega todas as alterações do log de eventos inseridas desde a última mesclagem e as aplica à tabela de sincronização. Quando estiver concluído, os dados ficarão disponíveis na tabela de sincronização e nas exibições niveladas.

Truncamento e carregamento

No modo de truncamento e carregamento, uma tabela temporária é criada para cada execução de ingestão. Cada página de linhas buscada é inserida primeiro nesta tabela temporária (esta tabela existe no esquema do conector interno e não está disponível para usuários do conector). Neste estágio, as alterações recém-buscadas ainda não estão disponíveis na tabela de sincronização ou por meio de exibições niveladas; elas ainda mostram os dados buscados na execução anterior. Quando a execução de ingestão for concluída e não houver mais dados disponíveis na tabela de origem, os dados da tabela temporária substituirão os dados existentes na tabela de sincronização. Todas as linhas buscadas também são adicionadas ao log de eventos. No fim, a tabela temporária é descartada.

Monitoramento do progresso

Para verificar o status de uma execução de ingestão atual ou passada, você pode consultar a exibição CONNECTOR_STATS. Ela fica visível na coluna STATUS. Ela é definida como DONE somente se os dados foram buscados com sucesso e todas as alterações foram aplicadas à tabela de sincronização. Quando a ingestão está em execução ou a mesclagem com a tabela de sincronização/substituição de linhas na tabela de sincronização ainda não foi concluída, o status será RUNNING.