Crea ed esegui un modello flessibile di esempio

Questo tutorial si concentra sui modelli flessibili, mostrando come creare ed eseguire una pipeline di dati containerizzata in Dataflow. Imparerai a creare pacchetti per le pipeline per un deployment efficiente utilizzando un modello flessibile di esempio.

Obiettivi

• Crea un modello flessibile Dataflow.
• Utilizza il modello per eseguire un job Dataflow.

Costi

In questo documento vengono utilizzati i seguenti componenti fatturabili di Google Cloud:

• Dataflow
• Cloud Storage
• Artifact Registry

Per generare una stima dei costi in base all'utilizzo previsto, utilizza il calcolatore prezzi.

I nuovi utenti di Google Cloud potrebbero avere diritto a una prova senza costi.

Al termine delle attività descritte in questo documento, puoi evitare l'addebito di ulteriori costi eliminando le risorse che hai creato. Per saperne di più, consulta Esegui la pulizia.

Prima di iniziare

Accedi al tuo account Google Cloud . Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti senza costi per l'esecuzione, il test e il deployment dei workload.
Installa Google Cloud CLI.
Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.
Per inizializzare gcloud CLI, esegui questo comando:
gcloud init
Crea o seleziona un Google Cloud progetto.
Ruoli richiesti per selezionare o creare un progetto
• Seleziona un progetto: la selezione di un progetto non richiede un ruolo IAM specifico. Puoi selezionare qualsiasi progetto per il quale ti è stato concesso un ruolo.
• Crea un progetto: per creare un progetto, devi disporre del ruolo Autore progetto (roles/resourcemanager.projectCreator), che contiene l'autorizzazione resourcemanager.projects.create. Scopri come concedere i ruoli.
Nota: se non prevedi di conservare le risorse che crei in questa procedura, crea un progetto invece di selezionarne uno già esistente. Una volta completata questa procedura, puoi eliminare il progetto e tutte le relative risorse.
• Creare un progetto Google Cloud :

  gcloud projects create PROJECT_ID

  Sostituisci PROJECT_ID con un nome per il progetto Google Cloud che stai creando.

• Seleziona il progetto Google Cloud che hai creato:

  gcloud config set project PROJECT_ID

  Sostituisci PROJECT_ID con il nome del progetto Google Cloud .
Verifica che la fatturazione sia abilitata per il tuo progetto Google Cloud .
Abilita le API Dataflow, Compute Engine, Logging, Cloud Storage, Cloud Storage JSON, Resource Manager e API Artifact Registry:
Ruoli richiesti per abilitare le API
Per abilitare le API, devi disporre del ruolo IAM Amministratore utilizzo dei servizi (roles/serviceusage.serviceUsageAdmin), che include l'autorizzazione serviceusage.services.enable. Scopri come concedere i ruoli.
gcloud services enable dataflow compute_component logging storage_component storage_api cloudresourcemanager.googleapis.com artifactregistry.googleapis.com
Se utilizzi una shell locale, crea credenziali di autenticazione locali per il tuo account utente:
gcloud auth application-default login
Non è necessario eseguire questa operazione se utilizzi Cloud Shell.
Se viene restituito un errore di autenticazione e utilizzi un provider di identità (IdP) esterno, verifica di aver acceduto a gcloud CLI con la tua identità federata.
Concedi ruoli al tuo account utente. Esegui il seguente comando una volta per ciascuno dei seguenti ruoli IAM: roles/iam.serviceAccountUser
gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE
Sostituisci quanto segue:
• PROJECT_ID: il tuo ID progetto.
• USER_IDENTIFIER: l'identificatore del tuo account utente . Ad esempio: [e-mail].
• ROLE: il ruolo IAM che concedi al tuo account utente.

Installa Google Cloud CLI.

Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.

Per inizializzare gcloud CLI, esegui questo comando:

gcloud init

Crea o seleziona un Google Cloud progetto.

Ruoli richiesti per selezionare o creare un progetto

• Seleziona un progetto: la selezione di un progetto non richiede un ruolo IAM specifico. Puoi selezionare qualsiasi progetto per il quale ti è stato concesso un ruolo.
• Crea un progetto: per creare un progetto, devi disporre del ruolo Autore progetto (roles/resourcemanager.projectCreator), che contiene l'autorizzazione resourcemanager.projects.create. Scopri come concedere i ruoli.

Nota: se non prevedi di conservare le risorse che crei in questa procedura, crea un progetto invece di selezionarne uno già esistente. Una volta completata questa procedura, puoi eliminare il progetto e tutte le relative risorse.

• Creare un progetto Google Cloud :

  gcloud projects create PROJECT_ID

  Sostituisci PROJECT_ID con un nome per il progetto Google Cloud che stai creando.

