Importar metadados

É possível importar metadados do catálogo do Dataplex, que entradas e seus aspectos, de um sistema de terceiros para o Dataplex.

Para importar metadados, siga estas etapas:

  1. Determine o escopo do job.

    Além disso, entenda como o Dataplex aplica a lógica de comparação e o modo de sincronização para entradas e aspectos.

  2. Crie um ou mais arquivos de importação de metadados que definam os dados a serem importados.

  3. Salve os arquivos de importação de metadados em um bucket do Cloud Storage.

  4. Executar um job de importação de metadados.

As etapas nesta página pressupõem que você esteja familiarizado com Conceitos do catálogo do Dataplex, incluindo grupos de entrada, tipos de entrada, e tipos de aspecto. Para mais informações, consulte Visão geral do catálogo do Dataplex.

Antes de começar

Antes de importar metadados, conclua as tarefas desta seção.

Funções exigidas

Para garantir que o Conta de serviço do Dataplex tem as permissões necessárias para acessar o bucket do Cloud Storage, peça seu administrador conceder à conta de serviço do Dataplex Papel do IAM Leitor de objetos do Storage (roles/storage.objectViewer) e a permissão storage.buckets.get no bucket.

Para ter as permissões necessárias para gerenciar jobs de metadados, peça ao administrador para conceder a você os seguintes papéis do IAM:

Para mais informações sobre como conceder papéis, consulte Gerenciar acesso.

Também é possível conseguir as permissões necessárias com papéis personalizados ou outros papéis predefinidos.

Criar recursos do Google Cloud

Prepare os seguintes recursos do Google Cloud:

  1. Criar um grupo de entrada para as entradas que você quer importar.
  2. Criar tipos de aspecto para os aspectos que você quer importar.
  3. Criar tipos de entrada para as entradas que você quer importar.
  4. Crie um bucket do Cloud Storage para armazenar seus arquivos de importação de metadados.

Componentes de um job de metadados

Ao importar metadados, considere os seguintes componentes de um job de metadados:

  • Escopo do trabalho: o grupo de entradas, os tipos de entrada e os tipos de aspecto a serem incluídos em o job.
  • Modo de sincronização: se é feita uma atualização completa ou uma atualização incremental atualizam sobre as entradas e aspectos do trabalho.
  • Arquivo de importação de metadados: um arquivo que define os valores a serem definidos para as entradas do trabalho. É possível fornecer vários arquivos de importação de metadados no mesmo job de metadados. Salve os arquivos no Cloud Storage.
  • Lógica de comparação: como o Dataplex determina quais entradas e aspectos a serem modificados.

Escopo do job

O escopo do job define o grupo de entradas, os tipos de entrada e, opcionalmente, tipos de aspecto que você quer incluir em um trabalho de metadados. Ao importar metadados, você modifica as entradas e os aspectos que pertencem aos recursos no escopo do job.

Para definir o escopo do job, siga estas diretrizes:

  • Grupo de entradas: especifique um único grupo de entradas para incluir no job. O trabalho modifica somente as entradas que pertencem a este grupo de entradas. O grupo de entrada e o job precisam estar na mesma região.

  • Tipos de entrada: especifique um ou mais tipos de entrada para incluir no job. A tarefa modifica somente as entradas que pertencem a esses tipos de entrada. O local de um tipo de entrada precisa corresponder ao local da tarefa ou o tipo de entrada precisa ser global.

  • Tipos de aspecto: opcional. Especifique um ou mais tipos de aspecto a serem incluídos no trabalho. Se você especificar um escopo para tipos de aspecto, o trabalho modifica apenas os aspectos que pertencem a esses tipos de aspecto. O local de um tipo de aspecto precisa corresponder ao local da tarefa ou o tipo de aspecto precisa ser global.

Você especifica o escopo do job ao criar um job de metadados.

Modo de sincronização

O modo de sincronização especifica se será feita uma atualização completa ou atualização incremental das entradas e aspectos de um trabalho de metadados.

  • FULL: compatível com entradas. Todas as entradas no escopo do job modificado.

    Se houver uma entrada no Dataplex, mas não estiver incluída na metadados, a entrada será excluída quando você executar o trabalho de metadados.

    A sincronização completa não é compatível com aspectos.

  • INCREMENTAL: compatível com aspectos. Um aspecto só é modificado se o arquivo de importação de metadados incluir uma referência ao aspecto no nos campos updateMask e aspectKeys. Para mais informações sobre esses campos no arquivo de importação de metadados, consulte a Seção Estrutura de um item de importação deste documento.

    A sincronização incremental não é compatível com entradas.

