Guia de início rápido sobre o uso do Python

Neste guia de início rápido, você aprenderá a usar o SDK do Apache Beam para Python na criação de um programa que defina um pipeline. Em seguida, execute o pipeline usando um executor local direto ou um executor baseado na nuvem, como o Dataflow.

Antes de começar

1. Faça login na sua conta do Google Cloud. Se você começou a usar o Google Cloud agora, crie uma conta para avaliar o desempenho de nossos produtos em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.

2. No Console do Google Cloud, na página do seletor de projetos, selecione ou crie um projeto do Google Cloud.

   Observação: se você não pretende manter os recursos criados neste procedimento, crie um projeto novo em vez de selecionar um que já existe. Depois de concluir essas etapas, é possível excluir o projeto. Para fazer isso, basta remover todos os recursos associados a ele.

   Acessar o seletor de projetos

3. Verifique se o faturamento está ativado para seu projeto na nuvem. Saiba como confirmar se o faturamento está ativado para o projeto.

4. Ative as APIs Dataflow, Compute Engine, Cloud Logging, Cloud Storage, Google Cloud Storage JSON, BigQuery, Cloud Pub/Sub, Cloud Datastore e Cloud Resource Manager.

   Ative as APIs

5. Crie uma conta de serviço:

   1. No Console do Cloud, acesse a página Criar conta de serviço.

      Acesse Criar conta de serviço
   2. Selecione um projeto.

   3. No campo Nome da conta de serviço, insira um nome. O Console do Cloud preenche o campo ID da conta de serviço com base nesse nome.

      No campo Descrição da conta de serviço, insira uma descrição. Por exemplo, Service account for quickstart.

   4. Clique em Criar e continuar.

   5. Clique no campo Selecionar um papel.

      Em Acesso rápido, clique em Básico e em Proprietário.

      Observação: o campo Papel afeta quais recursos a conta de serviço pode acessar no projeto. É possível revogar esses papéis ou conceder outros papéis posteriormente. Em ambientes de produção, não conceda os papéis de proprietário, editor ou visualizador. Em vez disso, conceda um papel predefinido ou um papel personalizado que atenda às suas necessidades.
   6. Clique em Continuar.

   7. Clique em Concluído para terminar a criação da conta de serviço.

      Não feche a janela do navegador. Você vai usá-lo na próxima etapa.

6. Crie uma chave de conta de serviço:

   1. No Console do Cloud, clique no endereço de e-mail da conta de serviço que você criou.
   2. Clique em Chaves.
   3. Clique em Adicionar chave e em Criar nova chave.
   4. Clique em Criar. O download de um arquivo de chave JSON é feito no seu computador.
   5. Clique em Fechar.

7. Defina a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS como o caminho do arquivo JSON que contém a chave da conta de serviço. Essa variável só se aplica à sessão de shell atual. Dessa maneira, se você abrir uma nova sessão, defina a variável novamente.

   Exemplo: Linux ou macOS

   export GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

   Substitua KEY_PATH pelo caminho do arquivo JSON que contém a chave da conta de serviço.

   Exemplo:

   export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"

   Exemplo: Windows

   Para PowerShell:

   $env:GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

   Substitua KEY_PATH pelo caminho do arquivo JSON que contém a chave da conta de serviço.

   Exemplo:

   $env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\service-account-file.json"

   Para prompt de comando:

   set GOOGLE_APPLICATION_CREDENTIALS=KEY_PATH

   Substitua KEY_PATH pelo caminho do arquivo JSON que contém a chave da conta de serviço.

8. No Console do Google Cloud, na página do seletor de projetos, selecione ou crie um projeto do Google Cloud.

   Observação: se você não pretende manter os recursos criados neste procedimento, crie um projeto novo em vez de selecionar um que já existe. Depois de concluir essas etapas, é possível excluir o projeto. Para fazer isso, basta remover todos os recursos associados a ele.

   Acessar o seletor de projetos

