Programar tarefas personalizadas do Spark e do Spark SQL

O Dataplex Universal Catalog permite programar a execução de código personalizado, seja como uma execução única, em uma programação regular ou sob demanda. O recurso sob demanda está em pré-lançamento e disponível apenas por API. É possível programar transformações de dados de clientes usando Spark (Java), PySpark (limitado à versão 3.2 do Spark) ou Spark SQL. O Dataplex Universal Catalog executa o código usando o processamento do Spark sem servidor e um programador sem servidor integrado.

Terminologia

Tarefa
Uma tarefa do Dataplex Universal Catalog representa o trabalho que você quer que o Dataplex Universal Catalog faça em uma programação. Ele encapsula seu código, seus parâmetros e a programação.
Job

Um job representa uma única execução de uma tarefa do Dataplex Universal Catalog. Por exemplo, se uma tarefa estiver programada para ser executada diariamente, o Dataplex Universal Catalog vai criar um job todos os dias.

Para jobs criados a partir de 10 de maio de 2023, o campo Gatilho mostra o tipo de gatilho de execução do job.

Estes são os tipos de acionadores de execução de jobs:

  • RUN_REQUEST: indica que o job foi executado devido a uma chamada da API RunTask.

  • TASK_CONFIG: indica que o job foi executado devido à configuração TriggerSpec da tarefa.

Modos de programação

O Dataplex Universal Catalog é compatível com os seguintes modos de programação:

Executar uma vez
Use esse modo para executar sua tarefa apenas uma vez. É possível executar o teste imediatamente ou em um horário definido no futuro. Se você executar a tarefa imediatamente, a execução ainda pode levar até dois minutos para começar.
Executar em uma programação
Use esse modo para executar a tarefa com uma frequência repetida. As repetições aceitas são diárias, semanais, mensais ou personalizadas.
Executar sob demanda

Use esse modo para executar uma tarefa criada anteriormente sob demanda. O modo de execução sob demanda é compatível apenas com a API RunTask. Quando o job é executado sob demanda, o Dataplex Universal Catalog usa parâmetros atuais para criar um job. É possível especificar os argumentos ExecutionSpec e os rótulos para executar o job.

Antes de começar

  1. Ative a API Dataproc.

    Ativar a API Dataproc

  2. Ative o Acesso Privado do Google para sua rede ou sub-rede. Ative o Acesso privado do Google na rede que você usa com as tarefas do Dataplex Universal Catalog. Se você não especificar uma rede ou sub-rede ao criar a tarefa do Dataplex Universal Catalog, a sub-rede padrão será usada. Nesse caso, é necessário ativar o Acesso Privado do Google para a sub-rede padrão.

  3. Crie uma conta de serviço. Uma conta de serviço é necessária para programar tarefas do Dataplex Universal Catalog. A conta de serviço precisa pertencer ao projeto em que você executa as tarefas. A conta de serviço precisa ter as seguintes permissões:

    • Acesso aos dados do BigQuery e do Cloud Storage que estão sendo processados.

    • Permissão do papel de worker do Dataproc no projeto em que você executa a tarefa.

    • Se a tarefa precisar ler ou atualizar a instância do metastore do Dataproc anexada ao lake, a conta de serviço precisará da função Leitor ou editor do metastore do Dataproc. Essa função precisa ser concedida no projeto em que o data lake do Dataplex Universal Catalog está configurado.

    • Se a tarefa for um job do Spark SQL, conceda à conta de serviço o papel de desenvolvedor do Universal Catalog do Dataplex. Esse papel precisa ser concedido no projeto em que o lake do Dataplex Universal Catalog está configurado.

    • Se a tarefa for um job do Spark SQL, você precisará de permissões de administrador do Cloud Storage no bucket em que os resultados são gravados.

    • Para programar e executar tarefas personalizadas do Spark e do Spark SQL, é necessário ter os papéis do IAM de leitor de metadados do catálogo universal do Dataplex (roles/dataplex.metadataReader), leitor do catálogo universal do Dataplex (roles/dataplex.viewer) e usuário de metadados do metastore do Dataproc (roles/metastore.metadataUser) na sua conta de serviço.

  4. Conceda à conta de usuário que está enviando o job o papel de Usuário da conta de serviço (roles/iam.serviceAccountUser). Para instruções, consulte Gerenciar o acesso a contas de serviço.

  5. Conceda à conta de serviço do lake do Dataplex Universal Catalog permissões para usar a conta de serviço. A conta de serviço do lake do Dataplex Universal Catalog está na página Detalhes do lake do consoleGoogle Cloud .

  6. Se o projeto que contém o lake do Dataplex Universal Catalog for diferente do projeto em que a tarefa será executada, conceda à conta de serviço do lake do Dataplex Universal Catalog o papel de editor do Dataproc no projeto em que você executa a tarefa.

  7. Coloque os artefatos de código necessários (JAR, Python ou arquivos de script SQL) ou arquivos arquivados (.jar, .tar, .tar.gz, .tgz, .zip) em um caminho do Cloud Storage.

  8. Verifique se a conta de serviço tem a permissão storage.objects.get necessária para o bucket do Cloud Storage que armazena esses artefatos de código.

