Il modello da SQL Server a BigQuery è una pipeline batch che copia i dati da una tabella SQL Server a una tabella BigQuery esistente. Questa pipeline utilizza JDBC per la connessione a SQL Server. Per un ulteriore livello di protezione, puoi anche passare una chiave Cloud KMS insieme a nome utente, password e parametri della stringa di connessione codificati in Base64 e criptati con la chiave Cloud KMS. Per saperne di più sulla crittografia di nome utente, password e parametri della stringa di connessione, consulta l'endpoint di crittografia dell'API Cloud KMS.
Requisiti della pipeline
- La tabella BigQuery deve esistere prima dell'esecuzione della pipeline.
- La tabella BigQuery deve avere uno schema compatibile.
- Il database relazionale deve essere accessibile dalla subnet in cui viene eseguito Dataflow.
Parametri del modello
Parametri obbligatori
- driverJars : l'elenco separato da virgole di file JAR del driver. Ad esempio: gs://your-bucket/driver_jar1.jar,gs://your-bucket/driver_jar2.jar.
- driverClassName : il nome della classe del driver JDBC. Ad esempio: com.mysql.jdbc.Driver.
- connectionURL : la stringa dell'URL di connessione JDBC. Ad esempio,
jdbc:mysql://some-host:3306/sampledb
. Puoi passare questo valore come stringa criptata con una chiave Cloud KMS e poi codificata in Base64. Rimuovi gli spazi vuoti dalla stringa codificata in Base64. Nota la differenza tra una stringa di connessione al database Oracle non RAC (jdbc:oracle:thin:@some-host:<port>:<sid>
) e una stringa di connessione al database Oracle RAC (jdbc:oracle:thin:@//some-host[:<port>]/<service_name>
) (ad esempio: jdbc:mysql://some-host:3306/sampledb). - outputTable : la posizione della tabella di output BigQuery. Esempio: <PROJECT_ID>:<DATASET_NAME>.<TABLE_NAME>.
- bigQueryLoadingTemporaryDirectory : la directory temporanea per il processo di caricamento di BigQuery. (ad esempio: gs://your-bucket/your-files/temp_dir).
Parametri facoltativi
- connectionProperties : la stringa di proprietà da utilizzare per la connessione JDBC. Il formato della stringa deve essere
[propertyName=property;]*
.Per ulteriori informazioni, consulta Proprietà di configurazione (https://dev.mysql.com/doc/connector-j/8.1/en/connector-j-reference-configuration-properties.html) nella documentazione di MySQL. (Esempio: unicode=true;characterEncoding=UTF-8). - username : 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. Rimuovi gli spazi vuoti dalla stringa codificata in 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. Rimuovi gli spazi vuoti dalla stringa codificata in Base64.
- query : la query da eseguire sull'origine per estrarre i dati. Tieni presente che alcuni tipi di SQL JDBC e BigQuery, anche se condividono lo stesso nome, presentano alcune differenze. Alcune mappature importanti dei tipi SQL -> BigQuery da ricordare sono: DATETIME --> TIMESTAMP
Se gli schemi non corrispondono, potrebbe essere necessaria la trasmissione dei tipi. Ad esempio, seleziona * da sampledb.sample_table.
- KMSEncryptionKey : la chiave di crittografia Cloud KMS da utilizzare per decriptare il nome utente, la password e la stringa di connessione. Se passi in una chiave Cloud KMS, devi criptare anche il nome utente, la password e la stringa di connessione. Ad esempio: projects/your-project/locations/global/keyRings/your-keyring/cryptoKeys/your-key.
- useColumnAlias : se impostato su
true
, la pipeline utilizza l'alias di colonna (AS
) anziché il nome della colonna per mappare le righe a BigQuery. Il valore predefinito èfalse
. - isTruncate : se impostato su
true
, la pipeline viene troncata prima di caricare i dati in BigQuery. Il valore predefinito èfalse
, per cui la pipeline aggiunge dati. - partitionColumn : se a questo parametro viene fornito il nome del parametro
table
definito come facoltativo, JdbcIO legge la tabella in parallelo eseguendo più istanze della query nella stessa tabella (sottoquery) utilizzando gli intervalli. Attualmente supporta soloLong
colonne di partizione. - table : la tabella da cui leggere quando utilizzi le partizioni. Questo parametro accetta anche una sottoquery tra parentesi. (Esempio: (seleziona ID, nome da Persona) come subq).
- numPartitions : il numero di partizioni. Con i limiti inferiore e superiore, questo valore forma gli incrementi di partizione per le espressioni della clausola
WHERE
generate che vengono utilizzate per suddividere in modo uniforme la colonna di partizione. Quando l'input è inferiore a1
, il numero viene impostato su1
. - lowerBound : il limite inferiore da utilizzare nello schema di partizione. Se non viene specificato, questo valore viene dedotto automaticamente da Apache Beam per i tipi supportati.
- upperBound : il limite superiore da utilizzare nello schema di partizione. Se non viene specificato, questo valore viene dedotto automaticamente da Apache Beam per i tipi supportati.
- fetchSize : il numero di righe da recuperare dal database alla volta. Non utilizzato per le letture partizionate. Il valore predefinito è 50.000.
- createDisposition : il valore CreateDisposition di BigQuery da utilizzare. Ad esempio,
CREATE_IF_NEEDED
oCREATE_NEVER
. Il valore predefinito è CREATE_NEVER. - bigQuerySchemaPath : il percorso Cloud Storage per lo schema JSON di BigQuery. Se
createDisposition
è impostato su CREATE_IF_NEEDED, è necessario specificare questo parametro. (Esempio: gs://your-bucket/your-schema.json). - disabledAlgorithms : algoritmi separati da virgole da disabilitare. Se questo valore è impostato su Nessuno, l'algoritmo non viene disabilitato. Utilizza questo parametro con cautela, perché gli algoritmi disattivati per impostazione predefinita potrebbero presentare vulnerabilità o problemi di prestazioni. ad esempio SSLv3, RC4.
- extraFilesToStage : percorsi Cloud Storage o secret di Secret Manager separati da virgole 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.
- useStorageWriteApi : se
true
, la pipeline utilizza l'API BigQuery Storage Write (https://cloud.google.com/bigquery/docs/write-api). Il valore predefinito èfalse
. Per saperne di più, consulta la pagina relativa all'utilizzo dell'API Storage Write (https://beam.apache.org/documentation/io/built-in/google-bigquery/#storage-write-api). - useStorageWriteApiAtLeastOnce : quando utilizzi l'API Storage Write, specifica la semantica della scrittura. Per utilizzare la semantica at-least-once (https://beam.apache.org/documentation/io/built-in/google-bigquery/#at-least-once-semantics), imposta questo parametro su
true
. Per utilizzare la semantica "exactly-once", imposta il parametro sufalse
. Questo parametro si applica solo quandouseStorageWriteApi
ètrue
. Il valore predefinito èfalse
.
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 delle regioni in cui puoi eseguire un job Dataflow, vedi Località Dataflow.
- Nel menu a discesa Modello Dataflow, seleziona the SQL Server to BigQuery template.
- Nei campi dei parametri forniti, inserisci i valori dei parametri.
- Fai clic su Esegui job.
gcloud
Nella shell o nel terminale, esegui il modello:
gcloud dataflow flex-template run JOB_NAME \ --project=PROJECT_ID \ --region=REGION_NAME \ --template-file-gcs-location=gs://dataflow-templates-REGION_NAME/VERSION/flex/SQLServer_to_BigQuery \ --parameters \ connectionURL=JDBC_CONNECTION_URL,\ query=SOURCE_SQL_QUERY,\ outputTable=PROJECT_ID:DATASET.TABLE_NAME, bigQueryLoadingTemporaryDirectory=PATH_TO_TEMP_DIR_ON_GCS,\ connectionProperties=CONNECTION_PROPERTIES,\ username=CONNECTION_USERNAME,\ password=CONNECTION_PASSWORD,\ KMSEncryptionKey=KMS_ENCRYPTION_KEY
Sostituisci quanto segue:
JOB_NAME
: un nome job univoco a tua sceltaVERSION
: la versione del modello che vuoi utilizzarePuoi utilizzare i seguenti valori:
latest
per utilizzare la versione più recente del modello, disponibile nella cartella padre senza data del bucket: gs://dataflow-templates-REGION_NAME/latest/- il nome della versione, come
2023-09-12-00_RC00
, per utilizzare una versione specifica del modello, che si trova nidificata nella rispettiva cartella padre con data all'interno del bucket: gs://dataflow-templates-REGION_NAME/
REGION_NAME
: la regione in cui vuoi eseguire il deployment del job Dataflow, ad esempious-central1
JDBC_CONNECTION_URL
: URL di connessione JDBCSOURCE_SQL_QUERY
: la query SQL da eseguire sul database di origineDATASET
: il tuo set di dati BigQueryTABLE_NAME
: nome della tua tabella BigQueryPATH_TO_TEMP_DIR_ON_GCS
: percorso Cloud Storage della directory temporaneaCONNECTION_PROPERTIES
: le proprietà di connessione JDBC, se necessarieCONNECTION_USERNAME
: il nome utente della connessione JDBCCONNECTION_PASSWORD
: password per la connessione JDBCKMS_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/SQLServer_to_BigQuery" "parameters": { "connectionURL": "JDBC_CONNECTION_URL", "query": "SOURCE_SQL_QUERY", "outputTable": "PROJECT_ID:DATASET.TABLE_NAME", "bigQueryLoadingTemporaryDirectory": "PATH_TO_TEMP_DIR_ON_GCS", "connectionProperties": "CONNECTION_PROPERTIES", "username": "CONNECTION_USERNAME", "password": "CONNECTION_PASSWORD", "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 DataflowJOB_NAME
: un nome job univoco a tua sceltaVERSION
: la versione del modello che vuoi utilizzarePuoi utilizzare i seguenti valori:
latest
per utilizzare la versione più recente del modello, disponibile nella cartella padre senza data del bucket: gs://dataflow-templates-REGION_NAME/latest/- il nome della versione, come
2023-09-12-00_RC00
, per utilizzare una versione specifica del modello, che si trova nidificata nella rispettiva cartella padre con data all'interno del bucket: gs://dataflow-templates-REGION_NAME/
LOCATION
: la regione in cui vuoi eseguire il deployment del job Dataflow, ad esempious-central1
JDBC_CONNECTION_URL
: URL di connessione JDBCSOURCE_SQL_QUERY
: la query SQL da eseguire sul database di origineDATASET
: il tuo set di dati BigQueryTABLE_NAME
: nome della tua tabella BigQueryPATH_TO_TEMP_DIR_ON_GCS
: percorso Cloud Storage della directory temporaneaCONNECTION_PROPERTIES
: le proprietà di connessione JDBC, se necessarieCONNECTION_USERNAME
: il nome utente della connessione JDBCCONNECTION_PASSWORD
: password per la connessione JDBCKMS_ENCRYPTION_KEY
: la chiave di crittografia di Cloud KMS
Passaggi successivi
- Scopri di più sui modelli Dataflow.
- Consulta l'elenco dei modelli forniti da Google.