Programar scripts e notebooks SQL

Com a programação de scripts e notebooks SQL, é possível operacionalizar os recursos criados no Workbench de exploração de dados (explorar).

O agendamento de um script SQL ou de um notebook cria uma tarefa do Dataplex que é executada em um horário predeterminado, uma vez ou de maneira recorrente. A cada execução, é criado um job que captura os metadados da execução, como os horários de início e término, o status e os registros gerados.

Quando uma execução é acionada para um script SQL programado ou para um notebook, a versão atual do notebook ou script SQL é executada. Isso significa que, se você programar um notebook ou script SQL e depois atualizar o conteúdo dele, a atualização também será refletida nas execuções programadas do notebook ou do script SQL.

Custos

Os scripts SQL programados e notebooks programados acionam a execução de jobs usando o Dataproc sem servidor. Os usos são cobrados de acordo com o modelo de preços do Dataproc, e as cobranças aparecem no Dataproc em vez de no Dataplex.

Antes de começar

Analise e cumpra os pré-requisitos descritos nos seguintes documentos:

Se um script SQL ou uma programação de notebook usar a API BigQuery, você precisará conceder à conta de serviço o papel Consumidor do Service Usage (roles/serviceusage.serviceUsageConsumer).

Limitações conhecidas

  • Ao programar um notebook usando o console do Google Cloud, os outros pacotes do Python configurados no ambiente selecionado não estarão disponíveis no ambiente de execução para o notebook programado. Para disponibilizá-las no ambiente de execução, é preciso criar uma programação de notebook que faça referência a uma imagem de contêiner com os pacotes adicionais necessários. Para mais informações, consulte Programar notebooks com pacotes personalizados.

  • Não é possível usar o console do Google Cloud para referenciar imagens de contêiner personalizadas ao programar notebooks. Em vez disso, use a CLI gcloud.

  • Não é possível editar uma programação depois de criá-la. Para atualizar os parâmetros de programação, recrie a programação com novos parâmetros.

  • Não é possível definir uma versão específica de um script ou notebook SQL para ser usada em uma programação. Quando a programação é acionada, é usada a versão atual do script ou notebook SQL.

  • Ao programar scripts e notebooks SQL usando o console do Google Cloud, a sub-rede padrão é usada. Para especificar outra rede ou sub-rede, use a CLI gcloud.

Além disso, revise as limitações conhecidas da ferramenta Explorar.

Criar e gerenciar programações para scripts SQL

Configuração do ambiente de execução para scripts SQL programados

Quando um script SQL é programado, ele é executado como uma tarefa do Dataplex. Quando uma programação é criada usando o console do Google Cloud, os parâmetros de ambiente de execução da tarefa correspondentes para scripts SQL programados são herdados do ambiente desse script SQL com base no mapeamento a seguir:

Parâmetro de configuração do ambiente Parâmetro de configuração de tarefa do script SQL programado
Tamanho do disco principal Imagem / propriedades do contêiner:
   spark.dataproc.driver.disk.size
   spark.dataproc.executor.disk.size
Número de nós Contagem de lotes / executores
Número máximo de nós Contagem de executores em lote / máximo
Versão de imagem Não herdado
Arquivos JAR Imagem do contêiner / JARS do Java
Pacotes do Python Não herdado
Outras propriedades Imagem / propriedades do contêiner

Programar um script SQL

Console

  1. No console do Google Cloud, acesse a página Explorar do Dataplex.

    Acessar o Dataplex Explore

  2. Selecione um script SQL que você queira programar. Para isso, selecione um único script SQL na lista Scripts do Spark SQL ou abra um script SQL no Spark SQL Editor.

  3. No menu Programação, clique em Criar programação.

  4. No campo Nome da programação, insira um nome para a instância programada.

  5. Na seção Opções de programação, selecione se quer executar o script SQL
    apenas uma vez ou de maneira recorrente:

    1. Se você selecionar Executar uma vez, especifique se quer executar o script SQL imediatamente ou em um horário programado, usando as opções no menu Iniciar. Para uma execução programada, especifique a data de início e o ambiente de execução.

    2. Se você selecionar Repetir, especifique se quer executar o script SQL diariamente, semanalmente, mensalmente ou em uma programação personalizada especificada usando a expressão cron. Além disso, especifique a data e o horário de início da execução inicial programada.

  6. Na seção Destino dos resultados, faça o seguinte:

    1. No campo Nome da pasta de saída, clique em Procurar e selecione uma pasta em um bucket do Cloud Storage em que as saídas do script serão armazenadas.

    2. Clique em Selecionar.

    3. Selecione o Formato de saída do script. Os formatos compatíveis são CSV, JSON, ORC e Parquet.

  7. Na seção Credenciais de script programadas, selecione uma conta de serviço no menu Conta de serviço do usuário.

  8. Clique em Programação.

