Esta página foi traduzida pela API Cloud Translation.

Apache Kafka

Use o conetor do Kafka para fazer a integração com o Apache Kafka e publicar mensagens em tópicos específicos. O conector do Kafka também suporta a subscrição de eventos, o que permite a criação de acionadores quando são recebidas mensagens num tópico.

Versões suportadas

O conetor do Apache Kafka tira partido das bibliotecas de clientes nativas para estabelecer uma ligação a um determinado cluster do Kafka, e o conetor funciona com a versão 3.3.1 do cliente. No entanto, o conetor pode estabelecer conetividade com clusters do Kafka das versões 3.0 a 3.3.1.

Antes de começar

Antes de usar o conetor do Apache Kafka, faça as seguintes tarefas:

No seu projeto do Google Cloud:
- Certifique-se de que a conetividade de rede está configurada. Para obter informações sobre padrões de rede, consulte o artigo Conetividade de rede.
- Conceda a função IAM roles/connectors.admin ao utilizador que está a configurar o conetor.
- Conceda as seguintes funções de IAM à conta de serviço que quer usar para o conector:
  - roles/secretmanager.viewer
  - roles/secretmanager.secretAccessor
  Uma conta de serviço é um tipo especial de Conta Google destinada a representar um utilizador não humano que precisa de autenticação e autorização para aceder a dados nas APIs Google. Se não tiver uma conta de serviço, tem de criar uma. O conector e a conta de serviço têm de pertencer ao mesmo projeto. Para mais informações, consulte Criar uma conta de serviço.
- Ative os seguintes serviços:
  - secretmanager.googleapis.com (Secret Manager API)
  - connectors.googleapis.com (API Connectors)
  Para saber como ativar serviços, consulte o artigo Ativar serviços.
Se estes serviços ou autorizações não tiverem sido ativados anteriormente para o seu projeto, é-lhe pedido que os ative quando configurar o conector.

Configure o conetor

Uma associação é específica de uma origem de dados. Isto significa que, se tiver muitas origens de dados, tem de criar uma associação separada para cada origem de dados. Para criar uma associação, faça o seguinte:

Na Cloud Console, aceda à página Integration Connectors > Ligações e, de seguida, selecione ou crie um projeto do Google Cloud.
Aceda à página Ligações
Clique em + CRIAR NOVO para abrir a página Criar associação.
No passo Localização, escolha a localização para a nova ligação do Apache Kafka:
1. Região: selecione uma região na lista.
2. Clicar em Seguinte.
No passo Detalhes da ligação, forneça detalhes sobre a nova ligação do Apache Kafka:
1. Versão do conetor: escolha uma versão disponível do conetor do Apache Kafka na lista.
2. Nome da associação: introduza um nome para a associação do Apache Kafka.
  Nota: os nomes das associações têm de cumprir os seguintes critérios:
  - Os nomes das associações podem usar letras, números ou hífenes.
  - As letras têm de ser minúsculas.
  - Os nomes das associações têm de começar com uma letra e terminar com uma letra ou um número.
  - Os nomes das associações não podem exceder 49 carateres.
  - Para os conetores que suportam a subscrição de eventos, os nomes das associações não podem começar com o prefixo "goog".
3. (Opcional) Descrição: introduza uma descrição para a associação.
4. (Opcional) Ativar registo na nuvem: selecione esta caixa de verificação para armazenar todos os dados de registo da ligação.
5. Conta de serviço: selecione uma conta de serviço com as funções do IAM necessárias para a ligação do Apache Kafka.
6. A opção Ativar subscrição de eventos, entidades e ações está selecionada por predefinição para a ligação do Apache Kafka.
  Nota: este conector não suporta a opção Enable only event subscription.
7. Esquema de deteção de tipo: selecione MessageOnly.
8. Serviço de registo: o serviço de registo de esquemas usado para trabalhar com esquemas de tópicos.
9. Tipo de registo: tipo do esquema especificado para um tópico específico.
10. Versão do registo: versão do esquema lido a partir de RegistryUrl para o tópico especificado.
11. Utilizador do registo: nome de utilizador ou valor da chave de acesso para autorizar junto do servidor especificado em RegistryUrl.
12. Palavra-passe do registo: o segredo do Secret Manager que contém o valor da chave da palavra-passe/segredo para autorizar com o servidor especificado em RegistryUrl.
13. Opcionalmente, configure as definições do nó de associação:
  - Número mínimo de nós: introduza o número mínimo de nós de ligação.
  - Número máximo de nós: introduza o número máximo de nós de ligação.
  Um nó é uma unidade (ou uma réplica) de uma ligação que processa transações. São necessários mais nós para processar mais transações para uma ligação e, inversamente, são necessários menos nós para processar menos transações. Para compreender como os nós afetam os preços dos conectores, consulte o artigo Preços dos nós de ligação. Se não introduzir valores, por predefinição, os nós mínimos são definidos como 2 (para uma melhor disponibilidade) e os nós máximos são definidos como 50.
