Ingerir dados do Gmail

info

Beta

Esse recurso está em Beta. Os administradores do workspace podem controlar o acesso a esse recurso na página Pré-visualizações . Consulte Gerenciar prévias do Databricks.

Crie um pipeline de ingestão gerenciado do Gmail para carregar as mensagens, rótulos, rascunhos, filtros e perfil de uma caixa de correio em tabelas do Unity Catalog. Você pode criar o pipeline na interface de ingestão de dados, com pacotes de automação declarativa ou por meio da API de Pipelines. Cada pipeline ingere o conjunto de caixas de correio único na conexão.

Requisitos

• Para criar um pipeline de ingestão, você deve primeiro atender aos seguintes requisitos:

  • Seu workspace deve estar habilitado para o Unity Catalog.

  • O recurso de computação sem servidor (Serverless Compute) deve estar habilitado para seu Workspace. Consulte os requisitos de Serverless computação.

  • Para criar uma nova conexão, você deve ter privilégios CREATE CONNECTION no metastore. Consulte Gerenciar privilégios no Unity Catalog.

    Se o conector for compatível com a criação de pipeline baseada na interface do usuário, um administrador poderá criar a conexão e o pipeline ao mesmo tempo, concluindo os passos nesta página. No entanto, se os usuários que criam pipelines usarem a criação de pipeline baseada em API ou forem usuários não administradores, um administrador deverá primeiro criar a conexão no Catalog Explorer. Consulte Conectar-se a fontes de ingestão gerenciadas.

  • Para usar uma conexão existente, você deve ter privilégios USE CONNECTION ou ALL PRIVILEGES no objeto de conexão.

  • Você deve ter privilégios USE CATALOG no catálogo de destino.

  • Você deve ter os privilégios USE SCHEMA e CREATE TABLE em um esquema existente ou privilégios CREATE SCHEMA no catálogo de destino.

• Para importar dados do Gmail, primeiro você precisa concluir os passos em Criar uma conexão com o Gmail.

Criar um pipeline de ingestão

Cada tabela ingerida é gravada em uma tabela de transmissão. O esquema de origem é default. Para obter a lista de tabelas que você pode ingerir, consulte Tabelas compatíveis.

Databricks UI

1. Na barra lateral do workspace do Databricks, clique em Ingestão de dados .
2. Na página Adicionar dados , em Conectores do Databricks , clique em Gmail .
3. Na página Connection do assistente de ingestão, selecione a conexão que armazena suas credenciais de acesso do Gmail. Se você tiver o privilégio CREATE CONNECTION no metastore, poderá clicar em Create connection para criar uma nova conexão com os detalhes de autenticação em Create a Gmail connection.
4. Clique em Avançar .
5. Na página Configuração de ingestão , insira um nome exclusivo para o pipeline.
6. Selecione um catálogo e um esquema para gravar logs de eventos. Se você tiver os privilégios USE CATALOG e CREATE SCHEMA no catálogo, poderá clicar em Create schema no menu suspenso para criar um novo esquema.
7. Clique em Criar pipeline e continuar .
8. Na página Origem , selecione as tabelas para ingestão.
9. Clique em Salvar e continuar .
10. Na página Destination , selecione um catálogo e um esquema para carregar os dados. Se você tiver os privilégios USE CATALOG e CREATE SCHEMA no catálogo, poderá clicar em Create schema no menu suspenso para criar um novo esquema.
11. Clique em Salvar e continuar .
12. (Opcional) Na página Cronogramas e notificações , clique em Crie um agendamento . Defina a frequência para refresh das tabelas de destino.
13. (Opcional) Clique em Adicionar notificação para definir notificações por email para sucesso ou falha da operação do pipeline e, em seguida, clique em Salvar e executar pipeline .

Declarative Automation Bundles

Use os Pacotes de Automação Declarativa para gerenciar pipelines do Gmail como código. Os pacotes podem conter definições YAML de Jobs e tarefas, são gerenciados usando a CLI do Databricks e podem ser compartilhados e ter execução em diferentes workspaces de destino (como desenvolvimento, staging e produção). Para obter mais informações, consulte O que são os Pacotes de Automação Declarativa?.

1. Crie um pacote usando a CLI do Databricks:

   Bash

   databricks bundle init

2. Adicione dois novos arquivos de recurso ao pacote:

   • Um arquivo de definição de pipeline (por exemplo, resources/gmail_pipeline.yml). Consulte pipeline.ingestion_definition e Exemplos.
   • Um arquivo de definição de Job que controla a frequência da ingestão de dados (por exemplo, resources/gmail_job.yml).

3. Implante o pipeline usando a CLI do Databricks:

   Bash

   databricks bundle deploy

Databricks notebook

1. Modifique a especificação do pipeline com os detalhes da sua configuração. Consulte pipeline.ingestion_definition e exemplos.
2. Execute o notebook.

Seleção de caixa de correio

