Organiser les composants de code avec des dossiers et des dépôts

Ce document présente les concepts liés au système de dossiers et de dépôts. Il récapitule également les champs et les méthodes de l'API Dataform utilisés pour travailler avec les dossiers et les dépôts.

L'API Dataform fournit des ressources que vous pouvez utiliser pour organiser les composants de code dans une structure hiérarchique semblable à celle d'un système de fichiers d'OS classique. Cette structure permet également l'héritage des stratégies Identity and Access Management (IAM), ce qui permet aux autorisations de se propager dans le chemin d'accès.

La liste suivante définit les termes clés utilisés pour décrire le système de dossiers et de dépôts :

Dossier
Un dossier est le conteneur de base pour organiser les ressources, comme un dossier de système de fichiers standard. Il vous permet d'organiser d'autres dossiers et dépôts, et de déplacer des ressources dans et hors des dossiers. Vous pouvez accorder des autorisations au niveau du nœud de dossier. Ces autorisations sont propagées à l'ensemble du contenu.
Dossier racine de l'utilisateur
Le dossier racine d'un utilisateur représente son espace personnel. Il contient tous les dossiers et dépôts qu'un utilisateur crée ou auxquels il accède. Un dossier racine utilisateur ne fait pas partie de l'arborescence d'un dossier d'équipe. Un dossier racine utilisateur est un concept virtuel qui n'est associé à aucune ressource d'API.
Dossier d'équipe
Un dossier d'équipe est semblable à un dossier, mais il est conçu pour la collaboration en équipe, comme un Drive partagé dans Google Drive. Il fournit un espace dédié aux composants de code principaux et accepte des autorisations de partage et d'accès plus strictes pour les composants principaux d'une équipe.
Fichier
Dans le contexte de cette structure de dossiers, un fichier est représenté par une ressource de dépôt Dataform. Chaque dépôt contient un seul fichier d'asset, tel qu'un notebook, une requête enregistrée, un canevas de données ou une préparation de données.

Rôles requis

Pour obtenir les autorisations nécessaires pour effectuer les tâches décrites dans ce document, demandez à votre administrateur de vous accorder les rôles IAM appropriés sur le projet, le dossier ou la ressource.

Les autorisations accordées sur un dossier sont propagées à tous les dossiers et fichiers qu'il contient.

Les rôles suivants s'appliquent aux dossiers et aux fichiers :

Rôle Accordée le Autorisations et cas d'utilisation
Propriétaire de code (roles/dataform.codeOwner) Dossier ou fichier Accorde un contrôle complet sur une ressource pour la gestion des composants de code. Un utilisateur disposant de ce rôle peut effectuer toutes les actions, y compris supprimer la ressource, définir sa stratégie IAM et la déplacer.
Éditeur de code (roles/dataform.codeEditor) Dossier ou fichier Permet de modifier et de gérer le contenu. Un utilisateur disposant de ce rôle peut ajouter du contenu à des dossiers, modifier des fichiers et obtenir la stratégie IAM pour un dossier ou un fichier. Ce rôle est également requis pour le dossier de destination lorsque vous déplacez une ressource.
Commentateur de code (roles/dataform.codeCommenter) Dossier ou fichier Permet de commenter des composants ou des dossiers de code.
Lecteur de code (roles/dataform.codeViewer) Dossier ou fichier Fournit un accès en lecture seule. Un utilisateur disposant de ce rôle peut interroger le contenu des dossiers et des fichiers.
Créateur de code (roles/dataform.codeCreator) Projet Permet de créer des dossiers et des fichiers dans un projet.

Les rôles suivants sont spécifiques à la gestion des dossiers d'équipe :

