Gerenciar seus recursos do Cloud SQL usando o Dataplex Catalog

Nesta página, explicamos como pesquisar e gerenciar os recursos do Cloud SQL usando o Dataplex Catalog.

O Dataplex Catalog é uma plataforma para armazenar, gerenciar e acessar seus metadados. Depois de ativar a integração do Dataplex Catalog na sua instância do Cloud SQL, o Dataplex Catalog recupera automaticamente os seguintes metadados de instâncias, bancos de dados, tabelas, colunas e visualizações do Cloud SQL:

  • Nome
  • Local (região)
  • Data de criação e data da última modificação
  • Esquema (para tabelas e visualizações)
  • Descrição

O Dataplex Catalog recupera metadados somente das instâncias principais do Cloud SQL e não de réplicas de leitura.

O Dataplex Catalog pode ser usado para descobrir e entender os metadados do Cloud SQL. Use o Dataplex Catalog para ajudar nas seguintes atividades:

  • Análise, incluindo dependências e adequação a um caso de uso
  • Gestão da mudança
  • Movimentação de dados (pipelines)
  • Evolução do esquema

Com o Dataplex Catalog, você seleciona metadados anexando aspectos às entradas de metadados do Cloud SQL. Cada aspecto pode ter vários campos de metadados e podem ser baseados em um tipo de aspecto predefinido ou personalizado.

Por exemplo, você pode anexar o seguinte aspecto a uma coluna que contenha um CPF ou CNPJ, que são informações de identificação pessoal (PII):

  pii:true
  pii_type:SSN

Para mais informações sobre o Dataplex Catalog, consulte Visão geral do Dataplex Catalog.

Antes de começar

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Make sure that billing is enabled for your Google Cloud project.

  4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  5. Make sure that billing is enabled for your Google Cloud project.

  6. Ativar a API Dataplex para o projeto.

    Ativar a API Dataplex

  7. Verifique as permissões.

    Você precisa de certos papéis e permissões do Identity and Access Management (IAM) para pesquisar e anexar entradas a recursos do Cloud SQL. Para mais detalhes, consulte Permissões e papéis do IAM necessários para o Dataplex Catalog.

Permissões e papéis do IAM necessários para o Dataplex Catalog

O Cloud SQL usa a permissão cloudsql.schemas.view para fornecer acesso aos metadados no Dataplex.

Para dar essa permissão, crie um papel personalizado que a inclua ou use um dos papéis predefinidos que tenham essa permissão.

Para mais informações, consulte Papéis predefinidos do IAM do Cloud SQL.

Ativar a integração do Dataplex Catalog na instância do Cloud SQL

Para ativar a integração do Dataplex Catalog na sua instância do Cloud SQL, use um dos procedimentos a seguir.

gcloud

Criar instância

Para criar uma instância do Cloud SQL, use o comando gcloud sql instances create.

gcloud sql instances create INSTANCE_NAME \
  --database-version=DATABASE_VERSION \
  --tier=MACHINE_TYPE \
  --region=REGION_NAME \
  --enable-dataplex-integration

Faça as seguintes substituições:

  • INSTANCE_NAME: o nome da instância.
  • DATABASE_VERSION: a versão do banco de dados da instância (por exemplo, POSTGRES_13); para uma lista completa de strings disponíveis, consulte SqlDatabaseVersion
  • MACHINE_TYPE: o tipo de máquina da instância
  • REGION_NAME: o nome da região da instância

Atualizar a instância

Para ativar a integração para uma instância atual, use o comando gcloud sql instances patch.

gcloud sql instances patch INSTANCE_NAME \
  --enable-dataplex-integration

Se você precisar ativar e atualizar todas as instâncias do Cloud SQL no projeto, execute um script semelhante ao seguinte:

gcloud sql instances list --format="(NAME)" \
| tail -n +2 | xargs -t -I %
gcloud sql instances patch % --enable-dataplex-integration

Este exemplo é baseado em Linux.

REST v1

Criar instância

Use este exemplo para criar uma instância com a integração ativada. Para uma lista completa de parâmetros disponíveis para essa chamada, consulte a página instances.insert.

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

  • PROJECT_ID: o ID ou número do projeto do Google Cloud que contém a instância
  • INSTANCE_NAME: o nome da instância.
  • REGION_NAME: o nome da região da instância
  • DATABASE_VERSION: string de enumeração da versão do banco de dados (por exemplo, POSTGRES_13). Para uma lista completa de strings disponíveis, consulte SqlDatabaseVersion.
  • PASSWORD: a senha do usuário root
  • MACHINE_TYPE: string de tipo enumerado do tipo de máquina (camada), como: db-custom-[CPUS]-[MEMORY_MBS]
  • EDITION_TYPE: sua edição do Cloud SQL

