Modelli Dataflow

I modelli Dataflow consentono di pacchettizzare una pipeline Dataflow per il deployment. Chiunque disponga delle autorizzazioni corrette può quindi utilizzare il template per eseguire il deployment della pipeline pacchettizzata. Puoi creare i tuoi template Dataflow personalizzati e Google fornisce template predefiniti per scenari comuni.

Vantaggi

I modelli offrono diversi vantaggi rispetto al deployment diretto di una pipeline in Dataflow:

  • I modelli separano la progettazione della pipeline dal deployment. Ad esempio, uno sviluppatore può creare un modello e un data scientist può eseguirne il deployment in un secondo momento.
  • I modelli possono avere parametri che ti consentono di personalizzare la pipeline quando esegui il deployment del modello.
  • Puoi eseguire il deployment di un template utilizzando la console Google Cloud , Google Cloud CLI o le chiamate API REST. Non è necessario un ambiente di sviluppo o dipendenze della pipeline installate sulla tua macchina locale.
  • Un template è un artefatto di codice che può essere archiviato in un repository di controllo del codice sorgente e utilizzato nelle pipeline di integrazione continua (CI/CD).

Modelli forniti da Google

Google fornisce una serie di modelli Dataflow open source predefiniti che puoi utilizzare per scenari comuni. Per saperne di più sui modelli disponibili, consulta Modelli forniti da Google.

Confronta i template flessibili e i modelli classici

Dataflow supporta due tipi di template: i template flessibili, che sono più recenti, e i modelli classici. Se stai creando un nuovo template Dataflow, ti consigliamo di crearlo come modello flessibile.

Con un modello flessibile, la pipeline viene pacchettizzata come immagine Docker in Artifact Registry, insieme a un file di specifica del template in Cloud Storage. La specifica del template contiene un puntatore all'immagine Docker. Quando esegui il template, il servizio Dataflow avvia una VM di lancio, esegue il pull dell'immagine Docker ed esegue la pipeline. Il grafico di esecuzione viene creato dinamicamente in base ai parametri di runtime forniti dall'utente. Per utilizzare l'API per avviare un job che utilizza un modello flessibile, utilizza il metodo projects.locations.flexTemplates.launch.

Un modello classico contiene la serializzazione JSON di un grafico dei job Dataflow. Il codice della pipeline deve aggregare tutti i parametri di runtime nell'interfaccia ValueProvider. Questa interfaccia consente agli utenti di specificare i valori parametro quando eseguono il deployment del modello. Per utilizzare l'API per lavorare con i modelli classici, consulta la documentazione di riferimento dell'API projects.locations.templates.

I template flessibili offrono i seguenti vantaggi rispetto ai modelli classici:

  • A differenza dei modelli classici, i modelli flessibili non richiedono l'interfaccia ValueProvider per i parametri di input. Non tutte le origini e i sink di Dataflow supportano ValueProvider.
  • Mentre i modelli classici hanno un grafico dei job statico, i template flessibili possono creare dinamicamente il grafico dei job. Ad esempio, il modello potrebbe selezionare un connettore di I/O diverso in base ai parametri di input.
  • Un modello flessibile può eseguire la pre-elaborazione su una macchina virtuale (VM) durante la costruzione della pipeline. Ad esempio, potrebbe convalidare i valori dei parametri di input.

Workflow del template

L'utilizzo dei template Dataflow prevede i seguenti passaggi generali:

  1. Gli sviluppatori configurano un ambiente di sviluppo e sviluppano la pipeline. L'ambiente include l'SDK Apache Beam e altre dipendenze.
  2. A seconda del tipo di template (flessibile o classico):
    • Per i template flessibili, gli sviluppatori pacchettizzano la pipeline in un'immagine Docker, eseguono il push dell'immagine in Artifact Registry e caricano un file di specifica del template in Cloud Storage.
    • Per i modelli classici, gli sviluppatori eseguono la pipeline, creano un file di modello e ne eseguono lo stage in Cloud Storage.
  3. Altri utenti inviano una richiesta al servizio Dataflow per eseguire il template.
  4. Dataflow crea una pipeline dal template. L'avvio della pipeline può richiedere da cinque a sette minuti.

