Skip to main content
O ClickPipes oferece suporte à integração com um registro de esquemas para decodificar valores de registros codificados em Avro e em Protobuf e chaves estruturadas do Kafka.

​
Registros compatíveis com ClickPipes do Kafka

Os ClickPipes do Kafka são compatíveis com duas famílias de registros de esquema:
  • Registros compatíveis com Confluent: qualquer registro compatível com a API do Confluent Schema Registry, como o próprio Confluent Schema Registry e o Redpanda Schema Registry. Compatível com Avro e Protobuf.
  • AWS Glue Schema Registry: para dados Avro serializados com o AWS Glue SerDe, normalmente provenientes do Amazon MSK.
Os ClickPipes ainda não são compatíveis com o Azure Schema Registry. Se precisar de suporte para ele, entre em contato com nossa equipe.

​
Registros compatíveis com o Confluent

​
Configuração

Para integrar um registro de esquema durante a configuração do ClickPipes, você deve usar uma das seguintes abordagens:
  1. Forneça o caminho completo para o subject do esquema (por exemplo, https://registry.example.com/subjects/events)
    • Opcionalmente, é possível referenciar uma versão específica acrescentando /versions/[version] à URL (caso contrário, o ClickPipes recuperará a versão mais recente).
  2. Forneça o caminho completo para o ID do esquema (por exemplo, https://registry.example.com/schemas/ids/1000)
  3. Forneça a URL raiz do registro de esquema (por exemplo, https://registry.example.com)

​
Conectividade de rede

O ClickPipes se conecta ao registro de esquemas via HTTPS na URL que você fornecer. O registro de esquemas não precisa ser acessível publicamente. Se os brokers do Kafka forem acessados por meio de um endpoint privado reverso (AWS PrivateLink ou GCP Private Service Connect), o registro de esquemas poderá usar a mesma conectividade privada. O ClickPipes resolve o hostname do registro por meio do DNS privado do endpoint privado reverso, portanto, um registro hospedado de forma privada junto com seus brokers poderá ser acessado, desde que seu hostname seja resolvido para os endereços IP privados do endpoint privado reverso (por meio do suporte a DNS privado do endpoint ou de um mapeamento personalizado de DNS privado). Tenha em mente o seguinte:
  • A URL do registro de esquemas deve usar https://.
  • Se o hostname do registro for resolvido para um endereço privado, ele deverá estar acessível por meio de um endpoint privado reverso selecionado para o ClickPipe; caso contrário, a verificação de conectividade durante o Setup falhará.

​
Como funciona

O ClickPipes recupera e aplica dinamicamente o esquema do registro de esquema configurado.
  • Se houver um ID de esquema incorporado ao valor do registro, ele será usado para recuperar o esquema.
  • Se não houver um ID de esquema incorporado ao valor do registro, será usado o ID de esquema ou o nome do subject especificado na configuração do ClickPipe para recuperar o esquema.
  • Se o valor do registro for gravado sem um ID de esquema incorporado e nenhum ID de esquema ou nome do subject for especificado na configuração do ClickPipe, o esquema não será recuperado e a mensagem será ignorada, com um SOURCE_SCHEMA_ERROR registrado na tabela de erros do ClickPipes.
  • Se o valor do registro não estiver em conformidade com o esquema, a mensagem será ignorada, com um DATA_PARSING_ERROR registrado na tabela de erros do ClickPipes.
  • Apenas para esquemas Protobuf: o ClickPipes carregará todos os esquemas importados definidos como dependências. Esquemas Avro com referências externas ainda não são compatíveis.
Quando mapeamentos para campos como _key.id são configurados, o ClickPipes resolve o ID de esquema incorporado à chave do Kafka independentemente do valor do registro. A chave pode usar um ID de esquema diferente, mas deve usar a mesma família de registro e o mesmo formato de serialização que o valor. Os esquemas de chave resolvidos são armazenados em cache, e as alterações de esquema são detectadas automaticamente.

​
AWS Glue Schema Registry

Se os seus produtores serializam Avro com o AWS Glue SerDe (por exemplo, AWSKafkaAvroSerializer para um tópico do Amazon MSK), o ClickPipes pode resolver esses esquemas diretamente no AWS Glue Schema Registry. O Glue usa um formato wire e uma API diferentes dos registries compatíveis com Confluent; por isso, é configurado separadamente. No momento, a configuração do AWS Glue Schema Registry está disponível apenas no ClickHouse Cloud console. Ela não é compatível com a API do ClickPipes nem com o Terraform provider.
Somente Avro. Os registries do AWS Glue são compatíveis apenas com o formato Avro. O Glue SerDe também pode encapsular JSON e Protobuf, mas eles não são compatíveis com o ClickPipes e são rejeitados quando o pipe é criado.

​
Configuração

No assistente de criação de ClickPipe, habilite o Registro de esquemas na etapa de conexão do Kafka e defina o Tipo de registro como AWS Glue: Não há URL de registro para configurar. Cada registro produzido pelo Glue SerDe contém o ID da própria versão de esquema, que o ClickPipes resolve usando glue:GetSchemaVersion e armazena em cache, com uma chamada de API por versão de esquema distinta. A evolução de esquema é tratada automaticamente: quando os registros passam a usar uma nova versão de esquema no meio do fluxo, ela é resolvida na primeira ocorrência.

​
Configuração do IAM

Use a das duas opções que melhor se adequar à sua configuração. A opção A é a mais comum para o Amazon MSK.

​
Opção A: reutilizar a identidade IAM do broker

Se o ClickPipe do Kafka já se autentica no MSK usando IAM, o ClickPipes usa a mesma identidade IAM para ler o registro. Deixe o campo ARN da função IAM em branco e adicione a seguinte instrução às permissões da identidade:
  • Função IAM: adicione a instrução à política de permissões da função configurada para o MSK.
  • Credenciais IAM: adicione a instrução à política de permissões do principal IAM associado à chave de acesso.
Para a autenticação baseada em funções, não é necessário alterar a política de confiança; a relação de confiança configurada para o MSK já abrange esse acesso. As credenciais do IAM não usam uma política de confiança de função.

​
Opção B: usar uma função dedicada para o registro

Use esta opção quando o broker não autenticar com IAM (SASL/SCRAM, SASL/PLAIN, mTLS) ou quando o registro estiver em uma conta da AWS diferente da conta do broker.
Somente para implantações na AWS. Esta opção requer um serviço do ClickHouse Cloud implantado na AWS, pois depende da função do AWS IAM do serviço. Se o serviço for executado no GCP ou no Azure e o broker não usar autenticação IAM, não será possível configurar uma função dedicada para o registro.
1

Obter o ARN da função IAM do serviço ClickHouse

Abra o serviço, selecione a aba Settings, role até a seção Network security information e copie o valor de Service role ID (IAM), um ARN no formato arn:aws:iam::123456789012:role/CH-S3-example-service-Role. Esse valor é referido abaixo como {ClickHouse_IAM_ARN}. Cada serviço ClickHouse implantado na AWS tem sua própria função; portanto, esse valor é diferente para cada serviço.
2

Criar a função IAM do registro

Crie uma função IAM na sua conta da AWS. O nome da função deve começar com ClickHouseAccessRole-.Configurar a política de confiançaSubstitua {ClickHouse_IAM_ARN} pelo valor da etapa anterior.
Configurar a política de permissões
3

Configurar o ClickPipe

Cole o ARN da nova função no campo ARN da função IAM do assistente.
Escopo dos recursos do IAM. Estes exemplos seguem a política da AWS documentada para desserializadores e a política gerenciada AWSGlueSchemaRegistryReadonlyAccess, ambas concedendo glue:GetSchemaVersion em "*". O ClickPipes verifica de forma independente cada esquema resolvido em relação ao Nome do registro configurado e rejeita versões de qualquer outro registro.

​
Solução de problemas

​
Limitações

  • Somente Avro. JSON Schema e Protobuf via Glue SerDe não são compatíveis.
  • Somente fontes Kafka. ClickPipes do Kinesis não podem usar um registro do Glue.

​
Mapeamento de esquema

As regras a seguir se aplicam tanto a registros compatíveis com Confluent quanto ao AWS Glue Schema Registry. Elas regem o mapeamento entre o esquema de valor recuperado e a tabela de destino do ClickHouse, e também se aplicam a campos de registro ou mensagem mapeados de chaves estruturadas com o prefixo _key.:
  • Se o esquema contiver um campo que não esteja incluído no mapeamento de destino do ClickHouse, esse campo será ignorado.
  • Se no esquema faltar um campo definido no mapeamento de destino do ClickHouse, a coluna do ClickHouse será preenchida com um valor “zero”, como 0 ou uma string vazia. Observe que expressões DEFAULT não têm suporte.
  • Se o campo do esquema e a coluna do ClickHouse forem incompatíveis, a inserção dessa linha/mensagem falhará, e a falha será registrada na tabela de erro do ClickPipes. Observe que há suporte para várias conversões implícitas (por exemplo, entre tipos numéricos), mas não para todas (por exemplo, um campo de registro Avro não pode ser inserido em uma coluna Int32 do ClickHouse).
Última modificação em 18 de agosto de 2026