Ingerir dados do Jira

Saiba como criar um pipeline de ingestão Jira gerenciado usando o Databricks Lakeflow Connect.

Requisitos

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

  • O seu workspace precisa estar habilitado para o Unity Catalog.

  • A computação sem servidor deve ser habilitada para seu workspace. Consulte os requisitos de computação sem servidor.

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

    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 seguindo os passos desta 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 Gerenciador de Catálogos. Consulte Conectar-se às fontes de ingestão gerenciadas.

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

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

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

• Para ingerir do Jira, primeiro você deve concluir as etapas em Criar uma conexão Jira.

Criar um pipeline de ingestão

Cada tabela de origem é transformada em uma tabela de streaming ou em uma tabela de instantâneo, dependendo da origem. Para uma lista das tabelas de origem suportadas, consulte a referência do conector Jira.

Interface do usuário do Databricks

1. Na barra lateral do workspace do Azure Databricks, clique em Ingestão de Dados.
2. Na página Adicionar dados, em conectores do Databricks, clique em Jira.
3. Na página Conexão do assistente de ingestão, selecione a conexão que armazena suas credenciais de acesso Jira. Se você tiver o privilégio CREATE CONNECTION no metastore, poderá clicar em Criar conexão para criar uma conexão usando os detalhes de autenticação em Criar uma conexão do Jira.
4. Clique em Próximo.
5. Na página de configuração de ingestão, insira um nome exclusivo para o pipeline.
6. Selecione um catálogo e um esquema para o qual gravar logs de eventos. Se você tiver privilégios USE CATALOG e CREATE SCHEMA no catálogo, poderá clicar em Criar esquema no menu suspenso para criar um novo esquema.
7. Clique em Criar pipeline e continuar.
8. Na página Origem , selecione as tabelas a serem ingeridas. Opcionalmente, você pode filtrar os dados por espaços ou projetos Jira. Use as chaves exatas do projeto, não os nomes de projeto ou as IDs.
9. Clique em Salvar e continuar.
10. Na página Destino , selecione um catálogo e um esquema para carregar dados. Se você tiver privilégios USE CATALOG e CREATE SCHEMA no catálogo, poderá clicar em Criar esquema no menu suspenso para criar um novo esquema.
11. Clique em Salvar e continuar.
12. (Opcional) Na página Agendas e notificações , clique no Criar agendamento. Defina a frequência para atualizar as tabelas de destino.
13. (Opcional) Clique Adicione uma notificação para definir notificações por email para êxito ou falha na operação do pipeline e clique em Salvar e executar pipeline.

Pacotes de Automação Declarativa

Use Pacotes de Automação Declarativa para gerenciar pipelines do Jira como código. Os pacotes podem conter definições YAML de trabalhos e tarefas, são gerenciados usando a CLI do Databricks e podem ser compartilhados e executados em diferentes workspaces de destino (como desenvolvimento, preparo e produção). Para obter mais informações, consulte o que são pacotes de automação declarativa?.

1. Crie um pacote usando a CLI do Databricks:

   databricks bundle init
   

2. Adicione dois novos arquivos de recurso ao pacote:

   • Um arquivo de definição de pipeline (por exemplo, resources/jira_pipeline.yml). Consulte pipeline.ingestion_definition e exemplos.
   • Um arquivo de definição de trabalho que controla a frequência da ingestão de dados (por exemplo, resources/jira_job.yml).

3. Implante o pipeline usando a CLI do Databricks:

   databricks bundle deploy
   

Bloco de anotações do Databricks

1. Importe o bloco de anotações a seguir para o workspace do Azure Databricks:

   Obter laptop

2. Deixe a célula um como está.

3. Modifique a terceira célula com os detalhes da configuração do pipeline. Consulte pipeline.ingestion_definition e exemplos.

4. Clique em Executar tudo.

Exemplos

Use esses exemplos para configurar o pipeline.

Ingerir uma única tabela de origem

Pacotes de Automação Declarativa

(Recomendado) O arquivo de definição de pipeline a seguir ingere uma única tabela de origem.

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

# The main pipeline for jira_dab
resources:
  pipelines:
    pipeline_jira:
      name: jira_pipeline
      catalog: ${var.dest_catalog}
      schema: ${var.dest_schema}
      ingestion_definition:
        connection_name: <jira-connection>
        objects:
          # An array of objects to ingest from Jira. This example ingests the issues table.
          - table:
              source_schema: default
              source_table: issues
              destination_catalog: ${var.dest_catalog}
              destination_schema: ${var.dest_schema}

Bloco de anotações do Databricks

(Recomendado) A seguinte especificação do pipeline ingere uma única tabela de origem:

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

Ingerir múltiplas tabelas de origem

Pacotes de Automação Declarativa

(Recomendado) O arquivo de definição de pipeline a seguir ingere várias tabelas de origem.

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

# The main pipeline for jira_dab
resources:
  pipelines:
    pipeline_jira:
      name: jira_pipeline
      catalog: ${var.dest_catalog}
      schema: ${var.dest_schema}
      ingestion_definition:
        connection_name: <jira-connection>
        objects:
          # An array of objects to ingest from Jira. This example ingests the issues and projects tables.
          - table:
              source_schema: default
              source_table: issues
              destination_catalog: ${var.dest_catalog}
              destination_schema: ${var.dest_schema}
          - table:
              source_schema: default
              source_table: projects
              destination_catalog: ${var.dest_catalog}
              destination_schema: ${var.dest_schema}

