Questa pagina è stata tradotta dall'API Cloud Translation.

Modello Java Database Connectivity (JDBC) a Pub/Sub

Il modello da Java Database Connectivity (JDBC) a Pub/Sub è una pipeline batch che importa dati da un'origine JDBC e scrive i record risultanti in un argomento Pub/Sub preesistente come stringa JSON.

Requisiti della pipeline

L'origine JDBC deve esistere prima dell'esecuzione della pipeline.
L'argomento di output di Pub/Sub deve esistere prima dell'esecuzione della pipeline.

Parametri del modello

Parametri obbligatori

driverClassName : il nome della classe del driver JDBC. (Esempio: com.mysql.jdbc.Driver).
connectionUrl : la stringa dell'URL di connessione JDBC. Puoi passare questo valore come stringa criptata con una chiave Cloud KMS e poi codificata in Base64. Rimuovi gli spazi dalla stringa codificata Base64. (Esempio: jdbc:mysql://some-host:3306/sampledb).
driverJars : percorsi di Cloud Storage separati da virgole per i driver JDBC. Esempio: gs://your-bucket/driver_jar1.jar,gs://your-bucket/driver_jar2.jar.
query : la query da eseguire sull'origine per estrarre i dati. Ad esempio, seleziona * da sampledb.sample_table.
outputTopic : l'argomento Pub/Sub in cui pubblicare, nel formato projects/<PROJECT_ID>/topics/<TOPIC_NAME> (ad esempio: projects/your-project-id/topics/your-topic-name).

Parametri facoltativi

nomeutente : il nome utente da utilizzare per la connessione JDBC. Puoi passare questo valore come stringa criptata con una chiave Cloud KMS e poi codificata in Base64. Ad esempio, echo -n 'some_username' | glcloud kms encrypt --location=my_location --keyring=mykeyring --key=mykey --plaintext-file=- --ciphertext-file=- | base64.
password : la password da utilizzare per la connessione JDBC. Puoi passare questo valore come stringa criptata con una chiave Cloud KMS e poi codificata in Base64. Ad esempio, echo -n 'some_password' | glcloud kms encrypt --location=my_location --keyring=mykeyring --key=mykey --plaintext-file=- --ciphertext-file=- | base64.
connectionProperties : la stringa delle proprietà da utilizzare per la connessione JDBC. Il formato della stringa deve essere [propertyName=property;]*. Esempio: unicode=true;characterEncoding=UTF-8.
KMSEncryptionKey : la chiave di crittografia di Cloud KMS da utilizzare per decriptare il nome utente, la password e la stringa di connessione. Se viene passata una chiave Cloud KMS, nome utente, password e stringa di connessione devono essere trasmessi in forma criptata e con codifica Base64. ad esempio projects/your-project/locations/global/keyRings/your-keyring/cryptoKeys/your-key.
disabledAlgorithms : algoritmi separati da virgole da disabilitare. Se questo valore è impostato su Nessuno, nessun algoritmo viene disabilitato. Usa questo parametro con cautela, perché gli algoritmi disabilitati per impostazione predefinita potrebbero presentare vulnerabilità o problemi di prestazioni. (Esempio: SSLv3, RC4).
extraFilesToStage : percorsi Cloud Storage o secret di Secret Manager separati da virgola per i file da inserire nel worker. Questi file vengono salvati nella directory /extra_files di ciascun worker. Esempio: gs://
defaultLogLevel : imposta il livello di log nei worker. Le opzioni supportate sono OFF, ERROR, WARN, INFO, DEBUG, TRACE. Il valore predefinito è INFO.

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 univoco per il job.
(Facoltativo) Per Endpoint a livello di regione, seleziona un valore dal menu a discesa. La regione predefinita è us-central1.
Per un elenco di regioni in cui è possibile eseguire un job Dataflow, consulta Località di Dataflow.
Dal menu a discesa Modello Dataflow, seleziona the JDBC to Pub/Sub template.
Inserisci i valori parametro negli appositi campi.
Fai clic su Esegui job.

