Como usar a interface de linha de comando do Dataflow

Ao executar o pipeline usando o serviço gerenciado pelo Dataflow, é possível acessar informações sobre o job do Dataflow usando a interface de linha de comando do Dataflow. A interface de linha de comando do Dataflow faz parte da ferramenta de linha de comando no SDK do Cloud.

Se você preferir ver e interagir com seus jobs do Dataflow usando o Console do Cloud, use a interface de monitoramento do Dataflow.

Instalação do componente de linha de comando do Dataflow

Para usar a interface de linha de comando do Dataflow no terminal local, instale e configure o SDK do Cloud.

Para o Cloud Shell, a interface da linha de comando do Dataflow está automaticamente disponível.

Como executar os comandos

Você interage com a interface de linha de comando do Dataflow executando os comandos disponíveis. Para ver a lista de comandos do Dataflow disponíveis, digite o seguinte comando no shell ou no terminal:

  gcloud dataflow --help

Como visto na saída, o comando do Dataflow tem os seguintes grupos: flex-template, jobs e sql.

Comandos do modelo do Flex

O grupo de subcomando flex-template permite trabalhar com modelos do Dataflow Flex. As seguintes operações são compatíveis:

  • build: cria um arquivo de modelo do Flex a partir dos parâmetros especificados.
  • run: executa um job do caminho especificado.

Para executar um modelo, é preciso criar um arquivo de especificação de modelo armazenado em um bucket do Cloud Storage. O arquivo de especificação do modelo contém todas as informações necessárias para executar o job, como informações e metadados do SDK. Além disso, o arquivo metadata.json contém informações sobre o modelo, como nome, descrição e parâmetros de entrada. Depois de criar o arquivo de especificação do modelo, você pode construir o modelo do Flex usando Java ou Python.

Para criar e executar um modelo do Flex usando o gcloud command-line tool, consulte o tutorial sobre Como usar modelos do Flex.

Comandos jobs

O grupo de subcomando jobs permite trabalhar com jobs do Dataflow no projeto. As seguintes operações são compatíveis:

  • cancel: cancela todos os jobs que correspondem aos argumentos da linha de comando.
  • describe: gera o objeto do job resultante da API Get.
  • drain: drena todos os jobs que correspondem aos argumentos da linha de comando.
  • list: lista todos os jobs em um projeto específico, opcionalmente filtrados por região.
  • run: executa um job do caminho especificado.
  • show: mostra uma breve descrição do job fornecido.

Para ver uma lista de todos os jobs do Dataflow no projeto, execute o seguinte comando no shell ou no terminal:

gcloud dataflow jobs list

O comando retorna uma lista dos jobs atuais. Veja um exemplo de saída:

  ID                                        NAME                                    TYPE   CREATION_TIME        STATE   REGION
  2015-06-03_16_39_22-4020553808241078833   wordcount-janedoe-0603233849            Batch  2015-06-03 16:39:22  Done    us-central1
  2015-06-03_16_38_28-4363652261786938862   wordcount-johndoe-0603233820            Batch  2015-06-03 16:38:28  Done    us-central1
  2015-05-21_16_24_11-17823098268333533078  bigquerytornadoes-johndoe-0521232402    Batch  2015-05-21 16:24:11  Done    europe-west1
  2015-05-21_13_38_06-16409850040969261121  bigquerytornadoes-johndoe-0521203801    Batch  2015-05-21 13:38:06  Done    us-central1
  2015-05-21_13_17_18-18349574013243942260  bigquerytornadoes-johndoe-0521201710    Batch  2015-05-21 13:17:18  Done    europe-west1
  2015-05-21_12_49_37-9791290545307959963   wordcount-johndoe-0521194928            Batch  2015-05-21 12:49:37  Done    us-central1
  2015-05-20_15_54_51-15905022415025455887  wordcount-johndoe-0520225444            Batch  2015-05-20 15:54:51  Failed  us-central1
  2015-05-20_15_47_02-14774624590029708464  wordcount-johndoe-0520224637            Batch  2015-05-20 15:47:02  Done    us-central1

Usando o job IDexibido para cada job, você pode executar o comando describe para exibir mais informações sobre um job.

gcloud dataflow jobs describe JOB_ID

Substitua JOB_ID pelo job ID de um dos jobs do Dataflow no projeto.

Por exemplo, se você executar o comando para o ID do job 2015-02-09_11_39_40-15635991037808002875, veja a seguir um exemplo de saída:

createTime: '2015-02-09T19:39:41.140Z'
currentState: JOB_STATE_DONE
currentStateTime: '2015-02-09T19:56:39.510Z'
id: 2015-02-09_11_39_40-15635991037808002875
name: tfidf-bchambers-0209193926
projectId: google.com:clouddfe
type: JOB_TYPE_BATCH

Para formatar o resultado em JSON, execute o comando com a opção --format=json:

gcloud --format=json dataflow jobs describe JOB_ID

Substitua JOB_ID pelo job ID de um dos jobs do Dataflow no projeto.

O exemplo de saída a seguir é formatado como JSON:

{
  "createTime": "2015-02-09T19:39:41.140Z",
  "currentState": "JOB_STATE_DONE",
  "currentStateTime": "2015-02-09T19:56:39.510Z",
  "id": "2015-02-09_11_39_40-15635991037808002875",
  "name": "tfidf-bchambers-0209193926",
  "projectId": "google.com:clouddfe",
  "type": "JOB_TYPE_BATCH"
}

Comandos SQL

O grupo de subcomando sql permite trabalhar com o SQL do Dataflow. O comando gcloud Dataflow sql query aceita e executa uma consulta SQL especificada pelo usuário no Dataflow.

Por exemplo, para executar uma consulta SQL simples em um job do Dataflow que lê um conjunto de dados do BigQuery e grava em outro conjunto de dados do BigQuery, execute o seguinte no shell ou no terminal:

gcloud dataflow sql query 'SELECT word FROM
bigquery.table.PROJECT_ID.input_dataset.input_table
where count > 3'
    --job-name=JOB_NAME \
    --region=us-west1 \
    --bigquery-dataset=OUTPUT_DATASET \
    --bigquery-table=OUTPUT_TABLE

Substitua:

  • PROJECT_ID: um nome globalmente exclusivo para o projeto
  • JOB_NAME: um nome para seu job do Dataflow
  • OUTPUT_DATASET: um nome para o conjunto de dados de saída
  • OUTPUT_TABLE: um nome para a tabela de saída

Iniciar um job do SQL do Dataflow pode levar vários minutos. Não é possível atualizar o job depois de criá-lo. Os jobs do Dataflow SQL usam escalonamento automático, e o Dataflow escolhe automaticamente o modo de execução para lote ou streaming. Não é possível controlar esse comportamento para jobs do SQL do Dataflow. Para interromper os jobs do Dataflow SQL, use o comando cancel. Não é possível interromper um job do SQL do Dataflow com o drain.

Para mais informações sobre como usar os comandos SQL do Dataflow, consulte as documentações Referência do SQL do Dataflow e gcloud Dataflow sql query.

Como usar comandos com endpoints regionais

A interface de linha de comando do Dataflow é compatível com endpoints regionais desde a versão 176 da ferramenta gcloud. Use a opção --region com qualquer comando para especificar o endpoint regional que gerencia o job.

Por exemplo, gcloud dataflow jobs list lista os jobs de todas as regiões, mas gcloud dataflow jobs list --region=europe-west1 lista apenas os jobs gerenciados a partir de europe-west1.