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
ousys_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
ousys_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 desys_created_on
, a ingestão dessa tabela pode causar problemas de desempenho.
Nota
Se os campos
sys_updated_on
ousys_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:
Entre em Snowsight como um usuário com a função ACCOUNTADMIN.
No menu de navegação, selecione Data Products » Apps.
Procure o Snowflake Connector para ServiceNow®V2 e selecione o bloco para o conector.
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.Selecione as tabelas que você deseja ingerir:
Procure a tabela que você deseja ingerir.
Selecione a caixa de seleção na coluna Status à esquerda da tabela que você deseja selecionar.
Em Sync Schedule, selecione com que frequência deseja sincronizar a tabela entre Snowflake e ServiceNow®.
Repita estes passos para cada tabela que você deseja ingerir no Snowflake.
Selecione o título da coluna Status para ver as tabelas que você selecionou no momento.
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:
Entre em Snowsight como um usuário com a função ACCOUNTADMIN.
No menu de navegação, selecione Data Products » Apps.
Procure o Snowflake Connector para ServiceNow®V2 e selecione o bloco para o conector.
Na página do Snowflake Connector for ServiceNow®V2, selecione Data Sync.
Selecione o botão Edit tables para entrar no modo de edição.
Modifique as tabelas que você deseja ingerir:
Procure a tabela que você deseja ingerir.
Selecione a caixa de seleção na coluna Status à esquerda da tabela que você deseja selecionar ou cancelar a seleção.
Em Sync Schedule, selecione com que frequência deseja sincronizar a tabela entre Snowflake e ServiceNow®.
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;
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>);
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']);
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>);
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']);
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>);
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
ouexclude_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
ereason
devem ser ingeridas,somente as linhas que têm a coluna
newvalue
começando com a cadeia de caracteresprivacy
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"' });
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>);
Onde:
table_to_enable
Especifica um nome de tabela do ServiceNow®.
table_config
Objeto incluindo as propriedades
include_columns
ouexclude_columns
com uma lista de nomes de colunas. Sesys_id
,sys_created_on
esys_updated_on
existirem, eles serão sempre inclusos. Você não precisa adicioná-los à matrizincluded_columns
e não pode excluí-los usandoexcluded_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'] });
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'] });
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>);
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
ouOR
.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
ousys_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 tabelaINCIDENT
, execute:
CALL ENABLE_TABLE('sys_audit', {
'row_filter': 'tablename = "incident" AND fieldname = "cause" AND newvalue LIKE "privacy"'
});
Para habilitar a ingestão da tabela
incident
, mas sincronizar apenas as linhas sob condições que:o campo
active
é igual atrue
,o campo
sys_created_by
começa comsupport
ou termina comadmin
,o campo
category
é um deNetwork
,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")'
});
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']
});
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>' }
, ondeinterval_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 quehour
especifica a hora no fuso horário UTC em que a ingestão deve começar eday_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ábadoOutros 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. Verifiqueschedule
do procedimento armazenadoCONFIGURE_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 armazenadoCONFIGURE_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>);
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'));
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);
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>');
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:
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.
O conector cria uma tabela temporária separada para ingestão.
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.
Depois de ingeridos os dados, o conector substitui os dados da tabela original pelos dados da tabela temporária.
O conector apaga a tabela temporária.
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:
Inicialmente, o tamanho da página padrão é definido como 10.000 linhas.
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.
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
.
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®.