Manual do utilizador da malha de dados

A arquitetura de malha de dados para a framework Cortex expande a base de dados para permitir a governança, a capacidade de deteção e o controlo de acesso de dados através dos metadados do BigQuery e do catálogo universal do Dataplex. Isto é implementado através da disponibilização de um conjunto base de recursos de metadados e anotações de recursos do BigQuery que podem ser personalizados e, opcionalmente, implementados juntamente com a base de dados. Estas especificações base oferecem uma configuração personalizada que é a base de metadados para complementar a base de dados do Cortex Framework. Consulte os conceitos de malha de dados antes de continuar com este guia.

Os passos descritos nesta página foram concebidos especificamente para configurar a malha de dados para a framework Cortex. Encontre os ficheiros de configuração da arquitetura de malha de dados nas pastas específicas de cada carga de trabalho na secção de diretórios da arquitetura de malha de dados.

Aviso: este guia da malha de dados pode mudar ao longo do tempo. Contacte a equipa do Cortex para enviar feedback ou comunicar problemas relacionados.

Figura 1. Arquitetura de malha de dados para o Cortex Framework.

Design

A malha de dados do Cortex foi concebida de forma semelhante à base de dados geral e consiste em três fases com diferentes subcomponentes geridos pelo Cortex ou pelos utilizadores:

1. Atualização das especificações dos recursos base: com cada lançamento, o Cortex atualiza as especificações dos recursos base, fornecendo uma base de metadados padronizada para a malha de dados.
2. Personalização das especificações dos recursos: antes da implementação, os utilizadores podem personalizar as especificações dos recursos para se alinharem com os respetivos exemplos de utilização e requisitos específicos.
3. Implementação e atualizações da malha de dados: os utilizadores podem ativar a malha de dados no ficheiro de configuração do Cortex. É implementado após os recursos de dados durante a implementação do Cortex. Além disso, os utilizadores têm a flexibilidade de implementar a malha de dados de forma independente para atualizações adicionais.

Figura 2. Design de malha de dados para o Cortex Framework.

Diretórios de malha de dados

Encontre os ficheiros de configuração base da malha de dados para cada carga de trabalho e origem de dados nas seguintes localizações. Tenha em atenção que os diretórios contêm uma estrutura de ficheiros diferente, mas todas as especificações estão localizadas de forma semelhante na pasta config.

Carga de trabalho	Origem de dados	Caminho do diretório
Operacional	SAP ECC	src/SAP/SAP_REPORTING/config/ecc
	SAP S/4 HANA	src/SAP/SAP_REPORTING/config/s4
	Salesforce Sales Cloud (SFDC)	src/SFDC/config
	Oracle EBS	src/OracleEBS/config
Marketing	CM360	src/marketing/src/CM360/config
	Google Ads	src/marketing/src/GoogleAds/config
	Meta	src/marketing/src/Meta/config
	Salesforce Marketing Cloud (SFMC)	src/marketing/src/SFMC/config
	TikTok	src/marketing/src/TikTok/config
	YouTube (com o DV360)	src/marketing/src/DV360/config
	Google Analytics 4	src/marketing/src/GA4/config

Nota: a Data Mesh não suporta dados da LiveRamp nem da Dun & Bradstreet (ESG).

Os recursos de metadados são definidos ao nível da origem de dados com um único ficheiro YAML por Google Cloud projeto e contêm uma lista de todos os recursos. Os utilizadores podem expandir o ficheiro existente ou criar ficheiros YAML adicionais que contenham especificações de recursos adicionais nesse diretório, se necessário.

As anotações de recursos são definidas ao nível do recurso e contêm muitos ficheiros YAML no diretório com uma única anotação por ficheiro.

Ative as APIs e valide as autorizações

A modificação dos valores predefinidos para a malha de dados permite-lhe implementar funcionalidades além das descrições. Se precisar de modificar os valores predefinidos da Data Mesh no config.json para implementar funcionalidades além das descrições, certifique-se de que as APIs necessárias e as autorizações estão definidas conforme descrito na tabela seguinte. Quando implementar a malha de dados com a base de dados, conceda autorizações ao utilizador de implementação ou à conta do Cloud Build. Se a implementação envolver projetos de origem e de destino diferentes, certifique-se de que estas APIs e autorizações estão ativadas em ambos os projetos sempre que essas funcionalidades forem usadas.