Ispeziona e controlla i job dei template

Quando controlli i job dei template Dataflow in esecuzione o storici in modo programmatico utilizzando l'API REST o Google Cloud CLI, la visualizzazione predefinita è una visualizzazione di riepilogo (JOB_VIEW_SUMMARY). La visualizzazione di riepilogo omette i dettagli di esecuzione della pipeline, i metadati del template e le opzioni della pipeline dell'SDK. Per recuperare i dettagli del template e le opzioni dell'ambiente, devi richiedere esplicitamente la visualizzazione completa del job.

Per esaminare i dettagli del template di un job, utilizza uno dei seguenti metodi:

gcloud CLI

Per recuperare la descrizione completa del job, inclusi i dettagli del template, esegui il comando gcloud dataflow jobs describe con il flag --full:

Prima di utilizzare i dati dei comandi riportati di seguito, effettua le seguenti sostituzioni:

  • REGION: la regione Dataflow in cui è in esecuzione il job.
  • JOB_ID: l'ID del job Dataflow.

Esegui questo comando:

Linux, macOS o Cloud Shell

gcloud dataflow jobs describe JOB_ID --full --region=REGION

Windows (PowerShell)

gcloud dataflow jobs describe JOB_ID --full --region=REGION

Windows (cmd.exe)

gcloud dataflow jobs describe JOB_ID --full --region=REGION

Dovresti ricevere una risposta simile alla seguente:

environment:
  sdkPipelineOptions:
    options:
      templateLocation: gs://BUCKET_NAME/templates/TEMPLATE_NAME
id: JOB_ID
name: JOB_NAME
type: JOB_TYPE_BATCH

REST

Per recuperare la risorsa del job completa, inclusi i dettagli del template, invia una richiesta HTTP GET al metodo projects.locations.jobs.get con il parametro di query view=JOB_VIEW_ALL:

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • PROJECT_ID: il tuo ID progetto Google Cloud .
  • REGION: la regione Dataflow in cui è in esecuzione il job.
  • JOB_ID: l'ID del job Dataflow.

Metodo HTTP e URL: 

GET https://dataflow.googleapis.com/v1b3/projects/PROJECT_ID/locations/REGION/jobs/JOB_ID?view=JOB_VIEW_ALL

Per inviare la richiesta, scegli una di queste opzioni:

curl

Esegui questo comando: 

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://dataflow.googleapis.com/v1b3/projects/PROJECT_ID/locations/REGION/jobs/JOB_ID?view=JOB_VIEW_ALL"

PowerShell

Esegui questo comando: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://dataflow.googleapis.com/v1b3/projects/PROJECT_ID/locations/REGION/jobs/JOB_ID?view=JOB_VIEW_ALL" | Select-Object -Expand Content

Dovresti ricevere una risposta JSON simile alla seguente:

{
  "id": "JOB_ID",
  "name": "JOB_NAME",
  "type": "JOB_TYPE_BATCH",
  "environment": {
    "sdkPipelineOptions": {
      "options": {
        "templateLocation": "gs://BUCKET_NAME/templates/TEMPLATE_NAME"
      }
    }
  }
}

Identifica i tipi di modelli