Rôle Accordée le Autorisations et cas d'utilisation
Propriétaire de dossier d'équipe (roles/dataform.teamFolderOwner) Dossier d'équipe Accorde un contrôle total sur un dossier d'équipe pour gérer les composants de code. Un utilisateur disposant de ce rôle peut supprimer le dossier d'équipe et définir sa stratégie IAM.
Contributeur de dossier d'équipe (roles/dataform.teamFolderContributor) Dossier d'équipe Permet de gérer le contenu d'un dossier d'équipe. Un utilisateur disposant de ce rôle peut modifier un dossier d'équipe.
Commentateur de dossier d'équipe (roles/dataform.teamFolderCommenter) Dossier d'équipe Permet de commenter un dossier d'équipe et les composants de code qu'il contient.
Lecteur de dossiers d'équipe (roles/dataform.teamFolderViewer) Dossier d'équipe Fournit un accès en lecture seule à un dossier d'équipe et à son contenu. Un utilisateur disposant de ce rôle peut afficher un dossier d'équipe et obtenir sa stratégie IAM.
Créateur de dossier d'équipe (roles/dataform.teamFolderCreator) Projet Permet de créer des dossiers d'équipe dans un projet.

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 effectuer les tâches décrites dans ce document. Pour afficher les autorisations exactes requises, développez la section Autorisations requises :

Autorisations requises

  • Pour créer un dossier :
    • folders.create sur le dossier utilisateur parent, le dossier d'équipe ou le projet
    • folders.addContents sur le dossier parent ou le dossier d'équipe
  • Récupérer les propriétés d'un dossier : folders.get sur le dossier
  • Interroger le contenu d'un dossier ou d'un dossier d'équipe : folders.queryContents sur le dossier
  • Mettre à jour un dossier : folders.update sur le dossier
  • Supprimer un dossier : folders.delete sur le dossier
  • Obtenir la stratégie IAM d'un dossier : folders.getIamPolicy sur le dossier
  • Définissez la stratégie IAM pour un dossier : folders.setIamPolicy sur le dossier.
  • Déplacer un dossier :
    • folders.move sur le dossier à déplacer
    • folders.addContents dans le dossier ou le dossier d'équipe de destination (inutile si vous déplacez l'élément vers un dossier racine)
  • Créer un dossier d'équipe : teamFolders.create sur le projet
  • Supprimer un dossier d'équipe : teamFolders.delete sur le dossier d'équipe
  • Obtenir la stratégie IAM pour un dossier d'équipe : teamFolders.getIamPolicy sur le dossier d'équipe
  • Définissez la stratégie IAM pour un dossier d'équipe : teamFolders.setIamPolicy sur le dossier d'équipe.
  • Récupérer les propriétés d'un dossier d'équipe : teamFolders.get sur le dossier d'équipe
  • Mettre à jour un dossier d'équipe : teamFolders.update sur le dossier d'équipe
  • Créez un dépôt :
    • repositories.create sur le dossier utilisateur parent, le dossier d'équipe ou le projet
    • folders.addContents sur le dossier parent ou le dossier d'équipe
  • Lire un dépôt : repositories.readFile sur le dépôt
  • Écrire dans un dépôt : repositories.commit sur le dépôt
  • Déplacer un dépôt :
    • repositories.move sur le dépôt à déplacer
    • folders.addContents sur le dossier utilisateur parent, le dossier d'équipe ou le projet de destination (non requis si vous déplacez le projet vers un dossier racine)
  • Récupérer les propriétés d'un dépôt : repositories.get sur le dépôt
  • Mettre à jour un dépôt : repositories.update sur le dépôt
  • Supprimer un dépôt : repositories.delete sur le dépôt

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

Pour obtenir un accès complet à la gestion des composants de code dans votre projet, demandez à votre administrateur de vous accorder les rôles IAM suivants sur le projet :

Héritage des stratégies IAM

L'accès IAM aux ressources de dossiers et de dépôts repose sur une structure hiérarchique. Cette hiérarchie garantit que les règles d'accès sont héritées des dossiers parents vers leur contenu.

