Crie e execute um exemplo de modelo flexível no Dataflow

Os modelos flexíveis do Dataflow permitem-lhe criar um pacote de um pipeline do Dataflow para implementação. Este tutorial mostra como criar um exemplo de modelo flexível e, em seguida, executar uma tarefa do Dataflow usando esse modelo.

Objetivos

• Crie um modelo flexível do Dataflow.
• Use o modelo para executar uma tarefa do Dataflow.

Custos

Neste documento, usa os seguintes componentes faturáveis da Google Cloud Platform:

• Dataflow
• Cloud Storage
• Artifact Registry

Para gerar uma estimativa de custos com base na sua utilização prevista, use a calculadora de preços.

Os novos Google Cloud utilizadores podem ser elegíveis para uma avaliação gratuita.

Quando terminar as tarefas descritas neste documento, pode evitar a faturação contínua eliminando os recursos que criou. Para mais informações, consulte o artigo Limpe.

Antes de começar

Sign in to your Google Cloud Platform account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
Install the Google Cloud CLI.
Se estiver a usar um fornecedor de identidade (IdP) externo, tem primeiro de iniciar sessão na CLI gcloud com a sua identidade federada.
Para inicializar a CLI gcloud, execute o seguinte comando:
gcloud init
Create or select a Google Cloud project.
Roles required to select or create a project
• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.
Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.
• Create a Google Cloud project:

  gcloud projects create PROJECT_ID

  Replace PROJECT_ID with a name for the Google Cloud project you are creating.

• Select the Google Cloud project that you created:

  gcloud config set project PROJECT_ID

  Replace PROJECT_ID with your Google Cloud project name.
Verify that billing is enabled for your Google Cloud project.
Enable the Dataflow, Compute Engine, Logging, Cloud Storage, Cloud Storage JSON, Resource Manager, and Artifact Registry API:
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.
gcloud services enable dataflow compute_component logging storage_component storage_api cloudresourcemanager.googleapis.com artifactregistry.googleapis.com
If you're using a local shell, then create local authentication credentials for your user account:
gcloud auth application-default login
You don't need to do this if you're using Cloud Shell.
If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.
Grant roles to your user account. Run the following command once for each of the following IAM roles: roles/iam.serviceAccountUser
gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE
Replace the following:
• PROJECT_ID: Your project ID.
• USER_IDENTIFIER: The identifier for your user account. For example, [e-mail].
• ROLE: The IAM role that you grant to your user account.

Install the Google Cloud CLI.

Se estiver a usar um fornecedor de identidade (IdP) externo, tem primeiro de iniciar sessão na CLI gcloud com a sua identidade federada.

Para inicializar a CLI gcloud, execute o seguinte comando:

gcloud init

Create or select a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

• Create a Google Cloud project:

  gcloud projects create PROJECT_ID

  Replace PROJECT_ID with a name for the Google Cloud project you are creating.

• Select the Google Cloud project that you created:

  gcloud config set project PROJECT_ID

  Replace PROJECT_ID with your Google Cloud project name.

Verify that billing is enabled for your Google Cloud project.

Enable the Dataflow, Compute Engine, Logging, Cloud Storage, Cloud Storage JSON, Resource Manager, and Artifact Registry API:

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

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

If you're using a local shell, then create local authentication credentials for your user account:

gcloud auth application-default login

You don't need to do this if you're using Cloud Shell.

If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

Grant roles to your user account. Run the following command once for each of the following IAM roles: roles/iam.serviceAccountUser

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

Replace the following:

• PROJECT_ID: Your project ID.
• USER_IDENTIFIER: The identifier for your user account. For example, [e-mail].
• ROLE: The IAM role that you grant to your user account.

1. Conceda funções à conta de serviço predefinida do Compute Engine. Execute o seguinte comando uma vez para cada uma das seguintes funções do 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

   Substitua o seguinte:

   • PROJECT_ID: o ID do seu projeto
   • PROJECT_NUMBER o seu número do projeto
   • SERVICE_ACCOUNT_ROLE: cada função individual

Prepare o ambiente

Instale o SDK e todos os requisitos para o seu ambiente de programação.

