Vous pouvez créer et rechercher des entrées d'ensembles de fichiers Cloud Storage (appelés "ensembles de fichiers" dans la suite de ce document) à l'aide des API Data Catalog.
Ensemble de fichiers
Un ensemble de fichiers Cloud Storage est une entrée d'un groupe d'entrées créé par l'utilisateur. Pour en savoir plus, consultez la page Entrées et groupes d'entrées.
Il est défini par un ou plusieurs modèles de fichier qui spécifient un ensemble d'un ou plusieurs fichiers Cloud Storage.
Exigences concernant les modèles de fichier :
- Un modèle de fichier doit commencer par
gs://bucket_name/
. - Le nom du bucket doit respecter les exigences concernant les noms de bucket Cloud Storage.
- Les caractères génériques sont autorisés dans les parties des modèles de fichier concernant le dossier et le fichier, mais les caractères génériques ne sont pas autorisés dans les noms de buckets. Pour obtenir des exemples, consultez les articles suivants :
- Noms avec des caractères génériques
- Documentation de référence de l'API GcsFilesetSpec.filePatterns
- Un ensemble de fichiers doit en avoir un et ne peut pas en comporter plus de cinq.
Vous pouvez interroger des ensembles de fichiers Data Catalog avec Dataflow SQL, mais seulement s'ils comportent un schéma défini et qu'ils ne contiennent que des fichiers CSV sans ligne d'en-tête.
Créer des groupes d'entrées et des ensembles de fichiers
Les ensembles de fichiers doivent être placés dans un groupe d'entrées créé par l'utilisateur. Si vous n'avez pas créé de groupe d'entrées, commencez par en créer un, puis créez l'ensemble de fichiers au sein de ce groupe d'entrées. Vous pouvez définir des stratégies IAM sur le groupe d'entrées pour déterminer qui a accès aux ensembles de fichiers et aux autres entrées du groupe d'entrées.
Console
Console
Accédez à la page Dataplex > Groupes d'entrées.
Cliquez sur Créer un groupe d'entrées.
Remplissez le formulaire Create Entry Group (Créer un groupe d'entrées), puis cliquez sur CREATE (Créer).
La page Détails du groupe d'entrées s'affiche. Après avoir sélectionné l'onglet ENTRIES (Entrées), cliquez sur CREATE (Créer).
Remplissez le formulaire Create Fileset (Créer un ensemble de fichiers).
- Pour associer un schéma, cliquez sur Define Schema (Définir un schéma) pour ouvrir le formulaire correspondant. Cliquez sur + ADD FIELDS (AJOUTER DES CHAMPS) pour ajouter des champs individuellement ou activez l'option Edit as text (Modifier sous forme de texte) en haut à droite du formulaire pour les spécifier au format JSON.
- Cliquez sur Save (Enregistrer) pour enregistrer le schéma.
Cliquez sur Create (Créer) pour créer l'ensemble de fichiers.
gcloud
gcloud
1. Créer un groupe d'entrées
Utilisez la commande gcloud data-catalog entry-groups create pour créer un groupe d'entrée auquel sont associés un schéma et une description.
Exemple :
gcloud data-catalog entry-groups create my_entrygroup \ --location=us-central1
2. Créer un ensemble de fichiers dans le groupe d'entrées
Utilisez la commande gcloud data-catalog entries create pour créer un ensemble de fichiers dans un groupe d'entrées. L'exemple de commande gcloud
ci-dessous crée une entrée d'ensemble de fichiers qui inclut un schéma de données d'ensemble de fichiers.
gcloud data-catalog entries create my_fileset_entry \ --location=us-central1 \ --entry-group=my_entrygroup \ --type=FILESET \ --gcs-file-patterns=gs://my-bucket/*.csv \ --schema-from-file=path_to_schema_file \ --description="Fileset description ..."
Notes sur les options :
--gcs-file-patterns
: consultez la section Exigences concernant les modèles de fichier.--schema-from-file
: l'exemple suivant montre le format JSON du fichier texte de schéma accepté par l'option--schema-from-file
.[ { "column": "first_name", "description": "First name", "mode": "REQUIRED", "type": "STRING" }, { "column": "last_name", "description": "Last name", "mode": "REQUIRED", "type": "STRING" }, { "column": "address", "description": "Address", "mode": "REPEATED", "type": "STRING" } ]
Java
Avant d'essayer cet exemple, suivez les instructions de configuration pour Java du guide de démarrage rapide de Data Catalog à l'aide des bibliothèques clientes. Pour en savoir plus, consultez les API Java Data Catalog documentation de référence.
Pour vous authentifier auprès de Data Catalog, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Node.js
Avant d'essayer cet exemple, suivez les instructions de configuration de Node.js dans le Démarrage rapide de Data Catalog avec bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API Data Catalog Node.js.
Pour vous authentifier auprès de Data Catalog, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Python
Avant d'essayer cet exemple, suivez les instructions de configuration pour Python du guide de démarrage rapide de Data Catalog à l'aide des bibliothèques clientes. Pour en savoir plus, consultez les API Python Data Catalog documentation de référence.
Pour vous authentifier auprès de Data Catalog, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
API REST et ligne de commande
REST
Si vous n'avez pas accès aux bibliothèques clientes Cloud pour votre langage ou si vous souhaitez tester l'API à l'aide de requêtes REST, consultez les exemples suivants et reportez-vous aux API REST Data Catalog entryGroups.create et entryGroups.entries.create.
1. Créer un groupe d'entrées
Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :
- project-id : ID de votre projet Google Cloud.
- entryGroupId : l'ID doit commencer par une lettre ou un trait de soulignement, ne doit contenir que des lettres en alphabet latin, des chiffres et des traits de soulignement, et ne doit pas contenir plus de 64 caractères.
- displayName : nom textuel du groupe d'entrées.
Méthode HTTP et URL :
POST https://datacatalog.googleapis.com/v1/projects/project-id/locations/region/entryGroups?entryGroupId=entryGroupId
Corps JSON de la requête :
{ "displayName": "Entry Group display name" }
Pour envoyer votre requête, développez l'une des options suivantes :
Vous devriez recevoir une réponse JSON de ce type :
{ "name": "projects/my_projectid/locations/us-central1/entryGroups/my_entry_group", "displayName": "Entry Group display name", "dataCatalogTimestamps": { "createTime": "2019-10-19T16:35:50.135Z", "updateTime": "2019-10-19T16:35:50.135Z" } }
2. Créer un ensemble de fichiers dans le groupe d'entrées
Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :
- project_id : ID de votre projet Google Cloud.
- entryGroupId : ID du groupe d'entrées existant. L'ensemble de fichiers sera créé dans ce groupe d'entrées.
- entryId : ID d'entrée du nouvel ensemble de fichiers. L'ID doit commencer par une lettre ou un trait de soulignement, ne doit contenir que des lettres en alphabet latin, des chiffres et des traits de soulignement, et ne doit pas contenir plus de 64 caractères.
- description : description de l'ensemble de fichiers.
- displayName : nom textuel de l'entrée d'ensemble de fichiers.
- filePatterns : doit commencer par "gs://bucket_name/". Consultez la section Exigences concernant les modèles de fichier.
- schema : schéma de l'ensemble de fichiers.
Exemple de schéma JSON :
{ ... "schema": { "columns": [ { "column": "first_name", "description": "First name", "mode": "REQUIRED", "type": "STRING" }, { "column": "last_name", "description": "Last name", "mode": "REQUIRED", "type": "STRING" }, { "column": "address", "description": "Address", "mode": "REPEATED", "subcolumns": [ { "column": "city", "description": "City", "mode": "NULLABLE", "type": "STRING" }, { "column": "state", "description": "State", "mode": "NULLABLE", "type": "STRING" } ], "type": "RECORD" } ] } ... }
Méthode HTTP et URL :
POST https://datacatalog.googleapis.com/v1/projects/project_id/locations/region/entryGroups/entryGroupId/entries?entryId=entryId
Corps JSON de la requête :
{ "description": "Fileset description.", "displayName": "Display name", "gcsFilesetSpec": { "filePatterns": [ "gs://bucket_name/file_pattern" ] }, "type": "FILESET", "schema": { schema } }
Pour envoyer votre requête, développez l'une des options suivantes :
Vous devriez recevoir une réponse JSON de ce type :
{ "name": "projects/my_project_id/locations/us-central1/entryGroups/my_entryGroup_id/entries/my_entry_id", "type": "FILESET", "displayName": "My Fileset", "description": "My Fileset description.", "schema": { "columns": [ { "type": "STRING", "description": "First name", "mode": "REQUIRED", "column": "first_name" }, { "type": "STRING", "description": "Last name", "mode": "REQUIRED", "column": "last_name" }, { "type": "RECORD", "description": "Address", "mode": "REPEATED", "column": "address", "subcolumns": [ { "type": "STRING", "description": "City", "mode": "NULLABLE", "column": "city" }, { "type": "STRING", "description": "State", "mode": "NULLABLE", "column": "state" } ] } ] }, "gcsFilesetSpec": { "filePatterns": [ "gs://my_bucket_name/chicago_taxi_trips/csv/shard-*.csv" ] }, "sourceSystemTimestamps": { "createTime": "2019-10-23T23:11:26.326Z", "updateTime": "2019-10-23T23:11:26.326Z" }, "linkedResource": "//datacatalog.googleapis.com/projects/my_project_id/locations/us-central1/entryGroups/my_entryGroup_id/entries/my_entry_id" }
Rôles, autorisations et stratégies IAM
Data Catalog définit les rôles d'entrée et de groupe d'entrée pour faciliter la gestion des autorisations des ensembles de fichiers et des autres ressources Data Catalog.
Rôles d'entrée | Description |
---|---|
dataCatalog.entryOwner |
Propriétaire d'une entrée ou d'un groupe d'entrées spécifique.
|
dataCatalog.entryViewer |
Peut consulter les détails de l'entrée et du groupe d'entrées.
|
Rôles de groupe d'entrées | Description |
---|---|
dataCatalog.entryGroupOwner |
Propriétaire d'un groupe d'entrées particulier.
|
dataCatalog.entryGroupCreator |
Peut créer des groupes d'entrées dans un projet. Le créateur d'un groupe d'entrées reçoit automatiquement le rôle dataCatalog.entryGroupOwner .
|
Définir des stratégies IAM
Les utilisateurs disposant de l'autorisation datacatalog.<resource>.setIamPolicy
peuvent définir des stratégies IAM sur des groupes d'entrées Data Catalog et d'autres ressources Data Catalog (consultez la section Rôles Data Catalog).
gcloud
Définissez la stratégie IAM d'un groupe d'entrée avec gcloud data-catalog entry-groups set-iam-policy :
gcloud data-catalog entry-groups set-iam-policy my_entrygroup \ --location=us-central1 \ policy file
Obtenez la stratégie IAM d'un groupe d'entrées avec gcloud data-catalog entry-groups get-iam-policy.
gcloud data-catalog entry-groups get-iam-policy my_entrygroup \ --location=us-central1
Console
Accédez à la page Détails du groupe d'entrées dans l'UI de Data Catalog, puis utilisez le panneau IAM situé à droite pour accorder ou révoquer des autorisations.
Attribuer des rôles de groupe d'entrées
Exemple 1 :
Une entreprise dont les ensembles de fichiers ont des contextes commerciaux différents crée des groupes d'entrées order-files
et user-files
distincts :
L'entreprise attribue aux utilisateurs le rôle Lecteur de groupes d'entrées pour order-files
, ce qui signifie qu'ils ne peuvent rechercher que les entrées contenues dans ce groupe d'entrées. Leurs résultats de recherche ne renvoient pas d'entrées dans le groupe d'entrées user-files
.
Exemple 2 :
Une entreprise attribue le rôle Lecteur de groupes d'entrées à un utilisateur dans le projet project_entry_group
seulement. L'utilisateur ne pourra afficher que les entrées de ce projet.
Effectuer des recherches dans des ensembles de fichiers
Les utilisateurs peuvent restreindre la portée de la recherche dans Data Catalog à l'aide de l'attribut type
. type=entry_group
limite la requête de recherche aux groupes d'entrées tandis que type=fileset
ne recherche que les ensembles de fichiers.
Les attributs type
peuvent être utilisés conjointement avec d'autres attributs, tels que projectid
.
gcloud
Rechercher des groupes d'entrées dans un projet :
gcloud data-catalog search \ --include-project-ids=my-project "projectid=my-project type=entry_group"
Rechercher tous les groupes d'entrées auxquels vous pouvez accéder :
gcloud data-catalog search \ --include-project-ids=my-project "type=entry_group"
Rechercher des ensembles de fichiers dans un projet :
gcloud data-catalog search \ --include-project-ids=my-project "type=entry.fileset"
Rechercher des ensembles de fichiers dans un projet (syntaxe simplifiée) :
gcloud data-catalog search \ --include-project-ids=my-project "type=fileset"