A caixa de correio da qual realizar a leitura é definida na conexão, não no pipeline. Configure-o com o campo Mailbox Email (impersonate_email) ao criar a conexão. Consulte Criar uma conexão com o Gmail. A account de serviço personifica este usuário por meio de delegação em todo o domínio, e o conector lê a caixa de correio desse usuário. Se você não a definir, a conexão será autenticada como a própria account de serviço, que não possui caixa de correio para ingerir. O conector marca o valor da caixa de correio como uma coluna mailbox em cada linha.

Cada conexão ingere uma única caixa de correio. Para importar dados de mais de uma caixa de correio, crie uma conexão e um pipeline separados para cada caixa de correio.

Programe o pipeline para ser execução pelo menos semanalmente

A Databricks recomenda agendar a execução do pipeline pelo menos uma vez a cada sete dias. As tabelas messages e message_labels são sincronizadas incrementalmente usando a API de Histórico do Gmail, e o Gmail retém o histórico por um período limitado (normalmente cerca de sete dias).

atenção

Se o pipeline for executado com menos frequência do que a janela de histórico do Gmail, o cursor historyId armazenado poderá expirar. Quando isso ocorre, a próxima execução realiza um refresh completo de messages e message_labels.

Exemplos

Use estes exemplos para configurar seu pipeline.

Ingerir uma única tabela de origem

Declarative Automation Bundles

O arquivo de definição de pipeline a seguir ingere uma única tabela de origem. O recurso pipeline_gmail é o pipeline principal, e objects define uma matriz de tabelas a serem ingeridas. Este exemplo ingere a tabela messages.

YAML

variables:
  dest_catalog:
    default: main
  dest_schema:
    default: ingest_destination_schema

# The main pipeline for gmail_dab
resources:
  pipelines:
    pipeline_gmail:
      name: gmail_pipeline
      catalog: ${var.dest_catalog}
      schema: ${var.dest_schema}
      ingestion_definition:
        connection_name: <gmail-connection>
        objects:
          # An array of objects to ingest from Gmail. This example ingests the messages table.
          - table:
              source_schema: default
              source_table: messages
              destination_catalog: ${var.dest_catalog}
              destination_schema: ${var.dest_schema}

Databricks notebook

A especificação de pipeline a seguir ingere uma única tabela de origem:

Python

pipeline_spec = """
{
  "name": "<pipeline-name>",
  "ingestion_definition": {
    "connection_name": "<gmail-connection>",
    "objects": [
      {
        "table": {
          "source_schema": "default",
          "source_table": "messages",
          "destination_catalog": "main",
          "destination_schema": "ingest_destination_schema"
        }
      }
    ]
  }
}
"""
create_pipeline(pipeline_spec)

Ingerir múltiplas tabelas de origem

Declarative Automation Bundles

O seguinte arquivo de definição de pipeline ingere várias tabelas de origem:

YAML

variables:
  dest_catalog:
    default: main
  dest_schema:
    default: ingest_destination_schema

# The main pipeline for gmail_dab
resources:
  pipelines:
    pipeline_gmail:
      name: gmail_pipeline
      catalog: ${var.dest_catalog}
      schema: ${var.dest_schema}
      ingestion_definition:
        connection_name: <gmail-connection>
        objects:
          # An array of objects to ingest from Gmail. This example ingests the messages and message_labels tables.
          - table:
              source_schema: default
              source_table: messages
              destination_catalog: ${var.dest_catalog}
              destination_schema: ${var.dest_schema}
          - table:
              source_schema: default
              source_table: message_labels
              destination_catalog: ${var.dest_catalog}
              destination_schema: ${var.dest_schema}

Databricks notebook

A seguinte especificação de pipeline ingere várias tabelas de origem:

Python

pipeline_spec = """
{
  "name": "<pipeline-name>",
  "ingestion_definition": {
    "connection_name": "<gmail-connection>",
    "objects": [
      {
        "table": {
          "source_schema": "default",
          "source_table": "messages",
          "destination_catalog": "main",
          "destination_schema": "ingest_destination_schema"
        }
      },
      {
        "table": {
          "source_schema": "default",
          "source_table": "message_labels",
          "destination_catalog": "main",
          "destination_schema": "ingest_destination_schema"
        }
      }
    ]
  }
}
"""
create_pipeline(pipeline_spec)

Arquivo de definição de job dos Pacotes de Automação Declarativa

O exemplo a seguir é um arquivo de definição de job para usar com Pacotes de Automação Declarativa. O job é executado todos os dias, exatamente um dia após a última execução.

YAML

resources:
  jobs:
    gmail_dab_job:
      name: gmail_dab_job

      trigger:
        periodic:
          interval: 1
          unit: DAYS

      email_notifications:
        on_failure:
          - <email-address>

      tasks:
        - task_key: refresh_pipeline
          pipeline_task:
            pipeline_id: ${resources.pipelines.pipeline_gmail.id}

Passos seguintes

Comece, programe e defina alertas em seu pipeline. Consulte Tarefas comuns de manutenção de pipeline.

Outros recursos

• Perguntas frequentes sobre o conector do Gmail
• Limitações do conector do Gmail
• Referência do conector do Gmail
• Solucione problemas de ingestão do Gmail