Bloco de anotações do Databricks

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

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

Ingerir todas as tabelas de origem

Pacotes de Automação Declarativa

O arquivo de definição de pipeline a seguir importa todas as tabelas de origem Jira disponíveis em um único pipeline. Verifique se o aplicativo OAuth inclui todos os escopos exigidos pelo conjunto de tabelas completo e se o usuário de autenticação tem as permissões Jira necessárias. Os pipelines falharão se algum escopo ou permissão necessário estiver ausente.

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

# The main pipeline for jira_dab
resources:
  pipelines:
    pipeline_jira:
      name: jira_pipeline
      catalog: ${var.dest_catalog}
      schema: ${var.dest_schema}
      ingestion_definition:
        connection_name: <jira-connection>
        objects:
          # An array of objects to ingest from Jira. This example ingests all tables in the default schema.
          - schema:
              source_schema: default
              destination_catalog: ${var.dest_catalog}
              destination_schema: ${var.dest_schema}

Bloco de anotações do Databricks

A seguinte especificação de pipeline ingere todas as tabelas de origem:

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

Arquivo de definição de trabalho para Pacotes de Automação Declarativa

Pacotes de Automação Declarativa

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

resources:
  jobs:
    jira_dab_job:
      name: jira_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_jira.id}

Filtrar por projeto

Você pode filtrar dados ingeridos para projetos específicos do Jira adicionando connector_options.jira_options a qualquer objeto de tabela em sua definição de pipeline. Especifique as chaves exatas do projeto em include_jira_spaces. Chaves de projeto diferenciam maiúsculas de minúsculas e diferem de nomes e IDs de projeto.

Para localizar a chave do projeto, verifique a URL dentro do projeto. A chave é exibida após /projects/. Como alternativa, vá para Configurações do Projeto>Detalhes para ver as chaves atuais e anteriores ou examine a parte superior de um cartão de problema do projeto.

Para obter mais informações, consulte Editar os detalhes de um espaço na documentação do Jira.

Pacotes de Automação Declarativa

- table:
    source_schema: default
    source_table: issues
    destination_catalog: ${var.dest_catalog}
    destination_schema: ${var.dest_schema}
    connector_options:
      jira_options:
        include_jira_spaces:
          - KEY1
          - KEY2

Bloco de anotações do Databricks

pipeline_spec = """
{
  "name": "<pipeline-name>",
  "ingestion_definition": {
    "connection_name": "<jira-connection>",
    "objects": [
      {
        "table": {
          "source_schema": "default",
          "source_table": "issues",
          "destination_catalog": "main",
          "destination_schema": "ingest_destination_schema",
          "connector_options": {
            "jira_options": {
              "include_jira_spaces": ["KEY1", "KEY2"]
            }
          }
        }
      }
    ]
  }
}
"""
create_pipeline(pipeline_spec)

Rastrear exclusões da tabela issues

Para detectar e propagar exclusões na tabela issues, o conector lê o log de auditoria do Jira. A leitura do log de auditoria requer um plano pago do Jira e permissões administrativas, por isso, o conector não o lê por padrão. Quando use_audit_logs é false (o padrão), a issues tabela mantém todas as linhas previamente ingeridas e reflete apenas inserções e atualizações. Quando você define use_audit_logs para true, o conector remove uma linha da issues tabela quando o problema correspondente é excluído no Jira.

Para rastrear exclusões, defina use_audit_logs como true em connector_options.jira_options no objeto de tabela issues, como mostrado nos exemplos a seguir. Essa opção afeta apenas a issues tabela.

Você pode definir use_audit_logs como true em um pipeline existente sem uma atualização completa. Isso entra em vigor na atualização seguinte do pipeline, quando o conector tiver processado as exclusões que ainda estão disponíveis no log de auditoria do Jira. O Jira mantém os registros de log de auditoria por um período limitado que depende do seu plano do Jira; então, os itens excluídos antes dessa janela de retenção permanecem na tabela de destino. Para remover essas linhas antigas excluídas, faça uma atualização completa da issues tabela.

Para ver os requisitos para habilitar o rastreamento de exclusão, consulte Rastreamento de exclusão e Como habilito os logs de auditoria no Jira?.

Pacotes de Automação Declarativa

- table:
    source_schema: default
    source_table: issues
    destination_catalog: ${var.dest_catalog}
    destination_schema: ${var.dest_schema}
    connector_options:
      jira_options:
        use_audit_logs: true

Notebook

pipeline_spec = """
{
  "name": "<pipeline-name>",
  "ingestion_definition": {
    "connection_name": "<jira-connection>",
    "objects": [
      {
        "table": {
          "source_schema": "default",
          "source_table": "issues",
          "destination_catalog": "main",
          "destination_schema": "ingest_destination_schema",
          "connector_options": {
            "jira_options": {
              "use_audit_logs": true
            }
          }
        }
      }
    ]
  }
}
"""
create_pipeline(pipeline_spec)

Padrões comuns

Para configurações avançadas de pipeline, consulte padrões comuns para pipelines de ingestão gerenciada.

Próximas Etapas 

Inicie, agende e defina alertas no seu fluxo de trabalho. Consulte Tarefas Comuns de Manutenção de Pipeline.

Recursos adicionais

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