9. Verifique se o faturamento está ativado para seu projeto na nuvem. Saiba como confirmar se o faturamento está ativado para o projeto.

10. Ative as APIs Dataflow, Compute Engine, Cloud Logging, Cloud Storage, Google Cloud Storage JSON, BigQuery, Cloud Pub/Sub, Cloud Datastore e Cloud Resource Manager.

    Ative as APIs

11. Crie uma conta de serviço:

    1. No Console do Cloud, acesse a página Criar conta de serviço.

       Acesse Criar conta de serviço
    2. Selecione um projeto.

    3. No campo Nome da conta de serviço, insira um nome. O Console do Cloud preenche o campo ID da conta de serviço com base nesse nome.

       No campo Descrição da conta de serviço, insira uma descrição. Por exemplo, Service account for quickstart.

    4. Clique em Criar e continuar.

    5. Clique no campo Selecionar um papel.

       Em Acesso rápido, clique em Básico e em Proprietário.

       Observação: o campo Papel afeta quais recursos a conta de serviço pode acessar no projeto. É possível revogar esses papéis ou conceder outros papéis posteriormente. Em ambientes de produção, não conceda os papéis de proprietário, editor ou visualizador. Em vez disso, conceda um papel predefinido ou um papel personalizado que atenda às suas necessidades.
    6. Clique em Continuar.

    7. Clique em Concluído para terminar a criação da conta de serviço.

       Não feche a janela do navegador. Você vai usá-lo na próxima etapa.

12. Crie uma chave de conta de serviço:

    1. No Console do Cloud, clique no endereço de e-mail da conta de serviço que você criou.
    2. Clique em Chaves.
    3. Clique em Adicionar chave e em Criar nova chave.
    4. Clique em Criar. O download de um arquivo de chave JSON é feito no seu computador.
    5. Clique em Fechar.

13. Defina a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS como o caminho do arquivo JSON que contém a chave da conta de serviço. Essa variável só se aplica à sessão de shell atual. Dessa maneira, se você abrir uma nova sessão, defina a variável novamente.

    Exemplo: Linux ou macOS

    export GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

    Substitua KEY_PATH pelo caminho do arquivo JSON que contém a chave da conta de serviço.

    Exemplo:

    export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"

    Exemplo: Windows

    Para PowerShell:

    $env:GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

    Substitua KEY_PATH pelo caminho do arquivo JSON que contém a chave da conta de serviço.

    Exemplo:

    $env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\service-account-file.json"

    Para prompt de comando:

    set GOOGLE_APPLICATION_CREDENTIALS=KEY_PATH

    Substitua KEY_PATH pelo caminho do arquivo JSON que contém a chave da conta de serviço.

Crie um bucket do Cloud Storage:
1. No Console do Cloud, acesse a página Navegador do Cloud Storage.

   Acessar o navegador

2. Clique em Criar bucket.
3. Na página Criar um bucket, insira as informações do seu bucket. Para ir à próxima etapa, clique em Continuar.
   • Em Nomear o bucket, insira um nome exclusivo. Não inclua informações confidenciais no nome do bucket já que o namespace dele é global e visível para o público.
   • Em Escolha um local para armazenar seus dados, faça o seguinte:
     • Selecione uma opção de Tipo de local.
     • Escolha uma opção de Local.
   • Em Escolha uma classe de armazenamento padrão para seus dados, selecione o seguinte: Standard.
   • Em Escolha como controlar o acesso a objetos, selecione uma opção de Controle de acesso.
   • Em Configurações avançadas (opcional), especifique um método de criptografia, uma política de retenção ou rótulos de bucket.
4. Clique em Criar.
14. Copie o ID do projeto do Google Cloud e o nome do bucket do Cloud Storage. Você precisará desses valores posteriormente neste documento.

Configure o ambiente

O Dataflow não é mais compatível com pipelines que usam o Python 2. Para mais informações, consulte a página Suporte para Python 2 no Google Cloud.

