Interface administrateur de Dataproc Metastore

Cette page explique comment utiliser l'interface administrateur de Dataproc Metastore.

L'interface administrateur vous fournit un outil centralisé pour inspecter et gérer les métadonnées stockées dans votre service Dataproc Metastore, le tout sans avoir à vous connecter à un cluster Dataproc ni à une instance Hive. Vous pouvez plutôt gérer vos métadonnées avec la CLI gcloud ou les API Dataproc Metastore.

Par exemple, à l'aide de l'interface administrateur, 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 implique de suivre moins d'étapes que le workflow standard, par exemple en créant un cluster Dataproc, en vous y connectant via SSH, en démarrant une instance Hive, puis en exécutant une requête (par exemple, SELECT * FROM table_name).

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

Avant de commencer

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

Rôles requis

Pour obtenir les autorisations nécessaires pour utiliser l'interface administrateur de Dataproc Metastore, demandez à votre administrateur de vous accorder les rôles IAM suivants sur votre projet, conformément au 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 des ressources 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 la page 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 d'administration de 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 administrateur de 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 les autorisations spécifiques de Dataproc Metastore, consultez la page Présentation d'IAM pour Dataproc Metastore.

Opérations d'administration compatibles

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

L'interface administrateur accepte les opérations suivantes.

• Opérations en lecture seule

  • Interrogez les métadonnées.
  Avertissement :N'exécutez les requêtes en lecture seule que de manière interactive. N'automatisez pas et n'exécutez pas de requêtes en lecture seule non interactives sur des 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.

  • Modifier l'emplacement des ressources de vos métadonnées, y compris les bases de données, les tables et les partitions
  • Modifier les propriétés de la table, telles que des paires clé-valeur personnalisées
  • Déplacer une table vers une autre base de données

Interroger les métadonnées

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

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

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

• Les fichiers de sortie ne sont pas automatiquement supprimés. Vous devez les supprimer manuellement de votre bucket Google Cloud . Si vous ne les supprimez pas, vous risquez de subir 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 se trouve votre service Dataproc Metastore.
   • QUERY: requête SQL permettant de 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 artifacts Google Cloud .

REST

Remarque :La commande suivante suppose que vous vous êtes connecté à la CLI gcloud 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 CLI gcloud. 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 de projet dans lequel se trouve le service Dataproc Metastore. Google Cloud
• SERVICE: nom de votre service Dataproc Metastore.
• LOCATION: région dans laquelle se trouve 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 la sortie 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 Google Cloud dossier dans votre bucket d'artefacts Google Cloud . Ce dossier est nommé query-results. Après chaque exécution de requête réussie (appel d'API), un nouveau dossier est créé dans le dossier query-results (qui est nommé avec un UUID généré de manière aléatoire).

Chaque nouveau dossier contient un fichier result manifest contenant 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"
  }

La sortie du fichier result manifest ressemble à ce qui suit:

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

Informations sur le fichier manifeste de résultats:

• Le champ status indique si la requête a réussi ou échoué.
• 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 de payer des frais de stockage supplémentaires.

Modifier l'emplacement des ressources de vos métadonnées

Cette opération vous permet de modifier l'emplacement des ressources 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 ressources des métadonnées, 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 se trouve 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. Ce chemin d'accès doit commencer par gs://. Par exemple, gs://bucket/object.

2. Vérifiez que le changement de l'emplacement des ressources a réussi.

REST

Remarque :La commande suivante suppose que vous êtes connecté à la CLI gcloud avec votre compte utilisateur. Vous pouvez vous connecter en exécutant gcloud init ou gcloud auth login, ou en utilisant Cloud Shell, qui vous permet de vérifier votre compte en exécutant 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 de projet dans lequel se trouve le service Dataproc Metastore. Google Cloud
• SERVICE: nom de votre service Dataproc Metastore.
• LOCATION: région dans laquelle se trouve 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. Ce chemin d'accès doit commencer par gs://. Par exemple, gs://bucket/object.

L'exemple suivant montre une commande qui déplace 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 une 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 se trouve votre service Dataproc Metastore.
   • TABLE_NAME : nom de la table contenant les propriétés que vous modifiez au format suivant : databases/{database_id}/tables/{table_id}.
   • UPDATE_MASK: valeurs de propriété existantes que vous mettez à jour. Utilisez une liste séparée par une virgule 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 une virgule pour décrire les paires clé-valeur. Exemple : a=1,b=2,c=3,.... Les valeurs que vous indiquez ici écrasent les valeurs de UPDATE_MASK.

REST

Remarque :La commande suivante suppose que vous êtes connecté à la CLI gcloud 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 CLI gcloud. 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 se trouve votre service Dataproc Metastore.
• TABLE_NAME : nom de la table contenant les propriétés que vous modifiez au format suivant : databases/{database_id}/tables/{table_id}.
• UPDATE_MASK: valeurs de propriété existantes que vous mettez à jour. Utilisez une liste séparée par une virgule 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 une virgule pour décrire les paires clé-valeur (par exemple, a=1,b=2,c=3,...). Les valeurs que vous indiquez ici écrasent les valeurs de UPDATE_MASK.

L'exemple suivant montre une commande qui modifie les propriétés 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 se trouve 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 êtes connecté à la CLI gcloud 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 CLI gcloud. 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 Google Cloud projet dans lequel se trouve votre service Dataproc Metastore.
• SERVICE: nom de votre service Dataproc Metastore.
• LOCATION: région dans laquelle se trouve 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 qui déplace 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

Étape suivante

• Exporter des métadonnées
• Mettre à jour un métastore
• Sauvegarder un métastore