Lorsqu'une stratégie IAM est définie sur un dossier, les autorisations accordées par cette stratégie s'appliquent également à tous les dépôts et sous-dossiers imbriqués de l'arborescence du dossier. En conséquence :

  • Les autorisations sont héritées via la hiérarchie des dossiers. Lorsqu'un utilisateur se voit attribuer un rôle spécifique sur un dossier de niveau supérieur, il dispose des autorisations incluses dans ce rôle pour toutes les ressources contenues dans ce dossier et ses sous-dossiers.
  • Les autorisations dont dispose un utilisateur sur une ressource sont constituées des règles définies directement sur cette ressource et de toutes les règles héritées de chaque dossier de son chemin d'accès jusqu'à la racine.

Par conséquent, vous n'avez pas besoin d'autorisations au niveau du projet pour effectuer des actions sur des ressources situées en profondeur dans une structure de dossiers. Vous n'avez besoin de l'autorisation appropriée que pour un dossier du chemin d'accès à cette ressource. Par exemple, si vous souhaitez créer un dépôt dans un sous-dossier, vous devez disposer des autorisations nécessaires sur le sous-dossier spécifique ou sur l'un de ses dossiers parents, y compris le dossier de premier niveau.

Voici les bonnes pratiques à suivre pour appliquer des règles IAM aux dossiers et aux dépôts :

  • Appliquez les stratégies IAM au dossier le plus élevé de la hiérarchie où les autorisations sont nécessaires de manière uniforme. Par exemple, si une équipe a besoin d'accéder à toutes les données du répertoire de son équipe, accordez les rôles nécessaires au niveau du dossier de l'équipe plutôt qu'au niveau des sous-dossiers de projet individuels.
  • Accordez toujours le nombre minimal d'autorisations requises pour que les utilisateurs ou les services puissent effectuer leurs tâches. Évitez d'attribuer des rôles généraux lorsque vous pouvez utiliser des rôles et des autorisations plus spécifiques au niveau des dossiers.

Rôles IAM accordés lors de la création de ressources

Les rôles suivants sont attribués automatiquement lors de la création de ressources :

  • Les utilisateurs qui créent des dossiers qui ne se trouvent pas dans une sous-arborescence de dossiers d'équipe reçoivent automatiquement le rôle Administrateur Dataform (roles/dataform.admin) pour ces dossiers.
  • Le créateur d'un dossier d'équipe racine reçoit automatiquement le rôle Administrateur Dataform (roles/dataform.admin) sur ce dossier d'équipe.
  • Lorsque vous définissez setAuthenticatedUserAdmin sur true dans la ressource projects.locations.repositories, les utilisateurs qui créent un dépôt dans le nœud racine de l'utilisateur reçoivent automatiquement le rôle Administrateur Dataform (roles/dataform.admin) sur le dépôt.

Vous pouvez utiliser l'API Config pour accorder un rôle spécifique lors de la création d'une ressource.

Vous ne recevez aucun rôle automatiquement lorsque vous créez des dossiers ou des dépôts dans le sous-arbre d'un dossier d'équipe.

Limites

Les dossiers et les dépôts sont soumis aux limites suivantes :

  • Vous ne pouvez imbriquer des dossiers que sur cinq niveaux.
  • Après avoir déplacé un dépôt dans un dossier, le dépôt et ses ressources enfants ne sont pas visibles dans Cloud Asset Inventory.
  • Un maximum de 100 ressources peuvent participer à une même opération de déplacement.
  • Si vous avez un très grand nombre de dossiers (des centaines de milliers), les performances seront ralenties lorsque vous travaillerez avec des dossiers.

Organisez vos ressources

Les sections suivantes décrivent comment organiser les ressources de dossiers, de dossiers d'équipe et de dépôts avec l'API Dataform.

Ressources de dossier

Le tableau suivant décrit les champs de l'API pour les dossiers :