gcloud

Nella shell o nel terminale, esegui il modello:

gcloud dataflow jobs run JOB_NAME \
    --gcs-location gs://dataflow-templates-REGION_NAME/VERSION/flex/Jdbc_to_PubSub \
    --region REGION_NAME \
    --parameters \
driverClassName=DRIVER_CLASS_NAME,\
connectionURL=JDBC_CONNECTION_URL,\
driverJars=DRIVER_PATHS,\
username=CONNECTION_USERNAME,\
password=CONNECTION_PASSWORD,\
connectionProperties=CONNECTION_PROPERTIES,\
query=SOURCE_SQL_QUERY,\
outputTopic=OUTPUT_TOPIC,\
KMSEncryptionKey=KMS_ENCRYPTION_KEY

Sostituisci quanto segue:

JOB_NAME: un nome job univoco a tua scelta
VERSION: la versione del modello che vuoi utilizzare
Puoi utilizzare i seguenti valori:
- latest per utilizzare la versione più recente del modello, disponibile nella cartella padre non con data del bucket: gs://dataflow-templates-REGION_NAME/latest/
- il nome della versione, ad esempio 2023-09-12-00_RC00, per utilizzare una versione specifica del modello, che è possibile trovare nidificata nella rispettiva cartella principale con data nel bucket: gs://dataflow-templates-REGION_NAME/
Attenzione:la versione più recente dei modelli potrebbe essere aggiornata con modifiche che provocano errori. I tuoi ambienti di produzione devono utilizzare i modelli conservati nella cartella principale con data più recente per evitare che queste modifiche che provocano un errore influiscano sui flussi di lavoro di produzione.
REGION_NAME: la regione in cui vuoi eseguire il deployment del job Dataflow, ad esempio us-central1
DRIVER_CLASS_NAME: il nome della classe del conducente
JDBC_CONNECTION_URL: URL di connessione JDBC
DRIVER_PATHS: il percorso o i percorsi Cloud Storage dei driver JDBC, separati da virgole,
CONNECTION_USERNAME: il nome utente della connessione JDBC
CONNECTION_PASSWORD: la password di connessione JDBC
CONNECTION_PROPERTIES: le proprietà di connessione JDBC, se necessario
SOURCE_SQL_QUERY: la query SQL da eseguire sul database di origine
OUTPUT_TOPIC: il nome Pub/Sub in cui pubblicare
KMS_ENCRYPTION_KEY: la chiave di crittografia di Cloud KMS

API

Per eseguire il modello utilizzando l'API REST, invia una richiesta POST HTTP. Per maggiori informazioni 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
{
  "launchParameter": {
    "jobName": "JOB_NAME",
    "containerSpecGcsPath": "gs://dataflow-templates-LOCATION/VERSION/flex/Jdbc_to_PubSub"
    "parameters": {
      "driverClassName": "DRIVER_CLASS_NAME",
      "connectionURL": "JDBC_CONNECTION_URL",
      "driverJars": "DRIVER_PATHS",
      "username": "CONNECTION_USERNAME",
      "password": "CONNECTION_PASSWORD",
      "connectionProperties": "CONNECTION_PROPERTIES",
      "query": "SOURCE_SQL_QUERY",
      "outputTopic": "OUTPUT_TOPIC",
      "KMSEncryptionKey":"KMS_ENCRYPTION_KEY"
    },
    "environment": { "zone": "us-central1-f" }
  }
}

Sostituisci quanto segue:

PROJECT_ID: l'ID del progetto Google Cloud in cui vuoi eseguire il job Dataflow
JOB_NAME: un nome job univoco a tua scelta
VERSION: la versione del modello che vuoi utilizzare
Puoi utilizzare i seguenti valori:
- latest per utilizzare la versione più recente del modello, disponibile nella cartella padre non con data del bucket: gs://dataflow-templates-REGION_NAME/latest/
- il nome della versione, ad esempio 2023-09-12-00_RC00, per utilizzare una versione specifica del modello, che è possibile trovare nidificata nella rispettiva cartella principale con data nel bucket: gs://dataflow-templates-REGION_NAME/
Attenzione:la versione più recente dei modelli potrebbe essere aggiornata con modifiche che provocano errori. I tuoi ambienti di produzione devono utilizzare i modelli conservati nella cartella principale con data più recente per evitare che queste modifiche che provocano un errore influiscano sui flussi di lavoro di produzione.
LOCATION: la regione in cui vuoi eseguire il deployment del job Dataflow, ad esempio us-central1
DRIVER_CLASS_NAME: il nome della classe del conducente
JDBC_CONNECTION_URL: URL di connessione JDBC
DRIVER_PATHS: il percorso o i percorsi Cloud Storage dei driver JDBC, separati da virgole,
CONNECTION_USERNAME: il nome utente della connessione JDBC
CONNECTION_PASSWORD: la password di connessione JDBC
CONNECTION_PROPERTIES: le proprietà di connessione JDBC, se necessario
SOURCE_SQL_QUERY: la query SQL da eseguire sul database di origine
OUTPUT_TOPIC: il nome Pub/Sub in cui pubblicare
KMS_ENCRYPTION_KEY: la chiave di crittografia di Cloud KMS

Codice sorgente del modello

Java

/*
 * Copyright (C) 2021 Google LLC
 *
 * Licensed under the Apache License, Version 2.0 (the "License"); you may not
 * use this file except in compliance with the License. You may obtain a copy of
 * the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 * License for the specific language governing permissions and limitations under
 * the License.
 */
package com.google.cloud.teleport.v2.templates;

import static com.google.cloud.teleport.v2.utils.KMSUtils.maybeDecrypt;

import com.google.cloud.teleport.metadata.Template;
import com.google.cloud.teleport.metadata.TemplateCategory;
import com.google.cloud.teleport.v2.common.UncaughtExceptionLogger;
import com.google.cloud.teleport.v2.options.JdbcToPubsubOptions;
import java.sql.Clob;
import java.sql.ResultSet;
import java.sql.ResultSetMetaData;
import org.apache.beam.sdk.Pipeline;
import org.apache.beam.sdk.PipelineResult;
import org.apache.beam.sdk.coders.StringUtf8Coder;
import org.apache.beam.sdk.io.gcp.pubsub.PubsubIO;
import org.apache.beam.sdk.io.jdbc.JdbcIO;
import org.apache.beam.sdk.options.PipelineOptionsFactory;
import org.apache.beam.sdk.options.ValueProvider.StaticValueProvider;
import org.apache.beam.sdk.values.PCollection;
import org.json.JSONObject;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

/**
 * The {@link JdbcToPubsub} batch pipeline reads data from JDBC and publishes to Google Cloud
 * PubSub.
 *
 * <p>Check out <a
 * href="https://github.com/GoogleCloudPlatform/DataflowTemplates/blob/main/v2/jdbc-to-googlecloud/README_Jdbc_to_PubSub.md">README</a>
 * for instructions on how to use or modify this template.
 */
@Template(
    name = "Jdbc_to_PubSub",
    category = TemplateCategory.BATCH,
    displayName = "JDBC to Pub/Sub",
    description =
        "The Java Database Connectivity (JDBC) to Pub/Sub template is a batch pipeline that ingests data from "
            + "JDBC source and writes the resulting records to a pre-existing Pub/Sub topic as a JSON string.",
    optionsClass = JdbcToPubsubOptions.class,
    flexContainerName = "jdbc-to-pubsub",
    documentation =
        "https://cloud.google.com/dataflow/docs/guides/templates/provided/jdbc-to-pubsub",
    contactInformation = "https://cloud.google.com/support",
    preview = true,
    requirements = {
      "The JDBC source must exist prior to running the pipeline.",
      "The Cloud Pub/Sub output topic must exist prior to running the pipeline."
    })