gcloud

Para mais informações sobre como programar scripts SQL usando a CLI gcloud, consulte Programar uma tarefa do SparkSQL.

REST

Use o API Explorer para criar uma tarefa.

Gerenciar programações de scripts SQL

Console

Abrir a lista de todas as programações de script SQL

  1. No console do Google Cloud, acesse a página Processo do Dataplex.

  2. Clique na guia Consultas programadas para ver a lista de programações de script SQL.

Abrir a lista de todas as programações de um script SQL específico

  1. No console do Google Cloud, acesse a página Explorar do Dataplex.

  2. Selecione o script SQL necessário.

  3. No menu Programação, clique em Ver programações.

    A guia Consultas programadas é aberta com uma lista de programações de script SQL filtradas pelo script SQL selecionado.

Ver os detalhes de uma programação de script SQL

  1. Acesse a guia Consultas programadas e selecione a programação de script SQL necessária.

  2. Clique na guia Detalhes para ver os detalhes da programação do script SQL e uma visualização do conteúdo do script SQL programado.

Ativar e desativar uma programação de script SQL

  1. Acesse a guia Consultas programadas e selecione a programação de script SQL necessária.

  2. Clique em Desativar para desativar uma programação de script SQL ativa.

  3. Clique em Ativar para ativar uma programação de script SQL inativa.

Excluir uma programação de script SQL

  1. Acesse a guia Consultas programadas e selecione a programação de script SQL necessária.

  2. Clique em Excluir para excluir permanentemente uma programação de script SQL.

Ver registros e gerenciar uma programação de script SQL

  1. Acesse a guia Consultas programadas e selecione a programação de script SQL necessária.

  2. Clique na guia Jobs e depois no ID do job da execução do script SQL programado que você quer visualizar.

  3. Clique em Ver registros para visualizar os registros relacionados ao script SQL programado selecionado executado no Cloud Logging.

  4. Clique em Código do lote do Dataproc para abrir a página do Dataproc no console do Google Cloud. Acesse os detalhes da sessão sem servidor correspondente do Dataproc.

  5. Clique em Gerenciar no Cloud Storage ao lado do rótulo de Saída para abrir a página do Cloud Storage no Console do Google Cloud. Acesse os detalhes do bucket do Cloud Storage correspondente que contém a saída da execução do script SQL.

gcloud

Para informações sobre como monitorar scripts SQL programados usando a CLI gcloud, consulte a guia gcloud em Monitorar sua tarefa.

Para informações sobre como gerenciar scripts SQL programados usando a CLI gcloud, consulte a guia gcloud em Gerenciar a programação.

REST

Para informações sobre como monitorar scripts SQL programados usando REST, consulte a guia REST em Monitorar sua tarefa.

Para mais informações sobre como gerenciar scripts SQL programados usando REST, consulte a guia REST em Gerenciar a programação.

Saída de um script SQL programado

A saída de cada execução de um script SQL programado é armazenada no local especificado por você para a pasta do Cloud Storage, na seguinte estrutura:

CLOUD_STORAGE_FOLDER_LOCATION/projects/PROJECT_ID/locations/LOCATION_ID/lakes/LAKE_ID/tasks/TASK_ID/JOB_ID/QUERY_NUMBER

Criar e gerenciar programações para notebooks

Configuração do ambiente de execução para notebooks programados

Quando um notebook é programado, ele é executado como uma tarefa do Dataplex. Quando uma programação é criada usando o console do Google Cloud, os parâmetros de ambiente de execução da tarefa correspondentes para notebooks programados são herdados do ambiente desse notebook com base no seguinte mapeamento:

Parâmetro de configuração do ambiente Parâmetro de configuração de tarefa do notebook programado
Tamanho do disco principal Imagem / propriedades do contêiner:
   spark.dataproc.driver.disk.size
   spark.dataproc.executor.disk.size
Número de nós Contagem de lotes / executores
Número máximo de nós Contagem de executores em lote / máximo
Versão de imagem Não herdado
Arquivos JAR Imagem do contêiner / JARS do Java
Pacotes do Python Não herdado
Outras propriedades Imagem / propriedades do contêiner

Programar notebooks com pacotes personalizados

Para notebooks interativos, ao configurar um ambiente, o Dataplex permite especificar pacotes personalizados do Python a serem instalados nas sessões do usuário provisionadas para o ambiente. Quando esse notebook é programado, os pacotes personalizados do Python configurados no ambiente dele não ficam disponíveis no ambiente de execução para o notebook programado, e o ambiente de execução padrão tem apenas os componentes do ambiente de execução sem servidor do Dataproc versão 1.0. Para que os pacotes Python personalizados estejam disponíveis no ambiente de execução para os notebooks programados, forneça uma imagem de contêiner personalizada com os pacotes personalizados necessários.

