Interface de administrador do Dataproc Metastore

Esta página explica como usar a interface de administrador do Dataproc Metastore.

A interface do administrador oferece-lhe uma ferramenta centralizada para inspecionar e gerir os metadados armazenados no seu serviço Dataproc Metastore, tudo sem ter de se ligar a um cluster do Dataproc ou a uma instância do Hive. Em alternativa, pode gerir os seus metadados com a CLI do Google Cloud ou as APIs do Dataproc Metastore.

Por exemplo, através da interface do administrador, pode executar uma consulta SQL diretamente nos metadados de back-end para obter um nome de tabela específico. Este processo envolve seguir menos passos do que o fluxo de trabalho típico, como criar um cluster do Dataproc, estabelecer ligação ao cluster através de SSH, iniciar uma instância do Hive e, finalmente, executar uma consulta (por exemplo, SELECT * FROM table_name).

Como resultado, a interface do administrador pode ajudar a poupar tempo e a diminuir a quantidade de Google Cloud recursos necessários para obter os seus dados.

Antes de começar

Funções necessárias

Para receber as autorizações de que precisa para usar a interface de administrador do Dataproc Metastore, peça ao seu administrador que lhe conceda as seguintes funções do IAM no seu projeto, com base no princípio do menor privilégio:

  • Para consultar metadados do Dataproc Metastore: Administrador de consultas de metadados (roles/metastore.metadataQueryAdmin) na conta de utilizador ou na conta de serviço
  • Para alterar a localização do recurso dos seus metadados, incluindo bases de dados, tabelas e partições, ou mover uma tabela para outra base de dados:
    • Administrador de mutação de metadados (roles/metastore.metadataMutateAdmin) na conta de utilizador ou na conta de serviço
    • Editor de Metastore do Dataproc (roles/metastore.editor) na conta de utilizador ou na conta de serviço

Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

Estas funções predefinidas contêm as autorizações necessárias para usar a interface de administrador do Dataproc Metastore. Para ver as autorizações exatas que são necessárias, expanda a secção Autorizações necessárias:

Autorizações necessárias

São necessárias as seguintes autorizações para usar a interface de administrador do Dataproc Metastore:

  • Para consultar metadados do Dataproc Metastore: metastore.services.queryMetadata
  • Para alterar ou mover tabelas do Dataproc Metastore: metastore.services.mutateMetadata

Também pode conseguir estas autorizações com funções personalizadas ou outras funções predefinidas.

Para mais informações acerca das funções e autorizações específicas do Dataproc Metastore, consulte o resumo da gestão de identidades e acessos do Dataproc Metastore.

Operações de administrador suportadas

Só pode executar operações da interface de administrador através da CLI gcloud ou das APIs Dataproc Metastore. As operações da interface do administrador não são suportadas na Google Cloud consola.

A interface de administrador suporta as seguintes operações.

  • Operações só de leitura.

    • Consultar metadados.

  • Operações de leitura e escrita.

    • Alterar a localização dos recursos dos metadados, incluindo bases de dados, tabelas e partições.
    • Alterar propriedades da tabela, como pares de chave-valor personalizados.
    • Mover uma tabela para outra base de dados.

Se a interface de administrador não suportar uma operação diferente, pode consultar diretamente o metastore do Hive. Por exemplo, para listar todas as tabelas numa instância do Dataproc Metastore, pode consultar diretamente o esquema do metastore do Hive. Neste caso, pode executar o comando select * from TBLS para listar todas as tabelas armazenadas no seu serviço.

Consultar metadados

Esta operação permite-lhe procurar informações de metadados na sua base de dados através de consultas SQL. Depois de executar uma consulta, os resultados são transferidos para o seu contentor de artefactos Google Cloud .

