Organiza recursos de código con carpetas y repositorios

En este documento, se presenta una descripción general conceptual del sistema de carpetas y repositorios. También se resumen los campos y métodos de la API de Dataform que se usan para trabajar con carpetas y repositorios.

La API de Dataform proporciona recursos que puedes usar para organizar los recursos de código en una estructura jerárquica similar a un sistema de archivos típico del sistema operativo. Esta estructura también permite la herencia de políticas de Identity and Access Management (IAM), lo que permite que los permisos se propaguen por la ruta.

En la siguiente lista, se definen los términos clave que se usan para describir el sistema de carpetas y repositorios:

Carpeta
Una carpeta es el contenedor básico para organizar recursos, similar a una carpeta estándar del sistema de archivos. Te permite organizar otras carpetas y repositorios, y puedes mover recursos dentro y fuera de las carpetas. Puedes otorgar permisos en el nodo de la carpeta, y estos se propagarán a todo el contenido.
Carpeta raíz del usuario
La carpeta raíz del usuario representa el espacio personal del usuario. Contiene todas las carpetas y los repositorios que crea o a los que accede un usuario. La carpeta raíz de un usuario no forma parte del subárbol de una carpeta de equipo. La carpeta raíz del usuario es un concepto virtual que no tiene un recurso de API asociado.
Carpeta de equipo
Una carpeta de equipo es similar a una carpeta, pero está diseñada para la colaboración en equipo, de forma similar a una unidad compartida en Google Drive. Proporciona un espacio dedicado para los recursos de código principales y admite permisos de acceso y uso compartido más estrictos para los recursos principales de un equipo.
Archivo
En el contexto de esta estructura de carpetas, un archivo se representa con un recurso del repositorio de Dataform. Cada repositorio contiene un solo activo de archivo, como un notebook, una consulta guardada, un lienzo de datos o una preparación de datos.

Roles obligatorios

Para obtener los permisos que necesitas para completar las tareas de este documento, pídele a tu administrador que te otorgue los roles de IAM adecuados en el proyecto, la carpeta o el recurso.

Los permisos otorgados en una carpeta se propagan a todas las carpetas y los archivos que contiene.

Las siguientes funciones se aplican a carpetas y archivos:

Rol Se otorgó el Permisos y casos de uso
Propietario del código (roles/dataform.codeOwner) Carpeta o archivo Otorga control total sobre un recurso para administrar activos de código. Un usuario con este rol puede realizar todas las acciones, como borrar el recurso, establecer su política de IAM y moverlo.
Editor de código (roles/dataform.codeEditor) Carpeta o archivo Permite editar y administrar contenido. Un usuario con este rol puede agregar contenido a las carpetas, editar archivos y obtener la política de IAM de una carpeta o un archivo. Este rol también es obligatorio en la carpeta de destino cuando se mueve un recurso.
Comentarista de código (roles/dataform.codeCommenter) Carpeta o archivo Permite comentar recursos o carpetas de código.
Visualizador de código (roles/dataform.codeViewer) Carpeta o archivo Proporciona acceso de solo lectura. Un usuario con este rol puede consultar el contenido de carpetas y archivos.
Creador de código (roles/dataform.codeCreator) Proyecto Otorga permiso para crear carpetas y archivos nuevos dentro de un proyecto.

Los siguientes roles son específicos para administrar carpetas de equipo:

Rol Se otorgó el Permisos y casos de uso
Propietario de la carpeta de equipo (roles/dataform.teamFolderOwner) Carpeta de equipo Otorga control total sobre una carpeta del equipo para administrar activos de código. Un usuario con este rol puede borrar la carpeta del equipo y establecer su política de IAM.
Colaborador de carpetas de equipo (roles/dataform.teamFolderContributor) Carpeta de equipo Permite administrar el contenido dentro de una carpeta de equipo. Un usuario con este rol puede actualizar una carpeta de equipo.
Comentarista de carpetas de equipo (roles/dataform.teamFolderCommenter) Carpeta de equipo Permite comentar una carpeta de equipo y los recursos de código que contiene.
Visualizador de carpetas de equipo (roles/dataform.teamFolderViewer) Carpeta de equipo Proporciona acceso de solo lectura a una carpeta de equipo y su contenido. Un usuario con este rol puede ver una carpeta de equipo y obtener su política de IAM.
Creador de carpetas de equipo (roles/dataform.teamFolderCreator) Proyecto Otorga permiso para crear carpetas de equipo nuevas dentro de un proyecto.

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