Não é possível especificar uma imagem de contêiner personalizada ao programar um notebook usando o console do Google Cloud. Em vez disso, use a CLI gcloud. Para mais informações, consulte Programar um notebook.

Se você programar um notebook com um ambiente que tem pacotes personalizados configurados, receberá o seguinte aviso:

Selected environment  has additional Python packages configured.
These packages will not be available in the default runtime for the scheduled notebook
when scheduling in the Console. To make the required additional Python packages
available in the runtime, please create Notebook Schedule using gcloud command
instead, referencing a container image with required additional packages.

Criar uma imagem de contêiner personalizada para notebooks programados

Para informações sobre como estabelecer uma imagem de contêiner para notebooks programados e instalar os pacotes Python personalizados necessários no dockerfile da imagem de contêiner, consulte Criar uma imagem de contêiner personalizada para o Dataproc sem servidor para o Spark.

Verifique se você instalou os seguintes pacotes conda na imagem do contêiner:

  • gcsfs
  • google-cloud-bigquery
  • google-cloud-storage
  • google-auth
  • ipykernel
  • papermill

Para instalar os componentes gcloud em uma imagem de contêiner, abra o arquivo dockerfile da imagem e conclua as etapas a seguir:

  1. Adicione o pacote google-cloud-sdk à lista de pacotes conda a serem instalados.

  2. Adicione as seguintes linhas após a etapa de instalação dos pacotes conda:

    # (Optional) Installing gcloud components
RUN gcloud components install alpha beta bq gsutil

Programar um notebook

Console

  1. No console do Google Cloud, acesse a página Explorar do Dataplex.

    Acessar o Dataplex Explore

  2. Selecione um notebook que você queira programar, selecionando um único notebook na visualização Notebooks ou abrindo um notebook na página de detalhes do notebook.

  3. No menu Programação, clique em Criar programação.

  4. No campo Nome da programação, insira um nome para a instância programada.

  5. Na seção Opções de programação, selecione se quer executar o notebook apenas uma vez ou de maneira recorrente:

    1. Se você selecionar Executar uma vez, especifique se quer executar o notebook imediatamente ou em um horário programado, usando as opções no menu Iniciar. Para uma execução programada, especifique a data de início e o ambiente de execução.

    2. Se você selecionar Repetir, especifique se quer executar o notebook diariamente, semanalmente, mensalmente ou em uma programação personalizada especificada usando a expressão cron. Além disso, especifique a data e o horário de início da execução inicial programada.

  6. Na seção Destino dos resultados, escolha um local em que você quer que a saída do notebook seja armazenada:

    1. No campo Nome da pasta de saída, clique em Procurar e selecione uma pasta em um bucket do Cloud Storage em que a saída do notebook será armazenada.

    2. Clique em Selecionar.

    3. Selecione o Formato de saída do script. Os formatos compatíveis são CSV, JSON, ORC e Parquet.

  7. Na seção Credenciais do notebook programado, selecione uma conta de serviço no menu Conta de serviço do usuário.

  8. Na seção Parâmetros, adicione parâmetros de execução do notebook como pares de chave-valor clicando em Adicionar novo.

  9. Clique em Programação.

gcloud

Execute o comando da CLI gcloud descrito em Programar uma tarefa do Spark (Java ou Python) com os seguintes parâmetros adicionais:

Parâmetro Descrição
--notebook Caminho para o conteúdo de um notebook do notebook de entrada. Os argumentos de execução são acessíveis como variáveis de ambiente. Por exemplo, TASK_key=value.
Observação: na documentação de referência gcloud para programar notebooks como tarefas, é mencionado que o valor do parâmetro --notebook pode ser o URI do Cloud Storage do arquivo de notebook. Isso não é permitido. Você só precisa especificar o caminho para o conteúdo do notebook para o parâmetro --notebook.
--notebook-archive-uris URIs de arquivos do Cloud Storage a serem extraídos para o diretório de trabalho de cada executor. Os tipos de arquivo compatíveis são JAR, tar, tar.gz, tgz e zip.
--notebook-file-uris URIs de arquivos do Google Cloud Storage a serem colocados no diretório de trabalho de cada executor.
Calcule os recursos necessários para uma tarefa ao usar o Dataproc sem servidor
--notebook-batch-executors-count Número de executores de job.
--notebook-batch-max-executors-count Máximo de executores configuráveis.
Se notebook-batch-max-executors-count for maior que notebook-batch-executors-count, o escalonamento automático será ativado.
Configuração do ambiente de execução da imagem do contêiner
--notebook-container-image Opcional: imagem de contêiner personalizada do job.
--notebook-container-image-java-jars Uma lista de JARs Java a serem adicionados ao classpath. A entrada válida inclui URIs do Cloud Storage para binários do JAR. Por exemplo, gs://BUCKET_NAME/my/path/to/file.jar.
--notebook-container-image-properties As propriedades que serão definidas nos arquivos de configuração do daemon.
As chaves de propriedade são especificadas no formato prefix:property. Por exemplo:
core:hadoop.tmp.dir.
Para mais informações, consulte Propriedades de cluster.
Rede VPC do Cloud usada para executar a infraestrutura
--notebook-vpc-network-tags Lista de tags de rede a serem aplicadas ao job.
O identificador de rede do Cloud VPC. É possível especificar no máximo uma das seguintes opções.
--notebook-vpc-network-name A rede VPC do Cloud em que o job é executado. Por padrão, é usada a rede do Cloud VPC denominada Padrão no projeto.
--notebook-vpc-sub-network-name A sub-rede do Cloud VPC em que o job é executado.
Local para saídas de notebook
--execution-args Para tarefas de notebook, o argumento a seguir é obrigatório e precisa ser transmitido como TASK_ARGS.
--execution-args=^::^TASK_ARGS="--output_location,CLOUD_STORAGE_URI_OF_OUTPUT_DIRECTORY"