Funcionalidade	Funções de autorização	Documentação
Acesso a recursos e linhas do BigQuery	Proprietário de dados do BigQuery	Para mais informações, consulte as funções obrigatórias para as funções de recursos e as autorizações obrigatórias para as funções de linhas.
Acesso a colunas do BigQuery	Administrador de etiquetas de políticas	Para mais informações, consulte a documentação Funções usadas com o controlo de acesso ao nível da coluna e Restrinja o acesso com o controlo de acesso ao nível da coluna.
Etiquetas de catálogo	Proprietário do TagTemplate do Data Catalog	Para mais informações, consulte os artigos Etiquete uma tabela do BigQuery com o Data Catalog e documentação da IAM do Data Catalog.
Dataplex Universal Catalog Lakes	Editor do Dataplex	Para mais informações, consulte a documentação Crie um lago.

Nota: o Cortex Data Mesh não requer a integração das APIs Dataproc e Dataproc Metastore.

Compreender as especificações dos recursos base

A interface principal para configurar a malha de dados para o Cortex é através das especificações de recursos base, que são um conjunto de ficheiros YAML fornecidos de imediato que definem os recursos de metadados e as anotações implementadas. As especificações base fornecem recomendações iniciais e exemplos de sintaxe, mas destinam-se a ser personalizadas ainda mais para se adequarem às necessidades dos utilizadores. Estas especificações dividem-se em duas categorias:

• Recursos de metadados que podem ser aplicados a vários recursos de dados. Por exemplo, Modelos de etiquetas de catálogo que definem como os recursos podem ser etiquetados com domínios empresariais.
• Anotações que especificam como os recursos de metadados são aplicados a um recurso de dados específico. Por exemplo, uma etiqueta de catálogo que associa uma tabela específica ao domínio de vendas.

As secções seguintes explicam exemplos básicos de cada tipo de especificação e como os personalizar. As especificações base estão etiquetadas com ## CORTEX-CUSTOMER, onde devem ser modificadas para se ajustarem a uma implementação se a opção de implementação associada estiver ativada. Para utilizações avançadas, consulte a definição canónica destes esquemas de especificações em src/common/data_mesh/src/data_mesh_types.py.

Recursos de metadados

Os recursos de metadados são entidades partilhadas que existem num projeto e que podem ser aplicadas a muitos recursos de dados. A maioria das especificações inclui um campo display_name sujeito aos seguintes critérios:

• Contém apenas letras Unicode, números (0-9), sublinhados (_), travessões (-) e espaços ( ).
• Não pode começar nem terminar com espaços.
• Comprimento máximo de 200 carateres.

Em alguns casos, o display_name também é usado como um ID, o que pode introduzir requisitos adicionais. Nesses casos, são incluídos links para documentação canónica.

Se a implementação fizer referência a recursos de metadados em projetos de origem e de destino diferentes, tem de existir uma especificação definida para cada projeto. Por exemplo, o Cortex Salesforce (SFDC) contém duas especificações do Lake. Um para as zonas de dados não processados e CDC e outro para relatórios.

Dataplex Universal Catalog Lakes

Os lagos, as zonas e os recursos do catálogo universal do Dataplex são usados para organizar os dados do ponto de vista da engenharia. Os lagos têm um region e as zonas têm um location_type. Ambos estão relacionados com a localização do Cortex (config.json > location). A localização do Cortex define onde os conjuntos de dados do BigQuery são armazenados e pode ser uma região única ou várias regiões. A zona location_type deve ser definida como SINGLE_REGION | MULTI_REGION para corresponder a essa. No entanto, as regiões de lagos têm de ser sempre uma única região. Se a localização e a zona do Cortex location_type forem de várias regiões, selecione uma única região nesse grupo para a região do Lake.

• Requisitos
  • O lago display_name é usado como o lake_id e tem de estar em conformidade com os requisitos oficiais. O mesmo se aplica à zona e ao recurso display_name. Os IDs das zonas têm de ser exclusivos em todos os lagos do projeto.
  • As especificações do lago têm de estar associadas a uma única região.
  • O asset_name deve corresponder ao ID do conjunto de dados do BigQuery, mas o display_name pode ser uma etiqueta mais fácil de usar.
