Funções Diff no Jitterbit Studio

Use funções Diff para sincronizar dados

O recurso Diff / Sincronizar do Jitterbit pode ser usado em transformações para sincronizar dados em uma única tabela com qualquer tipo de destino.

A fonte deve ser um banco de dados ou um arquivo CSV. Se for um banco de dados, a tabela de origem deve ter um conjunto de chaves que identifica de forma exclusiva uma linha de dados. Relações de tabelas de origem hierárquicas não são suportadas.

O recurso diff é usado para dividir os dados de origem em três categorias:

• linhas adicionadas
• linhas atualizadas
• linhas excluídas

Na primeira vez que uma operação diff é executada, todas as linhas de origem são classificadas como "adicionadas". A cada execução subsequente, apenas linhas adicionadas, alteradas ou excluídas serão processadas pelo Jitterbit. Isso pode economizar um tempo de processamento significativo em casos onde uma tabela de origem possui numerosos registros que mudam com pouca frequência.

Como será visto nos passos abaixo, uma "operação diff" geralmente consiste em várias operações encadeadas; cada operação sucessiva lida com adições, atualizações e exclusões, respectivamente.

Para configurar uma operação diff, siga estes passos:

1. Inicialize a sessão diff e defina o tipo de algoritmo diff a ser usado. Atualmente, são suportados "chunked" ou "ordered". Chunked sempre funcionará, mas ordered pode ser mais rápido se a ordem das linhas de dados de origem for garantida.
2. Lide com linhas adicionadas, atualizadas e excluídas. A ordem em que são tratadas é arbitrária e depende da ordem das operações que implementam a sincronização.
3. Finalize a sessão diff. Isso sinaliza o processo diff como completo; caso contrário, uma futura operação diff pode resultar em nenhum registro sendo processado.

Passo 1: Inicialize a sessão Diff

Inicialize a sessão diff chamando a função InitializeDiff com um "ID diff" exclusivo seguido pela função DiffKeyList (para um diff em chunked) ou pela função OrderedDiffKeyList (para um diff ordenado) para definir a(s) chave(s) primária(s) da tabela de origem:

InitializeDiff("A-unique-diff-ID-for-each-diff-process");
DiffKeyList("pk1", "pk2");

Passo 2: Lidar com linhas adicionadas, atualizadas e excluídas

Antes de cada transformação, as funções DiffAdd, DiffUpdate e DiffDelete são chamadas. Qualquer transformação executada após essas chamadas de função receberá as linhas adicionadas, atualizadas ou excluídas, respectivamente. A origem das transformações deve ser a mesma tabela de banco de dados ou arquivo CSV, mas o destino pode ser diferente em todos os três casos.

Passo 3: Finalizar a sessão de Diff

A função DiffComplete deve ser chamada quando os três casos tiverem sido tratados com sucesso. (No caso de erros, a função ResetDiff deve ser usada em vez disso.) Isso sinaliza que o processo de diff está completo; caso contrário, uma operação de diff futura pode resultar em nenhum registro sendo processado.

Funções adicionais de Diff

• DiffNode: Para fontes hierárquicas, especifica o nó que deve ser usado como o nó repetido para realizar o diff.
• OrderedDiffKeyList: Especifica a ordem de classificação da fonte quando o algoritmo de diff "ordenado" é utilizado.
• ResetDiff: Redefine ou purga a sessão de diff. Usado no tratamento de erros para redefinir a sessão de diff em caso de falha.
• SetDiffChunkSize: Define um parâmetro para o algoritmo de diff "em partes". Um valor maior é mais rápido, mas usa mais memória.

Exemplos de Diff

Para um exemplo usando diff no Design Studio, veja Capturar alterações de dados com alterações de tabela ou arquivo. Isso pode ser extrapolado para uso no Studio.

DiffAdd

Declaração

void DiffAdd()

Sintaxe

DiffAdd()

Descrição

Solicita os registros adicionados como entrada para a próxima transformação que será executada.

Exemplos

// Comece processando os registros adicionados nesta operação:
DiffAdd();

DiffComplete

Declaração

void DiffComplete()

Sintaxe

DiffComplete()

Descrição

Marca o processo de diff como completo. Este método deve ser chamado quando o processo de diff for concluído com sucesso; caso contrário, o processo de diff ficará em um estado inconsistente. Nesse caso, da próxima vez que a operação de diff for executada, nenhum registro será processado.

Exemplos

// Marca a operação de diff como completa
DiffComplete();

DiffDelete

Declaração

void DiffDelete()

Sintaxe

DiffDelete()

Descrição

Solicita os registros excluídos como entrada para a próxima transformação que será executada.

Exemplos

// Solicitando registros excluídos para a execução da transformação
DiffDelete();

DiffKeyList

Declaração

void DiffKeyList(string k1[, string k2,... string kN])

Sintaxe

DiffKeyList(<k1>[, <k2>,... <kN>])

Parâmetros obrigatórios

• k1, k2,... kN: Chaves de string que identificam as colunas na fonte de diff a serem usadas para identificar exclusivamente cada registro

Descrição

Define a lista de chaves a serem usadas para identificar exclusivamente um registro na fonte de diff. Este método é tipicamente chamado em conjunto com a função InitializeDiff.

Exemplos

// Usando um diff em partes com as chaves primárias de sincronização
// de CustomerId e OrderId:
DiffKeyList("CustomerId", "OrderId");