14. Opcionalmente, clique em + ADICIONAR ETIQUETA para adicionar uma etiqueta à associação sob a forma de um par de chave e valor.
15. Ativar SSL: este campo define se o SSL está ativado.
16. Clicar em Seguinte.
Na secção Destinos, introduza os detalhes do servidor de arranque do Kafka ao qual quer estabelecer ligação.
1. Tipo de destino: selecione um Tipo de destino.
  - Para especificar o nome de anfitrião ou o endereço IP de destino, selecione Endereço do anfitrião e introduza o endereço no campo Anfitrião 1.
  - Para estabelecer uma ligação privada, selecione Anexo do ponto final e escolha o anexo necessário na lista Anexo do ponto final.
    Nota: para saber como criar uma associação de ponto final, consulte Associação de serviço do PSC e Associação de ponto final. Depois de criar a associação do ponto final, esta fica visível na lista Associação do ponto final.
  Se quiser estabelecer uma ligação pública aos seus sistemas de back-end com segurança adicional, pode considerar configurar endereços IP estáticos de saída para as suas ligações e, em seguida, configurar as regras da firewall para permitir apenas os endereços IP estáticos específicos.
  
  Para especificar servidores de arranque do Kafka adicionais, clique em + ADICIONAR DESTINO.
2. Clicar em Seguinte.
Na secção Autenticação, introduza os detalhes de autenticação.
1. Selecione um Tipo de autenticação e introduza os detalhes relevantes.
  Os seguintes tipos de autenticação são suportados pela ligação do Apache Kafka:
  - Nome de utilizador e palavra-passe
    - Nome de utilizador: o nome de utilizador do Apache Kafka a usar para a ligação.
    - Palavra-passe: o segredo do Secret Manager que contém a palavra-passe associada ao nome de utilizador do Apache Kafka.
    - Esquema de autenticação: o esquema usado para autenticação.
      Os seguintes esquemas de autorização são suportados pela ligação do Apache Kafka:
      - Simples
      - SCRAM-SHA-1
      - SCRAM-SHA-256
  - Não disponível
    Se quiser usar o início de sessão anónimo, selecione Não disponível.
2. Clicar em Seguinte.
Introduza a configuração de mensagens não entregues. Se configurar a fila de mensagens rejeitadas, a ligação escreve os eventos não processados no tópico Pub/Sub especificado. Introduza os seguintes detalhes:
1. ID do projeto de mensagens não entregues: o ID do projeto do Google Cloud onde configurou o tópico Pub/Sub de mensagens não entregues.
2. Tópico de mensagens não entregues: o tópico do Pub/Sub onde quer escrever os detalhes do evento não processado.
Clicar em Seguinte.
Rever: reveja os detalhes da ligação e da autenticação.
Clique em Criar.

Limitações do sistema

O conetor do Apache Kafka pode processar um máximo de 50 transações por segundo, por nó, e limita todas as transações que excedam este limite. Por predefinição, os Integration Connectors atribuem 2 nós (para uma melhor disponibilidade) a uma ligação.

Para informações sobre os limites aplicáveis aos Integration Connectors, consulte Limites.

Nota: o número de nós de conectores de integração é dimensionado automaticamente de forma dinâmica com base na sua utilização. No entanto, se quiser reservar capacidade para grandes volumes sem esperar pela escalabilidade automática, pode ajustar o valor mínimo de nós para uma ligação. São necessários mais nós para processar mais transações para uma associação. Por outro lado, são necessários menos nós se uma associação processar menos transações. Para configurar os valores dos nós, faça o seguinte:

Se for cliente de pagamento conforme o uso, configure o valor mínimo e máximo do nó na página de edição da associação.
Se for cliente com base numa subscrição, contacte o apoio técnico.

O número máximo de transações que um nó pode processar depende de vários fatores. Assim, antes de ajustar os nós mínimos para um melhor débito, é recomendável verificar se os seus sistemas de back-end estão configurados de forma ideal para processar o tráfego necessário.

Ações

Ação PublishMessage

Esta ação publica uma mensagem num tópico do Apache Kafka. As tabelas seguintes descrevem os parâmetros de entrada e saída da ação PublishMessage.

Parâmetros de entrada

Nome do parâmetro	Obrigatória	Tipo de dados	Descrição
Tópico	Sim	String	Nome do tópico para o qual quer publicar a mensagem.
Partição	Não	String	A partição à qual a mensagem está atribuída. O valor tem de ser válido para o tópico indicado. Se não definir este valor, o mesmo é definido automaticamente pelo cliente nativo.
Chave	Não	String	A chave da mensagem.
Mensagem	Sim	String	A mensagem que quer publicar. A mensagem deve ser um JSON em forma de string e o tamanho máximo da mensagem suportado é de 10 MB.
HasBytes	Não	Booleano	Especifica se a mensagem está em formato binário.
MessageBytes	Não	String	A mensagem no formato de uma string codificada em Base64.
Validar	Não	Booleano	Especifica se a mensagem a publicar tem de ser validada de acordo com o esquema de mensagens definido no registo de esquemas para o tópico. Se especificou o registo de esquemas quando criou uma associação, a definição do esquema do tópico do registo é usada para fins de validação. O valor predefinido para este campo é `false`.