• Limitações
  • O catálogo universal do Dataplex só suporta o registo de conjuntos de dados do BigQuery, em vez de tabelas individuais, como recursos do catálogo universal do Dataplex.
  • Um recurso só pode ser registado numa única zona.
  • O catálogo universal do Dataplex só é suportado em determinadas localizações. Para mais informações, consulte o artigo Localizações do catálogo universal do Dataplex.

Veja o exemplo seguinte em lakes.yaml.

Estes recursos são definidos em ficheiros YAML que especificam data_mesh_types.Lakes.

Modelos de etiquetas de catálogo

Os modelos de etiquetas do catálogo de dados podem ser usados para adicionar contexto a tabelas do BigQuery ou colunas individuais. Ajudam a categorizar e compreender os seus dados de uma perspetiva técnica e empresarial de uma forma integrada com as ferramentas de pesquisa do catálogo universal do Dataplex. Definem os campos específicos que pode usar para etiquetar os seus dados e o tipo de informações que cada campo pode conter (por exemplo, texto, número, data). As etiquetas de catálogo são instâncias dos modelos com valores de campo reais.

O campo do modelo display_name é usado como o ID do campo e tem de cumprir os requisitos para TagTemplate.fields especificados em Class TagTemplate. Para mais informações sobre os tipos de campos suportados, consulte o artigo Tipos de campos do catálogo de dados.

A Cortex Data Mesh cria todos os modelos de etiquetas como publicamente legíveis. Também introduz um conceito level adicional às especificações do modelo de etiqueta, que define se uma etiqueta deve ser aplicada a um recurso inteiro, a campos individuais num recurso ou a ambos, com os seguintes valores possíveis: ASSET | FIELD | ANY. Embora isto não seja estritamente aplicado agora, as verificações de validação futuras podem garantir que as etiquetas são aplicadas ao nível adequado durante a implementação.

Veja o exemplo seguinte.

Os modelos são definidos em ficheiros YAML que especificam data_mesh_types.CatalogTagTemplates.

As etiquetas do catálogo são instâncias dos modelos e são abordadas abaixo nas anotações de recursos.

Controlo de acesso ao nível do recurso e da coluna com modelos de etiquetas

A framework Cortex oferece a capacidade de ativar o controlo de acesso ao nível do recurso ou da coluna em todos os artefactos associados a um modelo de etiqueta de catálogo. Por exemplo, se os utilizadores quiserem conceder acesso a recursos com base na linha de negócio, podem criar asset_policies para o modelo de etiqueta do catálogo line_of_business com diferentes responsáveis especificados para cada domínio empresarial. Cada política aceita filters que podem ser usadas para fazer corresponder apenas etiquetas com valores específicos. Neste caso, podemos fazer corresponder os valores de domain. Tenha em atenção que estes filters só suportam a correspondência por igualdade e nenhum outro operador. Se forem apresentados vários filtros, os resultados têm de satisfazer todos os filtros (por exemplo, filter_a AND filter_b). O conjunto final de políticas de recursos é a união das políticas definidas diretamente nas anotações e das políticas de modelos.

O controlo de acesso ao nível da coluna com etiquetas do catálogo tem um comportamento semelhante, aplicando etiquetas de política a campos correspondentes. No entanto, como só é possível aplicar uma etiqueta de política a uma coluna, a precedência é a seguinte:

1. Etiqueta de política direta: se uma etiqueta de política estiver definida diretamente na anotação da coluna, tem prioridade.
2. Política de modelo de etiqueta correspondente: caso contrário, o acesso é determinado pela primeira política correspondente definida num campo no modelo de etiqueta do catálogo associado.

Quando usar esta funcionalidade, recomendamos vivamente que ative ou desative a implementação de etiquetas de catálogo e listas de controlo de acesso (ACLs) em conjunto. Isto garante que as ACLs são implementadas corretamente.

Para compreender as especificações desta funcionalidade avançada, consulte as definições dos parâmetros asset_policies e field_policies em data_mesh_types.CatalogTagTemplate.