Champ Description
containing_folder Référence au dossier parent ou nom du dossier d'équipe. Vous pouvez définir l'ID d'un dossier ou d'un dossier d'équipe. Si vous ne définissez pas ce champ, il s'agit d'un dossier racine.
display_name Nom de la ressource visible par l'utilisateur. Le champ display_name doit être unique selon les règles suivantes :
  • Dans la racine utilisateur, le nom à afficher de chaque dossier doit être unique. Toutefois, les noms à afficher des dépôts à la racine de l'utilisateur peuvent être identiques à ceux d'autres dépôts et dossiers.
  • Dans un dossier, les noms à afficher doivent être uniques pour tous les dossiers et dépôts de ce dossier.
  • Dans un dossier d'équipe, les noms à afficher doivent être uniques pour tous les dossiers et dépôts de ce dossier d'équipe.
  • Les noms à afficher des dossiers d'équipe doivent être uniques dans l'ensemble du projet.

Le tableau suivant décrit les principales méthodes d'API projects.locations.folders :

Méthode API Description
create Crée un dossier.
get Obtient les propriétés d'un dossier.
patch Met à jour les propriétés d'un dossier, comme son nom.
queryFolderContents Liste les éléments d'un dossier.
move Déplace le dossier et l'ensemble de son sous-arbre vers un nouveau dossier parent. Une opération de déplacement est atomique, ce qui signifie qu'elle ne réussit que si toutes les ressources de la sous-arborescence du dossier sont correctement déplacées et qu'il n'y a pas d'échecs partiels.
delete Supprime le dossier. N'aboutit que si le dossier est vide.
setIamPolicy Attribue des rôles au dossier. Les rôles accordés sont automatiquement propagés à l'ensemble de la sous-arborescence du dossier.

L'exemple suivant montre comment créer un dossier au niveau racine :

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
      "displayName": "DISPLAY_NAME"
  }' \
  "https://dataform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/folders"

Remplacez les éléments suivants :

  • DISPLAY_NAME : nom visible par l'utilisateur pour la ressource.
  • PROJECT_ID : ID de votre projet Google Cloud .
  • LOCATION : emplacement du dépôt Dataform dans lequel les ressources sont créées.

L'exemple suivant montre comment créer un dossier imbriqué dans un autre dossier :

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
      "displayName": "DISPLAY_NAME",
      "containingFolder": "projects/PROJECT_ID/locations/LOCATION/folders/PARENT_FOLDER_ID"
  }' \
  "https://dataform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/folders"

Remplacez les éléments suivants :

  • DISPLAY_NAME : nom visible par l'utilisateur pour la ressource.
  • PROJECT_ID : ID de votre projet Google Cloud .
  • LOCATION : emplacement du dépôt Dataform dans lequel les ressources sont créées.
  • PARENT_FOLDER_ID : ID du dossier existant dans lequel vous souhaitez créer le nouveau dossier.

L'exemple suivant montre comment déplacer un dossier dans un autre :

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
      "destination_containing_folder": "projects/PROJECT_ID/locations/LOCATION/folders/DESTINATION_PARENT_FOLDER_ID"
  }' \
  "https://dataform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/folders/FOLDER_ID_TO_MOVE:move"

Remplacez les éléments suivants :

  • PROJECT_ID : ID de votre projet Google Cloud .
  • LOCATION : emplacement du dépôt Dataform.
  • DESTINATION_PARENT_FOLDER_ID : ID du dossier vers lequel vous souhaitez déplacer le dossier cible.
  • FOLDER_ID_TO_MOVE : ID du dossier que vous déplacez.

Ressources des dossiers d'équipe

Le tableau suivant décrit les principales méthodes d'API projects.locations.teamFolders :

Méthode API Description
create Crée un dossier d'équipe.
get Obtient les propriétés d'un dossier d'équipe.
patch Met à jour les propriétés d'un dossier d'équipe, comme son nom.
queryContents Liste les éléments d'un dossier d'équipe.
delete Supprime le dossier d'équipe. Cette opération ne fonctionne que si le dossier d'équipe est vide.
setIamPolicy Attribue des rôles au dossier de l'équipe. Les rôles accordés sont automatiquement propagés à l'ensemble de la sous-arborescence du dossier d'équipe.