Nesta seção, use o prompt de comando para configurar um ambiente virtual Python isolado e executar seu projeto de pipeline usando venv. Esse processo permite isolar as dependências de um projeto das dependências de outros projetos.

Caso você não tenha um prompt de comando disponível, use o Cloud Shell. O Cloud Shell já tem o gerenciador de pacotes do Python 3 instalado, portanto, você pode pular para a criação de um ambiente virtual.

Para instalar o Python e criar um ambiente virtual, siga estas etapas:

1. Verifique se o Python 3 e o pip estão em execução no sistema:

   python --version
   python -m pip --version
   

2. Se necessário, instale o Python 3 e, em seguida, configure um ambiente virtual do Python: siga as instruções fornecidas nas seções Como instalar o Python e Como configurar o venv do Como configurar uma página do ambiente de desenvolvimento em Python.

Observação: o Cython não é obrigatório, mas se estiver instalado, a versão precisará ser 0.28.1 ou posterior. Para verificar a versão do Cython, execute pip show cython.

Depois de concluir o guia de início rápido, execute deactivate para desativar o ambiente virtual.

Instale o SDK do Apache Beam

O SDK do Apache Beam é um modelo de programação de código aberto para pipelines de dados. Defina um pipeline com um programa do Apache Beam e escolha um executor, como o Dataflow, para executar o pipeline.

Para fazer o download e instalar o SDK do Apache Beam, siga estas etapas:

1. Verifique se você está no ambiente virtual do Python criado na seção anterior. Verifique se o prompt começa com <env_name>, em que env_name é o nome do ambiente virtual.
2. Instale o padrão de empacotamento da roda Python:

   pip install wheel
   

3. Instale a versão mais recente do SDK do Apache Beam para Python:

pip install 'apache-beam[gcp]'

Dependendo da conexão, a instalação pode levar algum tempo.

Execute o pipeline localmente

Para ver como um pipeline é executado localmente, use um módulo Python pronto para o exemplo wordcount incluído no pacote apache_beam.

O exemplo de pipeline wordcount faz o seguinte:

1. Usa um arquivo de texto como entrada.

   Este arquivo de texto está localizado em um bucket do Cloud Storage com o nome do recurso gs://dataflow-samples/shakespeare/kinglear.txt.

2. Analisa cada linha na forma de palavras.
3. Realiza uma contagem de frequência com base nas palavras tokenizadas.

Para preparar o pipeline wordcount localmente, siga estas etapas:

1. No terminal local, execute o exemplo wordcount:

   python -m apache_beam.examples.wordcount \
     --output outputs

2. Veja a saída do pipeline:

   more outputs*

3. Para sair, pressione q.

Executar o pipeline localmente permite testar e depurar o programa Apache Beam. O código-fonte do wordcount.py pode ser visualizado no GitHub do Apache Beam.

Executar o pipeline no serviço do Dataflow

Nesta seção, execute o pipeline de exemplo wordcount do pacote apache_beam no serviço do Dataflow. Este exemplo especifica DataflowRunner como o parâmetro para --runner.

• Execute o canal:

  python -m apache_beam.examples.wordcount \
      --region DATAFLOW_REGION \
      --input gs://dataflow-samples/shakespeare/kinglear.txt \
      --output gs://STORAGE_BUCKET/results/outputs \
      --runner DataflowRunner \
      --project PROJECT_ID \
      --temp_location gs://STORAGE_BUCKET/tmp/

  Substitua:

  • DATAFLOW_REGION: o endpoint regional em que você quer implantar o job do Dataflow. Por exemplo, europe-west1

    A sinalização --region substitui a região padrão definida no servidor de metadados, no cliente local ou nas variáveis de ambiente.

  • STORAGE_BUCKET: o nome do Cloud Storage que você copiou anteriormente.
  • PROJECT_ID: o ID do projeto do Google Cloud que você copiou anteriormente.