Glossário de catálogos

O glossário é uma ferramenta que pode ser usada para fornecer um dicionário de termos usados por colunas específicas em recursos de dados que podem não ser compreendidos universalmente. Os utilizadores podem adicionar termos manualmente na consola, mas não existe suporte através das especificações de recursos.

Taxonomias e etiquetas de políticas

As taxonomias e as etiquetas de políticas permitem o controlo de acesso ao nível da coluna sobre os recursos de dados confidenciais de forma padronizada. Por exemplo, pode existir uma taxonomia para etiquetas que controlam os dados PII numa determinada linha de negócio, em que apenas determinados grupos podem ler dados ocultados, dados não ocultados ou não ter acesso de leitura.

Para mais detalhes sobre as taxonomias e as etiquetas das políticas, consulte a documentação Introdução à ocultação de dados de colunas. As seguintes secções são particularmente relevantes:

• Como as funções interagem
• Herança de autorização
• Regras de ocultação e hierarquia
• Práticas recomendadas para etiquetas de políticas

A framework Cortex fornece etiquetas de políticas de exemplo para demonstrar como são especificadas e potenciais utilizações. No entanto, os recursos que afetam o controlo de acesso não são ativados na implementação da malha de dados por predefinição.

Veja o exemplo seguinte.

As taxonomias de políticas são definidas em ficheiros YAML que especificam data_mesh_types.PolicyTaxonomies.

Anotações de recursos

As anotações especificam metadados aplicáveis a um recurso específico e podem fazer referência aos recursos de metadados partilhados que foram definidos. As anotações incluem:

• Descrições dos recursos
• Descrições dos campos
• Etiquetas de catálogo
• Controlo de acesso ao nível do recurso, da linha e da coluna

Nota: se modificar um ficheiro de anotação, tenha em atenção que a consola apenas renderiza novas linhas nas descrições como um espaço em branco.

A base de dados do Cortex Framework oferece anotações (descrições) pré-configuradas para as seguintes cargas de trabalho.

• SAP ECC (dados não processados, CDC e relatórios)
• SAP S4 HANA (dados não processados, CDC e relatórios)
• SFDC (apenas relatórios)
• Oracle EBS (apenas relatórios)
• CM360 (apenas relatórios)
• Google Ads (apenas relatórios)
• Meta (apenas relatórios)
• SFMC (apenas relatórios)
• TikTok (apenas relatórios)
• YouTube (com o DV360) (apenas relatórios)
• Google Analytics 4 (apenas relatórios)

Veja o exemplo seguinte.

As anotações são definidas em ficheiros YAML que especificam data_mesh_types.BqAssetAnnotation.

Etiquetas de catálogo

As etiquetas de catálogo são instâncias dos modelos definidos, em que são atribuídos valores de campos que se aplicam ao recurso específico. Certifique-se de que atribui valores que correspondem aos tipos de campos declarados no modelo associado.

Os valores de TIMESTAMP devem estar num dos seguintes formatos:

  "%Y-%m-%d %H:%M:%S%z"
  "%Y-%m-%d %H:%M:%S"
  "%Y-%m-%d"

Veja o exemplo seguinte.

Consulte a definição da especificação em data_mesh_types.CatalogTag.

Especificar leitores e responsáveis da política de acesso

Controlar o acesso aos seus dados do BigQuery no Cortex Framework através de políticas de acesso. Estas políticas definem quem (diretores) pode aceder a recursos de dados específicos, linhas num recurso ou até colunas individuais. Os principais têm de seguir um formato específico definido pelo membro de associação da política do IAM.

Acesso ao nível do recurso

Pode conceder acesso a recursos completos do BigQuery com várias autorizações:

• READER: veja os dados no recurso.
• WRITER: modifique e adicione dados ao recurso.
• OWNER : controlo total sobre o recurso, incluindo a gestão de acesso.

Estas autorizações são equivalentes à declaração GRANT DCL em SQL.

Ao contrário do comportamento da maioria dos recursos e anotações, a flag de substituição não remove os principais existentes com a função OWNERS. Quando adiciona novos proprietários com a substituição ativada, estes são apenas anexados aos proprietários existentes. Esta é uma salvaguarda para evitar a perda não intencional de acesso. Para remover proprietários de recursos, use a consola. A substituição remove os principais existentes com a função READER ou WRITER.