Antes de executar esta operação, tenha em atenção as seguintes considerações:

  • As operações suportadas incluem apenas consultas do read-only MySQL ou do Spanner. Se a consulta tentar modificar os dados, a operação falha.
  • O ficheiro de saída contém um máximo de 1000 linhas. Não é possível alterar esta configuração.

  • Os ficheiros de saída não são eliminados automaticamente. Em alternativa, tem de os eliminar manualmente do seu Google Cloud contentor. Se não os eliminar, pode incorrer em custos de armazenamento adicionais.

CLI gcloud

  1. Para consultar metadados, execute o seguinte comando gcloud metastore services query-metadata:

    gcloud metastore services query-metadata SERVICE \
  --location=LOCATION \
  --query=QUERY

    Substitua o seguinte:

    • SERVICE: o nome do seu serviço do Dataproc Metastore.
    • LOCATION: a região em que o seu serviço Dataproc Metastore reside. Google Cloud
    • QUERY: a consulta SQL para segmentar os seus metadados.
      • Se estiver a usar uma base de dados do MySQL, use uma consulta normal do MySQL.
      • Se estiver a usar uma base de dados do Spanner, use uma consulta GoogleSQL.

  2. Veja o ficheiro de saída no contentor de artefactos Google Cloud .

REST

curl -X POST -s -i \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -X POST -d '{"query": "QUERY"}' \
  -H "Content-Type:application/json" \
  https://metastore.googleapis.com/projects/PROJECT_ID/locations/LOCATION/services/SERVICE:queryMetadata

Substitua o seguinte:

  • QUERY: a consulta SQL que está a usar para segmentar os seus metadados.
    • Se estiver a usar uma base de dados do MySQL, use uma consulta normal do MySQL.
    • Se estiver a usar uma base de dados do Spanner, use uma consulta GoogleSQL.
  • PROJECT_ID: o ID do projeto no qual o serviço Dataproc Metastore reside. Google Cloud
  • SERVICE: o nome do serviço Dataproc Metastore.
  • LOCATION: a região onde o Dataproc Metastore reside.

O exemplo seguinte mostra um comando de exemplo que executa uma consulta select * a partir de uma base de dados denominada DBS.

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" -X POST -d  '{"query": "select * from DBS;"}' \
  https://metastore.googleapis.com/projects/dpms/locations/us-central1/services/dpms1:queryMetadata

Interprete o resultado de uma operação de metadados de consulta

Quando executa um comando de metadados de consulta pela primeira vez, o Dataproc Metastore cria automaticamente uma Google Cloud pasta no seu contentor de artefactos Google Cloud . Esta pasta chama-se query-results. Após cada execução de consulta bem-sucedida (chamada API), é criada uma nova pasta na pasta query-results (que tem um UUID gerado aleatoriamente).

Cada nova pasta contém um ficheiro result manifest com os resultados da sua consulta. A localização desta pasta é devolvida na resposta da sua chamada API.

Por exemplo, na resposta, o campo resultManifestUri contém a localização do ficheiro.

"response": {
    "@type": "type.googleapis.com/google.cloud.metastore.QueryMetadataResponse",
    "resultManifestUri": "gs://gcs-bucket-6a3638b8-e319-46363-ad33-e632a5e/query-results/800156f5-2d13-4b80-bec3-2345a9e880f6/result-manifest"
  }

O resultado do ficheiro result manifest é semelhante ao seguinte:

{
  "status": {
    "code": 0,
    "message": "Query results are successfully uploaded to cloud storage",
    "details": []
  },
  "filenames": ["result-001"]
}

Detalhes do ficheiro de manifesto do resultado:

  • O campo status mostra se a consulta foi bem-sucedida ou falhou.
  • Se a execução da consulta for bem-sucedida, o campo filenames apresenta todos os ficheiros criados. Estes ficheiros estão na mesma pasta que o ficheiro result manifest.
  • Se a consulta resultar numa falha, o campo details mostra a mensagem de erro.

Altere a localização do recurso dos seus metadados

Esta operação permite-lhe alterar a localização do recurso de uma base de dados, uma tabela ou uma partição.

Quando executa este comando, apenas atualiza o diretório principal ou o recurso de metadados respetivo. Este comando não transfere dados existentes para a nova localização.