Ver os resultados

Quando você executa um pipeline usando o Dataflow, os resultados são armazenados em um bucket do Cloud Storage. Nesta seção, verifique se o pipeline está em execução usando o Console do Cloud ou o terminal local.

Console do Cloud

Para ver os resultados no Console do Cloud, siga estas etapas:

1. No Console do Cloud, acesse a página do Dataflow.

   Acessar "Jobs"

   A página Jobs exibe detalhes do job do wordcount, incluindo o status Em execução primeiro e depois Finalizado.

2. Acessar a página Navegador do Cloud Storage.

   Acessar o navegador

3. Na lista de buckets do projeto, clique no bucket de armazenamento que você criou anteriormente.

   No diretório wordcount, os arquivos de saída criados pelo seu job são exibidos.

Terminal local

Para ver os resultados do terminal, use a ferramenta gsutil. Também é possível executar os comandos do Cloud Shell.

1. Liste os arquivos de saída:

   gsutil ls -lh "gs://STORAGE_BUCKET/results/outputs*"  

Substitua STORAGE_BUCKET pelo nome do bucket do Cloud Storage usado no programa de pipeline.

2. Veja os resultados nos arquivos de saída:

   gsutil cat "gs://STORAGE_BUCKET/results/outputs*"

Modificar o código do pipeline

Nos exemplos anteriores, o pipeline wordcount diferencia letras maiúsculas e minúsculas. Nas etapas a seguir, mostramos como modificar o pipeline para que o wordcount não diferencie maiúsculas de minúsculas.

1. Na máquina local, faça o download da cópia mais recente do código wordcount no repositório do Apache Beam no GitHub.
2. No terminal local, execute o pipeline:

   python wordcount.py --output outputs

3. Ver os resultados:

   more outputs*

4. Para sair, pressione q.
5. Em um editor de sua escolha, abra o arquivo wordcount.py.
6. Dentro da função run, examine as etapas do pipeline:

   counts = (
           lines
           | 'Split' >> (beam.ParDo(WordExtractingDoFn()).with_output_types(str))
           | 'PairWIthOne' >> beam.Map(lambda x: (x, 1))
           | 'GroupAndSum' >> beam.CombinePerKey(sum))

   Depois de split, as linhas são divididas em palavras como strings.

7. Para usar letras minúsculas em strings, modifique a linha após split:

   counts = (
           lines
           | 'Split' >> (beam.ParDo(WordExtractingDoFn()).with_output_types(str))
           | 'lowercase' >> beam.Map(str.lower)
           | 'PairWIthOne' >> beam.Map(lambda x: (x, 1))
           | 'GroupAndSum' >> beam.CombinePerKey(sum)) 

   Essa modificação mapeia a função str.lower em todas as palavras. Essa linha é equivalente a beam.Map(lambda word: str.lower(word)).
8. Salve o arquivo e execute o job wordcount modificado:

   python wordcount.py --output outputs

9. Veja os resultados do pipeline modificado:

   more outputs*

10. Para sair, pressione q.

Limpar

Para evitar cobranças na sua conta do Google Cloud pelos recursos usados nesta página, siga estas etapas.

Observação: se você seguiu este guia de início rápido em um novo projeto, exclua o projeto.

1. No Console do Cloud, acesse a página Navegador do Cloud Storage.

   Acessar o navegador

2. Clique na caixa de seleção do bucket que você quer excluir.
3. Para excluir o bucket, clique em Excluir e siga as instruções.

A seguir

• Saiba mais sobre o modelo de programação do Apache Beam.
• Desenvolva interativamente um pipeline usando um notebook do Apache Beam.
• Saiba como projetar e criar seu próprio canal.
• Trabalhe nos exemplos do WordCount e Mobile Gaming.

Apache Beam^™ é uma marca registrada da The Apache Software Foundation ou afiliadas nos Estados Unidos e/ou em outros países.