• Seleziona il progetto Google Cloud che hai creato:

  gcloud config set project PROJECT_ID

  Sostituisci PROJECT_ID con il nome del progetto Google Cloud .

Verifica che la fatturazione sia abilitata per il tuo progetto Google Cloud .

Abilita le API Dataflow, Compute Engine, Logging, Cloud Storage, Cloud Storage JSON, Resource Manager e API Artifact Registry:

Ruoli richiesti per abilitare le API

Per abilitare le API, devi disporre del ruolo IAM Amministratore utilizzo dei servizi (roles/serviceusage.serviceUsageAdmin), che include l'autorizzazione serviceusage.services.enable. Scopri come concedere i ruoli.

gcloud services enable dataflow compute_component logging storage_component storage_api cloudresourcemanager.googleapis.com artifactregistry.googleapis.com

Se utilizzi una shell locale, crea credenziali di autenticazione locali per il tuo account utente:

gcloud auth application-default login

Non è necessario eseguire questa operazione se utilizzi Cloud Shell.

Se viene restituito un errore di autenticazione e utilizzi un provider di identità (IdP) esterno, verifica di aver acceduto a gcloud CLI con la tua identità federata.

Concedi ruoli al tuo account utente. Esegui il seguente comando una volta per ciascuno dei seguenti ruoli IAM: roles/iam.serviceAccountUser

gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE

Sostituisci quanto segue:

• PROJECT_ID: il tuo ID progetto.
• USER_IDENTIFIER: l'identificatore del tuo account utente . Ad esempio: [e-mail].
• ROLE: il ruolo IAM che concedi al tuo account utente.

1. Concedi ruoli al account di servizio Compute Engine predefinito. Esegui il seguente comando una volta per ciascuno dei seguenti ruoli IAM:

   • roles/dataflow.admin
   • roles/dataflow.worker
   • roles/storage.objectAdmin
   • roles/artifactregistry.writer

   gcloud projects add-iam-policy-binding PROJECT_ID --member="serviceAccount:[e-mail]" --role=SERVICE_ACCOUNT_ROLE

   Sostituisci quanto segue:

   • PROJECT_ID: il tuo ID progetto
   • PROJECT_NUMBER il tuo Google Cloud numero di progetto
   • SERVICE_ACCOUNT_ROLE: ogni singolo ruolo

Prepara l'ambiente per i modelli flessibili

Installa l'SDK e tutti i requisiti per l'ambiente di sviluppo.

Java

1. Scarica e installa la Java Development Kit (JDK) versione 17. Verifica che la variabile di ambiente JAVA_HOME sia impostata e punti all'installazione di JDK.

2. Scarica e installa Apache Maven seguendo la guida all'installazione di Maven per il tuo sistema operativo specifico.

Python

Installa l'SDK Apache Beam per Python.

Go

Utilizza la guida al download e all'installazione di Go per scaricare e installare Go per il tuo sistema operativo specifico. Per scoprire quali ambienti di runtime Go sono supportati da Apache Beam, consulta Supporto del runtime Apache Beam.

Scarica il esempio di codice.

Java

1. Clona il repository java-docs-samples.

   git clone https://github.com/GoogleCloudPlatform/java-docs-samples.git

2. Vai al esempio di codice per questo tutorial.

   cd java-docs-samples/dataflow/flex-templates/getting_started

3. Crea il progetto Java in un file uber JAR.

   mvn clean package

   Questo file Uber JAR contiene tutte le dipendenze incorporate. Puoi eseguire questo file come applicazione autonoma senza dipendenze esterne da altre librerie.

Python

1. Clona il repository python-docs-samples.

   git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git

2. Vai al esempio di codice per questo tutorial.

   cd python-docs-samples/dataflow/flex-templates/getting_started

Go

1. Clona il repository golang-samples.

   git clone https://github.com/GoogleCloudPlatform/golang-samples.git

2. Vai al esempio di codice per questo tutorial.

   cd golang-samples/dataflow/flex-templates/wordcount

3. Compila il binario Go.

   CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o wordcount .

Crea un bucket Cloud Storage per la pipeline di dati

Utilizza il comando gcloud storage buckets create per creare un bucket Cloud Storage:

gcloud storage buckets create gs://BUCKET_NAME

Sostituisci BUCKET_NAME con un nome per il tuo bucket Cloud Storage. I nomi dei bucket Cloud Storage devono essere univoci a livello globale e soddisfare i requisiti di denominazione dei bucket.

Crea un repository Artifact Registry

Crea un repository Artifact Registry in cui eseguire il push dell'immagine container Docker per il modello.

