Ingerir dados do Jira

info

Beta

Este recurso está em versão Beta. Os administradores do espaço de trabalho podem controlar o acesso a este recurso na página de Pré-visualizações . Veja as prévias do Gerenciador Databricks.

Aprenda como criar um pipeline de ingestão de dados do Jira usando Databricks LakeFlow Connect.

nota

O conector Jira tenta novamente automaticamente com recuo exponencial quando os limites de taxa são atingidos. Se os erros de limite de taxa persistirem, consulte Erros de limite de taxa.

Requisitos

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

  • Seu workspace deve estar habilitado para o Unity Catalog.

  • compute sem servidor (serverless compute) deve estar habilitado para seu workspace. Consulte os requisitos compute sem servidor.

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

    Se o conector suportar a criação pipeline baseada em interface de usuário, um administrador poderá criar a conexão e o pipeline simultaneamente, concluindo os passos desta página. No entanto, se os usuários que criam pipelines utilizarem a criação pipeline baseada em API ou não forem administradores, um administrador deverá primeiro criar a conexão no Catalog Explorer. Consulte Conectar para gerenciar fontes de ingestão.

  • Para usar uma conexão existente, você deve ter os 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 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, é necessário primeiro concluir os passos em Criar uma conexão Jira.

Crie um pipeline de ingestão.

Cada tabela de origem é inserida em uma tabela de transmissão ou em uma tabela de instantâneo, dependendo da origem. Para obter uma lista das tabelas de origem compatíveis, consulte a referência do conector Jira.

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 Jira .
3. Na página **Conexão** do assistente de ingestão, selecione a conexão que armazena suas credenciais de acesso ao Jira. Se você tiver o privilégio CREATE CONNECTION no metastore, você pode clicar em Criar conexão para criar uma nova conexão com os detalhes de autenticação em Criar uma Conexão Jira.
4. Clique em Avançar .
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 gravar logs de eventos. Se você tiver privilégios USE CATALOG e CREATE SCHEMA no catálogo, poderá clicar. Para criar um novo esquema, clique em "Criar esquema" no menu suspenso.
7. Clique em Criar pipeline e continue .
8. Na página Origem , selecione as tabelas que deseja importar. Opcionalmente, você pode filtrar os dados por espaços ou projetos do Jira. Use a chave exata do projeto, não os nomes ou IDs dos projetos.
9. Clique em Salvar e continuar .
10. Na página Destino , selecione um catálogo e um esquema para carregar os dados. Se você tiver privilégios USE CATALOG e CREATE SCHEMA no catálogo, poderá clicar. Para criar um novo esquema, clique em "Criar esquema" no menu suspenso.
11. Clique em Salvar e continuar .
12. (Opcional) Na página de programação e notificações , clique em Criar programar . Defina a frequência de refresh das tabelas de destino.
13. (Opcional) Clique Adicione uma notificação para configurar notificações email para operações pipeline bem-sucedidas ou com falha e, em seguida, clique em Salvar e execute pipeline .

Declarative Automation Bundles

Use pacotes de automação declarativa para gerenciar o pipeline do Jira como código. Os pacotes podem conter definições YAML de Job e tarefa, são gerenciados usando a CLI Databricks e podem ser compartilhados e executados em diferentes espaços de trabalho de destino (como desenvolvimento, teste e produção). Para mais informações, consulte O que são pacotes de automação declarativa?.

1. Crie um pacote usando a CLI do Databricks:

   Bash

   databricks bundle init

2. Adicione dois novos arquivos de recursos 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 de ingestão de dados (por exemplo, resources/jira_job.yml).

3. Implante o pipeline usando a CLI Databricks :

   Bash

   databricks bundle deploy

Databricks notebook

1. Importe o seguinte Notebook para o seu workspace Databricks :

Abrir notebook em uma nova abaOpen in Databricks

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

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

4. Clique em Executar tudo .

Exemplos

Utilize esses exemplos para configurar seu pipeline.

Ingerir uma única tabela de origem

Declarative Automation Bundles

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

YAML

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}

Databricks notebook

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

Python

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 várias tabelas de origem

Declarative Automation Bundles

(Recomendado) 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 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}

Databricks notebook

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

Python

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

Declarative Automation Bundles

O seguinte arquivo de definição de pipeline ingere todas as tabelas de origem Jira disponíveis em um único pipeline. Certifique-se de que seu aplicativo OAuth inclua todos os escopos exigidos pelo conjunto completo de tabelas e que o usuário que realiza a autenticação tenha as permissões necessárias do Jira. O pipeline falha se faltar algum escopo ou permissão necessária.

YAML

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}

Databricks notebook

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

Python

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 tarefas do Declarative Automation Bundles

Declarative Automation Bundles

Segue abaixo um exemplo de arquivo de definição de tarefa para uso com pacotes de automação declarativa. A execução do trabalho ocorre todos os dias, exatamente um dia após a última execução.

YAML

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 os dados ingeridos para projetos específicos do Jira adicionando connector_options.jira_options a qualquer objeto de tabela na definição do seu pipeline. Especifique a chave exata do projeto em include_jira_spaces. As chaves dos projetos diferenciam maiúsculas de minúsculas e são diferentes dos nomes e IDs dos projetos.

Para encontrar a key do seu projeto, consulte o URL dentro do projeto. A key aparece depois de /projects/. Como alternativa, acesse Configurações do projeto > Detalhes para ver a chave atual e a anterior, ou consulte a parte superior do cartão de problema do projeto.

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

Declarative Automation Bundles

YAML

- 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

Databricks notebook

Python

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 para a tabela de problemas

importante

Por default, o conector do Jira não rastreia exclusões para a tabela issues. Os problemas do Jira excluídos permanecem na tabela de destino. Para propagar exclusões, defina use_audit_logs como true em jira_options. Isso requer um plano pago do Jira e um usuário de conexão com permissões de administrador do Jira.

Para detectar e propagar exclusões para a 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 de administrador, portanto, o conector não o lê por default. Quando use_audit_logs é false (o default), a tabela issues retém todas as linhas ingeridas anteriormente e reflete apenas inserções e atualizações. Quando você define use_audit_logs como true, o conector remove uma linha da tabela issues quando o item 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, conforme mostrado nos exemplos a seguir. Esta opção afeta apenas a tabela issues.

Você pode definir use_audit_logs como true em um pipeline existente sem um refresh completo. Isso entra em vigor na próxima atualização do pipeline, quando o conector reconcilia as exclusões que ainda estão disponíveis no log de auditoria do Jira. O Jira retém registros de log de auditoria por um período limitado que depende do seu plano do Jira, portanto, os problemas excluídos antes dessa janela de retenção permanecem na tabela de destino. Para remover essas linhas excluídas mais antigas, execute um refresh completo da tabela issues.

Para os requisitos de ativação do acompanhamento de exclusão, consulte Acompanhamento de exclusão e Como ativo registros de auditoria no Jira?.

Declarative Automation Bundles

YAML

- 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

Python

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 pipeline , consulte Padrões comuns para gerenciar pipeline de ingestão.

Próximos passos

começar, programar e definir alerta em seu pipeline. Consulte Tarefa comum de manutenção pipeline.

Recursos adicionais

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