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

O Snowflake Connector para ServiceNow® V2 está sujeito aos Termos do Snowflake Connector.

Este tópico descreve como configurar a ingestão de dados para o Snowflake Connector for ServiceNow®V2.

Nota

O Snowflake Connector for ServiceNow®V2 ingere dados de tabelas ServiceNow® no Snowflake. A ingestão de dados depende de v2 da API de tabela do ServiceNow®.

Neste tópico:

Estratégias para a ingestão de tabelas do ServiceNow®

Nota

  • O conector só pode ingerir tabelas com colunas sys_id presentes.

  • Exibições do ServiceNow não são suportadas. Em vez de ingerir essas exibições, você deve sincronizar todas as tabelas para a exibição subjacente e fazer a junção das tabelas sincronizadas no Snowflake.

O conector utiliza diferentes estratégias de ingestão, dependendo do esquema da tabela. O conector usa três modos de ingestão:

  • A carga inicial de dados ocorre para cada tabela quando a tabela é habilitada para sincronização.

    Neste modo, a tabela é ingerida por iteração através dos registros identificados pelos IDs na coluna sys_id. Quando todos os registros forem ingeridos, a fase inicial de carga é concluída. Para determinadas tabelas, você também pode definir o valor do horário de início do intervalo de dados, que pode restringir quais registros serão ingeridos.

  • Atualizações incrementais ocorrem somente para tabelas com as colunas sys_updated_on ou sys_created_on.

    As atualizações incrementais começam depois que a carga inicial é feita e ocorrem em um horário regular que você pode configurar. Neste modo, o conector ingere apenas os registros que foram adicionados, atualizados ou excluídos desde a última sincronização.

Nota

As informações sobre exclusões vêm da tabela de diário fornecida durante a configuração do conector.

  • Para tabelas que não possuem colunas sys_updated_on ou sys_created_on, o conector usa o modo truncar e carregar.

    Neste modo, a tabela é sempre ingerida usando a abordagem de carga inicial, e os dados recém-ingeridos substituem os dados antigos. O conector substitui os dados executando o comando INSERT OVERWRITE.

Nota

  • No modo “atualizações incrementais”, o conector usa a coluna sys_updated_on, se essa coluna estiver presente.

    Se a coluna não estiver presente, o conector utiliza a coluna sys_created_on em seu lugar.

  • Para as tabelas giradas, o conector sempre usa a coluna sys_created_on. Se a tabela for girada usando uma coluna diferente de sys_created_on, a ingestão dessa tabela pode causar problemas de desempenho.

Nota

  • Se os campos sys_updated_on ou sys_created_on não forem atualizados quando o registro for modificado no ServiceNow, essas alterações não serão propagadas para o Snowflake, o que resulta em inconsistência de dados. Snowflake recomenda que você evite desabilitar a atualização dos campos do sistema.

  • Se um registro apagado não for auditado, as informações sobre registros apagados não serão propagadas para o Snowflake, resultando em uma inconsistência de dados.

Nota

Devido às restrições nas REST APIs do Snowflake e ServiceNow®, o conector não pode ingerir uma tabela se uma única linha exceder 16 MB de dados. Nesse caso, o conector tenta ingerir dados com a frequência definida no cronograma da tabela. Se uma linha exceder o limite, o conector gerará uma mensagem de erro e continuará ingerindo outras tabela. Para superar esse limite, é possível configurar a filtragem de colunas para excluir colunas grandes da ingestão.

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.

Ingestão paralela de tabelas do ServiceNow®

O conector ingere algumas tabelas em paralelo, mas a ingestão de cada tabela individual é um processo síncrono. Isto significa que a ingestão de tabelas grandes pode bloquear o conector de atualizar outras tabelas. Esta questão é mais provável que ocorra durante a fase de carga inicial do que em outras fases. Por padrão, o conector usa 10 threads de trabalho, o que é considerado um valor ideal para não sobrecarregar a instância de ServiceNow®. Se tiver certeza de que sua instância é capaz de suportar simultaneidade adicional, você pode aumentar esse valor para um máximo de 30 chamando o procedimento CONFIGURE_CONCURRENCY.

Configuração da ingestão de dados usando o Snowsight

Para configurar a ingestão de dados usando Snowsight, 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 a aba Data Sync.

    Isto exibirá uma lista de todas as tabelas do ServiceNow®.

    Nota

    O conector só pode ingerir tabelas com colunas sys_id presentes.

  5. Selecione 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.

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

    4. Repita estes passos para cada tabela que você deseja ingerir no Snowflake.

  6. Selecione o título da coluna Status para ver as tabelas que você selecionou no momento.

  7. Selecione Start sync para começar a ingerir dados em sua conta Snowflake.

O status do conector muda para Syncing data. Quando pelo menos uma das tabelas é ingerida com sucesso, o estado do conector muda para Last Sync: just now.

Consulte Monitoramento do Snowflake Connector for ServiceNow®V2 para obter informações sobre como visualizar o conteúdo das tabelas no 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.