Parâmetros de saída

Nome do parâmetro	Tipo de dados	Descrição
PartitionWritten	Número inteiro	A partição na qual a mensagem foi escrita.
OffsetWritten	Longo	A posição na partição na qual a mensagem foi escrita.
TimestampWritten	Longo	A hora (data/hora Unix) em que a mensagem foi confirmada na partição.
KeyWritten	String	O valor da chave da mensagem que foi escrita. O valor é NULL se não tiver sido fornecida nenhuma chave de mensagem ao escrever a mensagem.
Concluído	Booleano	Especifica se a mensagem foi publicada.

Nota: os resultados de todas as operações de entidades e ações vão estar disponíveis como uma resposta JSON no parâmetro de resposta connectorOutputPayload da tarefa de conectores depois de executar a integração.

Segue-se um exemplo de resposta da ação PublishMessage:

{Success: true,
PartitionWritten: 1,
OffsetWritten: 22301,
KeyWritten: "dGVzdA==",
TimestampWritten: 1690806748}

Configuração do Confluent Cloud

A configuração do Confluent Cloud difere ligeiramente dos passos documentados anteriormente para o Apache Kafka. Considere os seguintes pontos ao criar uma ligação para o Confluent Cloud:

A chave da API do cluster do Confluent Cloud é usada como o nome de utilizador e o segredo do Secret Manager da chave é usado como a palavra-passe para estabelecer ligação aos servidores de arranque. Tem de criar uma chave da API no Confluent Cloud se ainda não a tiver.
Selecione Usar SSL na secção Connection Details.

Se estiver a usar o registo de esquemas, configure os seguintes valores:

Na secção Connection Details:
- Versão do registo: introduza o número da versão do registo. Se quiser usar a versão mais recente, introduza latest.
- Utilizador do registo: introduza a chave da API do registo de esquemas. Tem de criar uma chave da API do registo de esquemas se ainda não a tiver.
- Palavra-passe do registo: introduza o segredo do Secret Manager da palavra-passe do registo.
- Versão do Secret: selecione o número da versão do Secret.
- Tipo de base de dados de registo: selecione Confluent.
- Esquema de deteção de tipo: selecione MessageOnly
Na secção Destinations, introduza o URL do registo no campo do nome do anfitrião.

Crie ligações com o Terraform

Pode usar o recurso do Terraform para criar uma nova associação.

Para saber como aplicar ou remover uma configuração do Terraform, consulte os comandos básicos do Terraform.

Para ver um modelo do Terraform de exemplo para a criação de ligações, consulte o modelo de exemplo.

Quando criar esta associação através do Terraform, tem de definir as seguintes variáveis no ficheiro de configuração do Terraform:

Nome do parâmetro	Tipo de dados	Obrigatória	Descrição
type_detection_scheme	ENUM	True	O esquema usado para a autenticação com o agente do Apache Kafka. Os valores suportados são: MessageOnly
registry_service	ENUM	Falso	O serviço de registo de esquemas usado para trabalhar com esquemas de tópicos. Os valores suportados são: Confluent
registry_type	ENUM	Falso	Tipo do esquema especificado para um tópico específico. Os valores suportados são: AVRO, JSON
registry_version	STRING	Falso	Versão do esquema lido a partir de RegistryUrl para o tópico especificado. Os valores válidos para a versão do registo estão entre [1,2^31-1] ou a string "latest", que devolve o esquema registado mais recente.
registry_user	STRING	Falso	Nome de utilizador para autorizar com o servidor especificado em RegistryUrl .
registry_password	SECRET	Falso	Secret do Secret Manager que contém o valor da chave secreta/palavra-passe para autorizar junto do servidor especificado em RegistryUrl.
usessl	BOOLEAN	Falso	Este campo define se a tecnologia SSL está ativada.

Use a ligação do Apache Kafka numa integração

Depois de criar a ligação, esta fica disponível no Apigee Integration e no Application Integration. Pode usar a ligação numa integração através da tarefa Conectores.

Para compreender como criar e usar a tarefa Connectors no Apigee Integration, consulte o artigo Tarefa Connectors.
Para compreender como criar e usar a tarefa Connectors na integração de aplicações, consulte o artigo Tarefa Connectors.

Obtenha ajuda da comunidade do Google Cloud

Pode publicar as suas perguntas e discutir este conector na comunidade do Google Cloud nos Fóruns do Cloud.

O que se segue?

Compreenda como suspender e retomar uma associação.
Compreenda como monitorizar a utilização do conector.
Compreenda como ver os registos do conetor.