Você especifica o modo de sincronização ao criar um job de metadados.

Arquivo de importação de metadados

O arquivo de importação de metadados é uma coleção das entradas e aspectos que você que quiser modificar. Define os valores a serem definidos para todos os campos que pertencem a essas entradas e aspectos. Você prepara o arquivo antes de executar um job de metadados.

É possível fornecer vários arquivos de importação de metadados no mesmo job.

As entradas fornecidas no arquivo substituem completamente todas as entradas entradas para todos os recursos que estão no escopo do job. Isso significa que você precisa incluir valores para todas as entradas em um job, não apenas os valores que que você deseja adicionar ou atualizar. Para ver uma lista das entradas atuais do seu projeto para usar como ponto de partida, use o Método de API entries.list.

Todas as entradas e aspectos incluídos no arquivo devem pertencer ao grupos de entradas, tipos de entrada e tipos de aspecto que você define no escopo do trabalho.

Use as diretrizes nas seções a seguir para criar um arquivo de importação de metadados.

Estrutura do arquivo

Cada linha no arquivo de importação de metadados contém um objeto JSON que corresponde a um item de importação. Um item de importação é um objeto que descreve os valores para modificar para uma entrada e seus aspectos anexados.

É possível fornecer vários itens de importação em um único arquivo de importação de metadados. No entanto, não fornecem o mesmo item de importação mais de uma vez em um trabalho de metadados. Use um caractere de nova linha (0x0a) para separar cada item de importação.

Um arquivo de importação de metadados com um caractere de nova linha entre cada item de importação é exibido. como o exemplo a seguir:

