Il modello da Pub/Sub a Elasticsearch è una pipeline di inserimento flussi che legge i messaggi da una sottoscrizione Pub/Sub, esegue una funzione definita dall'utente dall'utente e li scrive in Elasticsearch come documenti. Il modello Dataflow utilizza la funzionalità flussi di dati di Elasticsearch per archiviare i dati delle serie temporali su più indici, fornendo al contempo un'unica risorsa con nome per le richieste. I flussi di dati sono particolarmente adatti per log, metriche, tracce e altri dati generati continuamente e archiviati in Pub/Sub.
Il modello crea uno stream di dati denominato
logs-gcp.DATASET-NAMESPACE
, in cui:
- DATASET è il valore del parametro del modello
dataset
oppurepubsub
se non specificato. - NAMESPACE è il valore del parametro del modello
namespace
oppuredefault
se non specificato.
Requisiti della pipeline
- Deve esistere la sottoscrizione Pub/Sub di origine e i messaggi devono essere codificati in un formato JSON valido.
- Un host Elasticsearch accessibile pubblicamente su un'istanza Google Cloud o su Elastic Cloud con Elasticsearch versione 7.0 o successive. Per ulteriori dettagli, consulta Integrazione di Google Cloud per Elastic.
- Un argomento Pub/Sub per l'output di errore.
Parametri del modello
Parametri obbligatori
- inputSubscription : sottoscrizione Pub/Sub da cui utilizzare l'input. Il nome deve essere nel formato "projects/your-project-id/subscriptions/your-subscription-name" (ad esempio: projects/your-project-id/subscriptions/your-subscription-name).
- errorOutputTopic : argomento di output di Pub/Sub per la pubblicazione di record non riusciti nel formato "projects/your-project-id/topics/your-topic-name".
- connectionUrl : URL di Elasticsearch nel formato "https://hostname:[port]" o specifica CloudID se utilizzi Elastic Cloud (ad esempio: https://elasticsearch-host:9200).
- apiKey : chiave API codificata in Base64 utilizzata per l'autenticazione. Consulta: https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-api-key.html#security-api-create-api-key-request.
Parametri facoltativi
- dataset : il tipo di log inviati utilizzando Pub/Sub, per il quale disponiamo di una dashboard pronta all'uso. I valori dei tipi di log noti sono audit, vpcflow e firewall. Il valore predefinito "pubsub".
- namespace : un raggruppamento arbitrario, ad esempio un ambiente (sviluppo, produzione o QA), un team o un'unità aziendale strategica. Valore predefinito: "default".
- elasticsearchTemplateVersion : identificatore di versione del modello di Dataflow, in genere definito da Google Cloud. Il valore predefinito è 1.0.0.
- javascriptTextTransformGcsPath : il pattern del percorso di Cloud Storage per il codice JavaScript contenente le funzioni definite dall'utente. ad esempio gs://your-bucket/your-function.js.
- javascriptTextTransformFunctionName : il nome della funzione da chiamare dal file JavaScript. Utilizza solo lettere, numeri e trattini bassi. (ad esempio: "transform" o "transform_udf1").
- javascriptTextTransformReloadIntervalMinutes : definisci l'intervallo che i worker possono verificare per le modifiche della funzione JavaScript definita dall'utente per ricaricare i file. Il valore predefinito è 0.
- elasticsearchUsername : il nome utente 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 : dimensione del batch in numero di documenti. Valore predefinito: "1000".
- batchSizeBytes : dimensione del batch in byte utilizzati per l'inserimento batch di messaggi in Elasticsearch. Valore predefinito: "5242880 (5mb)".
- maxRetryAttempts : il numero massimo di nuovi tentativi deve essere maggiore di 0. Valore predefinito: "Nessun nuovo tentativo".
- maxRetryDuration : la durata massima dei nuovi tentativi in millisecondi deve essere maggiore di 0. Valore predefinito: "Nessun nuovo tentativo".
- propertyAsIndex : una proprietà nel documento indicizzato il cui valore specifica i metadati "_index" da includere nel documento nella richiesta collettiva (ha la precedenza su una funzione definita dall'utente "_index"). Valore predefinito: nessuno.
- javaScriptIndexFnGcsPath : il percorso Cloud Storage dell'origine della funzione JavaScript definita dall'utente per una funzione che specifica i metadati "_index" da includere con il documento nella richiesta collettiva. Valore predefinito: nessuno.
- javaScriptIndexFnName : nome della funzione JavaScript definita dall'utente per la funzione che specifica i metadati _index da includere nel documento nella richiesta in blocco. Valore predefinito: nessuno.
- propertyAsId : una proprietà nel documento indicizzato il cui valore specifica i metadati "_id" da includere nel documento nella richiesta collettiva (ha la precedenza su una funzione definita dall'utente "_id"). Valore predefinito: nessuno.
- javaScriptIdFnGcsPath : il percorso Cloud Storage dell'origine della funzione JavaScript definita dall'utente per una funzione che specifica i metadati "_id" da includere con il documento nella richiesta in blocco.Impostazione predefinita: nessuno.
- javaScriptIdFnName : nome della funzione JavaScript definita dall'utente per la funzione che specifica i metadati _id da includere con il documento nella richiesta collettiva. Valore predefinito: nessuno.
- javaScriptTypeFnGcsPath : il percorso Cloud Storage dell'origine della funzione JavaScript definita dall'utente per la funzione che specificherà i metadati "_type" da includere nel documento nella richiesta collettiva. Valore predefinito: nessuno.
- javaScriptTypeFnName : nome della funzione JavaScript definita dall'utente per la funzione che specifica i metadati "_type" da includere con il documento nella richiesta collettiva. Valore predefinito: nessuno.
- javaScriptIsDeleteFnGcsPath : il percorso di Cloud Storage dell'origine della funzione JavaScript definita dall'utente per la funzione che determinerà se il documento deve essere eliminato anziché inserito o aggiornato. La funzione deve restituire il valore della stringa "true" o "false". Valore predefinito: nessuno.
- javaScriptIsDeleteFnName : nome della funzione JavaScript definita dall'utente per la funzione che determina se il documento deve essere eliminato anziché inserito o aggiornato. La funzione deve restituire il valore della stringa "true" o "false". Valore predefinito: nessuno.
- usePartialUpdate : indica se utilizzare gli aggiornamenti parziali (update anziché creare o indicizzare, consentendo documenti parziali) con le richieste Elasticsearch. Valore predefinito: "false".
- bulkInsertMethod : se utilizzare "INDEX" (indice, consente l'upsert) o "CREATE" (crea, errori su _id duplicato) con le richieste collettive Elasticsearch. 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. Cripta 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}. Vedi: https://cloud.google.com/kms/docs/reference/rest/v1/projects.locations.keyRings.cryptoKeys/encrypt (ad esempio: projects/your-project-id/locations/global/keyRings/your-keyring/cryptoKeys/your-key-name).
- apiKeySecretId : 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 tra PLAINTEXT, KMS o SECRET_MANAGER. Questo parametro deve essere fornito se si utilizza Secret Manager o KMS. Se apiKeySource è impostato su KMS, è necessario specificare apiKeyKMSEncryptionKey e l'apiKey criptata. Se apiKeySource è impostato su SECRET_MANAGER, è necessario specificare apiKeySecretId. Se apiKeySource è impostato su PLAINTEXT, è necessario specificare l'API apiKey. Il valore predefinito è: PLAINTEXT.
Funzioni definite dall'utente
Questo modello supporta le funzioni definite dall'utente in diversi punti della pipeline, descritta di seguito. Per ulteriori informazioni, consulta Creare funzioni definite dall'utente per i modelli Dataflow.
Funzione di trasformazione del testo
Trasforma il messaggio Pub/Sub in un documento Elasticsearch.
Parametri del modello:
javascriptTextTransformGcsPath
: l'URI Cloud Storage del file JavaScript.javascriptTextTransformFunctionName
: il nome della funzione JavaScript.
Specifica della funzione:
- Input: il campo dati del messaggio Pub/Sub, serializzato come stringa JSON.
- Output: un documento JSON con stringhe da inserire in Elasticsearch.
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.
Specifica della funzione:
- Input: il documento Elasticsearch, serializzato come stringa JSON.
- Output: il valore del campo di metadati
_index
del documento.
Funzione ID documento
Restituisce l'ID del 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 del campo di metadati
_id
del documento.
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"
per eliminare il documento o"false"
per eseguire l'upsert del documento.
Funzione tipo di mappatura
Restituisce il tipo di mappatura del documento.
Parametri del modello:
javaScriptTypeFnGcsPath
: l'URI Cloud Storage del file JavaScript.javaScriptTypeFnName
: il nome della funzione JavaScript.
Specifica della funzione:
- Input: il documento Elasticsearch, serializzato come stringa JSON.
- Output: il valore del campo di metadati
_type
del documento.
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 Pub/Sub to Elasticsearch template.
- Inserisci i valori parametro negli appositi campi.
- 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/PubSub_to_Elasticsearch \ --parameters \ inputSubscription=SUBSCRIPTION_NAME,\ connectionUrl=CONNECTION_URL,\ dataset=DATASET,\ namespace=NAMESPACE,\ apiKey=APIKEY,\ errorOutputTopic=ERROR_OUTPUT_TOPIC
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 sceltaREGION_NAME
: 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 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/
ERROR_OUTPUT_TOPIC
: l'argomento Pub/Sub per l'output degli erroriSUBSCRIPTION_NAME
: nome della sottoscrizione Pub/SubCONNECTION_URL
: il tuo URL di ElasticsearchDATASET
: il tuo tipo di logNAMESPACE
: il tuo spazio dei nomi per il set di datiAPIKEY
: la tua chiave API codificata in Base64 per l'autenticazione
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 { "launch_parameter": { "jobName": "JOB_NAME", "parameters": { "inputSubscription": "SUBSCRIPTION_NAME", "connectionUrl": "CONNECTION_URL", "dataset": "DATASET", "namespace": "NAMESPACE", "apiKey": "APIKEY", "errorOutputTopic": "ERROR_OUTPUT_TOPIC" }, "containerSpecGcsPath": "gs://dataflow-templates-LOCATION/VERSION/flex/PubSub_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 a 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 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/
ERROR_OUTPUT_TOPIC
: l'argomento Pub/Sub per l'output degli erroriSUBSCRIPTION_NAME
: nome della sottoscrizione Pub/SubCONNECTION_URL
: il tuo URL di ElasticsearchDATASET
: il tuo tipo di logNAMESPACE
: il tuo spazio dei nomi per il set di datiAPIKEY
: la tua chiave API codificata in Base64 per l'autenticazione
Passaggi successivi
- Scopri di più sui modelli Dataflow.
- Consulta l'elenco dei modelli forniti da Google.