Estos roles predefinidos contienen los permisos necesarios para completar las tareas de este documento. Para ver los permisos exactos que son necesarios, expande la sección Permisos requeridos:

Permisos necesarios

  • Crea una carpeta:
    • folders.create en la carpeta del usuario principal, la carpeta del equipo o el proyecto
    • folders.addContents en la carpeta superior o la carpeta del equipo
  • Recupera las propiedades de una carpeta: folders.get en la carpeta
  • Consultar el contenido de una carpeta o una carpeta de equipo: folders.queryContents en la carpeta
  • Actualiza una carpeta: folders.update en la carpeta
  • Borra una carpeta: folders.delete en la carpeta
  • Obtén la política de IAM para una carpeta: folders.getIamPolicy en la carpeta
  • Establece la política de IAM para una carpeta: folders.setIamPolicy en la carpeta
  • Sigue estos pasos para mover una carpeta:
    • folders.move en la carpeta que se está moviendo
    • folders.addContents en la carpeta de destino o en la carpeta del equipo (no es necesario si se mueve a una carpeta raíz)
  • Crea una carpeta de equipo: teamFolders.create en el proyecto.
  • Borra una carpeta del equipo: teamFolders.delete en la carpeta del equipo
  • Obtén la política de IAM para una carpeta de equipo: teamFolders.getIamPolicy en la carpeta de equipo
  • Establece la política de IAM para una carpeta de equipo: teamFolders.setIamPolicy en la carpeta de equipo
  • Recupera las propiedades de una carpeta de equipo: teamFolders.get en la carpeta de equipo
  • Actualiza una carpeta de equipo: teamFolders.update en la carpeta de equipo
  • Crea un repositorio:
    • repositories.create en la carpeta del usuario principal, la carpeta del equipo o el proyecto
    • folders.addContents en la carpeta superior o la carpeta del equipo
  • Leer un repositorio: repositories.readFile en el repositorio
  • Escribe en un repositorio: repositories.commit en el repositorio
  • Cómo mover un repositorio:
    • repositories.move en el repositorio que se mueve
    • folders.addContents en la carpeta principal del usuario, la carpeta del equipo o el proyecto de destino (no es necesario si se mueve a una carpeta raíz)
  • Recupera las propiedades de un repositorio: repositories.get en el repositorio
  • Actualiza un repositorio: repositories.update en el repositorio
  • Borra un repositorio: repositories.delete en el repositorio

También puedes obtener estos permisos con roles personalizados o con otros roles predefinidos.

Para obtener acceso completo a la administración de los recursos de código en tu proyecto, pídele a tu administrador que te otorgue los siguientes roles de IAM en el proyecto:

Herencia de políticas de IAM

El acceso de IAM para los recursos de carpetas y repositorios aprovecha una estructura jerárquica. Esta jerarquía garantiza que las políticas de acceso se hereden de las carpetas principales a su contenido.

Cuando se establece una política de IAM en una carpeta, los permisos que otorga esa política también se aplican a todos los repositorios y subcarpetas anidadas en el subárbol de la carpeta. Esto tiene las siguientes consecuencias:

  • Los permisos se heredan a través de la jerarquía de carpetas. Cuando a un usuario se le otorga un rol específico en una carpeta de nivel superior, posee los permisos incluidos en ese rol para todos los recursos contenidos en esa carpeta y sus subcarpetas.
  • Los permisos que tiene un usuario en un recurso consisten en las políticas establecidas directamente en ese recurso y todas las políticas heredadas de cada carpeta en su ruta de acceso hasta la raíz.

Como resultado, no necesitas permisos a nivel del proyecto para realizar acciones en recursos ubicados en lo profundo de una estructura de carpetas. Solo necesitas el permiso adecuado en cualquier carpeta de la ruta de acceso a ese recurso. Por ejemplo, si deseas crear un repositorio en una subcarpeta, necesitas los permisos necesarios en la subcarpeta específica o en cualquiera de sus carpetas superiores, incluida la carpeta de nivel superior.

