Programar scripts e notebooks SQL

Cuidado:a Análise do Dataplex está descontinuado. O suporte ao recurso Explorar termina em 30 de junho de 2025. Recomendamos fazer a transição dos seus recursos para o BigQuery Studio de análise detalhada dos dados em todas as ferramentas de análise do Google Cloud. Consulte Migre de “Analisar” para o BigQuery Studio.

Programar scripts SQL e notebooks permite operacionalizar os recursos que foram Criada no workbench de exploração de dados (Análise).

Programar um script SQL ou um notebook cria uma tarefa do Dataplex que é executada em um horário predeterminado, uma vez ou com frequência. Em cada execução, um job é criado que captura os metadados da execução, como horário de início e término, status da execução, registros e saídas geradas.

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

Custos

Os scripts SQL e notebooks programados acionam a execução do job usando o Dataproc Serverless. Os usos são cobrados de acordo com o modelo de preços e cobranças do Dataproc aparecem no Dataproc, e não no Dataplex.

Antes de começar

Leia e conclua os pré-requisitos descritos nos seguintes documentos:

• Na seção Antes de começar de Usar a área de trabalho de análise de dados

• Seção Antes de começar de Programar tarefas personalizadas do Spark e do SparkSQL

  Observação: instruções relacionadas à conta de serviço de tarefas descrita em Programar tarefas personalizadas do Spark e do SparkSQL se estendem a scripts SQL e notebooks e aplicam-se à conta de serviço usada para programar scripts SQL e notebooks.
  
  As instruções para ativar o Acesso particular do Google descritas em Programar tarefas personalizadas do Spark e do SparkSQL se referem à rede usada para programar scripts e notebooks SQL. Só é possível usar a sub-rede padrão ao programar um script ou um notebook SQL usando o console do Google Cloud. Saiba mais em Limitações conhecidas.

Se um script SQL ou uma programação de notebook usar a API BigQuery, conceda à conta de serviço o papel de consumidor de uso do serviço (roles/serviceusage.serviceUsageConsumer).

Limitações conhecidas

• Ao programar um notebook usando o console do Google Cloud, outros pacotes Python configurados no ambiente selecionado não estarão disponíveis no momento da execução para o notebook programado. Para disponibilizá-los no ambiente de execução, é preciso criar uma programação de notebook referenciando um 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 fazer referência a 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 criada. Para atualizar os parâmetros da programação, recree a programação com novos parâmetros.

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

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

Além disso, leia as limitações conhecidas da Análise.

Criar e gerenciar programações para scripts SQL

Configuração do tempo 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 execução de tarefas correspondentes para scripts SQL programados são herdados do ambiente desse script SQL com base no seguinte mapeamento:

Parâmetro de configuração do ambiente	Parâmetro de configuração da tarefa de script SQL programada
Tamanho do disco principal	Imagem do contêiner / Propriedades:    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áxima
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 do contêiner / Propriedades

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ê quer programar, selecionando um único SQL da lista de Scripts do Spark SQL ou abrindo um script SQL no Editor do Spark SQL.

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

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

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

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

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

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 você quer armazenar as saídas do script.

   2. Clique em Selecionar.

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

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

8. Clique em Programação.

gcloud

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

Observação: em Programar uma tarefa SparkSQL a descrição do parâmetro --spark-sql-script-file declara que o o valor desse parâmetro pode ser o URI do Cloud Storage. Isso não é possível. É necessário especificar apenas o caminho para um conteúdo de script SQL para o parâmetro --spark-sql-script-file.

REST

Use o API Explorer para criar uma tarefa.

Observação: na documentação de referência do REST, a descrição do SparkTaskConfig informa que o valor do campo sqlScriptFile pode ser o URI do Cloud Storage. Não há suporte para isso. Especifique apenas o caminho para um conteúdo de script SQL no campo sqlScriptFile.

Gerenciar programações de scripts SQL

Console

Abrir a lista de todos os agendamentos de scripts 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 scripts 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.

Visualizar 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 exibir os detalhes da programação do script SQL e pré-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 do script SQL necessária.

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

Conferir 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 do SQL programado. execução do script que você quer visualizar.

3. Clique em Ver registros para conferir os registros relacionados à execução do script SQL agendado selecionado no Cloud Logging.

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

5. Clique em Gerenciar no Cloud Storage ao lado do rótulo 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 mais informações sobre como gerenciar scripts SQL programados com 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 Monitore sua tarefa.

Para 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 de 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, o ambiente de execução da tarefa correspondente os parâmetros dos notebooks programados são herdados do ambiente do notebook, com base no seguinte mapeamento:

Parâmetro de configuração do ambiente	Parâmetro de configuração da tarefa de notebook programada
Tamanho do disco principal	Imagem do contêiner / Propriedades:    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áxima
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 do contêiner / Propriedades

Observação: quando um notebook é programado, os parâmetros da tarefa do Dataplex correspondente são fixados com base na configuração original do ambiente. Mudar os parâmetros do ambiente de notebook original não afeta a configuração da tarefa do Dataplex correspondente.

Programar notebooks com pacotes personalizados

