Il modello BigQuery to Elasticsearch è una pipeline batch che importa i dati da una tabella BigQuery in Elasticsearch come documenti. Il modello può leggere l'intera tabella o leggere record specifici utilizzando una query fornita.
Requisiti della pipeline
- La tabella BigQuery di origine deve esistere.
- Un host Elasticsearch su un'istanza Google Cloud o su Elastic Cloud con Elasticsearch versione 7.0 o successive. Deve essere accessibile dalle macchine worker Dataflow.
Parametri del modello
Parametri obbligatori
- connectionUrl : l'URL Elasticsearch nel formato https://hostname:[port]. Se utilizzi Elastic Cloud, specifica il CloudID. (esempio: https://elasticsearch-host:9200).
- apiKey: la chiave API codificata in Base64 da utilizzare per l'autenticazione.
- index: l'indice Elasticsearch a cui vengono inviate le richieste, ad esempio
my-index.
(esempio: my-index).
Parametri facoltativi
- inputTableSpec: la tabella BigQuery da cui leggere. Formato:
projectId:datasetId.tablename
. Se specifichiinputTableSpec
, il modello legge i dati direttamente dallo spazio di archiviazione BigQuery utilizzando l'API BigQuery Storage Read (https://cloud.google.com/bigquery/docs/reference/storage). Per informazioni sulle limitazioni dell'API Storage Read, consulta https://cloud.google.com/bigquery/docs/reference/storage#limitations. Devi specificareinputTableSpec
oquery
. Se imposti entrambi i parametri, il modello utilizza il parametroquery
. ad esempio bigquery-project:dataset.input_table. - outputDeadletterTable: la tabella BigQuery per i messaggi che non sono riusciti a raggiungere la tabella di output, nel formato <PROJECT_ID>:<DATASET_NAME>.<DEADLETTER_TABLE>. Se una tabella non esiste, viene creata durante l'esecuzione della pipeline. Se non specificato, viene utilizzato
<outputTableSpec>_error_records
. ad esempio id-progetto:set-di-dati.nome-tabella. - query: la query SQL da utilizzare per leggere i dati da BigQuery. Se il set di dati BigQuery si trova in un progetto diverso da quello del job Dataflow, specifica il nome completo del set di dati nella query SQL, ad esempio: <PROJECT_ID>.<DATASET_NAME>.<TABLE_NAME>. Per impostazione predefinita, il parametro
query
utilizza GoogleSQL (https://cloud.google.com/bigquery/docs/introduction-sql), a meno cheuseLegacySql
non siatrue
. Devi specificareinputTableSpec
oquery
. Se imposti entrambi i parametri, il modello utilizza il parametroquery
. Ad esempio, seleziona * da sampledb.sample_table. - useLegacySql: impostato su true per utilizzare l'SQL precedente. Questo parametro si applica solo se utilizzi il parametro
query
. Il valore predefinito è false. - queryLocation : necessaria durante la lettura da una vista autorizzata senza l'autorizzazione della tabella sottostante. (Esempio: US).
- elasticsearchUsername: il nome utente di Elasticsearch con cui eseguire l'autenticazione. Se specificato, il valore di "apiKey" viene ignorato.
- elasticsearchPassword : la password Elasticsearch con cui eseguire l'autenticazione. Se specificato, il valore di "apiKey" viene ignorato.
- batchSize : la dimensione del batch in numero di documenti. Il valore predefinito è 1000.
- batchSizeBytes: le dimensioni del batch in numero di byte. Il valore predefinito è: 5242880 (5 MB).
- maxRetryAttempts: il numero massimo di nuovi tentativi. Deve essere maggiore di zero. Il valore predefinito è: nessun nuovo tentativo.
- maxRetryDuration : la durata massima dei nuovi tentativi in millisecondi. Deve essere maggiore di zero. Il valore predefinito è: nessun nuovo tentativo.
- propertyAsIndex : la proprietà nel documento indicizzato il cui valore specifica i metadati
_index
da includere nel documento nelle richieste collettive. Ha la precedenza su una UDF_index
. Il valore predefinito è: nessuno. - javaScriptIndexFnGcsPath: il percorso Cloud Storage dell'origine della funzione JavaScript UDF per una funzione che specifica i metadati
_index
da includere con il documento nelle richieste collettive. Il valore predefinito è: nessuno. - javaScriptIndexFnName : il nome della funzione JavaScript definita dall'utente che specifica i metadati
_index
da includere nel documento nelle richieste in blocco. Il valore predefinito è: nessuno. - propertyAsId: una proprietà del documento sottoposto a indicizzazione il cui valore specifica i metadati
_id
da includere con il documento nelle richieste collettive. Ha la precedenza su una UDF_id
. Il valore predefinito è: nessuno. - javaScriptIdFnGcsPath : il percorso Cloud Storage dell'origine della funzione JavaScript definita dall'utente per la funzione che specifica i metadati
_id
da includere nel documento nelle richieste in blocco. Il valore predefinito è: nessuno. - javaScriptIdFnName : il nome della funzione JavaScript definita dall'utente che specifica i metadati
_id
da includere nel documento nelle richieste in blocco. Il valore predefinito è: nessuno. - javaScriptTypeFnGcsPath : il percorso Cloud Storage dell'origine della funzione JavaScript definita dall'utente per una funzione che specifica i metadati
_type
da includere con i documenti nelle richieste collettive. Valore predefinito: nessuno. - javaScriptTypeFnName : il nome della funzione JavaScript definita dall'utente che specifica i metadati
_type
da includere nel documento nelle richieste in blocco. Il valore predefinito è: nessuno. - javaScriptIsDeleteFnGcsPath: il percorso Cloud Storage all'origine della funzione JavaScript UDF che determina se eliminare il documento anziché inserirlo o aggiornarlo. La funzione restituisce un valore di stringa
true
ofalse
. Il valore predefinito è: nessuno. - javaScriptIsDeleteFnName : il nome della funzione JavaScript definita dall'utente che determina se eliminare il documento anziché inserirlo o aggiornarlo. La funzione restituisce un valore stringa di
true
ofalse
. Il valore predefinito è: nessuno. - usePartialUpdate: indica se utilizzare aggiornamenti parziali (aggiornamento anziché creazione o indicizzazione, consentendo documenti parziali) con le richieste Elasticsearch. Il valore predefinito è false.
- bulkInsertMethod: indica se utilizzare
INDEX
(indice, consente gli upsert) oCREATE
(crea, errori su _id duplicati) con le richieste collettive di Elasticsearch. Il valore predefinito è: CREATE. - trustSelfSignedCerts : indica se considerare attendibile il certificato autofirmato o meno. Un'istanza Elasticsearch installata potrebbe avere un certificato autofirmato. Abilita questo valore su True per bypassare la convalida sul certificato SSL. (il valore predefinito è False).
- disableCertificateValidation : se "true", il certificato SSL autofirmato è attendibile. Un'istanza Elasticsearch potrebbe avere un certificato autofirmato. Per ignorare la convalida del certificato, imposta questo parametro su "true". Valore predefinito: false.
- apiKeyKMSEncryptionKey : la chiave Cloud KMS per decriptare la chiave API. Questo parametro deve essere fornito se apiKeySource è impostato su KMS. Se viene fornito questo parametro, la stringa apiKey deve essere passata in forma criptata. Crittografa i parametri utilizzando l'endpoint di crittografia dell'API KMS. La chiave deve essere nel formato projects/{gcp_project}/locations/{key_region}/keyRings/{key_ring}/cryptoKeys/{kms_key_name}. Consulta: https://cloud.google.com/kms/docs/reference/rest/v1/projects.locations.keyRings.cryptoKeys/encrypt (esempio: projects/your-project-id/locations/global/keyRings/your-keyring/cryptoKeys/your-key-name).
- apiKeySecretId: l'ID secret di Secret Manager per l'apiKey. Questo parametro deve essere fornito se apiKeySource è impostato su SECRET_MANAGER. Deve essere nel formato projects/{project}/secrets/{secret}/versions/{secret_version}. (esempio: projects/your-project-id/secrets/your-secret/versions/your-secret-version).
- apiKeySource: origine della chiave API. Uno dei valori PLAINTEXT, KMS o SECRET_MANAGER. Questo parametro deve essere fornito se viene utilizzato Secret Manager o KMS. Se apiKeySource è impostato su KMS, devono essere forniti apiKeyKMSEncryptionKey e apiKey criptato. Se apiKeySource è impostato su SECRET_MANAGER, è necessario fornire apiKeySecretId. Se apiKeySource è impostato su PLAINTEXT, è necessario specificare l'API apiKey. Il valore predefinito è: PLAINTEXT.
- javascriptTextTransformGcsPath: l'URI Cloud Storage del file .js che definisce la funzione definita dall'utente (UDF) JavaScript da utilizzare. (ad es. 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 funzioni JavaScript definite dall'utente, consulta gli esempi di funzioni definite dall'utente (https://github.com/GoogleCloudPlatform/DataflowTemplates#udf-examples).
Funzioni definite dall'utente
Questo modello supporta le funzioni definite dall'utente in diversi punti della come descritto di seguito. Per ulteriori informazioni, consulta Creare funzioni predefinite dall'utente per i modelli Dataflow.
Funzione indice
Restituisce l'indice a cui appartiene il documento.
Parametri del modello:
javaScriptIndexFnGcsPath
: l'URI Cloud Storage del file JavaScript.javaScriptIndexFnName
: il nome della funzione JavaScript.
Specifiche della funzione:
- Input: il documento Elasticsearch, serializzato come stringa JSON.
- Output: il valore del campo dei metadati
_index
del documento.
Funzione ID documento
Restituisce l'ID documento.
Parametri del modello:
javaScriptIdFnGcsPath
: l'URI Cloud Storage del file JavaScript.javaScriptIdFnName
: il nome della funzione JavaScript.
Specifica della funzione:
- Input: il documento Elasticsearch, serializzato come stringa JSON.
- Output: il valore
_id
del documento dei metadati.
Funzione di eliminazione dei documenti
Specifica se eliminare un documento. Per utilizzare questa funzione, imposta la modalità di inserimento collettivo su INDEX
e fornisci una funzione ID documento.
Parametri del modello:
javaScriptIsDeleteFnGcsPath
: l'URI Cloud Storage del file JavaScript.javaScriptIsDeleteFnName
: il nome della funzione JavaScript.
Specifica della funzione:
- Input: il documento Elasticsearch, serializzato come stringa JSON.
- Output: restituisce la stringa
"true"
da eliminare il documento o"false"
per eseguire l'upsert del documento.
Funzione di tipo di mappatura
Restituisce il tipo di mappatura del documento.
Parametri del modello:
javaScriptTypeFnGcsPath
: l'URI Cloud Storage di il file JavaScript.javaScriptTypeFnName
: il nome della funzione JavaScript.
Specifica della funzione:
- Input: il documento Elasticsearch, serializzato come stringa JSON.
- Output: il valore
_type
del documento dei metadati.
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. Il valore predefinito
è
us-central1
.Per un elenco di regioni in cui è possibile eseguire un job Dataflow, consulta Località di Dataflow.
- Nel menu a discesa Modello di flusso di dati, seleziona the BigQuery to Elasticsearch 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/BigQuery_to_Elasticsearch \ --parameters \ inputTableSpec=INPUT_TABLE_SPEC,\ connectionUrl=CONNECTION_URL,\ apiKey=APIKEY,\ index=INDEX
Sostituisci quanto segue:
PROJECT_ID
: l'ID del progetto Google Cloud in cui vuoi eseguire il job DataflowJOB_NAME
: un nome job univoco di tua sceltaREGION_NAME
: la regione in cui vuoi di eseguire il deployment del job Dataflow, ad esempious-central1
VERSION
: la versione del modello che vuoi utilizzarePuoi utilizzare i seguenti valori:
latest
per utilizzare la versione più recente del modello, disponibile in cartella principale non-dated nel 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 si trova nidificata nella rispettiva cartella principale datata nel bucket: gs://dataflow-templates-REGION_NAME/
INPUT_TABLE_SPEC
: il nome della tabella BigQuery.CONNECTION_URL
: URL di Elasticsearch.APIKEY
: la tua chiave API codificata in Base64 per l'autenticazione.INDEX
: il tuo indice Elasticsearch.
API
Per eseguire il modello utilizzando l'API REST, invia una richiesta POST HTTP. Per ulteriori informazioni sul
API e i 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": { "inputTableSpec": "INPUT_TABLE_SPEC", "connectionUrl": "CONNECTION_URL", "apiKey": "APIKEY", "index": "INDEX" }, "containerSpecGcsPath": "gs://dataflow-templates-LOCATION/VERSION/flex/BigQuery_to_Elasticsearch", } }
Sostituisci quanto segue:
PROJECT_ID
: l'ID del 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-central1
VERSION
: la versione del modello che vuoi utilizzarePuoi utilizzare i seguenti valori:
latest
per utilizzare la versione più recente del modello, disponibile in cartella principale non-dated nel 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 si trova nidificata nella rispettiva cartella principale datata nel bucket: gs://dataflow-templates-REGION_NAME/
INPUT_TABLE_SPEC
: il nome della tabella BigQuery.CONNECTION_URL
: URL di Elasticsearch.APIKEY
: la tua chiave API codificata in Base64 per l'autenticazione.INDEX
: l'indice Elasticsearch.
Passaggi successivi
- Scopri di più sui modelli Dataflow.
- Consulta l'elenco dei modelli forniti da Google.