Il payload della risposta varia a seconda che il job sia stato creato da un modello fornito da Google o da un modello personalizzato:

  • Modelli forniti da Google: Dataflow collega automaticamente etichette predefinite alla risorsa del job:
    • goog-dataflow-provided-template-name: il nome del template.
    • goog-dataflow-provided-template-type: il tipo di template, flex o legacy (classico).
    • goog-dataflow-provided-template-version: la versione di release del template.
  • Modelli personalizzati: i job dei modelli personalizzati non hanno le etichette goog-dataflow-provided-*. I job dei modelli flessibili e classici compilano l'opzione templateLocation in environment.sdkPipelineOptions. Per determinare il tipo di template per i job personalizzati quando le etichette sono assenti, controlla i seguenti campi nella risposta completa del job (JOB_VIEW_ALL):
    • Modelli classici: il campo templateLocation punta direttamente al file JSON del modello di gestione temporanea in Cloud Storage. Ad esempio, il percorso è simile a gs://BUCKET_NAME/templates/TEMPLATE_NAME. I job con modelli classici non hanno configurazioni di immagini del launcher di container.
    • Template flessibili: i job modello flessibile vengono eseguiti da un'immagine container di avvio. Nell'oggetto environment, i job modello flessibile contengono le specifiche e i parametri del container di avvio (come flexResourceLimits). Inoltre, il percorso di Cloud Storage templateLocation di gestione temporanea generato durante l'avvio contiene l'ID job.

Best practice: applica le etichette utente durante il lancio

Poiché la distinzione dei tipi di modelli personalizzati in modo programmatico richiede il recupero e l'analisi delle opzioni dell'ambiente JOB_VIEW_ALL complete, ti consigliamo di allegare etichette utente descrittive quando avvii i job dei modelli. Ad esempio, allega etichette come template-type: flex o template-type: classic.

Le etichette utente vengono restituite nella visualizzazione di riepilogo predefinita (JOB_VIEW_SUMMARY) e nelle operazioni di elenco dei job. Le etichette utente ti consentono di filtrare, cercare e controllare i job dei modelli in modo efficiente nel tuo progetto senza recuperare il payload di esecuzione completo per ogni job.

Per collegare le etichette quando avvii un template, utilizza i seguenti metodi:

  • Per i template flessibili in gcloud CLI, utilizza il flag --additional-user-labels nel comando gcloud dataflow flex-template run.
  • Per i modelli classici in gcloud CLI, utilizza il flag --labels nel comando gcloud dataflow jobs run.
  • Quando utilizzi l'API REST, includi la mappa di coppie chiave-valore labels nel corpo della richiesta di avvio.

Imposta autorizzazioni IAM

I job Dataflow, inclusi quelli eseguiti da template, utilizzano due service account IAM:

  • Il servizio Dataflow utilizza un service account Dataflow per manipolare le risorse Google Cloud , ad esempio per creare VM.
  • Le VM worker di Dataflow utilizzano un service account worker per accedere ai file e ad altre risorse della pipeline. Questo account di servizio deve avere accesso a tutte le risorse a cui fa riferimento il job della pipeline, inclusi l'origine e il sink utilizzati dal template. Per saperne di più, consulta Accedi alle risorse Google Cloud .

Assicurati che questi due service account dispongano dei ruoli appropriati. Per saperne di più, consulta Sicurezza e autorizzazioni di Dataflow.

Se la tua organizzazione utilizza le policy dei confini di accesso dell'entità (PAB), alle entità (come utenti o service account) potrebbe essere impedito di visualizzare ed eseguire i template forniti da Google. Per ulteriori informazioni e soluzioni, consulta Accedi ai template forniti da Google con le policy sul confine di accesso dell'entità.

Requisiti della versione dell'SDK Apache Beam

Per creare i tuoi template, assicurati che la versione dell'SDK Apache Beam supporti la creazione di template.

Java

Per creare modelli con l'SDK Apache Beam 2.x per Java, devi avere la versione 2.0.0-beta3 o successiva.

Python

Per creare modelli con l'SDK Apache Beam 2.x per Python, devi avere la versione 2.0.0 o successive.

Per eseguire i modelli con Google Cloud CLI, devi disporre di Google Cloud CLI versione 138.0.0 o successiva.

Estendi i modelli

Puoi creare i tuoi modelli estendendo i modelli Dataflow open source. Ad esempio, per un template che utilizza una durata della finestra fissa, i dati che arrivano al di fuori della finestra potrebbero essere ignorati. Per evitare questo comportamento, utilizza il codice del template come base e modificalo per richiamare l'operazione .withAllowedLateness.

Passaggi successivi