L'exemple suivant montre comment interroger le contenu d'un dossier d'équipe :

curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://dataform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/teamFolders/TEAM_FOLDER_ID:queryContents"

Remplacez les éléments suivants :

  • PROJECT_ID : ID de votre projet Google Cloud .
  • LOCATION : emplacement des ressources Dataform.
  • TEAM_FOLDER_ID : ID du dossier d'équipe Dataform spécifique que vous interrogez.

Ressources du dépôt

Vous pouvez organiser les ressources de dépôt existantes dans des ressources de dossier et de dossier d'équipe à l'aide du champ containing_folder au niveau du nœud folder.

Le tableau suivant décrit les méthodes d'API pour les dépôts :

Le tableau suivant décrit les principales méthodes d'API projects.locations.repositories :

Méthode API Description
create Crée un dépôt.
get Obtient les propriétés d'un dépôt.
patch Met à jour les propriétés d'un dépôt, comme son nom.
move Déplace le dépôt vers un nouveau dossier conteneur.
delete Supprime le dépôt.
setIamPolicy Attribue des rôles au dépôt. Les rôles accordés sont automatiquement propagés à l'ensemble de la sous-arborescence du dépôt.

L'exemple suivant montre comment créer un dépôt dans le nœud racine de l'utilisateur tout en définissant setAuthenticatedUserAdmin sur true :

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
      "displayName": "REPOSITORY_DISPLAY_NAME",
      "setAuthenticatedUserAdmin": true
  }' \
  "https://dataform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/repositories?repositoryId=REPOSITORY_ID"

Remplacez les éléments suivants :

  • REPOSITORY_DISPLAY_NAME : nom convivial du dépôt.
  • PROJECT_ID : ID de votre projet Google Cloud .
  • LOCATION : emplacement du dépôt.
  • REPOSITORY_ID : ID du nouveau dépôt.

L'exemple suivant montre comment créer un dépôt dans un dossier d'équipe :

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
      "containingFolder": "projects/PROJECT_ID/locations/LOCATION/teamFolders/CONTAINING_TEAM_FOLDER_ID"
  }' \
  "https://dataform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/repositories?repositoryId=REPOSITORY_ID"

Remplacez les éléments suivants :

  • PROJECT_ID : ID de votre projet Google Cloud .
  • LOCATION : emplacement où les ressources sont créées. Il doit s'agir du même emplacement que celui de CONTAINING_TEAM_FOLDER_ID.
  • CONTAINING_TEAM_FOLDER_ID : ID du dossier d'équipe spécifique dans lequel vous souhaitez placer le nouveau dépôt.
  • REPOSITORY_ID : ID du nouveau dépôt.

L'exemple suivant montre comment déplacer un dépôt dans le dossier racine :

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
      "destination_containing_folder": ""
  }' \
  "https://dataform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY_ID:move"

Remplacez les éléments suivants :

  • PROJECT_ID : ID de votre projet Google Cloud .
  • LOCATION : emplacement du dépôt.
  • REPOSITORY_ID : ID du dépôt que vous souhaitez déplacer au niveau racine.

Ressources occupées

Un dossier, un dossier d'équipe ou un dépôt est "occupé" s'il est activement impliqué dans une opération de déplacement, soit en tant qu'objet déplacé, soit en tant que destination du déplacement. Pour garantir l'intégrité des données pendant le transfert, le système empêche les ressources occupées d'effectuer les actions suivantes :

  • Être l'objet d'une autre opération de déplacement.
  • Être la destination d'une autre opération de transfert.
  • Être un ancêtre d'un objet Move.
  • Être l'objet d'une opération de suppression.

Étapes suivantes