Método HTTP e URL: 

POST https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances

Corpo JSON da solicitação:

{
  "name": "INSTANCE_NAME",
  "region": "REGION_NAME",
  "databaseVersion": "DATABASE_VERSION",
  "rootPassword": "PASSWORD",
  "settings": {
    "tier": "MACHINE_TYPE",
    "edition": "EDITION_TYPE",
    "enableDataplexIntegration": true
  }
}

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

Você receberá uma resposta JSON semelhante a esta:

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID",
  "status": "PENDING",
  "user": "user@example.com",
  "insertTime": "2024-09-25T22:19:33.735Z",
  "operationType": "CREATE",
  "name": "OPERATION_ID",
  "targetId": "INSTANCE_ID",
  "selfLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations/OPERATION_ID",
  "targetProject": "PROJECT_ID"
}

Atualizar a instância

Use este exemplo para atualizar uma instância. Para uma lista completa de parâmetros disponíveis para essa chamada, consulte a página instances.patch.

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

  • PROJECT_ID: o ID ou número do projeto do Google Cloud que contém a instância
  • INSTANCE_NAME: o nome da instância.

Método HTTP e URL: 

PATCH https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME

Corpo JSON da solicitação:

{
  "settings":
  {
    "enableDataplexIntegration": true
  }
}

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

Você receberá uma resposta JSON semelhante a esta:

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME",
  "status": "PENDING",
  "user": "user@example.com",
  "insertTime": "2024-01-16T02:32:12.281Z",
  "operationType": "UPDATE",
  "name": "OPERATION_ID",
  "targetId": "INSTANCE_NAME",
  "selfLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations/OPERATION_ID",
  "targetProject": "PROJECT_ID"
}

REST v1beta4

Criar instância

Use este exemplo para criar uma instância com a integração ativada. Para uma lista completa de parâmetros disponíveis para essa chamada, consulte a página instances.insert.

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

  • PROJECT_ID: o ID ou número do projeto do Google Cloud que contém a instância
  • INSTANCE_NAME: o nome da instância.
  • REGION_NAME: o nome da região da instância
  • DATABASE_VERSION: string de enumeração da versão do banco de dados (por exemplo, POSTGRES_13). Para uma lista completa de strings disponíveis, consulte SqlDatabaseVersion.
  • PASSWORD: a senha do usuário root
  • MACHINE_TYPE: string de tipo enumerado do tipo de máquina (camada), como: db-custom-[CPUS]-[MEMORY_MBS]
  • EDITION_TYPE: sua edição do Cloud SQL

Método HTTP e URL: 

POST https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances

Corpo JSON da solicitação:

{
  "name": "INSTANCE_NAME",
  "region": "REGION_NAME",
  "databaseVersion": "DATABASE_VERSION",
  "rootPassword": "PASSWORD",
  "settings": {
    "tier": "MACHINE_TYPE",
    "edition": "EDITION_TYPE",
    "enableDataplexIntegration": true
  }
}

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

Você receberá uma resposta JSON semelhante a esta:

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID",
  "status": "PENDING",
  "user": "user@example.com",
  "insertTime": "2024-09-25T22:19:33.735Z",
  "operationType": "CREATE",
  "name": "OPERATION_ID",
  "targetId": "INSTANCE_ID",
  "selfLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/operations/OPERATION_ID",
  "targetProject": "PROJECT_ID"
}

Atualizar a instância

Use este exemplo para atualizar uma instância. Para uma lista completa de parâmetros disponíveis para essa chamada, consulte a página instances.patch.

Use este exemplo para atualizar uma instância. Para uma lista completa de parâmetros disponíveis para essa chamada, consulte a página instances.patch.

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

  • PROJECT_ID: o ID ou número do projeto do Google Cloud que contém a instância
  • INSTANCE_NAME: o nome da instância.

Método HTTP e URL: 

PATCH https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_NAME

Corpo JSON da solicitação:

{
  "settings":
  {
    "enableDataplexIntegration": true
  }
}

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

