L'importazione di flussi di dati ad alto volume da Apache Kafka in BigQuery spesso richiede la scrittura e la manutenzione di pipeline personalizzate per gestire la serializzazione dei messaggi, la gestione delle connessioni e gli errori di elaborazione. Per eliminare questo lavoro manuale, puoi utilizzare il template Apache Kafka to BigQuery. Questa pipeline di streaming importa i messaggi JSON e Avro dagli argomenti Kafka e scrive i record direttamente nelle tabelle BigQuery.
La pipeline supporta Google Cloud Managed Service per Apache Kafka, nonché cluster autogestiti o esterni. Per evitare interruzioni della pipeline e proteggerti dalla perdita di dati quando l'elaborazione dei record non va a buon fine, puoi anche indirizzare gli errori di trasformazione e inserimento a una tabella BigQuery facoltativa per i messaggi non recapitabili.
Requisiti della pipeline
- Il server broker Apache Kafka deve essere in esecuzione e raggiungibile dalle macchine worker Dataflow.
- Gli argomenti Apache Kafka devono esistere.
- Devi abilitare le API Dataflow, BigQuery e Cloud Storage. Se è richiesta l'autenticazione, devi abilitare anche l'API Secret Manager.
- Crea un set di dati e una tabella BigQuery con lo schema appropriato per l'argomento di input Kafka. Se utilizzi più schemi nello stesso argomento e vuoi scrivere in più tabelle, non è necessario creare la tabella prima di configurare la pipeline.
- Quando la coda di messaggi non recapitabili (messaggi non elaborati) per il modello è abilitata, crea una tabella vuota senza uno schema per la coda di messaggi non recapitabili.
- Se ti connetti a un cluster Managed Service per Apache Kafka, la pipeline deve soddisfare anche i requisiti elencati in Utilizza Dataflow con Managed Service per Apache Kafka.
Formato dei messaggi Kafka
Questo template supporta la lettura dei messaggi da Kafka nei seguenti formati:
Formato JSON
Per leggere i messaggi JSON, imposta il parametro del template messageFormat su
"JSON".
Codifica binaria Avro
Per leggere i messaggi Avro binari, imposta i seguenti parametri del template:
messageFormat:"AVRO_BINARY_ENCODING".binaryAvroSchemaPath: la posizione di un file di schema Avro in Cloud Storage. Esempio:gs://BUCKET_NAME/message-schema.avsc.
Per saperne di più sul formato binario Avro, consulta Codifica binaria nella documentazione di Apache Avro.
Avro codificato con Confluent Schema Registry
Per leggere i messaggi in Avro codificato in Confluent Schema Registry, imposta i seguenti parametri del template:
messageFormat:"AVRO_CONFLUENT_WIRE_FORMAT".schemaFormat: uno dei seguenti valori:"SINGLE_SCHEMA_FILE": lo schema dei messaggi è definito in un file di schema Avro. Specifica la posizione in Cloud Storage del file di schema nel parametroconfluentAvroSchemaPath.-
"SCHEMA_REGISTRY": i messaggi vengono codificati utilizzando Confluent Schema Registry. Specifica l'URL dell'istanza di Confluent Schema Registry nel parametroschemaRegistryConnectionUrle la modalità di autenticazione nel parametroschemaRegistryAuthenticationMode.
Per saperne di più su questo formato, consulta Formato wire nella documentazione di Confluent.
Autenticazione
Il template da Apache Kafka a BigQuery supporta l'autenticazione SASL/PLAIN per i broker Kafka.
Parametri del modello
Parametri obbligatori
- readBootstrapServerAndTopic: argomento Kafka da cui leggere l'input.
- writeMode: scrive i record in una o più tabelle (in base allo schema). La modalità
DYNAMIC_TABLE_NAMESè supportata solo per il formato del messaggio di origineAVRO_CONFLUENT_WIRE_FORMATe l'origine dello schemaSCHEMA_REGISTRY. Il nome della tabella di destinazione viene generato automaticamente in base al nome dello schema Avro di ogni messaggio. Può essere uno schema singolo (creando una singola tabella) o più schemi (creando più tabelle). La modalitàSINGLE_TABLE_NAMEscrive in una singola tabella (schema singolo) specificata dall'utente. Il valore predefinito èSINGLE_TABLE_NAME. - kafkaReadAuthenticationMode: la modalità di autenticazione da utilizzare con il cluster Kafka. Utilizza
NONEper nessuna autenticazione,SASL_PLAINper nome utente e password SASL/PLAIN,SASL_SCRAM_512per l'autenticazione SASL_SCRAM_512 eTLSper l'autenticazione basata su certificato.APPLICATION_DEFAULT_CREDENTIALSdeve essere utilizzato solo per il cluster Google Cloud Managed Service per Apache Kafka, consente l'autenticazione utilizzando le credenziali predefinite dell'applicazione. - messageFormat: il formato dei messaggi Kafka da leggere. I valori supportati sono
AVRO_CONFLUENT_WIRE_FORMAT(Avro con codifica Confluent Schema Registry),AVRO_BINARY_ENCODING(Avro binario normale) eJSON. Il valore predefinito è: AVRO_CONFLUENT_WIRE_FORMAT. - useBigQueryDLQ: se true, i messaggi non riusciti verranno scritti in BigQuery con informazioni aggiuntive sull'errore. Il valore predefinito è false.
Parametri facoltativi
- outputTableSpec: la posizione della tabella BigQuery in cui scrivere l'output. Il nome deve essere nel formato
<project>:<dataset>.<table_name>. Lo schema della tabella deve corrispondere agli oggetti di input. - persistKafkaKey: se true, la pipeline renderà persistente la chiave del messaggio Kafka nella tabella BigQuery, in un campo
_keydi tipoBYTES. Il valore predefinito èfalse(la chiave viene ignorata). - outputProject: progetto di output BigQuery in cui si trova il set di dati. Le tabelle verranno create dinamicamente nel set di dati. Il valore predefinito è vuoto.
- outputDataset: set di dati di output BigQuery in cui scrivere l'output. Le tabelle verranno create dinamicamente nel set di dati. Se le tabelle vengono create in anticipo, i nomi delle tabelle devono seguire la convenzione di denominazione specificata. Il nome deve essere
bqTableNamePrefix + Avro Schema FullName, con ogni parola separata da un trattino-. Il valore predefinito è vuoto. - bqTableNamePrefix: prefisso di denominazione da utilizzare durante la creazione delle tabelle di output BigQuery. Applicabile solo quando si utilizza il registry dello schema. Il valore predefinito è vuoto.
- createDisposition: CreateDisposition di BigQuery. Ad esempio:
CREATE_IF_NEEDED,CREATE_NEVER. Valore predefinito: CREATE_IF_NEEDED. - writeDisposition: BigQuery WriteDisposition. Ad esempio:
WRITE_APPEND,WRITE_EMPTYoWRITE_TRUNCATE. Il valore predefinito è: WRITE_APPEND. - useAutoSharding: se true, la pipeline utilizza lo sharding automatico durante la scrittura in BigQuery. Il valore predefinito è
true. - numStorageWriteApiStreams: specifica il numero di stream di scrittura. Questo parametro deve essere impostato. Il valore predefinito è
0. - storageWriteApiTriggeringFrequencySec: specifica la frequenza di attivazione in secondi. Questo parametro deve essere impostato. Il valore predefinito è 5 secondi.
- useStorageWriteApiAtLeastOnce: questo parametro ha effetto solo se l'opzione "Utilizza l'API BigQuery Storage Write" è abilitata. Se abilitata, verrà utilizzata la semantica "at-least-once" per l'API Storage Write, altrimenti verrà utilizzata la semantica "exactly-once". Il valore predefinito è false.
- enableCommitOffsets: esegue il commit degli offset dei messaggi elaborati in Kafka. Se abilitata, questa opzione ridurrà al minimo le lacune o l'elaborazione duplicata dei messaggi durante il riavvio della pipeline. Richiede l'ID gruppo di consumer. Il valore predefinito è false.
- consumerGroupId: l'identificatore univoco del gruppo di consumer a cui appartiene questa pipeline. Obbligatorio se l'opzione Commit offset in Kafka è abilitata. Il valore predefinito è vuoto.
- kafkaReadOffset: il punto di partenza per la lettura dei messaggi quando non esistono offset di cui è stato eseguito il commit. Il più recente è quello iniziale, mentre il meno recente viene calcolato partendo dal messaggio più recente. Il valore predefinito è: latest.
- kafkaReadUsernameSecretId: l'ID secret di Secret Manager di Google Cloud che contiene il nome utente Kafka da utilizzare con l'autenticazione
SASL_PLAIN. Ad esempio:projects/<PROJECT_ID>/secrets/<SECRET_ID>/versions/<SECRET_VERSION>. Il valore predefinito è vuoto. - kafkaReadPasswordSecretId: l'ID secret di Secret Manager di Google Cloud che contiene la password Kafka da utilizzare con l'autenticazione
SASL_PLAIN. Ad esempio:projects/<PROJECT_ID>/secrets/<SECRET_ID>/versions/<SECRET_VERSION>. Il valore predefinito è vuoto. - kafkaReadKeystoreLocation: il percorso di Google Cloud Storage del file Java KeyStore (JKS) che contiene il certificato TLS e la chiave privata da utilizzare per l'autenticazione con il cluster Kafka. Ad esempio,
gs://your-bucket/keystore.jks. - kafkaReadTruststoreLocation: il percorso di Google Cloud Storage del file Java TrustStore (JKS) che contiene i certificati attendibili da utilizzare per verificare l'identità del broker Kafka.
- kafkaReadTruststorePasswordSecretId: l'ID secret di Secret Manager di Google Cloud che contiene la password da utilizzare per accedere al file Java TrustStore (JKS) per l'autenticazione TLS di Kafka. Ad esempio,
projects/<PROJECT_ID>/secrets/<SECRET_ID>/versions/<SECRET_VERSION>. - kafkaReadKeystorePasswordSecretId: l'ID secret di Secret Manager di Google Cloud che contiene la password da utilizzare per accedere al file Java KeyStore (JKS) per l'autenticazione TLS di Kafka. Ad esempio,
projects/<PROJECT_ID>/secrets/<SECRET_ID>/versions/<SECRET_VERSION>. - kafkaReadKeyPasswordSecretId: l'ID secret di Secret Manager di Google Cloud che contiene la password da utilizzare per accedere alla chiave privata all'interno del file Java KeyStore (JKS) per l'autenticazione TLS di Kafka. Ad esempio,
projects/<PROJECT_ID>/secrets/<SECRET_ID>/versions/<SECRET_VERSION>. - kafkaReadSaslScramUsernameSecretId: l'ID secret di Secret Manager di Google Cloud che contiene il nome utente Kafka da utilizzare con l'autenticazione
SASL_SCRAM. Ad esempio:projects/<PROJECT_ID>/secrets/<SECRET_ID>/versions/<SECRET_VERSION>. - kafkaReadSaslScramPasswordSecretId: l'ID secret di Secret Manager di Google Cloud che contiene la password Kafka da utilizzare con l'autenticazione
SASL_SCRAM. Ad esempio:projects/<PROJECT_ID>/secrets/<SECRET_ID>/versions/<SECRET_VERSION>. - kafkaReadSaslScramTruststoreLocation: il percorso di Google Cloud Storage del file Java TrustStore (JKS) che contiene i certificati attendibili da utilizzare per verificare l'identità del broker Kafka.
- kafkaReadSaslScramTruststorePasswordSecretId: l'ID secret di Secret Manager di Google Cloud che contiene la password da utilizzare per accedere al file Java TrustStore (JKS) per l'autenticazione Kafka SASL_SCRAM. Ad esempio,
projects/<PROJECT_ID>/secrets/<SECRET_ID>/versions/<SECRET_VERSION>. - schemaFormat: il formato dello schema Kafka. Può essere fornito come
SINGLE_SCHEMA_FILEoSCHEMA_REGISTRY. Se viene specificatoSINGLE_SCHEMA_FILE, utilizza lo schema indicato nel file di schema Avro per tutti i messaggi. Se viene specificatoSCHEMA_REGISTRY, i messaggi possono avere uno o più schemi. Il valore predefinito è: SINGLE_SCHEMA_FILE. - confluentAvroSchemaPath: il percorso di Google Cloud Storage del singolo file di schema Avro utilizzato per decodificare tutti i messaggi di un argomento. Il valore predefinito è vuoto.
- schemaRegistryConnectionUrl: l'URL dell'istanza del registro di schema Confluent utilizzata per gestire gli schemi Avro per la decodifica dei messaggi. Il valore predefinito è vuoto.
- binaryAvroSchemaPath: il percorso di Google Cloud Storage del file dello schema Avro utilizzato per decodificare i messaggi Avro con codifica binaria. Il valore predefinito è vuoto.
- schemaRegistryAuthenticationMode: la modalità di autenticazione da utilizzare con il registro di schemi. Utilizza
NONEper nessuna autenticazione,TLSper l'autenticazione basata su certificati eOAUTHper l'autenticazione OAuth2.APPLICATION_DEFAULT_CREDENTIALSdeve essere utilizzato solo per il registro di schema di Google Cloud Managed Service per Apache Kafka, consente l'autenticazione utilizzando le credenziali predefinite dell'applicazione. - schemaRegistryTruststoreLocation: posizione del certificato SSL in cui è archiviato l'archivio di attendibilità per l'autenticazione in Schema Registry. Ad esempio,
/your-bucket/truststore.jks. - schemaRegistryTruststorePasswordSecretId: SecretId in Secret Manager in cui è archiviata la password per accedere al secret nel truststore. Ad esempio,
projects/your-project-number/secrets/your-secret-name/versions/your-secret-version. - schemaRegistryKeystoreLocation: posizione del keystore che contiene il certificato SSL e la chiave privata. Ad esempio,
/your-bucket/keystore.jks. - schemaRegistryKeystorePasswordSecretId: SecretId in Secret Manager in cui si trova la password per accedere al file del keystore, ad esempio
projects/your-project-number/secrets/your-secret-name/versions/your-secret-version. - schemaRegistryKeyPasswordSecretId: SecretId della password richiesta per accedere alla chiave privata del client archiviata nel keystore, ad esempio
projects/your-project-number/secrets/your-secret-name/versions/your-secret-version. - schemaRegistryOauthClientId: ID client utilizzato per autenticare il client Schema Registry in modalità OAUTH. Obbligatorio per il formato dei messaggi AVRO_CONFLUENT_WIRE_FORMAT.
- schemaRegistryOauthClientSecretId: l'ID secret di Google Cloud Secret Manager che contiene il client secret da utilizzare per autenticare il client Schema Registry in modalità OAUTH. Obbligatorio per il formato dei messaggi AVRO_CONFLUENT_WIRE_FORMAT. Ad esempio,
projects/<PROJECT_ID>/secrets/<SECRET_ID>/versions/<SECRET_VERSION>. - schemaRegistryOauthScope: l'ambito del token di accesso utilizzato per autenticare il client Schema Registry in modalità OAUTH. Questo campo è facoltativo, in quanto la richiesta può essere effettuata senza passare un parametro di ambito. Ad esempio,
openid. - schemaRegistryOauthTokenEndpointUrl: l'URL basato su HTTP(S) per il provider di identità OAuth/OIDC utilizzato per autenticare il client Schema Registry in modalità OAUTH. Obbligatorio per il formato dei messaggi AVRO_CONFLUENT_WIRE_FORMAT.
- outputDeadletterTable: nome della tabella BigQuery completo per i messaggi non riusciti. I messaggi che non sono riusciti a raggiungere la tabella di output per diversi motivi (ad esempio, schema non corrispondente, JSON non valido) vengono scritti in questa tabella. La tabella verrà creata dal template. Ad esempio,
your-project-id:your-dataset.your-table-name. - javascriptTextTransformGcsPath: l'URI Cloud Storage del file .js che definisce la funzione definita dall'utente (UDF) JavaScript da utilizzare. Ad esempio,
gs://my-bucket/my-udfs/my_file.js. - javascriptTextTransformFunctionName: il nome della funzione definita dall'utente (UDF) JavaScript da utilizzare. Ad esempio, se il codice della funzione JavaScript è
myTransform(inJson) { /*...do stuff...*/ }, il nome della funzione èmyTransform. Per esempi di UDF JavaScript, consulta Esempi di UDF (https://github.com/GoogleCloudPlatform/DataflowTemplates#udf-examples). - javascriptTextTransformReloadIntervalMinutes: specifica la frequenza di ricaricamento della funzione definita dall'utente, in minuti. Se il valore è maggiore di 0, Dataflow controlla periodicamente il file della funzione definita dall'utente in Cloud Storage e ricarica la funzione definita dall'utente se il file viene modificato. Questo parametro consente di aggiornare la funzione definita dall'utente mentre la pipeline è in esecuzione, senza dover riavviare il job. Se il valore è
0, il ricaricamento delle UDF è disabilitato. Il valore predefinito è0.
Funzione definita dall'utente
Se vuoi, puoi estendere questo modello scrivendo una funzione definita dall'utente (UDF). Il template chiama la funzione definita dall'utente per ogni elemento di input. I payload degli elementi vengono serializzati come stringhe JSON. Per saperne di più, consulta Crea funzioni definite dall'utente per i template Dataflow.
Il template supporta le funzioni definite dall'utente solo per i messaggi Kafka in formato JSON. Se i messaggi Kafka utilizzano il formato Avro, la funzione definita dall'utente non viene richiamata.Specifica della funzione
La funzione definita dall'utente ha la seguente specifica:
- Input: il valore del record Kafka, serializzato come stringa JSON
- Output: una stringa JSON che corrisponde allo schema della tabella di destinazione BigQuery
Esegui il modello
Console
- Vai alla pagina Crea job da modello di Dataflow. Vai a Crea job da modello
- Nel campo Nome job, inserisci un nome job univoco.
- (Facoltativo) Per Endpoint a livello di regione, seleziona un valore dal menu a discesa. La regione predefinita è
us-central1.Per un elenco delle regioni in cui puoi eseguire un job Dataflow, consulta Località di Dataflow.
- Dal menu a discesa Modello Dataflow, seleziona il modello Da Kafka a BigQuery.
- Nei campi dei parametri forniti, inserisci i valori dei parametri.
- (Facoltativo) Per passare dall'elaborazione "exactly-once" alla modalità flusso di dati "at-least-once", seleziona Almeno una volta.
- Fai clic su Esegui job.
gcloud
Nella shell o nel terminale, esegui il template:
gcloud dataflow flex-template run JOB_NAME \ --project=PROJECT_ID \ --region=REGION_NAME \ --template-file-gcs-location=gs://dataflow-templates/VERSION/flex/Kafka_to_BigQuery_Flex \ --parameters \ readBootstrapServerAndTopic=BOOTSTRAP_SERVER_AND_TOPIC,\ kafkaReadAuthenticationMode=APPLICATION_DEFAULT_CREDENTIALS,\ messageFormat=JSON,\ writeMode=SINGLE_TABLE_NAME,\ outputTableSpec=PROJECT_ID:DATASET_NAME.TABLE_NAME,\ useBigQueryDLQ=true,\ outputDeadletterTable=PROJECT_ID:DATASET_NAME.ERROR_TABLE_NAME
Sostituisci quanto segue:
PROJECT_ID: l'ID progetto Google Cloud in cui vuoi eseguire il job DataflowJOB_NAME: un nome job univoco di tua sceltaREGION_NAME: la regione in cui vuoi eseguire il deployment del job Dataflow, ad esempious-central1VERSION: la versione del template che vuoi utilizzarePuoi utilizzare i seguenti valori:
latestper utilizzare l'ultima versione del template, disponibile nella cartella padre senza data nel bucket: gs://dataflow-templates/latest/- il nome della versione, ad esempio
2023-09-12-00_RC00, per utilizzare una versione specifica del template, che si trova nidificata nella rispettiva cartella padre con data nel bucket: gs://dataflow-templates/
BOOTSTRAP_SERVER_AND_TOPIC: l'indirizzo e l'argomento del server bootstrap Apache KafkaIl formato dell'indirizzo del server bootstrap e dell'argomento dipende dal tipo di cluster:
- Cluster Managed Service per Apache Kafka:
projects/PROJECT_ID/locations/REGION_NAME/clusters/CLUSTER_NAME/topics/TOPIC_NAME - Cluster Kafka esterno:
BOOTSTRAP_SERVER_ADDRESS;TOPIC_NAME
- Cluster Managed Service per Apache Kafka:
DATASET_NAME: il nome del tuo set di dati BigQueryTABLE_NAME: il nome della tabella di output BigQueryERROR_TABLE_NAME: il nome della tabella BigQuery in cui scrivere i record di errore
API
Per eseguire il template utilizzando l'API REST, invia una richiesta POST HTTP. Per saperne di più sull'API e sui relativi ambiti di autorizzazione, consulta projects.templates.launch.
POST https://dataflow.googleapis.com/v1b3/projects/PROJECT_ID/locations/LOCATION/flexTemplates:launch { "launch_parameter": { "jobName": "JOB_NAME", "parameters": { "readBootstrapServerAndTopic": "BOOTSTRAP_SERVER_AND_TOPIC", "kafkaReadAuthenticationMode": "APPLICATION_DEFAULT_CREDENTIALS", "messageFormat": "JSON", "writeMode": "SINGLE_TABLE_NAME", "outputTableSpec": "PROJECT_ID:DATASET_NAME.TABLE_NAME", "useBigQueryDLQ": "true", "outputDeadletterTable": "PROJECT_ID:DATASET_NAME.ERROR_TABLE_NAME" }, "containerSpecGcsPath": "gs://dataflow-templates/VERSION/flex/Kafka_to_BigQuery_Flex", } }
Sostituisci quanto segue:
PROJECT_ID: l'ID progetto Google Cloud in cui vuoi eseguire il job DataflowJOB_NAME: un nome job univoco di tua sceltaLOCATION: la regione in cui vuoi eseguire il deployment del job Dataflow, ad esempious-central1VERSION: la versione del template che vuoi utilizzarePuoi utilizzare i seguenti valori:
latestper utilizzare l'ultima versione del template, disponibile nella cartella padre senza data nel bucket: gs://dataflow-templates/latest/- il nome della versione, ad esempio
2023-09-12-00_RC00, per utilizzare una versione specifica del template, che si trova nidificata nella rispettiva cartella padre con data nel bucket: gs://dataflow-templates/
BOOTSTRAP_SERVER_AND_TOPIC: l'indirizzo e l'argomento del server bootstrap Apache KafkaIl formato dell'indirizzo del server bootstrap e dell'argomento dipende dal tipo di cluster:
- Cluster Managed Service per Apache Kafka:
projects/PROJECT_ID/locations/LOCATION/clusters/CLUSTER_NAME/topics/TOPIC_NAME - Cluster Kafka esterno:
BOOTSTRAP_SERVER_ADDRESS;TOPIC_NAME
- Cluster Managed Service per Apache Kafka:
DATASET_NAME: il nome del tuo set di dati BigQueryTABLE_NAME: il nome della tabella di output BigQueryERROR_TABLE_NAME: il nome della tabella BigQuery in cui scrivere i record di errore
Per saperne di più, consulta Scrivi dati da Kafka a BigQuery con Dataflow.
Passaggi successivi
- Scopri di più sui template Dataflow.
- Consulta l'elenco dei modelli forniti da Google.