A continuación, se indican las prácticas recomendadas para aplicar políticas de IAM a carpetas y repositorios:

  • Aplica políticas de IAM a la carpeta más alta de la jerarquía en la que se necesiten los permisos de manera uniforme. Por ejemplo, si un equipo necesita acceso a todos los datos del directorio de su equipo, otorga los roles necesarios a nivel de la carpeta del equipo en lugar de a nivel de las subcarpetas de proyectos individuales.
  • Siempre otorga el conjunto mínimo de permisos necesarios para que los usuarios o servicios realicen sus tareas. Evita otorgar roles amplios cuando puedas usar roles y permisos más específicos a nivel de la carpeta.

Roles de IAM otorgados en la creación de recursos

Las siguientes funciones se otorgan automáticamente cuando se crea el recurso:

Puedes usar la API de Config para otorgar un rol específico cuando se crea un recurso.

No recibes automáticamente ningún rol cuando creas carpetas o repositorios nuevos dentro del subárbol de una carpeta de equipo.

Limitaciones

Las carpetas y los repositorios tienen las siguientes limitaciones:

  • Solo puedes anidar carpetas hasta 5 niveles de profundidad.
  • Después de mover un repositorio a una carpeta, el repositorio y sus recursos secundarios no se ven en Cloud Asset Inventory.
  • En una sola operación de movimiento, pueden participar hasta 100 recursos.
  • Tener una gran cantidad de carpetas (cientos de miles) ralentiza el rendimiento cuando se trabaja con ellas.

Organiza los recursos

En las siguientes secciones, se describe cómo puedes organizar los recursos de carpetas, carpetas de equipo y repositorios con la API de Dataform.

Recursos de carpeta

En la siguiente tabla, se describen los campos de la API para las carpetas:

Campo Descripción
containing_folder Es una referencia a la carpeta superior o al nombre de la carpeta del equipo. Puedes establecerlo como un ID de carpeta o un ID de carpeta de equipo. Si no configuras este campo, se trata de una carpeta raíz.
display_name Es el nombre visible para el usuario del recurso. El campo display_name debe ser único según las siguientes reglas:
  • Dentro de la raíz del usuario, todas las carpetas deben tener nombres visibles únicos. Sin embargo, los nombres visibles de los repositorios en la raíz del usuario pueden coincidir con otros nombres de repositorios y carpetas.
  • Dentro de una carpeta, los nombres visibles deben ser únicos en todas las carpetas y repositorios de esa carpeta.
  • Dentro de una carpeta del equipo, los nombres visibles deben ser únicos en todas las carpetas y repositorios de esa carpeta del equipo.
  • Los nombres visibles de las carpetas del equipo deben ser únicos en todo el proyecto.

En la siguiente tabla, se describen los principales métodos de la API de projects.locations.folders:

Método de la API Descripción
create Crea una carpeta nueva.
get Obtiene las propiedades de una carpeta.
patch Actualiza las propiedades de una carpeta, como su nombre.
queryFolderContents Enumera los elementos de una carpeta.
move Mueve la carpeta y todo su subárbol a una nueva carpeta contenedora. Una operación de movimiento es atómica, lo que significa que solo se realiza correctamente si todos los recursos del subárbol de la carpeta se mueven correctamente y no hay fallas parciales.
delete Borra la carpeta. Solo se realiza correctamente si la carpeta está vacía.
setIamPolicy Otorga roles a la carpeta. Los roles otorgados se propagan automáticamente a todo el subárbol de la carpeta.

En el siguiente ejemplo, se muestra cómo crear una carpeta de nivel raíz:

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"

Reemplaza lo siguiente:

  • DISPLAY_NAME: Es el nombre del recurso visible para el usuario.
  • PROJECT_ID: Es el ID del proyecto de Google Cloud .
  • LOCATION: Es la ubicación del repositorio de Dataform en el que se crean los recursos.

En el siguiente ejemplo, se muestra cómo crear una carpeta anidada dentro de otra carpeta:

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"

Reemplaza lo siguiente:

  • DISPLAY_NAME: Es el nombre del recurso visible para el usuario.
  • PROJECT_ID: Es el ID del proyecto de Google Cloud .
  • LOCATION: Es la ubicación del repositorio de Dataform en el que se crean los recursos.
  • PARENT_FOLDER_ID: Es el ID de la carpeta existente en la que deseas crear la carpeta nueva.