Programar uma tarefa do Spark (Java ou Python)

Console

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

    Acessar "Processo"

  2. Clique em Criar tarefa.

  3. Em Criar tarefa personalizada do Spark, clique em Criar tarefa.

  4. Escolha um data lake do Dataplex Universal Catalog.

  5. Informe um nome para a tarefa.

  6. Crie um ID para sua tarefa.

  7. Na seção Configuração da tarefa, em Tipo, selecione Spark ou PySpark.

  8. Insira os argumentos relevantes.

  9. No campo Conta de serviço, insira uma conta de serviço de usuário que sua tarefa personalizada do Spark possa executar.

  10. Clique em Continuar.

  11. Opcional: Definir programação: selecione Executar uma vez ou Repetir. Preencha os campos obrigatórios.

  12. Clique em Continuar.

  13. Opcional: Personalizar recursos e Adicionar outras configurações.

  14. Clique em Criar.

gcloud

É possível programar uma tarefa do Spark (Java / Python) usando o comando da CLI gcloud. A tabela a seguir lista os parâmetros obrigatórios e opcionais para uso:

Parâmetro Descrição
--lake O ID do recurso de lake do serviço Dataplex Universal Catalog.
--location O local do serviço do Dataplex Universal Catalog.
--spark-main-class A classe principal do driver. O arquivo jar que contém a classe precisa estar no CLASSPATH padrão.
--spark-main-jar-file-uri O URI do Cloud Storage do arquivo jar que contém a classe principal.
--spark-archive-uris Opcional: URIs do Cloud Storage de arquivos a serem extraídos para o diretório de trabalho de cada executor. Tipos de arquivos aceitos: .jar, .tar, .tar.gz, .tgz e .zip.
--spark-file-uris Opcional: URIs do Cloud Storage de arquivos a serem colocados no diretório de trabalho de cada executor.
--batch-executors-count Opcional: o número total de executores de jobs. O valor padrão é 2.
--batch-max-executors-count Opcional: o número máximo de executores configuráveis. O valor padrão é 1000. Se batch-max-executors-count for maior que batch-executors-count, o Dataplex Universal Catalog vai ativar o escalonamento automático.
--container-image-java-jars Opcional: uma lista de JARs Java a serem adicionados ao classpath. A entrada válida inclui URIs do Cloud Storage para binários Jar.
Por exemplo, gs://bucket-name/my/path/to/file.jar.
--container-image-properties Opcional: chaves de propriedade, especificadas no formato prefix:property.
Por exemplo, core:hadoop.tmp.dir.
Para mais informações, consulte Propriedades do cluster.
--vpc-network-tags Opcional: uma lista de tags de rede a serem aplicadas ao job.
--vpc-network-name Opcional: a rede de nuvem privada virtual em que o job é executado. Por padrão, o Dataplex Universal Catalog usa a rede VPC chamada Default no projeto.
Use apenas um dos seguintes: --vpc-network-name ou --vpc-sub-network-name.
--vpc-sub-network-name Opcional: a sub-rede VPC em que o job é executado.
Use apenas um dos seguintes: --vpc-sub-network-name ou --vpc-network-name.
--trigger-type Tipo de acionador da tarefa especificada pelo usuário. Os valores precisam ser um destes:
ON_DEMAND: a tarefa é executada uma vez logo após a criação.
RECURRING: a tarefa é executada periodicamente em uma programação.
--trigger-start-time Opcional: o horário da primeira execução da tarefa. O formato é `{year}-{month}-{day}T{hour}:{min}:{sec}Z`, em que o fuso horário é UTC. Por exemplo, "2017-01-15T01:30:00Z" codifica 01:30 UTC em 15 de janeiro de 2017. Se esse valor não for especificado, a tarefa será executada após o envio se o tipo de acionador for ON_DEMAND ou na programação especificada se o tipo de acionador for RECURRING.
--trigger-disabled Opcional: impede a execução da tarefa. Esse parâmetro não cancela as tarefas em execução, mas desativa temporariamente as tarefas RECURRING.
--trigger-max-retires Opcional: o número de novas tentativas antes de cancelar. Defina o valor como zero para nunca tentar de novo uma tarefa com falha.
--trigger-schedule Programação do cron para executar tarefas periodicamente.
--description Opcional: descrição da tarefa.
--display-name Opcional: nome de exibição da tarefa.
--labels Opcional: lista de pares de rótulos KEY=VALUE a serem adicionados.
--execution-args Opcional: os argumentos a serem transmitidos para a tarefa. Os argumentos podem ser uma combinação de pares de chave-valor. É possível transmitir uma lista separada por vírgulas de pares de chave-valor como argumentos de execução. Para transmitir argumentos posicionais, defina a chave como TASK_ARGS e o valor como uma string separada por vírgulas de todos os argumentos posicionais. Para usar um delimitador diferente de uma vírgula, consulte escape.
Caso key-value e argumentos posicionais sejam transmitidos juntos, TASK_ARGS será transmitido como o último argumento.
--execution-service-account Conta de serviço a ser usada para executar uma tarefa.
--max-job-execution-lifetime Opcional: a duração máxima antes da expiração da execução do job.
--container-image Opcional: imagem de contêiner personalizada para o ambiente de execução do job. Se não for especificado, uma imagem de contêiner padrão será usada.
--kms-key Opcional: a chave do Cloud KMS a ser usada para criptografia, no formato:
projects/{project_number}/locations/{location_id}/keyRings/{key-ring-name}/cryptoKeys/{key-name}