Veja o exemplo seguinte.

Consulte a definição da especificação em data_mesh_types.BqAssetPolicy.

Acesso ao nível da linha

Pode conceder acesso a conjuntos de linhas com base em determinados filtros de valores de colunas. Quando especificar a política de acesso ao nível da linha, a string de filtro fornecida é inserida num elemento CREATE DDL statement. Se a flag overwrite estiver ativada, elimina todas as políticas de acesso ao nível da linha existentes antes de aplicar novas.

Considere o seguinte acerca do acesso ao nível da linha:

• A adição de políticas de acesso ao nível da linha significa que os utilizadores não especificados nessas políticas não têm acesso para ver nenhuma linha.
• As políticas de linhas só funcionam com tabelas e não com vistas.
• Evite usar colunas particionadas nos filtros da política de acesso ao nível da linha. Consulte o ficheiro YAML de definições de relatórios associado para ver informações sobre o tipo de recurso e as colunas particionadas.

Para mais informações sobre as políticas de acesso ao nível da linha, consulte as práticas recomendadas de segurança ao nível da linha.

Veja o exemplo seguinte.

Consulte a definição da especificação em data_mesh_types.BqRowPolicy.

Acesso ao nível da coluna

Para ativar o acesso ao nível da coluna, anote os campos individuais com uma etiqueta de política identificada pelo nome da etiqueta de política e pelo nome da taxonomia. Atualize o recurso de metadados da etiqueta de política para configurar o controlo de acesso.

Veja o exemplo seguinte.

Consulte a definição da especificação em data_mesh_types.PolicyTagId.

Implementar a malha de dados

A malha de dados pode ser implementada como parte da implementação da base de dados ou de forma independente. Em qualquer dos casos, usa o ficheiro config.json do Cortex para determinar as variáveis relevantes, como os nomes dos conjuntos de dados do BigQuery e as opções de implementação. Por predefinição, a implementação da malha de dados não remove nem substitui recursos ou anotações existentes para evitar perdas não intencionais. No entanto, também existe a capacidade de substituir recursos existentes quando implementados de forma autónoma.

Opções de implementação

As seguintes opções de implementação podem ser ativadas ou desativadas com base nas necessidades do utilizador e nas restrições de gastos em config.json > DataMesh.

Nota: recomendamos vivamente que o controlo de acesso seja feito exclusivamente através destas especificações de recursos se deployACLs estiver ativado. Isto evita a adição ou a remoção não intencional do acesso.

Opção	Notes
deployDescriptions	Esta é a única opção ativada por predefinição e implementa anotações do BigQuery com descrições de recursos e colunas. Não requer a ativação de APIs nem autorizações adicionais.
deployLakes	Implementa lagos e zonas.
deployCatalog	Implementa recursos de modelos de catálogos e as respetivas etiquetas associadas em anotações de recursos.
deployACLs	Implementa recursos da taxonomia de políticas e políticas de controlo de acesso ao nível do recurso, da linha e da coluna através de anotações de recursos. Os registos contêm mensagens que indicam como as políticas de acesso foram alteradas.

Implementação com a base de dados

Por predefinição, config.json > deployDataMesh permite a implementação das descrições dos recursos da Data Mesh no final de cada passo de compilação da carga de trabalho. Esta configuração predefinida não requer a ativação de APIs nem funções adicionais. Podem ser implementadas funcionalidades adicionais da malha de dados com a base de dados ativando as opções de implementação, as APIs e as funções necessárias e modificando as especificações de recursos associadas.

Implementação individual

Para implementar apenas a malha de dados, os utilizadores podem usar o ficheiro common/data_mesh/deploy_data_mesh.py. Esta utilidade é usada durante os processos de compilação para implementar a malha de dados uma carga de trabalho de cada vez, mas quando é chamada diretamente, também pode ser usada para implementar várias cargas de trabalho em simultâneo. As cargas de trabalho para a implementação das especificações devem estar ativadas no ficheiro config.json. Por exemplo, certifique-se de que deploySAP=true se estiver a implementar a malha de dados para o SAP.

