Importar links de entrada de uma planilha Google

O utilitário de importação de links de entrada permite importar em massa links de entrada de uma planilha Google para o Knowledge Catalog (antigo Dataplex Universal Catalog). É possível usar uma planilha para definir e atualizar as relações entre termos do glossário e recursos de dados em grande escala.

Antes de começar

Antes de importar links de entrada para o Knowledge Catalog, conclua os pré-requisitos a seguir.

Configurar a conta de serviço

Para executar o utilitário de importação usando o Google Planilhas, 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 links de entrada de uma planilha do Google, 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 links de entrada, 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
cd dataplex-glossary

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 init
gcloud auth login
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

Requisitos para importação entre projetos

Para importar links de entrada em vários projetos do Google Cloud , verifique se a configuração atende aos seguintes requisitos antes de executar o utilitário de importação:

  • Configure as permissões do IAM entre projetos: a conta de serviço que executa o script de importação precisa ter permissões suficientes em todos os projetos de destino.

  • Verificar a existência de entradas: as entradas de destino já precisam existir nos respectivos projetos do Knowledge Catalog antes de executar a importação.

  • Conceda ao bucket do Cloud Storage acesso aos agentes de serviço do Knowledge Catalog: as contas de serviço do Knowledge Catalog em cada projeto de destino exigem acesso aos buckets do Cloud Storage.

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 coluna preciso para definir os links de entrada, incluindo os tipos de link de entrada definition, related e synonym. Esse esquema permite que o utilitário de importação analise e valide seus 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:

Cabeçalho da coluna Obrigatório ou opcional Descrição
entry_link_type Obrigatório O valor precisa ser definition, related ou synonym.
source_entry Obrigatório O caminho completo do recurso da entrada de origem no formato:
projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRYGROUP_NAME/entries/ENTRY_NAME
target_entry Obrigatório O caminho completo do recurso da entrada de destino no formato:
projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRYGROUP_NAME/entries/ENTRY_NAME
source_path Opcional Caminho da coluna ou do campo para links de definição (por exemplo, Schema.column_name).

Configurar variáveis de ambiente

Configure as seguintes variáveis de ambiente:

# Set your Google Sheet URL
export SPREADSHEET_URL="GOOGLE_SHEET_URL"

# Set your bucket name
export BUCKETS="COMMA_SEPARATED_LIST_OF_BUCKETS"

# Set the project ID
export USER_PROJECT="USER_PROJECT"

Importar links de entrada do arquivo do Google Planilhas

Para importar os links de entrada da planilha do Google para o Knowledge Catalog, execute o script entrylinks-import.py:

cd import
python3 entrylinks-import.py \
  --spreadsheet-url="$SPREADSHEET_URL" \
  --buckets="$BUCKETS" \
  --user-project="$USER_PROJECT"

Para executar vários jobs de importação em paralelo, especifique vários buckets do Cloud Storage no parâmetro --buckets. O script divide os metadados em lotes menores e os processa simultaneamente nos buckets, reduzindo o tempo total de ingestão.

É 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