Java

1. Transfira e instale a versão 17 do Java Development Kit (JDK). Verifique se a variável de ambiente JAVA_HOME está definida e aponta para a instalação do JDK.

2. Transfira e instale o Apache Maven seguindo o guia de instalação do Maven para o seu sistema operativo específico.

Python

Instale o SDK Apache Beam para Python.

Ir

Use o guia de transferência e instalação do Go para transferir e instalar o Go para o seu sistema operativo específico. Para saber que ambientes de execução do Go são suportados pelo Apache Beam, consulte o artigo Suporte de execução do Apache Beam.

Transfira o exemplo de código.

Java

1. Clone o repositório java-docs-samples.

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

2. Navegue para o exemplo de código deste tutorial.

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

3. Crie o projeto Java num ficheiro JAR Uber.

   mvn clean package

   Este ficheiro JAR Uber tem todas as dependências incorporadas. Pode executar este ficheiro como uma aplicação autónoma sem dependências externas noutras bibliotecas.

Python

1. Clone o repositório python-docs-samples.

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

2. Navegue para o exemplo de código deste tutorial.

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

Ir

1. Clone o repositório golang-samples.

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

2. Navegue para o exemplo de código deste tutorial.

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

3. Compile o binário Go.

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

Crie um contentor do Cloud Storage

Use o comando gcloud storage buckets create para criar um contentor do Cloud Storage:

gcloud storage buckets create gs://BUCKET_NAME

Substitua BUCKET_NAME por um nome para o seu contentor do Cloud Storage. Os nomes dos contentores do Cloud Storage têm de ser globalmente únicos e cumprir os requisitos de nomenclatura de contentores.

Crie um repositório do Artifact Registry

Crie um repositório do Artifact Registry onde vai enviar a imagem do contentor Docker para o modelo.

1. Use o comando gcloud artifacts repositories create para criar um novo repositório do Artifact Registry.

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

   Substitua o seguinte:

   • REPOSITORY: um nome para o seu repositório. Os nomes dos repositórios têm de ser exclusivos para cada localização de repositório num projeto.
   • LOCATION: a localização regional ou multirregional do repositório.

2. Use o comando gcloud auth configure-docker para configurar o Docker de modo a autenticar pedidos para o Artifact Registry. Este comando atualiza a configuração do Docker para que possa estabelecer ligação ao Artifact Registry para enviar imagens.

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

Os modelos flexíveis também podem usar imagens armazenadas em registos privados. Para mais informações, consulte o artigo Use uma imagem de um registo privado.

Crie o modelo flexível

Neste passo, usa o comando gcloud dataflow flex-template build para criar o modelo flexível.

Um modelo flexível é composto pelos seguintes componentes:

• Uma imagem de contentor do Docker que inclui o código do pipeline. Para os modelos flexíveis Java e Python, a imagem do Docker é criada e enviada para o repositório do Artifact Registry quando executa o comando gcloud dataflow flex-template build.
• Um ficheiro de especificação de modelo. Este ficheiro é um documento JSON que contém a localização da imagem do contentor, além de metadados sobre o modelo, como parâmetros do pipeline.

O repositório de exemplo no GitHub contém o ficheiro metadata.json.

• java-docs-samples repositório
• python-docs-samples repositório
• golang-samples repositório

Para estender o seu modelo com metadados adicionais, pode criar o seu próprio ficheiro 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"

Substitua o seguinte:

• BUCKET_NAME: o nome do contentor do Cloud Storage que criou anteriormente
• LOCATION: a localização
• PROJECT_ID: o Google Cloud ID do projeto
• REPOSITORY: o nome do repositório do Artifact Registry que criou anteriormente

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"

Substitua o seguinte:

• BUCKET_NAME: o nome do contentor do Cloud Storage que criou anteriormente
• LOCATION: a localização
• PROJECT_ID: o Google Cloud ID do projeto
• REPOSITORY: o nome do repositório do Artifact Registry que criou anteriormente

Ir

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"

Substitua o seguinte:

• BUCKET_NAME: o nome do contentor do Cloud Storage que criou anteriormente.
• LOCATION: a localização
• PROJECT_ID: o Google Cloud ID do projeto
• REPOSITORY: o nome do repositório do Artifact Registry que criou anteriormente

Execute o modelo flexível

Neste passo, usa o modelo para executar uma tarefa do Dataflow.

Java

1. Use o comando gcloud dataflow flex-template run para executar uma tarefa do Dataflow que usa o modelo flexível.

   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"

   Substitua o seguinte:

   • BUCKET_NAME: o nome do contentor do Cloud Storage que criou anteriormente
   • REGION: a região

2. Para ver o estado da tarefa do Dataflow na Google Cloud consola, aceda à página Tarefas do Dataflow.

   Aceder a Empregos

Se a tarefa for executada com êxito, escreve o resultado num ficheiro denominado gs://BUCKET_NAME/output--00000-of-00001.txt no seu contentor do Cloud Storage.

Python

1. Use o comando gcloud dataflow flex-template run para executar uma tarefa do Dataflow que usa o modelo flexível.

   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"

   Substitua o seguinte:

   • BUCKET_NAME: o nome do contentor do Cloud Storage que criou anteriormente
   • REGION: a região

2. Para ver o estado da tarefa do Dataflow na Google Cloud consola, aceda à página Tarefas do Dataflow.

   Aceder a Empregos

Se a tarefa for executada com êxito, escreve o resultado num ficheiro denominado gs://BUCKET_NAME/output--00000-of-00001.txt no seu contentor do Cloud Storage.

Ir

1. Use o comando gcloud dataflow flex-template run para executar uma tarefa do Dataflow que usa o modelo flexível.

   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"

   Substitua o seguinte:

   • BUCKET_NAME: o nome do contentor do Cloud Storage que criou anteriormente
   • REGION: a região

2. Para ver o estado da tarefa do Dataflow na Google Cloud consola, aceda à página Tarefas do Dataflow.

   Aceder a Empregos

Se a tarefa for executada com êxito, escreve a saída num ficheiro denominado gs://BUCKET_NAME/samples/dataflow/templates/count.txt no seu contentor do Cloud Storage.

Se a tarefa não for executada e for apresentada a mensagem de erro A Timeout in polling error message, consulte o artigo Resolva problemas de tempo limite de modelos flexíveis.

Limpar

Para evitar incorrer em custos na sua conta do Google Cloud pelos recursos usados neste tutorial, elimine o projeto que contém os recursos ou mantenha o projeto e elimine os recursos individuais.

Elimine o projeto

Atenção: a eliminação de um projeto tem os seguintes efeitos:

• Tudo no projeto é eliminado. Se usou um projeto existente para as tarefas neste documento, quando o elimina, também elimina qualquer outro trabalho que tenha feito no projeto.
• Os IDs dos projetos personalizados são perdidos. Quando criou este projeto, pode ter criado um ID do projeto personalizado que quer usar no futuro. Para preservar os URLs que usam o ID do projeto, como um URL appspot.com, elimine os recursos selecionados no projeto em vez de eliminar o projeto inteiro.

Se planeia explorar várias arquiteturas, tutoriais ou inícios rápidos, a reutilização de projetos pode ajudar a evitar exceder os limites de quota de projetos.

Delete a Google Cloud project:

gcloud projects delete PROJECT_ID

Elimine recursos individuais

1. Elimine o contentor do Cloud Storage e todos os objetos no contentor.

   gcloud storage rm gs://BUCKET_NAME --recursive

2. Elimine o repositório do Artifact Registry.

   gcloud artifacts repositories delete REPOSITORY \
       --location=LOCATION

3. Revogue as funções que concedeu à conta de serviço predefinida do Compute Engine. Execute o seguinte comando uma vez para cada uma das seguintes funções do 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. Optional: Revoke the authentication credentials that you created, and delete the local credential file.

   gcloud auth application-default revoke

5. Optional: Revoke credentials from the gcloud CLI.

   gcloud auth revoke

O que se segue?

• Use modelos flexíveis para criar um pacote de um pipeline do Dataflow.
• Consulte a lista de modelos fornecidos pela Google.