Você receberá uma resposta JSON semelhante a esta:

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_NAME",
  "status": "PENDING",
  "user": "user@example.com",
  "insertTime": "2024-01-16T02:32:12.281Z",
  "operationType": "UPDATE",
  "name": "OPERATION_ID",
  "targetId": "INSTANCE_NAME",
  "selfLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/operations/OPERATION_ID",
  "targetProject": "PROJECT_ID"
}

Verificar a integração do Dataplex Catalog na instância do Cloud SQL

Para verificar se a integração do Dataplex Catalog está ativada na sua instância, use um dos procedimentos a seguir.

gcloud

Para verificar se a integração do Dataplex Catalog está ativada em uma instância atual, use o comando gcloud sql instances describe.

gcloud sql instances describe INSTANCE_NAME

Substitua INSTANCE_NAME pelo nome da instância. Na saída, procure a configuração enableDataplexIntegration definida como true.

REST v1

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

  • PROJECT_ID: o ID do projeto
  • INSTANCE_ID<: o ID da instância

Método HTTP e URL: 

GET https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID

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

Você receberá uma resposta JSON semelhante a esta:

{
"settings":
  {
  "enableDataplexIntegration": true
  }
}

REST v1beta4

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

  • PROJECT_ID: o ID do projeto
  • INSTANCE_ID<: o ID da instância

Método HTTP e URL: 

GET https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID

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

Você receberá uma resposta JSON semelhante a esta:

{
"settings":
  {
  "enableDataplexIntegration": true
  }
}

Desativar a integração do Dataplex Catalog na instância do Cloud SQL

Para desativar a integração do Dataplex Catalog na sua instância do Cloud SQL, use um dos procedimentos a seguir.

gcloud

Para desativar a integração de uma instância atual, use o comando gcloud sql instances patch.

gcloud sql instances patch INSTANCE_NAME \
  --no-enable-dataplex-integration

Se você precisar desativar a integração e atualizar as instâncias do Cloud SQL no projeto, é possível executar um script semelhante ao seguinte:

gcloud sql instances list --format="(NAME)" \
| tail -n +2 | xargs -t -I %
gcloud sql instances patch % --no-enable-dataplex-integration

Este exemplo é baseado em Linux.

REST v1

Use este exemplo para desativar a integração.

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

  • PROJECT_ID: o ID ou número do projeto do Google Cloud que contém a instância
  • INSTANCE_NAME: o nome da instância.

Método HTTP e URL: 

PATCH https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_NAME

Corpo JSON da solicitação:

{
  "settings":
  {
    "enableDataplexIntegration": false
  }
}

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

Você receberá uma resposta JSON semelhante a esta:

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_NAME",
  "status": "PENDING",
  "user": "user@example.com",
  "insertTime": "2024-01-16T02:32:12.281Z",
  "operationType": "UPDATE",
  "name": "OPERATION_ID",
  "targetId": "INSTANCE_NAME",
  "selfLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/operations/OPERATION_ID",
  "targetProject": "PROJECT_ID"
}

REST v1beta4

Use este exemplo para desativar a integração.

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

  • PROJECT_ID: o ID ou número do projeto do Google Cloud que contém a instância
  • INSTANCE_NAME: o nome da instância.

Método HTTP e URL: 

PATCH https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_NAME

Corpo JSON da solicitação:

{
  "settings":
  {
    "enableDataplexIntegration": false
  }
}

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

Você receberá uma resposta JSON semelhante a esta:

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_NAME",
  "status": "PENDING",
  "user": "user@example.com",
  "insertTime": "2024-01-16T02:32:12.281Z",
  "operationType": "UPDATE",
  "name": "OPERATION_ID",
  "targetId": "INSTANCE_NAME",
  "selfLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/operations/OPERATION_ID",
  "targetProject": "PROJECT_ID"
}

Enriquecer os recursos do Cloud SQL com aspectos

Os tipos de aspecto são recursos reutilizáveis que podem ser usados como modelos. Os tipos de aspecto ajudam a evitar a duplicação de trabalho e aspectos incompletos. É possível usar o Dataplex Catalog para criar os tipos de aspecto que você precisa.

Depois de criar tipos personalizados de aspecto, é possível anexar aspectos aos seus recursos do Cloud SQL. Ao anexar aspectos aos recursos do Cloud SQL você pode fazer o seguinte:

  • Adicionar metadados comerciais aos recursos
  • Pesquise recursos por metadados da empresa e outros metadados personalizados