Configuração da ingestão de dados usando instruções SQL

Para configurar a ingestão de dados usando instruções SQL, faça o seguinte:

Nota

Para definir estas configurações, são utilizados procedimentos armazenados que são definidos no esquema PUBLIC do banco de dados que serve como instância do conector.

Antes de chamar esses procedimentos armazenados, selecione esse banco de dados como o banco de dados a ser utilizado para a sessão.

Por exemplo, se esse banco de dados for nomeado my_connector_servicenow, execute o seguinte comando:

USE DATABASE my_connector_servicenow;
Copy

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.

Como habilitar várias tabelas usando a configuração padrão

Para habilitar a sincronização de dados para pelo menos uma tabela 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 em vez da 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á em 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

Como desabilitar várias tabelas

Para desabilitar a sincronização de dados de 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 em vez da 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á em 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

Desabilitar a tabela interrompe a sincronização normalmente, assim que possível. Quando a sincronização da tabela é reativada, a ingestão recomeça de onde foi feita a pausa.

Nota

Desabilitar todas as tabelas de sincronização não significa que Snowflake Connector for ServiceNow®V2 deixará de gerar custos. Tarefas em segundo plano, como aquelas relacionadas a notificações, podem continuar sendo executadas.

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

Nota

O conector não oferece suporte para reversão ou exclusão de recuperações no ServiceNow®.

A utilização dos recursos de reversão e exclusão de recuperação pode resultar em inconsistência de dados. Os registros recuperados no ServiceNow® ainda podem ser marcados como excluídos no Snowflake. Para resolver isso, é possível recarregar a tabela.

Como habilitar uma única tabela usando configuração personalizada

Para habilitar a sincronização de dados com configuração personalizada para uma tabela específica no ServiceNow®, chame o procedimento armazenado ENABLE_TABLE com os seguintes argumentos:

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

Onde:

table_to_enable

Especifica um nome de tabela do ServiceNow®.

table_config

Opcional, especifica um objeto com configuração de ingestão de tabela. Se não for especificado, a ingestão da tabela usará a configuração padrão.

As configurações atualmente compatíveis são:

  • filtragem de colunas, onde é possível fornecer as propriedades include_columns ou exclude_columns com uma lista de nomes de colunas,

  • filtragem de linha, onde é possível fornecer a propriedade filter com uma expressão de filtro,

  • cronograma de sincronização, onde é possível fornecer a propriedade schedule com cronograma de ingestão personalizado.

Nota

Todas as configurações personalizadas podem ser combinadas em um único objeto e usadas simultaneamente para uma única ingestão de tabela, por exemplo, para habilitar a ingestão de tabela sys_audit com a configuração abaixo:

  • a tabela deve ser sincronizada todos os sábados às 10:00 AM UTC,

  • somente as colunas newvalue e reason devem ser ingeridas,

  • somente as linhas que têm a coluna newvalue começando com a cadeia de caracteres privacy devem ser ingeridas,

execute o seguinte comando:

CALL ENABLE_TABLE('sys_audit', {
  'schedule': { 'type': 'custom', 'value': { 'hour': 10, 'day_of_week': '6' } },
  'include_columns': ['newvalue', 'reason'],
  'row_filter': 'newvalue STARTSWITH "privacy"'
});
Copy

Como habilitar uma única tabela usando filtragem de coluna

Se você não precisar de todas as colunas de uma tabela ServiceNow® no Snowflake, o conector poderá ignorá-las. Por exemplo, pule para as colunas se uma única linha exceder o tamanho máximo de linha de 16 MB.

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

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

Onde:

table_to_enable

Especifica um nome de tabela do ServiceNow®.

table_config

Objeto incluindo as propriedades include_columns ou exclude_columns com uma lista de nomes de colunas. Se sys_id, sys_created_on e sys_updated_on existirem, eles serão sempre inclusos. Você não precisa adicioná-los à matriz included_columns e não pode excluí-los usando excluded_columns visto que o conector os utiliza no processo de ingestão.

Nota

Como as colunas no ServiceNow® são escritas em letras minúsculas e a API usada pelo conector diferencia maiúsculas de minúsculas, os valores fornecidos para colunas especificadas também devem estar em letras minúsculas.

Nota

Você não deve fornecer include_columns e exclude_columns. Se quiser listar include_columns, você deve ignorar a propriedade exclude_columns e vice-versa. Se ambas as matrizes não estiverem vazias e não houver colunas conflitantes, include_columns terá precedência sobre exclude_columns.

Se include_columns e exclude_columns forem matrizes vazias, todas as colunas disponíveis serão ingeridas.

Por exemplo, com uma tabela ServiceNow® nomeada u_table com colunas sys_id, sys_updated_on, col_1 e col_2 executando:

CALL ENABLE_TABLE('u_table', { 'include_columns': ['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('u_table', { 'exclude_columns': ['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®. A API ServiceNow® oferece suporte apenas ao modo de inclusão. Como resultado, o conector transforma matrizes de colunas fornecidas em listas de colunas inclusas e as envia com cada solicitação ao ServiceNow®. A URL com colunas inclusas podem ser muito longas para serem manipuladas pelo ServiceNow®. O conector valida essa limitação quando ENABLE_TABLE é invocado.

A configuração das colunas para cada tabela pode ser encontrada na coluna INCLUDED_COLUMNS da exibição CONFIGURED_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 a tabela apenas usando o procedimento ENABLE_TABLE. Não é possível usar o ENABLE_TABLES, que aceita uma lista de tabelas como argumento.

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 a filtragem de colunas não estiver configurada, as visualizações conterão todas as colunas disponíveis.

Nota

A alteração da configuração não afeta os dados ingeridos anteriormente. A filtragem de coluna se aplica apenas aos registros recém-ingeridos. Para aplicar o filtro aos dados ingeridos anteriormente, a tabela precisa ser recarregada.

Como habilitar uma única tabela usando filtragem de linha

É possível excluir a ingestão de dados para linhas selecionadas de uma tabela ServiceNow® especificando uma condição de filtro. Por exemplo, para excluir as linhas que incluem dados confidenciais que você não deseja no Snowflake, ou excluir as linhas que incluem dados desnecessários para reduzir custo.

Para habilitar a ingestão de tabela com o filtro de linha especificado, execute o seguinte comando:

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

Onde:

table_to_enable

Especifica um nome de tabela do ServiceNow®.

table_config

Objeto incluindo a propriedade row_filter com uma expressão de filtro, que é uma cadeia de caracteres válida.

Os operadores de filtro atualmente compatíveis são:

Operador

Descrição

Exemplo

AND

Operador lógico para unir condições, onde ambas devem ser atendidas.

active = "true" AND impact = "2"

OR

Operador lógico para unir condições, onde pelo menos uma delas deve ser atendida.

Importante

Tem precedência sobre o operador AND. Consulte os exemplos abaixo.

tablename = "incident" OR tablename = "problem"

=

Verifica se os valores são iguais.

priority = "1"

!=

Verifica se os valores não são iguais.

state != "7"

LIKE

Verifica se o valor contém a sequência de caracteres especificada.*

newvalue LIKE "privacy"

STARTSWITH

Verifica se o valor começa com a sequência de caracteres especificada.*

description STARTSWITH "important"

ENDSWITH

Verifica se o valor termina com a sequência de caracteres especificada.*

description ENDSWITH "important"

IN

Verifica se o valor é igual a algum da lista de valores.**

tablename IN ("incident", "task", "cmdb_ci")

(*) – os campos devem ser do tipo de dados string. (**) – os campos de escolha devem conter cadeias de caracteres.

Regras e limitações de expressão de filtro:

  • Quaisquer duas expressões de filtro devem ser unidas com o operador AND ou OR.

  • Os operadores devem ser separados por espaço e estar em letras maiúsculas.

  • Expressões de valor devem ser colocadas entre aspas duplas.

  • As expressões diferenciam maiúsculas de minúsculas.

  • A expressão não pode operar em colunas sys_id, sys_updated_on ou sys_created_on.

Nota

As alterações de configuração não afetam os dados ingeridos anteriormente. A filtragem de linhas se aplica somente aos registros recém-ingeridos. Para aplicar o filtro aos dados já ingeridos, a tabela deve ser recarregada.

Exemplos
  • Para habilitar a ingestão da tabela sys_audit, mas sincronizar apenas as linhas relacionadas aos incidentes de privacidade na tabela INCIDENT, execute:

CALL ENABLE_TABLE('sys_audit', {
  'row_filter': 'tablename = "incident" AND fieldname = "cause" AND newvalue LIKE "privacy"'
});
Copy
  • Para habilitar a ingestão da tabela incident, mas sincronizar apenas as linhas sob condições que:

    • o campo active é igual a true,

    • o campo sys_created_by começa com support ou termina com admin,

    • o campo category é um de Network, Cloud Management,

    execute:

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")'
});
Copy
  • Para habilitar a ingestão da tabela incident, mas ingerir apenas as linhas no estado de incidente especificado e apenas as colunas fornecidas, execute:

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

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>);
Copy

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>);
Copy

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' } });
Copy

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>);
Copy

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

CALL CONFIGURE_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 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.

Nota

Você não pode definir a hora de início do intervalo de dados para tabelas sem as colunas sys_updated_on e sys_created_on presentes.

  • 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®.

Nota

Carregar os dados respeitando a hora de início do intervalo de dados pode demorar mais do que carregar todos os dados históricos devido ao desempenho inferior da atualização incremental.

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>');
Copy

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>');
Copy

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>';
Copy

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>');
Copy

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.

Próximos passos

Depois de configurar a ingestão, execute as etapas descritas em Acesso aos dados do ServiceNow® no Snowflake para visualizar e acessar os dados do ServiceNow®.