Escolha fontes de esquema

Introdução

Ao criar transformações, é necessário decidir como definir seus esquemas de origem e destino. Esta página explica suas opções.

Você pode definir esquemas de duas maneiras:

Esquemas definidos por atividade: Esquemas que as atividades do conector geram automaticamente.
Esquemas definidos por transformação: Esquemas personalizados que você cria dentro da transformação.

Entender quando usar cada abordagem ajuda a construir transformações que são mais fáceis de manter e mais flexíveis. Para prática prática com esses conceitos, veja o Crie sua primeira transformação.

Esquemas definidos por atividade

Esquemas definidos por atividade são criados automaticamente pelas atividades do conector. Essas atividades incluem consultas a bancos de dados, chamadas de API ou operações de arquivos. Esses esquemas herdam sua estrutura do sistema conectado.

Esquemas definidos por atividade são benéficos para os seguintes cenários:

Seus conectores suportam geração automática. Exemplos incluem atividades de banco de dados, Salesforce, NetSuite e ServiceNow.
Você deseja atualizações automáticas e manutenção reduzida. Mudanças no sistema de origem atualizam as transformações automaticamente e mantêm os endpoints sincronizados.
Você está trabalhando com formatos de dados padrão e estabelecidos. Isso inclui esquemas de banco de dados, especificações de API e aplicações empresariais.

Esquemas definidos por atividade seguem este processo:

Configure sua atividade: Configure conexões de banco de dados, endpoints de API ou locais de arquivos.
Geração de esquema: A atividade gera automaticamente esquemas de solicitação, esquemas de resposta ou ambos.
Herdabilidade de esquema: Transformações adjacentes herdam esses esquemas automaticamente.
Precedência: Esquemas de atividade têm prioridade sobre esquemas definidos por transformação.

Exemplo

Uma atividade de consulta a banco de dados gera automaticamente um esquema de resposta com base nos resultados da sua consulta SQL. Quando você adiciona uma transformação após esta atividade, ela herda este esquema como sua fonte.

Tipos de esquema de atividade

As atividades geram esquemas de duas maneiras:

Esquemas gerados por conectores: Gerados diretamente a partir dos metadados do endpoint e atualizados automaticamente quando você atualiza a atividade. Exemplos incluem estruturas de tabelas de banco de dados e formatos de resposta de API.
Esquemas definidos pelo usuário em atividades: Esquemas personalizados que você faz o upload durante a configuração da atividade e permanecem fixos, a menos que você os atualize manualmente. Exemplos incluem arquivos JSON de amostra para atividades HTTP ou modelos CSV para atividades de arquivo.

Esquemas definidos por transformação

Esquemas definidos por transformação são esquemas personalizados que você cria dentro da própria transformação. Você tem controle total sobre sua estrutura e conteúdo.

Esquemas definidos por transformação são benéficos para os seguintes cenários:

Você precisa de estruturas especializadas que não são fornecidas por conectores padrão. Exemplos incluem formatos de saída personalizados, combinação de várias fontes de dados e aplicações especializadas.
Seus endpoints não fornecem esquemas automáticos. Isso inclui sistemas legados, APIs personalizadas sem especificações e formatos de arquivo manuais.
Você deseja esquemas que não mudem com atualizações externas. Use essa abordagem para formatos padronizados, integrações compartilhadas e quando precisar de controle direto sobre a estrutura.

Você pode criar esquemas de transformação usando estes métodos:

Tipo de esquema	Descrição	Melhor para
[Personalizado plano]	Estruturas de nível único, como arquivos CSV.	Dados tabulares e mapeamento simples.
[Personalizado hierárquico]	Estruturas complexas e aninhadas, como XML ou JSON.	Múltiplos níveis, relacionamentos e organizações de dados complexas.
[Arquivo de amostra]	Gere esquemas a partir de arquivos de dados existentes (CSV, JSON, XML, XSD).	Detectando automaticamente a estrutura e os tipos de dados a partir de exemplos.
[Espelhado]	Copie a estrutura do outro lado da sua transformação.	Quando a origem e o destino têm formatos semelhantes que precisam de personalização.

