Interface administrateur de Dataproc Metastore

Cette page explique comment utiliser l'interface d'administration Dataproc Metastore.

L'interface d'administration vous fournit un outil centralisé pour inspecter et gérer les métadonnées stockées dans votre service Dataproc Metastore, sans avoir à vous connecter à un cluster Dataproc ni à une instance Hive. Vous pouvez gérer vos métadonnées avec Google Cloud CLI ou les API Dataproc Metastore.

Par exemple, à l'aide de l'interface d'administration, vous pouvez exécuter une requête SQL directement sur vos métadonnées de backend pour récupérer un nom de table spécifique. Ce processus comporte moins d'étapes que le workflow habituel, comme la création d'un cluster Dataproc, la connexion au cluster à l'aide de SSH, le démarrage d'une instance Hive et l'exécution d'une requête (par exemple, SELECT * FROM table_name).

Par conséquent, l'interface d'administration peut vous aider à gagner du temps et à réduire la quantité de ressources Google Cloud nécessaires pour récupérer vos données.

Avant de commencer

• Activez Dataproc Metastore dans votre projet.
• Créez un service Dataproc Metastore.
• Importer des métadonnées dans Dataproc Metastore

Rôles requis

Pour obtenir les autorisations nécessaires pour utiliser l'interface d'administration Dataproc Metastore, demandez à votre administrateur de vous accorder les rôles IAM suivants sur votre projet, en fonction du principe du moindre privilège :

• Pour interroger les métadonnées Dataproc Metastore : Administrateur de requêtes de métadonnées (roles/metastore.metadataQueryAdmin) sur le compte utilisateur ou le compte de service
• Pour modifier l'emplacement de ressource de vos métadonnées, y compris les bases de données, les tables et les partitions, ou pour déplacer une table vers une autre base de données :
  • Administrateur de modification des métadonnées (roles/metastore.metadataMutateAdmin) sur le compte utilisateur ou le compte de service
  • Éditeur Dataproc Metastore (roles/metastore.editor) sur le compte utilisateur ou le compte de service

Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Ces rôles prédéfinis contiennent les autorisations requises pour utiliser l'interface administrateur Dataproc Metastore. Pour connaître les autorisations exactes requises, développez la section Autorisations requises :

Autorisations requises

Vous devez disposer des autorisations suivantes pour utiliser l'interface d'administration Dataproc Metastore :

• Pour interroger les métadonnées Dataproc Metastore : metastore.services.queryMetadata
• Pour modifier ou déplacer des tables Dataproc Metastore : metastore.services.mutateMetadata

Vous pouvez également obtenir ces autorisations avec des rôles personnalisés ou d'autres rôles prédéfinis.

Pour en savoir plus sur les rôles et autorisations Dataproc Metastore spécifiques, consultez Présentation d'Identity and Access Management pour Dataproc Metastore.

Opérations d'administration compatibles

Vous ne pouvez exécuter des opérations d'interface d'administration qu'à l'aide de la gcloud CLI ou des API Dataproc Metastore. Les opérations d'interface administrateur ne sont pas compatibles avec la console Google Cloud .

L'interface d'administration permet d'effectuer les opérations suivantes.

• Opérations en lecture seule

  • Interrogez les métadonnées.
  Avertissement : N'exécutez les requêtes en lecture seule qu'en mode interactif. N'automatisez pas les requêtes en lecture seule non interactives sur les processus critiques pour la production. L'exécution de requêtes non interactives peut entraîner des problèmes si le schéma de base de données sous-jacent change sans préavis.

• Opérations de lecture et d'écriture

  • Modifiez l'emplacement de la ressource de vos métadonnées, y compris les bases de données, les tables et les partitions.
  • Modifier les propriétés des tables, comme les paires clé/valeur personnalisées.
  • Déplacez une table vers une autre base de données.

Si l'interface d'administration n'est pas compatible avec une autre opération, vous pouvez interroger directement le métastore Hive. Par exemple, pour lister toutes les tables d'une instance Dataproc Metastore, vous pouvez interroger directement le schéma du métastore Hive. Dans ce cas, vous pouvez exécuter select * from TBLS pour lister toutes les tables stockées dans votre service.

Interroger les métadonnées

Cette opération vous permet de rechercher des informations sur les métadonnées dans votre base de données à l'aide de requêtes SQL. Une fois la requête exécutée, les résultats sont placés dans votre bucket d'artefacts Google Cloud .

Avant d'exécuter cette opération, tenez compte des points suivants :

• Les opérations compatibles n'incluent que les requêtes read-only MySQL ou Spanner. Si la requête tente de modifier les données, l'opération échoue.
• Le fichier de sortie contient au maximum 1 000 lignes. Cette configuration ne peut pas être modifiée.

• Les fichiers de sortie ne sont pas supprimés automatiquement. Vous devez à la place les supprimer manuellement de votre bucket Google Cloud . Si vous ne les supprimez pas, vous risquez d'engendrer des coûts de stockage supplémentaires.

CLI gcloud