DiffNode

Declaração

void DiffNode(string nodeName)

Sintaxe

DiffNode(<nodeName>)

Parâmetros obrigatórios

• nodeName: Uma string que especifica o nó repetido a ser usado para a operação de diff

Descrição

Para fontes hierárquicas, isso especifica o nó a ser usado como o nó repetido sobre o qual o diff é realizado.

Exemplos

// Execute o diff no nó do elemento XML <Listing>
DiffNode("Listing");

DiffUpdate

Declaração

void DiffUpdate()

Sintaxe

DiffUpdate()

Descrição

Solicita os registros atualizados como entrada para a próxima transformação que será executada.

Exemplos

// Solicitando registros atualizados para a execução da transformação
DiffUpdate();

InitializeDiff

Declaração

void InitializeDiff(string diffId)

Sintaxe

InitializeDiff(<diffId>)

Parâmetros obrigatórios

• diffId: Uma string que identifica exclusivamente a operação de diff em relação a outras operações de diff em execução no sistema. A string deve ser a mesma para cada execução da operação a fim de identificar o diff corretamente.

Descrição

Inicializa uma nova sessão de diff.

A string passada como diffId deve ser diferente de todos os outros identificadores de diff usados no sistema, mas deve ser a mesma toda vez que a operação for executada. Se uma sessão de diff já estiver em execução, uma chamada a este método falhará. Para limpar uma sessão de diff antiga (como no caso de uma falha do sistema), chame a função ResetDiff uma vez.

Este método é tipicamente chamado no script pré-fonte da primeira operação que implementa um diff/sincronização.

Exemplos

// Synchronize the order database:
InitializeDiff("Order Database Synchronization");

// Using chunked diff with the synchronizing primary keys
// of CustomerId and OrderId:
DiffKeyList("CustomerId", "OrderId");

// With sufficient memory available, increase the chunk size:
SetDiffChunkSize(100000);

// Start by processing the added records in this operation:
DiffAdd();

OrderedDiffKeyList

Declaração

void OrderedDiffKeyList(string k1, bool isAscending1[, string k2, bool isAscending2,... string kN, bool isAscendingN])

Sintaxe

OrderedDiffKeyList(<k1>, <isAscending1>[, <k2>, <isAscending2>,... <kN>, <isAscendingN>])

Parâmetros obrigatórios

• k1, k2,... kN: Nomes das colunas em formato de string que serão usados para identificar de forma única um registro em uma fonte

• isAscending1, isAscending2,... isAscendingN: Valores booleanos para cada coluna indicando se cada coluna está ordenada de forma ascendente (true) ou descendente (false)

• O número de argumentos fornecidos deve ser dois ou mais e deve ser um número par.

Descrição

Define a lista de chaves usadas para identificar de forma única um registro na fonte e especifica a ordem dos registros da chave como ascendente (true) ou descendente (false).

Use este método (em vez da função DiffKeyList) em casos onde os registros da fonte estão garantidos em uma ordem específica.

O processamento de diferenças é mais eficiente se os campos da fonte estiverem ordenados da mesma forma a cada vez. Nesses casos, nenhum tamanho de bloco será utilizado e o uso de memória não será um problema. Este método é tipicamente chamado em conjunto com a função InitializeDiff.

ResetDiff

Declaração

void ResetDiff(string diffId, int action)

Sintaxe

ResetDiff(<diffId>, <action>)

Parâmetros obrigatórios

• diffId: Uma string que identifica de forma única a operação de diferença em relação a outras operações de diferença em execução no sistema
• action: Um inteiro (ou 0 ou 1) que especifica como a sessão de diferença deve ser redefinida

Descrição

Redefine uma sessão de diff existente.

O parâmetro action (que pode ser 0 ou 1) especifica como a sessão de diff deve ser redefinida:

• 0 (Redefinir): Esquece completamente a última captura e começa do início. Isso fará com que o sistema trate todas as entradas como "adicionadas."
• 1 (Purga): Remove quaisquer arquivos restantes de uma sessão de diff anterior. Isso não redefine a última captura; apenas limpa arquivos obsoletos deixados de sessões de diff antigas, falhadas ou canceladas.

Esse método é tipicamente chamado quando algo foi alterado em um processo de diff existente ou se um processo de diff falhou e deixou um estado inconsistente. Não deve ser chamado durante o processamento normal de diff. Se nenhuma sessão de diff estiver presente para este diff_id, nenhuma ação é realizada.

Exemplos

// Purge any files left over from a previous diff session,
// but keep the latest snapshot
ResetDiff("Sincronização do Banco de Dados de Pedidos", 1);

SetDiffChunkSize

Declaração

void SetDiffChunkSize(int chunkSize)

Sintaxe

SetDiffChunkSize(<chunkSize>)

Parâmetros obrigatórios

• chunkSize: Tamanho em bytes para os chunks usados durante o diff

Descrição

Define o tamanho do chunk (em bytes) usado durante o diff.

Um tamanho de chunk maior fará com que o sistema use mais memória, mas processará o diff mais rapidamente. O padrão é 50000 bytes; se você tiver memória suficiente, pode aumentar esse número.

Esse método é tipicamente chamado em conjunto com a função InitializeDiff.

Exemplos

// Com memória suficiente disponível, aumente o tamanho do bloco:
SetDiffChunkSize(100000);