{ "entry": { "name": "entry 1", #Information about entry 1 }
{ "entry": { "name": "entry 2", #Information about entry 2 }

Estrutura de um item de importação

Cada item de importação no arquivo de importação de metadados inclui os campos a seguir. O exemplo a seguir é formatado com quebras de linha para facilitar a leitura, mas quando você salvar o arquivo, inclua um caractere de nova linha somente depois de cada importação do item de linha. Não inclua quebras de linha entre os campos de um único item de importação.

{
  "entry": {
    "name": "ENTRY_NAME",
    "entryType": "ENTRY_TYPE",
    "entrySource": {
      "resource": "RESOURCE",
      "system": "SYSTEM",
      "platform": "PLATFORM",
      "displayName": "DISPLAY_NAME",
      "description": "DESCRIPTION",
      "createTime": "ENTRY_CREATE_TIMESTAMP",
      "updateTime": "ENTRY_UPDATE_TIMESTAMP"
    }
    "aspects": {
      "ASPECT": {
        "data": {
          "KEY": "VALUE"
        },
        "aspectSource": {
          "createTime": "ASPECT_CREATE_TIMESTAMP"
          "updateTime": "ASPECT_UPDATE_TIMESTAMP"
        }
      },
      # Additional aspect maps
    },
    "parentEntry": "PARENT_ENTRY",
    "fullyQualifiedName": "FULLY_QUALIFIED_NAME"
  },
  "updateMask": "UPDATE_MASK_FIELDS",
  "aspectKeys": [
    "ASPECT_KEY",
    # Additional aspect keys
  ],
}

Substitua:

  • ENTRY_NAME: o nome do recurso relativo da entrada. no formato projects/PROJECT_ID_OR_NUMBER/locations/LOCATION_ID/entryGroups/ENTRY_GROUP_ID/entries/ENTRY_ID.
  • ENTRY_TYPE: o nome do recurso relativo do tipo de entrada usado para criar esta entrada, no formato projects/PROJECT_ID_OR_NUMBER/locations/LOCATION_ID/entryTypes/ENTRY_TYPE_ID.
  • entrySource: informações do sistema de origem sobre o recurso de dados que é representada pela entrada:
    • RESOURCE: o nome do recurso na origem. sistema.
    • SYSTEM: o nome do sistema de origem.
    • PLATFORM: a plataforma que contém o sistema de origem.
    • DISPLAY_NAME: um nome de exibição fácil de usar.
    • DESCRIPTION: uma descrição da entrada.
    • ENTRY_CREATE_TIMESTAMP: a hora em que a entrada foi criados no sistema de origem.
    • ENTRY_UPDATE_TIMESTAMP: a hora em que a entrada foi atualizados no sistema de origem.

  • aspects: os aspectos anexados à entrada. O objeto aspect e seus dados são chamados de mapa de aspectos.

    • ASPECT: um aspecto anexado à entrada. Dependendo de como o aspecto é anexado à entrada, use uma das seguintes opções: formatos:

      • Se o aspecto estiver anexado diretamente à entrada, forneça o recurso relativo nome de seu tipo de aspecto, no formato PROJECT_ID_OR_NUMBER.LOCATION_ID.ASPECT_TYPE_ID:
      • Se o aspecto estiver anexado ao caminho da entrada, forneça o valor caminho, no formato PROJECT_ID_OR_NUMBER.LOCATION_ID.ASPECT_TYPE_ID@PATH:

    • KEY e VALUE: o conteúdo do de acordo com o esquema de tipo de aspecto. O conteúdo precisa ser codificado como UTF-8 O tamanho máximo do campo é 120 KB.

    • ASPECT_CREATE_TIMESTAMP: a hora em que o aspecto foi criado. no sistema de origem.

    • ASPECT_UPDATE_TIMESTAMP: a hora em que o aspecto foi atualizado. no sistema de origem.

    • PARENT_ENTRY: o nome do recurso da entrada pai.

    • FULLY_QUALIFIED_NAME: um nome para a entrada que pode ser referenciadas por um sistema externo.

  • UPDATE_MASK_FIELDS: os campos a serem atualizados, em caminhos que são em relação ao recurso Entry. Separe cada campo com uma vírgula.

    No modo de sincronização de entrada FULL, o Dataplex inclui os caminhos de todos dos campos de uma entrada que pode ser modificada, incluindo aspectos.

    O campo update_mask é ignorado quando uma entrada é criada ou recriada.

  • ASPECT_KEY: os aspectos a serem modificados. Oferece suporte ao seguintes sintaxes:

    • ASPECT_TYPE_REFERENCE: corresponde ao tipo de aspecto de aspectos que estão anexados diretamente à entrada.
    • ASPECT_TYPE_REFERENCE@PATH: corresponde ao tipo de aspecto e ao caminho especificado.
    • ASPECT_TYPE_REFERENCE@*: corresponde ao tipo de aspecto. para todos os caminhos.

    Substitua ASPECT_TYPE_REFERENCE por uma referência ao tipo de aspecto, no formato PROJECT_ID_OR_NUMBER.LOCATION_ID.ASPECT_TYPE_ID.

    Se você deixar esse campo em branco, ele será tratado como uma especificação exata das aspectos que estão presentes na entrada especificada.

    No modo de sincronização de entrada FULL, o Dataplex adiciona implicitamente as chaves para todos os aspectos necessários de uma entrada.

Requisitos dos arquivos

O arquivo de importação de metadados tem os seguintes requisitos:

  • O arquivo precisa estar no formato JSON Lines, que é um arquivo JSON delimitado por nova linha. Usar um caractere de nova linha (0x0a) para separar cada item importado.
  • O arquivo precisa usar a codificação de caracteres UTF-8.
  • As extensões de arquivo aceitas são .jsonl e .json.
  • O tamanho do arquivo precisa ser menor que 1 GiB.
  • As entradas e os aspectos especificados no arquivo devem fazer parte do escopo do job de importação.
  • O arquivo precisa ser enviado para um bucket do Cloud Storage. Não salve o arquivo em uma pasta chamada CLOUD_STORAGE_URI/deletions/.

Lógica de comparação

O Dataplex determina quais entradas e aspectos modificar comparando as e carimbos de data/hora fornecidos no arquivo de importação de metadados com os valores e carimbos de data/hora que existem no projeto.

Em alto nível, o Dataplex atualiza os valores no seu projeto quando pelo menos uma alteração proposta no arquivo de importação de metadados será alterada. o estado do seu projeto quando o job for executado, sem introduzir versões dados. A alteração proposta precisa ser referenciada no campo da máscara de atualização ou no aspecto chaves no arquivo de importação de metadados.

Para cada entrada que faz parte do escopo do job, o Dataplex faz uma o seguinte:

  • Cria uma entrada e aspectos anexados. Se o arquivo de importação de metadados incluir uma entrada que não existe no seu projeto, o Dataplex cria a entrada e os aspectos anexados.
  • Exclui uma entrada e aspectos anexados. Se houver uma entrada na sua projeto, mas o arquivo de importação de metadados não inclui a entrada, O Dataplex exclui a entrada e os aspectos anexados do projeto.

  • Atualiza uma entrada e aspectos anexados. Se uma entrada existir nos dois o arquivo de importação de metadados e, no seu projeto, o Dataplex avalia os carimbos de data/hora da origem de entrada e da origem do aspecto que são associados à entrada para determinar quais valores modificar. Depois, O Dataplex faz uma ou mais das seguintes ações:

    • Recria a entrada. Se a origem da entrada criar um carimbo de data/hora no arquivo de importação de metadados é mais recente do que o carimbo de data/hora correspondente no projeto, o Dataplex recria a entrada no projeto.
    • Atualiza a entrada. Se o carimbo de data/hora da atualização da origem de entrada nos metadados de importação é mais recente do que o carimbo de data/hora correspondente no seu projeto, O Dataplex atualiza a entrada no seu projeto.
    • Cria um aspecto. Se um aspecto estiver incluído no objeto de entrada no de importação de metadados, mas não esteja incluído no campo de máscara de atualização, O Dataplex cria o aspecto.
    • Exclui um aspecto. Se um aspecto não estiver incluído no objeto de entrada no o arquivo de importação de metadados, mas incluído no campo de máscara de atualização, O Dataplex exclui o aspecto.

    • Atualiza um aspecto. Se o carimbo de data/hora da atualização da fonte do aspecto nos metadados de importação é mais recente do que o carimbo de data/hora correspondente no seu projeto, O Dataplex atualiza o aspecto no seu projeto. O Dataplex também atualiza o aspecto se a entrada anexada estiver está faltando um carimbo de data/hora de atualização da fonte de entrada ou se esse carimbo no arquivo de importação de metadados é mais recente do que o carimbo de data/hora correspondente em seu projeto.

      No entanto, se pelo menos um aspecto no arquivo de importação de metadados tiver um que o carimbo de data/hora correspondente no projeto, O Dataplex não faz atualizações na entrada anexada.

Criar um arquivo de importação de metadados

Antes de importar metadados, crie um arquivo de importação de metadados para seu job. Siga estas etapas:

  1. Prepare um arquivo de importação de metadados da seguinte forma: as diretrizes descritas anteriormente neste documento.
  2. Faça upload do arquivo para um bucket do Cloud Storage.

É possível fornecer vários arquivos de importação de metadados no mesmo job. Para fornecer vários arquivos, salvá-los no mesmo Cloud Storage do Google Cloud. Ao executar o job, você especifica um bucket, não um arquivo específico. O Dataplex ingere metadados de todos os arquivos salvos incluindo os que estão em subpastas.

Executar um job de importação de metadados

Depois de criar um arquivo de importação de metadados, execute um job de importação de metadados usando o API.

REST

Para importar metadados, use o método método metadataJobs.create.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PROJECT_NUMBER: o número do projeto do Google Cloud ou ID do projeto.
  • LOCATION_ID: o local do Google Cloud, como us-central1.
  • METADATA_JOB_ID: opcional. O ID do job de metadados.

  • CLOUD_STORAGE_URI: o URI do Bucket ou pasta do Cloud Storage que contém os arquivos de importação de metadados. Para mais informações sobre os requisitos do arquivo, consulte Arquivo de importação de metadados.

  • ENTRY_GROUP: o nome do recurso relativo do grupo de entrada que está no escopo do trabalho, no formato projects/PROJECT_ID_OR_NUMBER/locations/LOCATION_ID/entryGroups/ENTRY_GROUP_ID. Informe apenas um grupo de entrada. Para mais informações, consulte Escopo do job.

  • ENTRY_TYPE: o nome do recurso relativo de um tipo de entrada que é no escopo do trabalho, no formato projects/PROJECT_ID_OR_NUMBER/locations/LOCATION_ID/entryTypes/ENTRY_TYPE_ID. Para mais informações, consulte Escopo do job.

  • ASPECT_TYPE: opcional. O nome de recurso relativo de um aspecto tipo que está no escopo do trabalho, no formato projects/PROJECT_ID_OR_NUMBER/locations/LOCATION_ID/aspectTypes/ASPECT_TYPE_ID: Para mais informações, consulte Escopo do job.
  • LOG_LEVEL: o nível de registros a serem capturados, como INFO ou DEBUG. Para mais informações, consulte Veja os registros de jobs e solucione problemas.

Método HTTP e URL: 

POST https://dataplex.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/metadataJobs?metadataJobId=METADATA_JOB_ID

Corpo JSON da solicitação:

{
  "type": IMPORT,
  "import_spec": {
    "source_storage_uri": gs://CLOUD_STORAGE_URI/,
    "scope": {
      "entryGroups": [
        ENTRY_GROUP
      ],
      "entry_types": [
        ENTRY_TYPE
      ],
      "aspect_types": [
        ASPECT_TYPE
      ]
    },
    "entry_sync_mode": FULL,
    "aspect_sync_mode": INCREMENTAL,
    "log_level": LOG_LEVEL
  }
}

Para enviar a solicitação, expanda uma destas opções:

A resposta identifica uma operação de longa duração.

Receber detalhes sobre um job de metadados

Para obter informações sobre um trabalho de metadados, como o status do trabalho e as número de entradas que foram modificadas, siga as etapas abaixo. Para mais informações sobre como resolver problemas de uma tarefa com falha, consulte a Visualizar registros de jobs e solucionar problemas deste documento.

REST

Para obter informações sobre um trabalho de metadados, use o método metadataJobs.get.

Receber uma lista de jobs de metadados

É possível conseguir uma lista dos jobs de metadados mais recentes. Empregos mais antigos que têm atingir um estado terminal são excluídos periodicamente do sistema.

REST

Para obter uma lista dos jobs de metadados mais recentes, use o método metadataJobs.list.

Cancelar um job de metadados

É possível cancelar um job de metadados que você não quer executar.

REST

Para cancelar um job de metadados, use o método metadataJobs.cancel.

Ver registros de jobs e resolver problemas

Usar o Cloud Logging para ver os registros de um job de metadados. Para mais informações, consulte Monitorar os registros do Dataplex.

Você configura o nível de registro ao criar um job de metadados. O registro a seguir estão disponíveis:

  • INFO: fornece registros no nível geral do job. Inclui registros agregados sobre importar itens, mas não especifica qual deles contém um erro.

  • DEBUG: fornece registros detalhados para cada item de importação. Usar a geração de registros no nível de depuração para resolver problemas com itens de importação específicos. Por exemplo, use geração de registros de nível de depuração para identificar recursos que estão faltando no job entradas ou aspectos que não estão em conformidade com o tipo de entrada associado ou tipo de aspecto ou outras configurações incorretas com o arquivo de importação de metadados.

Erros de validação

O Dataplex valida os arquivos de importação de metadados em relação ao metadados em seu projeto. Se houver um problema de validação, o status do job poderá retorna um dos seguintes estados:

  • FAILED: acontece quando o arquivo de importação de metadados tem um erro. O Dataplex não importa os metadados, e o job falha. Exemplos de erros no arquivo de importação de metadados incluem o seguinte:
    • Não é possível analisar um item do arquivo como um item de importação válido
    • Uma entrada ou aspecto no arquivo pertence a um grupo de entradas, um tipo de entrada ou tipo de aspecto que não faz parte do escopo do trabalho.
    • O mesmo nome de entrada é especificado mais de uma vez no job.
    • Um tipo de aspecto especificado no mapa de aspecto ou nas chaves de aspecto não usa o formato PROJECT_ID_OR_NUMBER.LOCATION_ID.ASPECT_TYPE_ID@OPTIONAL_PATH
  • SUCCEEDED_WITH_ERRORS: acontece quando o arquivo de importação de metadados pode ser analisado, mas importar um item no arquivo causaria uma entrada que o projeto fique em um estado inconsistente. O Dataplex ignora essas entradas, mas importa o restante dos metadados do arquivo.

Use os registros de jobs para solucionar o erro.

A seguir