1. Pour interroger les métadonnées, exécutez la commande gcloud metastore services query-metadata suivante :

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

   Remplacez les éléments suivants :

   • SERVICE : nom de votre service Dataproc Metastore.
   • LOCATION : région Google Cloud dans laquelle réside votre service Dataproc Metastore.
   • QUERY : requête SQL pour cibler vos métadonnées.
     • Si vous utilisez une base de données MySQL, utilisez une requête MySQL standard.
     • Si vous utilisez une base de données Spanner, utilisez une requête GoogleSQL.

2. Affichez le fichier de sortie dans votre bucket Google Cloud artifacts.

REST

Remarque : La commande suivante suppose que vous vous êtes connecté à la gcloud CLI avec votre compte utilisateur. Vous pouvez vous connecter en exécutant gcloud init ou gcloud auth login, ou en utilisant Cloud Shell, qui vous connecte automatiquement à la gcloud CLI. Vous pouvez vérifier le compte actif en exécutant gcloud auth list.

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

Remplacez les éléments suivants :

• QUERY : requête SQL que vous utilisez pour cibler vos métadonnées.
  • Si vous utilisez une base de données MySQL, utilisez une requête MySQL standard.
  • Si vous utilisez une base de données Spanner, utilisez une requête GoogleSQL.
• PROJECT_ID : ID du projet Google Cloud dans lequel réside votre service Dataproc Metastore.
• SERVICE : nom de votre service Dataproc Metastore.
• LOCATION : région dans laquelle réside votre Dataproc Metastore.

L'exemple suivant montre une commande qui exécute une requête select * à partir d'une base de données nommée 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

Interpréter le résultat d'une opération de métadonnées de requête

Lorsque vous exécutez une commande de métadonnées de requête pour la première fois, Dataproc Metastore crée automatiquement un dossier Google Cloud dans votre bucket d'artefacts Google Cloud . Ce dossier est nommé query-results. Après chaque exécution de requête (appel d'API) réussie, un nouveau dossier est créé dans le dossier query-results (dont le nom est un UUID généré de manière aléatoire).

Chaque nouveau dossier contient un fichier result manifest avec les résultats de votre requête. L'emplacement de ce dossier est renvoyé dans la réponse de votre appel d'API.

Par exemple, dans la réponse, le champ resultManifestUri contient l'emplacement du fichier.

"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"
  }

Le résultat du fichier result manifest ressemble à ce qui suit :

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

Détails du fichier manifeste des résultats :

• Le champ status indique si la requête a abouti ou non.
• Si l'exécution de la requête aboutit, le champ filenames liste tous les fichiers créés. Ces fichiers se trouvent dans le même dossier que le fichier result manifest.
• Si la requête a échoué, le champ details affiche le message d'erreur.

Remarque : Par défaut, les fichiers de sortie n'ont pas de TTL (Time to live). Vous devez les supprimer manuellement de votre bucket Google Cloud ou créer une règle TTL personnalisée dans le dossier query-results. Si vous ne les supprimez pas, vous risquez d'être facturé pour l'espace de stockage supplémentaire.

Modifier l'emplacement de la ressource de vos métadonnées

Cette opération vous permet de modifier l'emplacement de la ressource d'une base de données, d'une table ou d'une partition.

Lorsque vous exécutez cette commande, elle ne met à jour que le répertoire parent ou la ressource de métadonnées correspondante. Cette commande ne transfère aucune donnée existante vers le nouvel emplacement.

CLI gcloud

1. Pour modifier l'emplacement des métadonnées de ressources, exécutez la commande gcloud metastore services alter-metadata-resource-location suivante :

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

   Remplacez les éléments suivants :

   • SERVICE : nom de votre service Dataproc Metastore.
   • LOCATION : région Google Cloud dans laquelle réside votre service Dataproc Metastore.
   • RESOURCE_NAME : nom de la base de données, de la table ou de la partition que vous modifiez.
   • LOCATION_URI : nouveau chemin d'accès Cloud Storage pour le contenu de RESOURCE_NAME. Cette valeur correspond au chemin vers lequel vous déplacez l'emplacement de votre ressource de métadonnées. Le chemin d'accès doit commencer par gs://. Par exemple, gs://bucket/object.

2. Vérifiez que le changement de région de la ressource a bien été effectué.

REST

Remarque : La commande suivante suppose que vous vous êtes connecté à la gcloud CLI avec votre compte utilisateur. Vous pouvez vous connecter en exécutant gcloud init ou gcloud auth login, ou en utilisant Cloud Shell, qui exécute automatiquement gcloud auth login. Pour vérifier le compte actuellement actif, exécutez gcloud auth list.

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

Remplacez les éléments suivants :

• PROJECT_ID : ID du projet Google Cloud dans lequel réside votre service Dataproc Metastore.
• SERVICE : nom de votre service Dataproc Metastore.
• LOCATION : région dans laquelle réside votre Dataproc Metastore.
• RESOURCE_NAME : nom de la base de données, de la table ou de la partition que vous modifiez.
• LOCATION_URI : nouveau chemin d'accès Cloud Storage pour le contenu de RESOURCE_NAME. Cette valeur correspond au chemin vers lequel vous déplacez l'emplacement de votre ressource de métadonnées. Le chemin d'accès doit commencer par gs://. Par exemple, gs://bucket/object.