Nota

Considere estas regras de precedência ao construir suas operações:

Esquemas de atividades adjacentes substituem esquemas de transformação.
Mesmo que você mova uma atividade, seu esquema permanece herdado.
Esquemas de transformação são usados por padrão apenas quando nenhum esquema de atividade está disponível.

Exemplo de cenário

Nesta operação, a precedência de esquemas funciona da seguinte forma:

herança de transformação

Esquema de origem: Herdado da atividade de Consulta de Banco de Dados (definido pela atividade).
Esquema de destino: Herdado da atividade HTTP v2 POST (se o esquema for fornecido) ou definido pela transformação. Se você remover a atividade HTTP v2 POST, a transformação mantém o esquema de destino como um esquema definido pela transformação.

Atualizar esquemas a partir de endpoints

Quando sistemas externos mudam, você deve regenerar esquemas para usar essas mudanças em seu projeto. Isso pode ser necessário quando você:

Adiciona campos personalizados a um sistema.
Atualiza para uma nova versão da API.
Modifica estruturas de tabelas de banco de dados.

Atualizar esquemas gerados por conectores

Esquemas gerados por conectores obtêm sua estrutura da API do endpoint. Quando o endpoint muda, você deve atualizar o esquema no Integration Studio.

Para todos os conectores, exceto [Banco de Dados], NetSuite, Salesforce, Salesforce Service Cloud e ServiceMax, você pode regenerar o esquema de dois locais:

Configuração da atividade: Abra a atividade e navegue até a etapa Esquema de Dados e clique em Atualizar.
Transformação: Passe o mouse sobre a estrutura de origem ou destino e clique em Atualizar esquema.

O esquema é atualizado a partir do endpoint e é atualizado em todos os locais onde é referenciado.

Conectores de Banco de Dados, NetSuite e certos conectores Salesforce

Os conectores Database, NetSuite, Salesforce, Salesforce Service Cloud e ServiceMax requerem reconfiguração para atualizar esquemas:

Abra a configuração da atividade.
Avance por cada etapa de configuração.
Faça pelo menos uma alteração, como adicionar ou remover um caractere do nome da atividade.
Complete a configuração.

O esquema é atualizado quando você completa as etapas de configuração.

Nota

Quando você atualiza um esquema, todas as instâncias desse esquema em todo o seu projeto são atualizadas. Isso inclui todas as transformações e atividades que referenciam o esquema.

Atualizar esquemas definidos por transformação

Mudanças em esquemas definidos pelo usuário se propagam automaticamente para todas as referências. Quando você edita um esquema usado em vários lugares, um diálogo mostra os componentes afetados:

Texto do diálogo

Esquema usado por múltiplos componentes
Este esquema é usado por múltiplos componentes. Quaisquer alterações feitas nele podem afetar a validade desses componentes: - Componente 1 - Componente 2

Para evitar que as alterações afetem outros componentes, primeiro remova ou substitua a referência do esquema nesses componentes.

Lidar com mudanças de esquema em operações

Se o esquema de um endpoint mudar, mas você não o regenerou no Integration Studio, suas operações podem falhar. O impacto depende de:

Quais campos mudaram.
Se os campos alterados estão mapeados.
Se os campos alterados são obrigatórios.

Por exemplo:

Campo obrigatório removido: As operações falham com erros do endpoint.
Campo opcional removido: As operações podem ter sucesso se o campo não estiver mapeado.
Campo obrigatório adicionado: As operações falham se o campo não estiver mapeado.
Campo opcional adicionado: As operações têm sucesso, mas o novo campo é ignorado.

Dica

Regere os esquemas sempre que você modificar sistemas de endpoint para evitar erros em tempo de execução.

Migração de projeto legado

Projetos criados antes da versão 10.33.2 do Harmony renomeiam automaticamente esquemas definidos pelo usuário usando este padrão:

<Nome do Esquema Original>_<Nome da Transformação>_<Fonte ou Destino>

Por exemplo, CustomerData se torna CustomerData_TransformCustomers_Source.

Essa nomenclatura garante a identificação única do esquema em todas as transformações.