public class JdbcToPubsub {

  /* Logger for class.*/
  private static final Logger LOG = LoggerFactory.getLogger(JdbcToPubsub.class);

  /**
   * {@link JdbcIO.RowMapper} implementation to convert Jdbc ResultSet rows to UTF-8 encoded JSONs.
   */
  public static class ResultSetToJSONString implements JdbcIO.RowMapper<String> {

    @Override
    public String mapRow(ResultSet resultSet) throws Exception {
      ResultSetMetaData metaData = resultSet.getMetaData();
      JSONObject json = new JSONObject();

      for (int i = 1; i <= metaData.getColumnCount(); i++) {
        Object value = resultSet.getObject(i);

        // JSONObject.put() does not support null values. The exception is JSONObject.NULL
        if (value == null) {
          json.put(metaData.getColumnLabel(i), JSONObject.NULL);
          continue;
        }

        switch (metaData.getColumnTypeName(i).toLowerCase()) {
          case "clob":
            Clob clobObject = resultSet.getClob(i);
            if (clobObject.length() > Integer.MAX_VALUE) {
              LOG.warn(
                  "The Clob value size {} in column {} exceeds 2GB and will be truncated.",
                  clobObject.length(),
                  metaData.getColumnLabel(i));
            }
            json.put(
                metaData.getColumnLabel(i), clobObject.getSubString(1, (int) clobObject.length()));
            break;
          default:
            json.put(metaData.getColumnLabel(i), value);
        }
      }
      return json.toString();
    }
  }

  /**
   * Main entry point for pipeline execution.
   *
   * @param args Command line arguments to the pipeline.
   */
  public static void main(String[] args) {
    UncaughtExceptionLogger.register();

    JdbcToPubsubOptions options =
        PipelineOptionsFactory.fromArgs(args).withValidation().as(JdbcToPubsubOptions.class);

    run(options);
  }

  /**
   * Runs a pipeline which reads message from JDBC and writes to Pub/Sub.
   *
   * @param options The execution options.
   * @return The pipeline result.
   */
  public static PipelineResult run(JdbcToPubsubOptions options) {
    // Create the pipeline
    Pipeline pipeline = Pipeline.create(options);

    LOG.info("Starting Jdbc-To-PubSub Pipeline.");

    /*
     * Steps:
     *  1) Read data from a Jdbc Table
     *  2) Write to Pub/Sub topic
     */
    JdbcIO.DataSourceConfiguration dataSourceConfiguration =
        JdbcIO.DataSourceConfiguration.create(
                StaticValueProvider.of(options.getDriverClassName()),
                maybeDecrypt(options.getConnectionUrl(), options.getKMSEncryptionKey()))
            .withDriverJars(options.getDriverJars());
    if (options.getUsername() != null) {
      dataSourceConfiguration =
          dataSourceConfiguration.withUsername(
              maybeDecrypt(options.getUsername(), options.getKMSEncryptionKey()));
    }
    if (options.getPassword() != null) {
      dataSourceConfiguration =
          dataSourceConfiguration.withPassword(
              maybeDecrypt(options.getPassword(), options.getKMSEncryptionKey()));
    }
    if (options.getConnectionProperties() != null) {
      dataSourceConfiguration =
          dataSourceConfiguration.withConnectionProperties(options.getConnectionProperties());
    }

    PCollection<String> jdbcData =
        pipeline.apply(
            "readFromJdbc",
            JdbcIO.<String>read()
                .withDataSourceConfiguration(dataSourceConfiguration)
                .withQuery(options.getQuery())
                .withCoder(StringUtf8Coder.of())
                .withRowMapper(new ResultSetToJSONString()));

    jdbcData.apply("writeSuccessMessages", PubsubIO.writeStrings().to(options.getOutputTopic()));

    return pipeline.run();
  }
}

Passaggi successivi

Scopri di più sui modelli Dataflow.
Consulta l'elenco dei modelli forniti da Google.