L'exemple suivant montre une commande qui permet de déplacer une table appelée test-table2 vers un nouveau bucket 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

Modifier les propriétés d'une table

Cette opération vous permet de modifier les propriétés d'un tableau, comme une paire clé-valeur personnalisée que vous utilisez pour stocker des données. Par exemple, vous pouvez remplacer la paire clé-valeur properties.customerID_1 par properties.customerID_2.

CLI gcloud

1. Pour modifier les propriétés d'une table, exécutez la commande gcloud metastore services alter-table-properties suivante :

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

   Remplacez les éléments suivants :

   • SERVICE : nom de votre service Dataproc Metastore.
   • LOCATION : région Google Cloud dans laquelle réside votre service Dataproc Metastore.
   • TABLE_NAME : nom de la table contenant les propriétés que vous modifiez, au format databases/{database_id}/tables/{table_id}.
   • UPDATE_MASK : valeurs de propriété existantes que vous mettez à jour. Utilisez une liste séparée par des virgules pour décrire les paires clé-valeur, par exemple properties.1,properties.2,properties.3,....
   • PROPERTIES : nouvelles propriétés de votre table. Utilisez une liste séparée par des virgules pour décrire les paires clé-valeur. Exemple : a=1,b=2,c=3,.... Les valeurs que vous indiquez ici remplacent celles de UPDATE_MASK.

REST

Remarque : La commande suivante suppose que vous vous êtes connecté à la gcloud CLI avec votre compte utilisateur. Vous pouvez vous connecter en exécutant gcloud init ou gcloud auth login, ou en utilisant Cloud Shell, qui vous connecte automatiquement à la gcloud CLI. Vous pouvez vérifier le compte actif en exécutant gcloud auth list.

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

Remplacez les éléments suivants :

• SERVICE : nom de votre service Dataproc Metastore.
• LOCATION : région Google Cloud dans laquelle réside votre service Dataproc Metastore.
• TABLE_NAME : nom de la table contenant les propriétés que vous modifiez, au format databases/{database_id}/tables/{table_id}.
• UPDATE_MASK : valeurs de propriété existantes que vous mettez à jour. Utilisez une liste séparée par des virgules pour décrire les paires clé-valeur, par exemple properties.1,properties.2,properties.3,....
• PROPERTIES : nouvelles propriétés de votre table. Utilisez une liste séparée par des virgules pour décrire les paires clé-valeur, par exemple a=1,b=2,c=3,.... Les valeurs que vous indiquez ici remplacent celles de UPDATE_MASK.

L'exemple suivant montre un exemple de commande qui modifie les propriétés de table d'une table appelée test-table. Dans cet exemple, la paire clé/valeur existante properties.customerID_1 est remplacée par la nouvelle valeur 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

Déplacer un tableau vers une autre base de données

Cette opération vous permet de déplacer une table interne (table gérée) vers une autre base de données. Dans ce cas, le répertoire parent de la base de données et ses données sont déplacés.

Vous ne pouvez pas déplacer les données stockées dans des tables externes.

CLI gcloud

1. Pour déplacer une table vers une autre base de données, exécutez la commande gcloud metastore services move-table-to-database suivante :

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

   Remplacez les éléments suivants :

   • SERVICE : nom de votre service Dataproc Metastore.
   • LOCATION : région Google Cloud dans laquelle réside votre service Dataproc Metastore.
   • DB_NAME : nom de la base de données source contenant la table que vous souhaitez déplacer.
   • TABLE_NAME : nom de la table que vous souhaitez déplacer.
   • DESTINATION_DB_NAME : nom de la nouvelle base de données vers laquelle vous souhaitez déplacer la table.

2. Vérifiez que la modification de la table a bien été effectuée.

REST

Remarque : La commande suivante suppose que vous vous êtes connecté à la gcloud CLI avec votre compte utilisateur. Vous pouvez vous connecter en exécutant gcloud init ou gcloud auth login, ou en utilisant Cloud Shell, qui vous connecte automatiquement à la gcloud CLI. Vous pouvez vérifier le compte actif en exécutant gcloud auth list.

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

Remplacez les éléments suivants :

• PROJECT_ID : ID du projet Google Cloud dans lequel réside votre service Dataproc Metastore.
• SERVICE : nom de votre service Dataproc Metastore.
• LOCATION : région dans laquelle réside votre Dataproc Metastore.
• DB_NAME : nom de la base de données source contenant la table que vous souhaitez déplacer.
• TABLE_NAME : nom de la table que vous souhaitez déplacer.
• DESTINATION_DB_NAME : nom de la nouvelle base de données vers laquelle vous souhaitez déplacer la table.

L'exemple suivant montre une commande permettant de déplacer une base de données appelée testdb1 vers une autre base de données appelée 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

Étapes suivantes

• Exporter les métadonnées
• Mettre à jour un metastore
• Sauvegarder un metastore