Para saber mais sobre como criar tipos de aspecto e anexar aspectos ao Cloud SQL, consulte Gerenciar aspectos e aprimorar metadados.

Pesquisar recursos do Cloud SQL

Usar a página de pesquisa do Dataplex Catalog no console do Google Cloud para pesquisar recursos do Cloud SQL.

  1. Acesse a página de pesquisa do Dataplex Catalog.

    Acesse o Dataplex.

  2. Em Escolher plataforma de pesquisa, selecione Dataplex Catalog.

  3. No painel Filtros, clique em Sistemas e selecione Cloud SQL.

  4. Opcional. Em Aliases de tipo, é possível filtrar os resultados da pesquisa para uma consulta de recurso do Cloud SQL selecionando um ou mais dos aliases de tipo a seguir:

    • Banco de dados
    • Database schema
    • Serviço
    • Tabela
    • Ver
    .

Usar consultas para realizar pesquisas

Também é possível usar o campo de pesquisa no Dataplex Catalog para realizar consultas de pesquisa. Para visualizar todos os recursos do Cloud SQL, insira system=Cloud_SQL.

Em seguida, insira palavras-chave específicas. Por exemplo, para exibir todas os bancos de dados do Cloud SQL:

system=Cloud_SQL AND type=Database

Para visualizar todas as tabelas do Cloud SQL, insira a seguinte consulta:

system=Cloud_SQL AND type=Table

Também é possível usar parênteses e os operadores lógicos AND e OR para expressões complexas. Para saber mais sobre as expressões que você pode usar no campo de pesquisa, consulte Sintaxe de pesquisa para o Dataplex Catalog.

É possível inserir diretamente consultas de pesquisa para recursos específicos do Cloud SQL no campo de pesquisa. O formato da string de consulta é o seguinte:

type="projects/PROJECT_ID/locations/global/entryTypes/QUERY_STRING"

Substitua:

  • PROJECT_ID: ID do projeto

  • QUERY_STRING: use a tabela a seguir para identificar uma string de consulta com base no mecanismo do Cloud SQL e o tipo de recurso que você quer consultar

    Mecanismo do Cloud SQL Strings de consulta
    Cloud SQL para MySQL
    • cloudsql-mysql-database
    • cloudsql-mysql-instance
    • cloudsql-mysql-table
    • cloudsql-mysql-view
    .
    Cloud SQL para PostgreSQL
    • cloudsql-postgresql-database
    • cloudsql-postgresql-instance
    • cloudsql-postgresql-table
    • cloudsql-postgresql-schema
    • cloudsql-postgresql-view
    Cloud SQL para SQL Server
    • cloudsql-sqlserver-database
    • cloudsql-sqlserver-instance
    • cloudsql-sqlserver-table
    • cloudsql-sqlserver-schema
    • cloudsql-sqlserver-view

Um exemplo de consulta pode ser semelhante ao seguinte:

type="projects/1234567890/locations/global/entryTypes/cloudsql-postgresql-instance"

Filtrar recursos do Cloud SQL por dialeto do Cloud SQL

Por padrão, o Dataplex Catalog mostra todos os componentes de uma empresa. Para filtrar os recursos do Cloud SQL para MySQL, Cloud SQL para PostgreSQL, ou apenas SQL Server, siga as etapas abaixo.

  1. No painel Aspectos, clique no menu Adicionar mais tipos de aspecto.

  2. Selecione Acesso SQL.

  3. Clique em OK.

  4. Clique no botão "Editar aspecto" playlist_add . Na página Acesso SQL, faça o seguinte:

    • No campo Dialeto, selecione SQL Server para filtrar os recursos do SQL Server.
  5. Opcional. Selecione o campo Versão e insira uma versão específica do SQL Server.

  6. Clique em Aplicar. O Catálogo do Dataplex só exibe recursos do SQL Server.

