Dela via

Kafka Connect för Azure Cosmos DB

GÄLLER FÖR: NoSQL

Kafka Connect är ett verktyg för skalbara och tillförlitligt strömmande data mellan Apache Kafka och andra system. Med Kafka Connect kan du definiera anslutningsappar som flyttar stora datamängder till och från Kafka. Kafka Anslut för Azure Cosmos DB är en anslutningsapp för att läsa från och skriva data till Azure Cosmos DB.

Semantik för käll- och mottagaranslutningar

  • Källanslutning – För närvarande stöder den här anslutningen minst en gång med flera uppgifter och exakt en gång för enskilt uppdrag.

  • Sänkkontakt – Denna kontakt har fullt stöd för exakt-en-gång-semantik.

Dataformat som stöds

Kontakterna för source och sink kan konfigureras att stödja följande dataformat:

Format beskrivning
Oformaterad JSON JSON-poststruktur utan något kopplat schema.
JSON med schema JSON-poststruktur med explicit schemainformation för att säkerställa att data matchar det förväntade formatet.
AVRO Ett radorienterat fjärrproceduranrop och data serialiseringsramverk som utvecklats i Apaches Hadoop-projekt. Den använder JSON för att definiera datatyper, protokoll och serialiserar data i ett kompakt binärt format.

Nyckel- och värdeinställningarna, inklusive format och serialisering, kan konfigureras separat i Kafka. Därför är det möjligt att arbeta med olika dataformat för nycklar respektive värden. För att hantera olika dataformat finns det konverterarkonfiguration för både key.converter och value.converter.

Konfigurationsexempel för konverterare

Oformaterad JSON

Om du behöver använda JSON utan schemaregister för att ansluta data använder du det JsonConverter som stöds med Kafka. I följande exempel visas nyckel JsonConverter - och värdeegenskaperna som läggs till i konfigurationen:

key.converter=org.apache.kafka.connect.json.JsonConverter
key.converter.schemas.enable=false
value.converter=org.apache.kafka.connect.json.JsonConverter
value.converter.schemas.enable=false

JSON med schema

Ange egenskaperna key.converter.schemas.enable och value.converter.schemas.enable till true så att nyckeln eller värdet behandlas som ett sammansatt JSON-objekt som innehåller både ett internt schema och data. Utan dessa egenskaper behandlas nyckeln eller värdet som oformaterad JSON.

key.converter=org.apache.kafka.connect.json.JsonConverter
key.converter.schemas.enable=true
value.converter=org.apache.kafka.connect.json.JsonConverter
value.converter.schemas.enable=true

Det resulterande meddelandet till Kafka skulle se ut som exemplet nedan, med schema och nyttolast som element på den översta nivån i JSON:

{
  "schema": {
    "type": "struct",
    "fields": [
      {
        "type": "int32",
        "optional": false,
        "field": "userid"
      },
      {
        "type": "string",
        "optional": false,
        "field": "name"
      }
    ],
    "optional": false,
    "name": "ksql.users"
  },
  "payload": {
    "userid": 123,
    "name": "user's name"
  }
}

Anteckning

Meddelandet som skrivits till Azure Cosmos DB består av schemat och nyttolasten. Observera meddelandets storlek samt den andel av meddelandet som består av nyttolasten jämfört med schemat. Schemat upprepas i varje meddelande som du skriver till Kafka. I sådana här scenarier kanske du vill använda ett serialiseringsformat som JSON-schema eller AVRO, där schemat lagras separat, och meddelandet innehåller bara nyttolasten.

AVRO

Kafka Connector stöder AVRO-dataformat. Om du vill använda AVRO-format konfigurerar du ett AvroConverter så att Kafka Connect vet hur man arbetar med AVRO-data. Azure Cosmos DB Kafka Connect har testats med AvroConverter som tillhandahålls av Confluent under Apache 2.0-licens. Du kan också använda en annan anpassad konverterare om du vill.

Kafka hanterar nycklar och värden oberoende av varandra. Ange egenskaperna key.converter och value.converter enligt vad som krävs i arbetskonfigurationen. När du använder AvroConverterlägger du till en extra konverteraregenskap som tillhandahåller URL:en för schemaregistret. I följande exempel visas nyckel- och värdeegenskaperna för AvroConverter som läggs till i konfigurationen:

key.converter=io.confluent.connect.avro.AvroConverter
key.converter.schema.registry.url=http://schema-registry:8081
value.converter=io.confluent.connect.avro.AvroConverter
value.converter.schema.registry.url=http://schema-registry:8081

Välj ett konverteringsformat

Följande är några saker att tänka på när du väljer ett konverteringsformat:

  • När du konfigurerar en källanslutning:

    • Om du vill att Kafka Connect ska inkludera oformaterad JSON i meddelandet som den skriver till Kafka anger du Plain JSON-konfiguration .

    • Om du vill att Kafka Connect ska inkludera schemat i meddelandet som det skriver till Kafka anger du JSON med Schemakonfiguration .

    • Om du vill att Kafka Connect ska inkludera AVRO-format i meddelandet som skrivs till Kafka anger du AVRO-konfiguration .

  • Om du använder JSON-data från ett Kafka-ämne i en Sink connector, är det viktigt att förstå hur JSON serialiserades när de skrevs till Kafka-ämnet:

    • Om den har skrivits med JSON-serialiseraren anger du Kafka Connect för att använda JSON-konverteraren (org.apache.kafka.connect.json.JsonConverter).

      • Om JSON-data har skrivits som en vanlig sträng kontrollerar du om data innehåller ett kapslat schema eller nyttolast. Om så är fallet, ställ in JSON med schemakonfiguration.
      • Men om du använder JSON-data och den inte har schema- eller nyttolastkonstruktionen måste du be Kafka Connect att inte söka efter ett schema genom att ange schemas.enable=false enligt Vanlig JSON-konfiguration .

    • Om den skrevs med AVRO-serialiseraren anger du Kafka Connect så att AVRO-konverteraren (io.confluent.connect.avro.AvroConverter) används enligt AVRO-konfigurationen .

Konfiguration

Vanliga konfigurationsegenskaper

Kopplingarna för källa och mottagare har följande gemensamma konfigurationsinställningar:

Namn Typ beskrivning Obligatoriskt/valfritt
connect.cosmos.connection.endpoint URI Azure Cosmos DB-slutpunkts-URI-sträng Obligatoriskt
connect.cosmos.master.key sträng Den primära Azure Cosmos DB-nyckel som mottagaren ansluter till. Obligatoriskt
connect.cosmos.databasename sträng Namnet på Den Azure Cosmos DB-databas som mottagaren skriver till. Obligatoriskt
connect.cosmos.containers.topicmap sträng Mappning mellan Kafka-ämnen och Azure Cosmos DB-containrar. Den formateras med CSV som topic#container,topic2#container2 Obligatoriskt
connect.cosmos.connection.gateway.enabled booleskt Indikera om gatewayläge ska användas med en flagga. Som standard är det falskt. Valfritt

Information om anslutningsspecifik konfiguration för mottagare finns i dokumentationen för anslutningsappen för mottagare

Information om konfiguration som är specifik för källanslutningsappen finns i dokumentationen för källanslutningsappen

Vanliga konfigurationsfel

Om du felkonfigurerar konverterarna i Kafka Connect kan det leda till fel. De här felen visas i Kafka Connector-mottagaren eftersom du försöker deserialisera de meddelanden som redan lagras i Kafka. Konverterarproblem uppstår vanligtvis inte i källan eftersom serialisering anges vid källan.

Mer information finns i dokumentet vanliga konfigurationsfel .

Projektinställningar

Se utvecklaregenomgång och projektgenomgång för inledande installationsinstruktioner.

Prestandatest

Mer information om prestandatesterna som körs för mottagar- och källanslutningarna finns i dokumentet prestandatestning.

Referera till prestandamiljöns inställning för exakta steg för att implementera prestandatestmiljön för kontakterna.

Resurser

Nästa steg

  • Kafka Connect för Azure Cosmos DB-källanslutning
  • Kafka Connect för Azure Cosmos DB-sink-koppling
  • Last updated on