1. Utilizza il comando gcloud artifacts repositories create per creare un nuovo repository Artifact Registry.

   gcloud artifacts repositories create REPOSITORY \
    --repository-format=docker \
    --location=LOCATION

   Sostituisci quanto segue:

   • REPOSITORY: un nome per il repository. I nomi dei repository devono essere univoci per ogni posizione del repository in un progetto.
   • LOCATION: la posizione regionale o multiregionale per il repository.

2. Utilizza il comando gcloud auth configure-docker per configurare Docker in modo da autenticare le richieste per Artifact Registry. Questo comando aggiorna la configurazione Docker, in modo da poterti connettere ad Artifact Registry per eseguire il push delle immagini.

   gcloud auth configure-docker LOCATION-docker.pkg.dev

I modelli flessibili possono utilizzare anche immagini archiviate in registri privati. Per saperne di più, consulta Utilizzare un'immagine di un registro privato.

Crea il modello flessibile Dataflow

In questo passaggio, utilizzi il comando gcloud dataflow flex-template build per creare il modello flessibile.

Un modello flessibile è costituito dai seguenti componenti:

• Un'immagine container Docker che contiene il codice della pipeline, formando una pipeline di dati containerizzata. Per i modelli flessibili Java e Python, l'immagine Docker viene creata e ne viene eseguito il push nel repository Artifact Registry quando esegui il comando gcloud dataflow flex-template build.
• Un file di specifica del modello. Questo file è un documento JSON che contiene la posizione dell'immagine del container e i metadati relativi al modello, ad esempio i parametri della pipeline.

Il repository di esempio in GitHub contiene il file metadata.json.

• Repository java-docs-samples
• Repository python-docs-samples
• Repository golang-samples

Per estendere il modello con metadati aggiuntivi, puoi creare il tuo file metadata.json.

Java

gcloud dataflow flex-template build gs://BUCKET_NAME/getting_started-java.json \
 --image-gcr-path "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/getting-started-java:latest" \
 --sdk-language "JAVA" \
 --flex-template-base-image JAVA17 \
 --metadata-file "metadata.json" \
 --jar "target/flex-template-getting-started-1.0.jar" \
 --env FLEX_TEMPLATE_JAVA_MAIN_CLASS="com.example.dataflow.FlexTemplateGettingStarted"

Sostituisci quanto segue:

• BUCKET_NAME: il nome del bucket Cloud Storage che hai creato in precedenza
• LOCATION: la posizione
• PROJECT_ID: l' Google Cloud ID progetto
• REPOSITORY: il nome del repository Artifact Registry che hai creato in precedenza

Python

gcloud dataflow flex-template build gs://BUCKET_NAME/getting_started-py.json \
 --image-gcr-path "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/getting-started-python:latest" \
 --sdk-language "PYTHON" \
 --flex-template-base-image "PYTHON3" \
 --metadata-file "metadata.json" \
 --py-path "." \
 --env "FLEX_TEMPLATE_PYTHON_PY_FILE=getting_started.py" \
 --env "FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE=requirements.txt"

Sostituisci quanto segue:

• BUCKET_NAME: il nome del bucket Cloud Storage che hai creato in precedenza
• LOCATION: la posizione
• PROJECT_ID: l' Google Cloud ID progetto
• REPOSITORY: il nome del repository Artifact Registry che hai creato in precedenza

Go

gcloud dataflow flex-template build gs://BUCKET_NAME/samples/dataflow/templates/wordcount-go.json \
 --image-gcr-path "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/dataflow/wordcount-go:latest" \
 --sdk-language "GO" \
 --flex-template-base-image "GO" \
 --metadata-file "metadata.json" \
 --go-binary-path="." \
 --env "FLEX_TEMPLATE_GO_BINARY=wordcount"

Sostituisci quanto segue:

• BUCKET_NAME: il nome del bucket Cloud Storage che hai creato in precedenza.
• LOCATION: la posizione
• PROJECT_ID: l' Google Cloud ID progetto
• REPOSITORY: il nome del repository Artifact Registry che hai creato in precedenza

Esegui il modello flessibile

In questo passaggio, utilizzi il modello per eseguire un job Dataflow.

Java

1. Utilizza il comando gcloud dataflow flex-template run per eseguire un job Dataflow che utilizza il modello flessibile.

   gcloud dataflow flex-template run "getting-started-`date +%Y%m%d-%H%M%S`" \
    --template-file-gcs-location "gs://BUCKET_NAME/getting_started-java.json" \
    --parameters output="gs://BUCKET_NAME/output-" \
    --region "REGION"

   Sostituisci quanto segue:

   • BUCKET_NAME: il nome del bucket Cloud Storage che hai creato in precedenza
   • REGION: la regione

