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 en suivant moins d'étapes que le workflow classique, comme la création un cluster Dataproc, en se connectant au cluster via SSH, en démarrant une instance Hive, Enfin, vous exécuterez une requête (par exemple, SELECT * FROM table_name).

Ainsi, l'interface d'administration vous permet de gagner du temps et de réduire la quantité de ressources Google Cloud requise 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 déplacer une table vers une autre base de données:
  • Administrateur de mutation 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 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 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 à Dataproc Metastore, consultez la page Présentation d'IAM de 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 Metastore Dataproc. Les opérations de l'interface administrateur ne sont pas compatibles avec la console Google Cloud.

L'interface d'administration prend en charge les opérations suivantes.

• Opérations en lecture seule

  • Interroger 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 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 et les tables et les partitions.
  • modifier les propriétés d'un tableau, telles que les paires clé-valeur personnalisées ;
  • Déplacer une table vers une autre base de données

Métadonnées de requête

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 Google Cloud d'artefacts.

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

• Les opérations compatibles n'incluent que les requêtes MySQL ou Spanner read-only. Si la requête tente pour 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 supprimer manuellement depuis votre bucket Google Cloud. Si vous ne les supprimez pas, des coûts de stockage supplémentaires.

CLI gcloud

1. Pour interroger des 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 Google Cloud d'artefacts.

REST

Remarque :La commande suivante suppose que 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 CLI gcloud. Vous pouvez vérifier le compte actif en exécutant la commande 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 que vous Le service Dataproc Metastore réside.
• SERVICE: nom de votre Dataproc Metastore Google Cloud.
• 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 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 Google Cloud d'artefacts. Ce dossier est nommé query-results. Après chaque exécution de requête (appel d'API), un dossier est créé dans le dossier query-results (nommé par 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. Le lieu 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"]
}

Détails du fichier manifeste des 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 répertorie 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 valeur TTL (Time To Live). Vous devez les supprimer manuellement de votre bucket Google Cloud ou créer une règle TTL personnalisée sur le dossier query-results. Si vous ne les supprimez pas, vous risquez d'avoir un espace de stockage supplémentaire coûts.

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 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 nouvel emplacement.

CLI gcloud

1. Pour modifier l'emplacement des ressources des métadonnées, exécutez la commande suivante : Commande 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

   Remplacez les éléments suivants :

   • SERVICE: nom de votre Dataproc Metastore Google Cloud.
   • LOCATION: région Google Cloud dans laquelle Le service Dataproc Metastore réside.
   • RESOURCE_NAME: nom de la base de données, de la table ou 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 la modification de l'emplacement des ressources 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 la commande gcloud init. ou gcloud auth login, ou à l'aide de Cloud Shell, qui en exécutant la commande 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 se trouve le service Dataproc Metastore.
• 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 un exemple de 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'un tableau

Cette opération vous permet de modifier les propriétés d'un tableau, comme clé-valeur 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 la commande gcloud init. ou gcloud auth login, ou à l'aide de 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 se trouve votre service Dataproc Metastore.
• TABLE_NAME: nom de la table contenant la 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 d'éléments séparés 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 d'éléments séparés 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 dans 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é 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 suivante : Commande 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

   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 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 CLI gcloud. Vous pouvez consulter compte en exécutant la commande 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 de projet Google Cloud dans lequel réside votre service Metastore Dataproc.
• 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 un exemple de commande qui déplace un objet appelé 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 les métadonnées
• Mettre à jour un métastore
• Sauvegarder un métastore