Exemplo em Java:

glcoud dataplex tasks create --project=<project-name> --location=<location> --lake=<lake-id> --trigger-type=ON_DEMAND spark-main-jar-file-uri=<gcs location to java file> --execution-service-account=<service-account-email> --trigger-start-time=<timestamp after which job starts ex. 2099-01-01T00:00:00Z> --labels=key1=value1,key2=value3,key3=value3 --execution-args=arg1=value1,arg2=value3,arg3=value3 <task-id>

Exemplo do PySpark:

gcloud dataplex tasks create --project=<project-name> --location=<location> --lake=<lake-id> --trigger-type=RECURRING --trigger-schedule=<Cron schedule https://en.wikipedia.org/wiki/Cron> --spark-python-script-file=<gcs location to python script> --execution-service-account=<service-account-email> --execution-args=^::^arg1=value1::arg2=value2::TASK_ARGS="pos-arg1, pos-arg2" <task-id>

REST

Para criar uma tarefa, use o APIs Explorer.

Programar uma tarefa do Spark SQL

gcloud

Para programar uma tarefa do Spark SQL, execute o mesmo comando da CLI gcloud que em Programar uma tarefa do Spark (Java ou Python), com os seguintes parâmetros adicionais:

Parâmetro Descrição
--spark-sql-script O texto da consulta SQL. É necessário spark-sql-script ou spark-sql-script-file.
--spark-sql-script-file Uma referência a um arquivo de consulta. Esse valor pode ser o URI do Cloud Storage do arquivo de consulta ou o caminho para o conteúdo do script SQL. É necessário spark-sql-script ou spark-sql-script-file.
--execution-args Para tarefas do Spark SQL, os seguintes argumentos são obrigatórios e precisam ser transmitidos como argumentos posicionais:
, --output_location, <GCS uri of the output directory>
e --output_format, <output file format>.
Os formatos compatíveis são arquivo CSV, arquivo JSON, parquet e orc.
gcloud dataplex tasks create --project=<project-name> --location=<location> --lake=<lake-id> --execution-service-account=<service-account-email> --trigger-type=ON_DEMAND --spark-sql-script=<sql-script> --execution-args=^::^TASK_ARGS="--output_location, <gcs folder location>, --output_format, json" <sql-task-id>