Veja a seguir um exemplo do comando gcloud usado para programar notebooks: 

gcloud dataplex tasks create sample-task --project=sample-project --location=us-central1 --lake=my-lake --trigger-type=ON_DEMAND --notebook="projects/my-project-id/locations/us-central1/lakes/my-lake/content/my-notebook.ipynb" --execution-service-account=associated-service-account@sample-project.iam.gserviceaccount.com  --execution-args=^::^TASK_ARGS="--output_location,gs://my-bucket/Demo" --notebook-batch-executors-count=2 --notebook-batch-max-executors-count=5 --notebook-container-image=container-image --notebook-container-image-java-jars=java-jar1,java-jar-2

REST

Use o API Explorer para criar uma tarefa.

Gerenciar programações de notebook

Console

Abrir a lista de todas as programações de notebook

  1. No console do Google Cloud, acesse a página Processo do Dataplex.

  2. Clique na guia Notebooks programados para ver a lista de programações de script SQL.

Abrir a lista de todas as programações de um notebook específico

  1. No console do Google Cloud, acesse a página Explorar do Dataplex.

  2. Selecione o notebook necessário.

  3. No menu Programação, clique em Ver programações.

    A guia Consultas programadas é aberta com uma lista de programações de notebook filtradas pelo notebook selecionado.

Ver os detalhes da programação de notebook

  1. Acesse a guia Notebooks programados e selecione a programação de notebook necessária.

  2. Clique nos detalhes em Detalhes da programação do notebook e em uma visualização do conteúdo do notebook programado.

Ativar e desativar uma programação de notebook

  1. Acesse a guia Notebook programado e selecione a programação de notebook necessária.

  2. Clique em Desativar para desativar uma programação de bloco de notas ativa.

  3. Clique em Ativar para ativar uma programação de notebook inativa.

Excluir uma programação de notebook

  1. Acesse a guia Notebook programado e selecione a programação de notebook necessária.

  2. Clique em Excluir para excluir permanentemente uma programação de notebook existente.

Ver registros e gerenciar uma programação de notebook

  1. Acesse a guia Notebook programado e selecione a programação de notebook necessária.

  2. Clique na guia Jobs e depois no ID do job do notebook programado que você quer ver.

  3. Na seção Visualizar saída, revise a saída da execução do notebook.

  4. Clique em Ver registros para ver os registros relacionados ao notebook programado selecionado executado no Cloud Logging.

  5. Clique em Código do lote do Dataproc para abrir a página do Dataproc no console do Google Cloud. Acesse os detalhes da sessão sem servidor correspondente do Dataproc.

  6. Clique em Gerenciar no Cloud Storage ao lado do rótulo de Saída para abrir a página do Cloud Storage no Console do Google Cloud. Acesse os detalhes do bucket do Cloud Storage correspondente que contém a saída da execução do notebook.

gcloud

Para informações sobre como monitorar notebooks programados usando a CLI gcloud, consulte a guia gcloud em Monitorar sua tarefa.

Para informações sobre como gerenciar notebooks programados usando a CLI gcloud, consulte a guia gcloud em Gerenciar a programação.

REST

Para mais informações sobre como monitorar notebooks programados usando REST, consulte a guia REST em Monitorar sua tarefa.

Para informações sobre como gerenciar notebooks programados usando REST, consulte a guia REST em Gerenciar a programação.

Saída de um notebook programado

A saída de cada execução de um notebook programado é armazenada no local especificado por você para a pasta do Cloud Storage, na seguinte estrutura:

CLOUD_STORAGE_FOLDER_LOCATION/projects/PROJECT_ID/locations/LOCATION_ID/lakes/LAKE_ID/tasks/TASK_ID/JOB_ID/QUERY_NUMBER

A seguir