En el siguiente ejemplo, se muestra cómo mover una carpeta a otra:

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"

Reemplaza lo siguiente:

  • PROJECT_ID: Es el ID del proyecto de Google Cloud .
  • LOCATION: Es la ubicación del repositorio de Dataform.
  • DESTINATION_PARENT_FOLDER_ID: Es el ID de la carpeta a la que deseas mover la carpeta de destino.
  • FOLDER_ID_TO_MOVE: Es el ID de la carpeta que estás moviendo.

Recursos de carpetas de equipo

En la siguiente tabla, se describen los principales métodos de la API de projects.locations.teamFolders:

Método de la API Descripción
create Crea una carpeta de equipo nueva.
get Obtiene las propiedades de una carpeta de equipo.
patch Actualiza las propiedades de una carpeta de equipo, como su nombre.
queryContents Enumera los elementos de una carpeta de equipo.
delete Borra la carpeta del equipo. Solo se completa correctamente si la carpeta del equipo está vacía.
setIamPolicy Otorga roles a la carpeta del equipo. Los roles otorgados se propagan automáticamente a todo el subárbol de la carpeta del equipo.

En el siguiente ejemplo, se muestra cómo consultar el contenido de una carpeta de equipo:

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"

Reemplaza lo siguiente:

  • PROJECT_ID: Es el ID del proyecto de Google Cloud .
  • LOCATION: Es la ubicación de los recursos de Dataform.
  • TEAM_FOLDER_ID: Es el ID de la carpeta específica del equipo de Dataform que consultas.

Recursos del repositorio

Puedes organizar los recursos existentes del repositorio en recursos de carpetas y carpetas de equipo con el campo containing_folder en el nodo de la carpeta.

En la siguiente tabla, se describen los métodos de la API para los repositorios:

En la siguiente tabla, se describen los principales métodos de la API de projects.locations.repositories:

Método de la API Descripción
create Crea un repositorio nuevo.
get Obtiene las propiedades de un repositorio.
patch Actualiza las propiedades de un repositorio, como su nombre.
move Mueve el repositorio a una nueva carpeta contenedora.
delete Borra el repositorio.
setIamPolicy Otorga roles al repositorio. Los roles otorgados se propagan automáticamente a todo el subárbol del repositorio.

En el siguiente ejemplo, se muestra cómo crear un repositorio en el nodo raíz del usuario y, al mismo tiempo, establecer setAuthenticatedUserAdmin en 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"

Reemplaza lo siguiente:

  • REPOSITORY_DISPLAY_NAME: Es un nombre descriptivo para el repositorio.
  • PROJECT_ID: Es el ID del proyecto de Google Cloud .
  • LOCATION: Es la ubicación del repositorio.
  • REPOSITORY_ID: Es el ID del repositorio nuevo.

En el siguiente ejemplo, se muestra cómo crear un repositorio dentro de una carpeta de equipo:

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"

Reemplaza lo siguiente:

  • PROJECT_ID: Es el ID del proyecto de Google Cloud .
  • LOCATION: Es la ubicación en la que se crean los recursos. Debe ser la misma ubicación que la de CONTAINING_TEAM_FOLDER_ID.
  • CONTAINING_TEAM_FOLDER_ID: Es el ID de la carpeta de equipo específica en la que deseas colocar el repositorio nuevo.
  • REPOSITORY_ID: Es el ID del repositorio nuevo.

En el siguiente ejemplo, se muestra cómo mover un repositorio a la carpeta raíz:

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"

Reemplaza lo siguiente:

  • PROJECT_ID: Es el ID del proyecto de Google Cloud .
  • LOCATION: Es la ubicación en la que existe el repositorio.
  • REPOSITORY_ID: Es el ID del repositorio que deseas mover al nivel raíz.

Recursos ocupados

Una carpeta, una carpeta de equipo o un repositorio están "ocupados" si participan activamente en una operación de movimiento, ya sea como el objeto que se mueve o el destino del movimiento. Para garantizar la integridad de los datos durante la transferencia, el sistema restringe los recursos ocupados de las siguientes acciones:

  • El objeto es el destino de otra operación de movimiento.
  • Ser el destino de otra operación de movimiento
  • Ser un ancestro de un objeto de movimiento
  • Ser el objeto de una operación de eliminación

¿Qué sigue?