2. Per visualizzare lo stato del job Dataflow nella consoleGoogle Cloud , vai alla pagina Job di Dataflow.

   Vai a Job

Se il job viene eseguito correttamente, scrive l'output in un file denominato gs://BUCKET_NAME/output--00000-of-00001.txt nel bucket Cloud Storage.

Python

1. Utilizza il comando gcloud dataflow flex-template run per eseguire un job Dataflow che utilizza il modello flessibile.

   gcloud dataflow flex-template run "getting-started-`date +%Y%m%d-%H%M%S`" \
    --template-file-gcs-location "gs://BUCKET_NAME/getting_started-py.json" \
    --parameters output="gs://BUCKET_NAME/output-" \
    --region "REGION"

   Sostituisci quanto segue:

   • BUCKET_NAME: il nome del bucket Cloud Storage che hai creato in precedenza
   • REGION: la regione

2. Per visualizzare lo stato del job Dataflow nella consoleGoogle Cloud , vai alla pagina Job di Dataflow.

   Vai a Job

Se il job viene eseguito correttamente, scrive l'output in un file denominato gs://BUCKET_NAME/output--00000-of-00001.txt nel bucket Cloud Storage.

Go

1. Utilizza il comando gcloud dataflow flex-template run per eseguire un job Dataflow che utilizza il modello flessibile.

   gcloud dataflow flex-template run "wordcount-go-`date +%Y%m%d-%H%M%S`" \
    --template-file-gcs-location "gs://BUCKET_NAME/samples/dataflow/templates/wordcount-go.json" \
    --parameters output="gs://BUCKET_NAME/samples/dataflow/templates/counts.txt" \
    --region "REGION"

   Sostituisci quanto segue:

   • BUCKET_NAME: il nome del bucket Cloud Storage che hai creato in precedenza
   • REGION: la regione

2. Per visualizzare lo stato del job Dataflow nella consoleGoogle Cloud , vai alla pagina Job di Dataflow.

   Vai a Job

Se il job viene eseguito correttamente, scrive l'output in un file denominato gs://BUCKET_NAME/samples/dataflow/templates/count.txt nel bucket Cloud Storage.

Se il job non viene eseguito e ricevi il seguente messaggio di errore, consulta la sezione Risoluzione dei problemi relativi ai timeout dei modelli flessibili.

A Timeout in polling error message

Esegui la pulizia

Per evitare che al tuo Account Google Cloud vengano addebitati costi relativi alle risorse utilizzate in questo tutorial, elimina il progetto che contiene le risorse oppure mantieni il progetto ed elimina le singole risorse.

Elimina il progetto

Attenzione: l'eliminazione di un progetto ha i seguenti effetti:

• L'intero contenuto del progetto viene eliminato. Se hai utilizzato un progetto esistente per, le attività descritte in questo documento, eliminerai anche tutto il lavoro che hai svolto nel progetto.
• Gli ID progetto personalizzati non sono più disponibili. Quando hai creato questo progetto, potresti aver creato un ID progetto personalizzato che vuoi utilizzare in futuro. Per conservare gli URL che utilizzano l'ID progetto, ad esempio un URL appspot.com, elimina le risorse selezionate all'interno del progetto anziché eliminare l'intero progetto.

Se intendi esplorare più architetture, tutorial o guide rapide, puoi riutilizzare i progetti ed evitare così di superare i limiti di quota.

Elimina un progetto Google Cloud :

gcloud projects delete PROJECT_ID

Elimina singole risorse

1. Elimina il bucket Cloud Storage e tutti gli oggetti al suo interno.

   gcloud storage rm gs://BUCKET_NAME --recursive

2. Elimina il repository Artifact Registry.

   gcloud artifacts repositories delete REPOSITORY \
       --location=LOCATION

3. Revoca i ruoli che hai concesso al account di servizio Compute Engine predefinito. Esegui il seguente comando una volta per ciascuno dei seguenti ruoli IAM:
   • roles/dataflow.admin
   • roles/dataflow.worker
   • roles/storage.objectAdmin
   • roles/artifactregistry.writer

   gcloud projects remove-iam-policy-binding PROJECT_ID \
       --member=serviceAccount:[e-mail] \
       --role=SERVICE_ACCOUNT_ROLE

4. (Facoltativo) Revoca le credenziali di autenticazione che hai creato ed elimina il file delle credenziali locale.

   gcloud auth application-default revoke

5. (Facoltativo) Revoca le credenziali da gcloud CLI.

   gcloud auth revoke

Passaggi successivi

• Utilizza i modelli flessibili per pacchettizzare una pipeline Dataflow.
• Esplora i vantaggi dei modelli predefiniti e dei modelli forniti da Google per i casi d'uso comuni.