CLI gcloud

  1. Para alterar a localização do recurso dos metadados, execute o seguinte comando gcloud metastore services alter-metadata-resource-location:

    gcloud metastore services alter-metadata-resource-location SERVICE \
  --location=LOCATION \
  --resource_name=RESOURCE_NAME \
  --location_uri=LOCATION_URI

    Substitua o seguinte:

    • SERVICE: o nome do serviço Dataproc Metastore.
    • LOCATION: a região em que o seu serviço Dataproc Metastore reside. Google Cloud
    • RESOURCE_NAME: o nome da base de dados, da tabela ou da partição que está a alterar.
    • LOCATION_URI: o novo caminho do Cloud Storage para o conteúdo de RESOURCE_NAME. Este valor é o caminho para o qual está a mover a localização do recurso de metadados. Este caminho tem de começar com gs://. Por exemplo, gs://bucket/object.

  2. Verifique se a alteração da localização do recurso foi bem-sucedida.

REST

curl -X POST -s -i \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  POST -d '{"resource_name": "RESOURCE_NAME", "location_uri":"LOCATION_URI"}' \
  -H "Content-Type:application/json" \
  https://metastore.googleapis.com/projects/PROJECT_ID/locations/LOCATION/services/SERVICE:alterLocation

Substitua o seguinte:

  • PROJECT_ID: o ID do projeto no qual o serviço Dataproc Metastore reside. Google Cloud
  • SERVICE: o nome do seu serviço Dataproc Metastore.
  • LOCATION: a região onde reside o seu Dataproc Metastore.
  • RESOURCE_NAME: o nome da base de dados, da tabela ou da partição que está a alterar.
  • LOCATION_URI: o novo caminho do Cloud Storage para o conteúdo de RESOURCE_NAME. Este valor é o caminho para o qual está a mover a localização do recurso de metadados. Este caminho tem de começar com gs://. Por exemplo, gs://bucket/object.

O exemplo seguinte mostra um comando de exemplo que move uma tabela denominada test-table2 para um novo contentor do Cloud Storage.

 curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   -X POST -d  '{"resource_name": "databases/testdb1/tables/test-table2",
   "location_uri":"gs://gcs-bucket-dpms1-9425bd83-b794-4f1c-9e79-2d833f758cc1/empty"}'
   https://metastore.googleapis.com/projects/dpms/locations/us-central1/services/dpms1:alterLocation

Altere as propriedades da tabela

Esta operação permite-lhe alterar as propriedades de uma tabela, como um par de chave-valor personalizado que está a usar para armazenar dados. Por exemplo, pode alterar um par de chave-valor de properties.customerID_1 para properties.customerID_2.

CLI gcloud

  1. Para alterar as propriedades de uma tabela, execute o seguinte comando gcloud metastore services alter-table-properties:

    gcloud metastore services alter-table-properties SERVICE \
  --location=LOCATION \
  --table-name=TABLE_NAME \
  --update-mask=UPDATE_MASK \
  --properties=PROPERTIES

    Substitua o seguinte:

    • SERVICE: o nome do seu serviço do Dataproc Metastore.
    • LOCATION: a região em que o seu serviço Dataproc Metastore reside. Google Cloud
    • TABLE_NAME: o nome da tabela que contém as propriedades que está a alterar no seguinte formato: databases/{database_id}/tables/{table_id}.
    • UPDATE_MASK: os valores das propriedades existentes que está a atualizar. Use uma lista separada por vírgulas para descrever os pares de chave-valor, por exemplo, properties.1,properties.2,properties.3,....
    • PROPERTIES: as novas propriedades da tabela. Use uma lista separada por vírgulas para descrever os pares chave-valor. Por exemplo, a=1,b=2,c=3,.... Os valores que indicar aqui substituem os valores em UPDATE_MASK.

REST