Para garantir que está a implementar com os pacotes e as versões necessários, pode executar o utilitário a partir da mesma imagem usada pelo processo de implementação do Cortex com os seguintes comandos:

  # Run container interactively
  docker container run -it gcr.io/kittycorn-public/deploy-kittycorn:v2.0

  # Clone the repo
  git clone https://github.com/GoogleCloudPlatform/cortex-data-foundation

  # Navigate into the repo
  cd cortex-data-foundation

Para obter ajuda com os parâmetros disponíveis e a respetiva utilização, execute o seguinte comando:

  python src/common/data_mesh/deploy_data_mesh.py -h

Segue-se um exemplo de invocação para o SAP ECC:

  python src/common/data_mesh/deploy_data_mesh.py \
    --config-file config/config.json \
    --lake-directories \
        src/SAP/SAP_REPORTING/config/ecc/lakes \
    --tag-template-directories \
        src/SAP/SAP_REPORTING/config/ecc/tag_templates \
    --policy-directories \
        src/SAP/SAP_REPORTING/config/ecc/policy_taxonomies \
    --annotation-directories \
        src/SAP/SAP_REPORTING/config/ecc/annotations

Consulte a secção Diretórios da malha de dados para ver informações sobre as localizações dos diretórios.

Substituir

Aviso: leia atentamente esta secção antes de usar a opção de substituição.

Por predefinição, a implementação da malha de dados não substitui os recursos nem as anotações existentes. No entanto, a flag --overwrite pode ser ativada quando implementar a Data Mesh sozinha para alterar a implementação das seguintes formas.

A substituição de recursos de metadados, como lagos, modelos de etiquetas de catálogo e etiquetas de políticas, elimina todos os recursos existentes que partilham os mesmos nomes. No entanto, não modifica os recursos existentes com nomes diferentes. Isto significa que, se uma especificação de recurso for removida completamente do ficheiro YAML e, em seguida, a malha de dados for reimplementada com a substituição ativada, essa especificação de recurso não é eliminada porque não existe colisão de nomes. Isto destina-se a que a implementação do Cortex Data Mesh não afete os recursos existentes que possam estar em utilização.

Para recursos aninhados, como lagos e zonas, a substituição de um recurso remove todos os respetivos filhos. Por exemplo, a substituição de um lago também remove as respetivas zonas e referências de recursos existentes. Para modelos de etiquetas de catálogo e etiquetas de políticas substituídas, as referências de anotações associadas existentes também são removidas dos recursos. A substituição de etiquetas de catálogo numa anotação de recursos apenas substitui as instâncias existentes de etiquetas de catálogo que partilham o mesmo modelo.

As substituições de recursos e descrições de campos só têm efeito se for fornecida uma nova descrição válida não vazia que entre em conflito com a descrição existente.

Por outro lado, as ACLs têm um comportamento diferente. A substituição das ACLs remove todos os principais existentes (com exceção dos proprietários ao nível do recurso). Isto deve-se ao facto de os principais omitidos das políticas de acesso serem igualmente importantes para os principais aos quais é concedido acesso.

Explorar a malha de dados

Após a implementação da malha de dados, os utilizadores podem pesquisar e ver os recursos de dados com o catálogo de dados. Isto inclui a capacidade de descobrir recursos com base nos valores das etiquetas do catálogo que foram aplicados. Os utilizadores também podem criar e aplicar manualmente termos do glossário do catálogo, se necessário.

As políticas de acesso implementadas podem ser vistas na página Esquema do BigQuery para ver as políticas aplicadas a um recurso específico em cada nível.

Linhagem de dados

Os utilizadores podem achar útil ativar e visualizar a linhagem entre os recursos do BigQuery. Também pode aceder à linhagem de forma programática através da API. A linhagem de dados só suporta a linhagem ao nível do recurso. A linhagem de dados não está interligada com a malha de dados do Cortex. No entanto, podem ser introduzidas novas funcionalidades no futuro que utilizem a linhagem.

Para quaisquer pedidos relacionados com o Cortex Data Mesh ou o Cortex Framework, aceda à secção de apoio técnico.