O Dataplex Catalog inclui alguns tipos de aspectos integrados que você pode usar para realizar pesquisas.

  1. No painel Aspectos, clique no menu Adicionar mais tipos de aspecto.

  2. Opcional. Selecione Acesso SQL para filtrar os resultados por dialeto do Cloud SQL. Para mais informações, consulte o procedimento anterior, Filtrar recursos do Cloud SQL por dialeto do Cloud SQL.

  3. Selecione um ou mais dos seguintes tipos de aspecto para limitar os resultados da pesquisa a esse tipo.

    • Banco de dados do Cloud SQL
    • Instância do Cloud SQL
    • Visualização do Cloud SQL
    • Esquema do Cloud SQL
    • Tabela do Cloud SQL

  4. Clique em OK.

  5. Na tabela de resultados, clique no nome de um recurso para visualizar os metadados dele.

  6. Opcional: aprimore ou visualize seus recursos. Você poderá escolher qualquer uma das seguintes opções:

    • Em Visão geral, clique em Adicionar para incluir uma descrição em rich text do recurso.
    • Em Aspectos, clique em Adicionar para anexar um aspecto ao recurso.
    • Em uma instância, para visualizar os bancos de dados dos membros, clique no botão Lista de entradas e depois em Mostrar todas as entradas filhas na pesquisa. Se a guia Lista de entradas não for exibida, isso significa que a instância não tem bancos de dados.
    • Em Detalhes da entrada, confira todos os detalhes do recurso. Clique no nome da entrada para detalhar até entradas adicionais.

Exemplo de fluxo de trabalho: detalhamento da instância para as colunas

Neste fluxo de trabalho de exemplo, você começa pesquisando uma instância do Cloud SQL. Em seguida, você visualiza o banco de dados de membros, uma tabela nesse banco de dados e as colunas na tabela.

  1. Acesse a página de pesquisa do Dataplex Catalog.

    Acesse o Dataplex.

  2. Na opção Escolher plataforma de pesquisa, selecione Dataplex Catalog.

  3. No painel Filtros, selecione Sistemas e, em seguida, Cloud SQL. Se preferir, digite system=Cloud_SQL no campo de pesquisa.

  4. Selecione um nome de instância.

  5. Na página Detalhes do Cloud SQL, clique na guia Lista de entradas e depois em Mostrar todas as entradas filhas na pesquisa. O Dataplex Catalog exibe os bancos de dados na instância.

  6. Na página Detalhes do banco de dados do Cloud SQL, clique na guia Lista de entradas e depois em Exibir entradas filhas na pesquisa. O Dataplex Catalog exibe as tabelas no banco de dados.

  7. Selecione um nome de tabela e, na página Detalhes da tabela do Cloud SQL, clique em Esquema para ver as colunas da tabela.

  8. Opcional: para adicionar um tipo de aspecto a uma coluna, clique no botão Adicionar aspecto.

Esse fluxo de trabalho demonstra o detalhamento de uma instância para uma tabela. Você pode acessar diretamente uma lista de tabelas inserindo system=Cloud_SQL AND type=Table; no campo de pesquisa.

Preços

Não há custos para armazenar metadados técnicos do Cloud SQL no Dataplex Catalog. Os preços padrão do Dataplex se aplicam a chamadas de API e ao aprimoramento de outros metadados comerciais. Para mais informações, consulte a Página de preços do Dataplex.

Uso de recursos

O Dataplex Catalog extrai dados das instâncias periodicamente. O processo de extração exige uma certa quantidade de uso da CPU. Instâncias com tipos de máquina menores, por exemplo, máquinas com núcleos compartilhados e esquemas maiores (10.000 ou mais tabelas), podem utilizar até 40% da CPU durante o processo de extração.

Limitações

Nesta seção, listamos as limitações de uso do Cloud SQL e Dataplex Catalog.

  • A integração do Dataplex Catalog com o Cloud SQL é desativado para todas as instâncias que restringem o acesso a recursos devido à inscrição de recursos no Assured Workloads.

  • Depois de ativar o catálogo do Dataplex em uma instância, pode levar de 2 a 48 horas para que os recursos do Cloud SQL apareçam no Catálogo do Dataplex como recursos, dependendo do tamanho da máquina, versão e tipo do mecanismo do Cloud SQL que está sendo usado.

  • Bancos de dados do SQL Server com a opção Auto Close ativada não poderão sincronizar as informações do esquema com o catálogo do Dataplex. Como uma prática recomendada geral e, por motivos de desempenho, recomendamos definir a opção Auto Close como "false" no SQL Server. No entanto, se quiser usar o Dataplex Catalog, é necessário definir a opção Auto Close como falsa. Para as edições Express, a opção Auto Close é definida como verdadeira por padrão, conforme projetado pelo mecanismo do SQL Server.

A seguir