curl -X POST -s -i \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  POST -d '{"table_name": "TABLE_NAME", "update_mask":"UPDATE_MASK", "properties":PROPERTIES}'\
  -H "Content-Type:application/json" \
  https://metastore.googleapis.com/projects/PROJECT_ID/locations/LOCATION/services/SERVICE:alterTableProperties

Substitua o seguinte:

  • SERVICE: o nome do seu serviço do Dataproc Metastore.
  • LOCATION: a região em que o seu serviço Dataproc Metastore reside. Google Cloud
  • TABLE_NAME: o nome da tabela que contém as propriedades que está a alterar no seguinte formato: databases/{database_id}/tables/{table_id}.
  • UPDATE_MASK: os valores das propriedades existentes que está a atualizar. Use uma lista separada por vírgulas para descrever os pares de chave-valor, por exemplo, properties.1,properties.2,properties.3,....
  • PROPERTIES: as novas propriedades da tabela. Use uma lista separada por vírgulas para descrever os pares de chave-valor, por exemplo, a=1,b=2,c=3,.... Os valores que indicar aqui substituem os valores em UPDATE_MASK.

O exemplo seguinte mostra um comando de exemplo que altera as propriedades da tabela de uma tabela denominada test-table. Neste exemplo, o par de chave-valor existente, properties.customerID_1 é atualizado para o novo valor properties.customerID_2

  curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json"
   -X POST -d  '{"table_name": "databases/default/tables/test-table", "update_mask":{"paths":"properties.customerID_1"}, "properties":{"customerID_1":"customerID_2"}}' https://metastore.googleapis.com/projects/dpms-p

Mova uma tabela para outra base de dados

Esta operação permite-lhe mover uma tabela interna (tabela gerida) para outra base de dados. Neste caso, tanto o diretório principal da base de dados como os respetivos dados são movidos.

Não pode mover dados armazenados em tabelas externas.

CLI gcloud

  1. Para mover uma tabela para outra base de dados, execute o seguinte comando gcloud metastore services move-table-to-database:

    gcloud metastore services move-table-to-database SERVICE \
  --location=LOCATION \
  --db_name=DB_NAME \
  --table_name=TABLE_NAME \
  --destination_db_name=DESTINATION_DB_NAME

    Substitua o seguinte:

    • SERVICE: o nome do seu serviço Dataproc Metastore.
    • LOCATION: a Google Cloud região em que o seu serviço Dataproc Metastore reside.
    • DB_NAME: o nome da base de dados de origem que contém a tabela que quer mover.
    • TABLE_NAME: o nome da tabela que quer mover.
    • DESTINATION_DB_NAME: o nome da nova base de dados para a qual quer mover a tabela.

  2. Verifique se a alteração da tabela foi bem-sucedida.

REST

curl -X POST -s -i \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  POST -d '{"table_name": "TABLE_NAME", "db_name": "DB_NAME", "destination_db_name": "DESTINATION_DB_NAME"}'\
  -H "Content-Type:application/json" \
  https://metastore.googleapis.com/projects/PROJECT_ID/locations/LOCATION/services/SERVICE:moveTableToDatabase

Substitua o seguinte:

  • PROJECT_ID: o ID do projeto no qual reside o seu serviço do Dataproc Metastore. Google Cloud
  • SERVICE: o nome do serviço Dataproc Metastore.
  • LOCATION: a região onde o Dataproc Metastore reside.
  • DB_NAME: o nome da base de dados de origem que contém a tabela que quer mover.
  • TABLE_NAME: o nome da tabela que quer mover.
  • DESTINATION_DB_NAME: o nome da nova base de dados para a qual quer mover a tabela.

O exemplo seguinte mostra um comando de exemplo que move uma base de dados denominada testdb1 para uma base de dados diferente denominada testdb2.

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
 -H "Content-Type: application/json"
 -X POST -d  '{"table_name": "testtb1", "db_name": "testdb1",
 "destination_db_name": "testdb2"}' https://metastore.googleapis.com/projects/dpms/locations/asia-northeast2/services/dpms1:moveTableToDatabase

O que se segue?