REST

Para criar uma tarefa, use o APIs Explorer.

Monitorar sua tarefa

Console

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

    Acessar "Processo"

  2. Na guia Tarefas, há uma lista de tarefas filtradas por tipos de modelo de tarefa.

  3. Na coluna Nome, clique em qualquer tarefa que você queira visualizar.

  4. Clique no ID do job da tarefa que você quer conferir.

    A página do Dataproc é aberta no console doGoogle Cloud , permitindo que você veja os detalhes de monitoramento e saída.

gcloud

A tabela a seguir lista os comandos da CLI gcloud para monitorar suas tarefas.

Ação Comando da CLI gcloud
Listar tarefas gcloud dataplex tasks list --project=<project-name> --location=<location> --lake=<lake-id>
Como ver detalhes da tarefa gcloud dataplex tasks describe --project=<project-name> --location=<location> --lake=<lake-id> <task-id>
Listar jobs de uma tarefa gcloud dataplex tasks jobs list --project=<project-name> --location=<location> --lake=<lake-id> --task=<task-id>
Como ver detalhes do job gcloud dataplex tasks jobs describe --project=<project-name> --location=<location> --lake=<lake-id> --task=<task-id> <job-id>

O Dataplex Universal Catalog executa jobs no Dataproc sem servidor (lotes). Para conferir os registros de execução de um job do Dataplex Universal Catalog, siga estas etapas:

  1. Receba o ID do job do Dataproc sem servidor (lotes). Execute este comando:

    gcloud dataplex tasks jobs describe --project=<project-name> --location=<location> --lake=<lake-id> --task=<task-id> <job-id>
    
  2. Veja os registros. Execute o comando a seguir usando o ID do job que você recebeu ao executar o comando anterior:

    gcloud beta dataproc batches wait --project=<project-name> --region=<location> <job-id>
    

REST

Para get ou list uma tarefa ou um job, use o APIs Explorer.

Gerenciar a programação

No console do Google Cloud , dentro do Dataplex Universal Catalog, é possível editar a programação de uma tarefa, excluir uma tarefa ou cancelar um job em andamento. A tabela a seguir lista os comandos da CLI gcloud para essas ações.

Ação Comando da CLI gcloud
Editar programação de tarefas gcloud dataplex tasks update --project=<project-name> --location=<location> --lake=<lake-id> --trigger-schedule=<updated-schedule> <task-id>
Excluir uma tarefa gcloud dataplex tasks delete --project=<project-name> --location=<location> --lake=<lake-id> <task-id>
Cancelar um job gcloud dataplex tasks jobs cancel --project=<project-name> --location=<location> --lake=<lake-id> --task=<task-id> <job-id>

A seguir