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

Registros arquivados¶

O conector não reflete ativamente os registros arquivados em ServiceNow no lado do Snowflake para as tabelas ingeridas. Supondo que você arquive registros inativos mais antigos que uma determinada data, o seguinte se aplica:

• Qualquer registro arquivado antes do conector ingeri-lo (por exemplo, antes do carregamento inicial da tabela) não estará presente na tabela do lado do Snowflake.

• Qualquer registro arquivado após já ter sido ingerido pelo conector permanece no lado do Snowflake sem nenhuma indicação de ação de arquivamento em progresso.

• Qualquer registro arquivado restaurado para uma tabela que já esteja operando no modo de atualizações incrementais não será ingerido do lado do Snowflake, a menos que esse registro também seja modificado posteriormente (com seu valor sys_updated_on sendo atualizado para a hora atual).

• Um registro arquivado restaurado durante o carregamento inicial da tabela pode ser ingerido no lado do Snowflake dependendo de seu ID na coluna sys_id.

Se quiser atualizar a tabela com uma regra de arquivamento ativa, você pode recarregar a tabela inteira, mas qualquer registro arquivado ou restaurado após a conclusão da recarga seguirá os mesmos princípios listados acima.

As tabelas de arquivo do ServiceNow ar_[table_name] podem ser habilitadas para sincronização. No entanto, a primeira atualização incremental após o carregamento inicial dessa tabela pesquisará registros criados/atualizados após a data do carregamento inicial da tabela de arquivo ter sido iniciada. Como nem sys_updated_on nem sys_created_on são modificados quando o registro é arquivado, os registros arquivados após o carregamento inicial da tabela de arquivo até um certo momento estarão ausentes no lado do Snowflake. Por exemplo, se você arquivar registros com mais de um ano, qualquer registro arquivado por um ano após o carregamento inicial da tabela de arquivo não será ingerido na tabela de arquivo no lado do Snowflake. Os registros arquivados que tiverem sido restaurados ou excluídos por uma regra de destruição após o carregamento inicial de uma tabela de arquivo nunca serão removidos dela no lado do Snowflake.

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. No menu de navegação, selecione Data Products » Apps.

3. Procure o Snowflake Connector para ServiceNow®V2 e selecione o bloco para o conector.

4. Na página do Snowflake Connector for ServiceNow®V2, selecione Data Sync.

5. Selecione o botão Edit tables para entrar no modo de edição.

6. 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 à esquerda da tabela que você deseja selecionar ou cancelar a seleção.

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

7. Selecione Update data sync.

Como habilitar ou desabilitar a sincronização de tabela¶

Esta seção descreve como habilitar ou desabilitar a sincronização de uma tabela no ServiceNow®. A ativação da sincronização pode ser feita com configuração padrão e personalizada.

CALL ENABLE_TABLES(<tables_to_enable>);

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

CALL DISABLE_TABLES(<tables_to_disable>);

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

CALL ENABLE_TABLE('<table_to_enable>', <table_config>);

CALL ENABLE_TABLE('<table_to_enable>', <table_config>);

CALL ENABLE_TABLE('u_table', { 'include_columns': ['sys_id', 'sys_updated_on'] });

CALL ENABLE_TABLE('u_table', { 'exclude_columns': ['col_1'] });

CALL ENABLE_TABLE('<table_to_enable>', <table_config>);

CALL ENABLE_TABLE('sys_audit', {
  'row_filter': 'tablename = "incident" AND fieldname = "cause" AND newvalue LIKE "privacy"'
});

CALL ENABLE_TABLE('incident', {
  'row_filter': 'active = "true" AND sys_created_by STARTSWITH "support" OR sys_created_by ENDSWITH "admin" AND category IN ("Network", "Cloud Management")'
});

CALL ENABLE_TABLE('incident', {
  'row_filter': 'incident_state IN ("1", "2", "3")', -- "New", "In Progress", "On Hold"
  'include_columns': ['incident_state', 'description']
});

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

O Snowflake Connector for ServiceNow®V2 sincroniza os dados de todas as tabelas do ServiceNow® no Snowflake em um cronograma 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_DATA_INGESTION_SCHEDULE com os seguintes argumentos:

CALL CONFIGURE_DATA_INGESTION_SCHEDULE(<schedule>);

Onde:

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>, 'day_of_week': '<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.

É possível configurar o cronograma de ingestão para uma tabela específica durante sua ativação. Para habilitar uma única tabela e definir seu cronograma de ingestão, chame o procedimento armazenado ENABLE_TABLE com os seguintes argumentos:

CALL ENABLE_TABLE('<table_name>', <table_config>);

Onde:

table_name

Especifica um nome de tabela ServiceNow® a ser habilitado.

table_config

Objeto incluindo a propriedade schedule, que especifica a configuração da sincronização da tabela. Verifique schedule do procedimento armazenado CONFIGURE_DATA_INGESTION_SCHEDULE para obter detalhes.

Por exemplo, para permitir a ingestão da tabela table_1 e sincronizar os dados a cada 3 horas, chame o seguinte procedimento armazenado:

CALL ENABLE_TABLE('table_1', { 'schedule': { 'type': 'interval', 'value': '3h' } });

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. Verifique schedule do procedimento armazenado CONFIGURE_DATA_INGESTION_SCHEDULE para obter detalhes.

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, 'day_of_week': '0,6' } });

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 quadro de tempo chamando o procedimento armazenado CONFIGURE_CUSTOM_SCHEDULE_START_INGESTION_WINDOW:

CALL CONFIGURE_CUSTOM_SCHEDULE_START_INGESTION_WINDOW(<window_length>);

onde window_length é o comprimento da janela no formato de duração ISO 8601. A duração deve ser arredondada para a próxima 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.

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

Por padrão, o Snowflake Connector for ServiceNow®V2 sincroniza todos os registros nas tabelas do 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®.

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 o ServiceNow® busca uma página.

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 TABLES_STATE. Para ver o tamanho da página, execute o seguinte comando:

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

Onde:

table_name

Especifica o nome da tabela do ServiceNow® 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® 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.