Para notebooks interativos, ao configurar um ambiente, o Dataplex permite especificar pacotes Python personalizados para serem instalados em sessões de usuário provisionadas para o ambiente. Quando um notebook é programado, os pacotes Python personalizados configurados no ambiente não estão 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 do Spark no Dataproc sem servidor versão 1.0. Para que os pacotes Python personalizados estejam disponíveis no momento da execução para notebooks programados, forneça uma imagem de contêiner personalizada com os pacotes personalizados necessários.

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

Se você programar um notebook com um ambiente que tenha 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 do contêiner, consulte Crie uma imagem de contêiner personalizada para o Dataproc sem servidor para 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

Observação :os pacotes, exceto google-auth, ipykernel e papermill, estão presentes no dockerfile de amostra descritos em Criar uma imagem de contêiner personalizada para o Dataproc sem servidor para Spark.

Para instalar os componentes gcloud em uma imagem do contêiner, abra o arquivo dockerfile da imagem do contêiner e siga estas etapas:

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

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

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

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ê quer programar selecionando um único notebook na visualização Notebooks ou abrindo um notebook na página de detalhes.

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 você quer executar o notebook apenas uma vez ou de forma 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, especificar a data de início e o horário 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 de início e o horário da execução programada inicial.

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

   1. No campo Nome da pasta de saída, faça o seguinte: Clique em Procurar e selecione uma pasta no bucket do Cloud Storage quer que a saída do notebook seja armazenada.

   2. Clique em Selecionar.

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

7. Na seção Credenciais programadas do notebook, 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 para o notebook como chave-valor. clicando em Adicionar novo.

9. Clique em Programação.

gcloud

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

Parâmetro	Descrição
--notebook	Caminho para um conteúdo de notebook para o 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, é mencionou que o valor do parâmetro --notebook pode ser o URI do Cloud Storage do no arquivo do notebook. Isso não é possível. Você só deve especificar o caminho para Notebook Conteúdo do parâmetro --notebook.
--notebook-archive-uris	URIs do Cloud Storage de arquivos a serem extraídos para o diretório de trabalho de cada executor. Os tipos de arquivo aceitos são JAR, tar, tar.gz, tgz e zip.
--notebook-file-uris	URIs do Cloud Storage de arquivos a serem colocados no diretório de trabalho de cada executor.
Recursos de computação necessários para uma tarefa ao usar o Dataproc Serverless
--notebook-batch-executors-count	Número de executores de jobs.
--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 para a vaga.
--notebook-container-image-java-jars	Uma lista de JARs Java a serem adicionados ao caminho de classe. A entrada válida inclui URIs do Cloud Storage para binários JAR. Por exemplo, gs://BUCKET_NAME/my/path/to/file.jar.
--notebook-container-image-properties	As propriedades a serem definidas nos arquivos de configuração daemon. As chaves de propriedade são especificadas no formato prefix:property. Por exemplo: core:hadoop.tmp.dir. Para mais informações, consulte Propriedades do cluster.
rede VPC do Google Cloud usada para executar a infraestrutura
--notebook-vpc-network-tags	Lista de tags de rede para aplicar à vaga.
O identificador de rede VPC do Cloud. É possível especificar no máximo uma das opções a seguir.
--notebook-vpc-network-name	A rede VPC do Cloud em que o job é executado. Por padrão, a rede VPC do Cloud chamada O padrão dentro do projeto é usado.
--notebook-vpc-sub-network-name	A sub-rede VPC do Cloud em que o job é executado.
Local para saídas do notebook
--execution-args	Para tarefas de bloco de notas, 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"

Este é 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=[e-mail]  --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 APIs Explorer para criar uma tarefa.

Observação: na documentação de referência do REST, a descrição do recurso NotebookTaskConfig indica que o valor do campo notebook pode ser o URI do Cloud Storage. Isso não é possível. É necessário especificar apenas o caminho para um conteúdo de bloco de notas para o parâmetro notebook.

Gerenciar programações de notebooks

Console

Abrir a lista de todos os horários de notebooks

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

2. Clique na guia Notebooks programados para acessar a lista de programações de scripts 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 notebooks filtradas pelo notebook selecionado.

Conferir os detalhes de uma programação de notas

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

2. Clique em Detalhes para conferir a programação do notebook e uma prévia do conteúdo programado.

Ativar e desativar uma programação do notebook

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

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

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

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 remover permanentemente uma programação de notebook.

Visualizar registros e gerenciar uma programação de notebook

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

2. Clique na guia Jobs e, em seguida, no ID do job da execução de notebook programada que você quer consultar.

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

4. Clique em Ver registros para conferir os registros relacionados à execução do notebook programado selecionado no Cloud Logging.

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

6. Clique em Gerenciar no Cloud Storage ao lado do rótulo 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 mais informações sobre como monitorar notebooks programados usando a CLI gcloud, consulte a guia gcloud em Monitor your task.

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

REST

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

Para mais 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

• Programar tarefas personalizadas do Spark e do SparkSQL
• Configure alertas e notificações para tarefas do Dataplex.