Importar glossários empresariais de uma planilha Google

O utilitário de importação de glossários permite importar glossários, categorias e termos em massa de uma planilha do Google para o Knowledge Catalog (antigo Dataplex Universal Catalog). É possível usar uma planilha para organizar, atualizar e padronizar de forma colaborativa seu vocabulário empresarial em grande escala antes de fazer upload das mudanças no catálogo.

Antes de começar

Antes de importar glossários, conclua os seguintes pré-requisitos.

Configurar a conta de serviço

Para executar o utilitário de importação usando uma planilha do Google, configure uma conta de serviço com as permissões necessárias para acessar a API Google Sheets e personificar suas credenciais de usuário:

  1. Identifique ou crie uma conta de serviço.

    Selecione uma conta de serviço atual ou crie uma nova no projeto em que você executa o utilitário de importação. Para mais informações, consulte Criar contas de serviço. Anote o e-mail da conta de serviço (por exemplo, SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com).

  2. Configurar a identidade temporária de conta de serviço.

    Para executar o script do utilitário de importação localmente, sua conta de usuário precisa ter permissão para personificar a conta de serviço. Conceda à sua conta de usuário o papel de Criador de token da conta de serviço (roles/iam.serviceAccountTokenCreator) na conta de serviço.

    Para mais informações, consulte Gerenciar o acesso a contas de serviço.

  3. Conceda à conta de serviço Editor acesso à planilha do Google.

    Abra o arquivo do Google Planilhas que você quer usar para o processo de importação, clique em Compartilhar e adicione o e-mail da conta de serviço como Editor. Essa permissão permite que a conta de serviço leia ou grave dados na planilha.

Criar um bucket do Cloud Storage

Crie um bucket do Cloud Storage para servir como uma área de preparo para arquivos de importação.

Funções exigidas

Para garantir que a conta de serviço tenha as permissões necessárias para importar glossários de um arquivo do Google Planilhas, peça ao administrador para conceder os seguintes papéis do IAM à conta de serviço:

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

O administrador também pode conceder à conta de serviço as permissões necessárias por meio de papéis personalizados ou de outros papéis predefinidos.

Ativar APIs

Para importar glossários, ative as seguintes APIs no seu projeto:

Funções necessárias para ativar APIs

Para ativar APIs, você precisa da permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão pelo papel de proprietário (roles/owner). Caso contrário, é possível conseguir essa permissão pelo papel de administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.

Ativar as APIs

Configurar o repositório Git

Clone o repositório dataplex-labs:

git clone https://github.com/GoogleCloudPlatform/dataplex-labs.git
cd dataplex-labs/dataplex-quickstart-labs/00-resources/scripts/python/business-glossary-import/dataplex-glossary/import

Instalar dependências

Instale as dependências do Python necessárias:

pip3 install -r requirements.txt

Se você tiver problemas com a instalação do pacote, configure um novo ambiente de desenvolvimento em Python.

Autenticar e configurar a identidade temporária de conta de serviço

Inicialize a Google Cloud CLI e faça a autenticação usando o Application Default Credentials (ADC) com a identidade temporária de conta de serviço:

# Set your service account email address
SA_EMAIL="SERVICE_ACCOUNT_EMAIL"

# Authenticate ADC using service account impersonation and required scopes
gcloud auth application-default login \
  --impersonate-service-account="${SA_EMAIL}" \
  --scopes="https://www.googleapis.com/auth/spreadsheets"

Substitua SERVICE_ACCOUNT_EMAIL pelo ID de e-mail da conta de serviço. Exemplo:

SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com

Criar e estruturar o arquivo do Google Planilhas para importação

Para executar uma importação em massa, crie uma planilha do Google usando um esquema de colunas preciso para que o utilitário de importação possa analisar e validar os campos de metadados. Verifique se você concedeu à conta de serviço Editor acesso à planilha do Google.

A primeira linha da planilha precisa conter estes cabeçalhos de esquema exatos, que diferenciam maiúsculas de minúsculas:

Campo Obrigatório ou opcional Descrição
id Obrigatório Um identificador exclusivo para o termo ou categoria no glossário.
parent Opcional O ID da categoria pai. Se estiver vazio, o item será um filho de nível raiz do glossário. O ID pai referenciado precisa existir na planilha e pertencer a uma categoria.
display_name Obrigatório O nome de exibição do termo ou da categoria.
description Opcional Uma breve descrição do termo ou da categoria.
overview Opcional Uma descrição em rich text do termo ou da categoria (aceita tags HTML).
type Obrigatório O tipo de linha. Os valores válidos são TERM ou CATEGORY.
contact1_email Opcional Endereço de e-mail do gestor de dados principal do termo ou da categoria.
contact1_name Opcional Nome do gestor de dados principal do termo ou da categoria.
contact2_email Opcional Endereço de e-mail do gestor de dados secundário do termo ou da categoria.
contact2_name Opcional Nome do gestor de dados secundário do termo ou da categoria.
label1_key Opcional Chave do primeiro rótulo atribuído.
label1_value Opcional Valor do primeiro rótulo atribuído.
label2_key Opcional Chave do segundo rótulo atribuído.
label2_value Opcional Valor do segundo rótulo atribuído.

Importar glossário do arquivo do Google Planilhas

Depois de configurar o ambiente e preparar o arquivo do Google Planilhas, execute o script glossary_import.py:

python3 bg_import/dataplex-glossary/glossary_import.py

O utilitário glossary_import analisa e valida dados de uma planilha do Google, converte-os em um formato compatível com a API CreateMetadataJob do Knowledge Catalog e os envia para um bucket do Cloud Storage antes de acionar o job de importação. O utilitário de importação imprime o resultado da execução da API CreateMetadataJob diretamente no terminal. Verifique se o status do job indica sucesso.

É possível analisar os registros de execução no diretório logs/ no caminho de execução local. Esses registros ajudam a auditar o processo de transferência e identificar entradas ignoradas ou avisos de formatação.

A seguir