使用文件夹和代码库整理代码资产

本文档从概念上简要介绍了文件夹和代码库系统。本文还总结了用于处理文件夹和代码库的 Dataform API 字段和方法。

Dataform API 提供的资源可用于以类似于典型操作系统文件系统的层次结构来整理代码资产。此结构还支持 Identity and Access Management (IAM) 政策继承，从而允许权限沿路径向下传播。

以下列表定义了用于描述文件夹和代码库系统的关键术语：

文件夹: 文件夹是用于整理资源的基本容器，类似于标准文件系统文件夹。借助它，您可以整理其他文件夹和代码库，还可以将资源移入和移出文件夹。您可以在文件夹节点授予权限，这些权限会传播到所有内容。
用户根文件夹: 用户根文件夹表示用户的个人空间。它包含用户创建或访问的所有文件夹和代码库。用户根文件夹不属于团队文件夹的子树。用户根文件夹是一个虚拟概念，没有关联的 API 资源。
团队文件夹: 团队文件夹类似于普通文件夹，但专为团队协作而设计，类似于 Google 云端硬盘中的共享云端硬盘。它为核心代码资产提供专用空间，并支持为团队的核心资产设置更严格的共享和访问权限。
文件: 在此文件夹结构中，文件由 Dataform 代码库资源表示。每个代码库都包含单个文件资源，例如笔记本、保存的查询、数据画布或数据准备。

所需的角色

如需获得完成本文档中的任务所需的权限，请让您的管理员为您授予项目、文件夹或资源的相应 IAM 角色。

在文件夹上授予的权限会传播到其中包含的所有文件夹和文件。

以下角色适用于文件夹和文件：

角色	针对哪个（些）对象授予	权限和使用场景
Code Owner (`roles/dataform.codeOwner`)	文件夹或文件	授予对用于管理代码资产的资源的完全控制权。具有此角色的用户可以执行所有操作，包括删除资源、设置其 IAM 政策和移动资源。
Code Editor (`roles/dataform.codeEditor`)	文件夹或文件	允许编辑和管理内容。拥有此角色的用户可以向文件夹添加内容、修改文件，以及获取文件夹或文件的 IAM 政策。移动资源时，目标文件夹也需要此角色。
Code Commenter (`roles/dataform.codeCommenter`)	文件夹或文件	允许对代码资产或文件夹进行评论。
Code Viewer (`roles/dataform.codeViewer`)	文件夹或文件	提供只读权限。具有此角色的用户可以查询文件夹和文件的内容。
Code Creator (`roles/dataform.codeCreator`)	项目	授予在项目中创建新文件夹和文件的权限。

以下角色专门用于管理团队文件夹：

角色	针对哪个（些）对象授予	权限和使用场景
Team Folder Owner (`roles/dataform.teamFolderOwner`)	团队文件夹	授予对团队文件夹的完全控制权，以便管理代码资产。拥有此角色的用户可以删除团队文件夹并设置其 IAM 政策。
Team Folder Contributor (`roles/dataform.teamFolderContributor`)	团队文件夹	允许在团队文件夹中进行内容管理。具有此角色的用户可以更新团队文件夹。
Team Folder Commenter (`roles/dataform.teamFolderCommenter`)	团队文件夹	允许对团队文件夹及其包含的代码资产进行评论。
Team Folder Viewer (`roles/dataform.teamFolderViewer`)	团队文件夹	拥有对团队文件夹及其内容的只读权限。拥有此角色的用户可以查看团队文件夹并获取其 IAM 政策。
Team Folder Creator (`roles/dataform.teamFolderCreator`)	项目	授予在项目中创建新团队文件夹的权限。

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

这些预定义角色包含完成本文档中的任务所需的权限。如需查看所需的确切权限，请展开所需权限部分：

所需权限

创建文件夹：
- 针对父级用户文件夹、团队文件夹或项目的 folders.create 权限
- 父文件夹或团队文件夹的 folders.addContents 权限
检索文件夹的属性：文件夹上的 folders.get
查询文件夹或团队文件夹的内容：folders.queryContents 文件夹
更新文件夹：针对文件夹的 folders.update 权限
删除文件夹：点按文件夹上的 folders.delete
获取文件夹的 IAM 政策：针对文件夹的 folders.getIamPolicy 权限
为文件夹设置 IAM 政策：folders.setIamPolicy 在文件夹上
移动文件夹：
- folders.move 权限
- 目标文件夹或团队文件夹的 folders.addContents 权限（如果移动到根文件夹，则不需要此权限）
创建团队文件夹：项目的 teamFolders.create 权限
删除团队文件夹：点击团队文件夹上的 teamFolders.delete
获取团队文件夹的 IAM 政策：团队文件夹的 teamFolders.getIamPolicy 权限
为团队文件夹设置 IAM 政策：teamFolders.setIamPolicy 在团队文件夹上
检索团队文件夹的属性：点击团队文件夹中的 teamFolders.get
更新团队文件夹：点击团队文件夹上的 teamFolders.update
创建代码库：
- 针对父级用户文件夹、团队文件夹或项目的 repositories.create 权限
- 父文件夹或团队文件夹的 folders.addContents 权限
读取代码库：代码库中的 repositories.readFile
写入代码库：repositories.commit 在代码库中
移动代码库：
- 要移动的代码库的 repositories.move
- 目标父级用户文件夹、团队文件夹或项目的 folders.addContents 权限（如果移动到根文件夹，则不需要此权限）
检索代码库的属性：代码库中的 repositories.get
更新代码库：repositories.update 代码库
删除代码库：点击代码库上的 repositories.delete

您也可以使用自定义角色或其他预定义角色来获取这些权限。

如需获得管理项目中的代码资产的完整访问权限，请让您的管理员为您授予项目的以下 IAM 角色：

Dataform Admin (roles/dataform.admin)
Dataform Editor (roles/dataform.editor)
Dataform Viewer (roles/dataform.viewer)

IAM 政策继承

文件夹和代码库资源的 IAM 访问权限采用分层结构。此层次结构可确保访问权限政策从父文件夹继承到其内容。

当对文件夹设置 IAM 政策时，该政策授予的权限也会应用于该文件夹子树中的所有代码库和嵌套子文件夹。这会导致以下结果：

权限通过文件夹层次结构继承。如果用户被授予高级别文件夹的特定角色，则他们对该文件夹及其子文件夹中包含的所有资源都拥有该角色所含的权限。
用户对资源拥有的权限包括直接针对该资源设置的政策，以及从其路径中的每个文件夹（直至根文件夹）继承的所有政策。

因此，您无需项目级权限即可对位于文件夹结构深处的资源执行操作。您只需对该资源路径中的任何文件夹拥有适当的权限。例如，如果您想在子文件夹中创建代码库，则需要对该特定子文件夹或其任何父文件夹（包括顶级文件夹）拥有必要的权限。

以下是将 IAM 政策应用于文件夹和代码库的最佳实践：

将 IAM 政策应用于层次结构中需要统一权限的最高文件夹。例如，如果某个团队需要访问其团队目录中的所有数据，请在团队文件夹级层授予必要的角色，而不是在各个项目子文件夹级层授予。
请始终授予用户或服务执行其任务所需的最低权限集。避免授予广泛的角色，而应尽可能使用更具体的文件夹级角色和权限。

在创建资源时授予的 IAM 角色

在创建资源时，系统会自动授予以下角色：

创建的文件夹不在团队文件夹子树中的用户会自动获得这些文件夹的 Dataform Admin 角色 (roles/dataform.admin)。
根团队文件夹的创建者会自动获得该团队文件夹的 Dataform Admin 角色 (roles/dataform.admin)。
如果您在 projects.locations.repositories 资源中将 setAuthenticatedUserAdmin 设置为 true，则在用户根节点中创建代码库的用户会自动获得该代码库的 Dataform Admin 角色 (roles/dataform.admin)。

您可以使用 Config API 在创建资源时授予特定角色。

在团队文件夹的子树内创建新文件夹或代码库时，您不会自动获得任何角色。

限制

文件夹和代码库存在以下限制：

文件夹最多只能嵌套 5 层。
将代码库移入文件夹后，该代码库及其子资源不会显示在 Cloud Asset Inventory 中。
一次移动操作最多可包含 100 个资源。
如果文件夹数量非常多（数十万个），则在处理文件夹时性能会下降。

整理资源

以下部分介绍了如何使用 Dataform API 整理文件夹、团队文件夹和代码库资源。

文件夹资源

下表介绍了文件夹的 API 字段：

字段说明

containing_folder 对父文件夹或团队文件夹名称的引用。您可以将此属性设置为文件夹 ID 或团队文件夹 ID。如果您未设置此字段，则表示这是根文件夹。

字段	说明
`containing_folder`	对父文件夹或团队文件夹名称的引用。您可以将此属性设置为文件夹 ID 或团队文件夹 ID。如果您未设置此字段，则表示这是根文件夹。
`display_name`	资源的用户可见名称。`display_name` 字段必须是唯一的，并符合以下规则：在用户根目录下，所有文件夹都必须具有唯一的显示名称。不过，用户根目录中的代码库显示名称可以与其他代码库和文件夹名称冲突。在某个文件夹中，显示名称在相应文件夹中的所有文件夹和代码库中都必须是唯一的。在团队文件夹中，显示名称在相应团队文件夹中的所有文件夹和代码库中必须是唯一的。团队文件夹显示名在整个项目中必须是唯一的。

display_name

资源的用户可见名称。display_name 字段必须是唯一的，并符合以下规则：

在用户根目录下，所有文件夹都必须具有唯一的显示名称。不过，用户根目录中的代码库显示名称可以与其他代码库和文件夹名称冲突。
在某个文件夹中，显示名称在相应文件夹中的所有文件夹和代码库中都必须是唯一的。
在团队文件夹中，显示名称在相应团队文件夹中的所有文件夹和代码库中必须是唯一的。
团队文件夹显示名在整个项目中必须是唯一的。

下表介绍了主要的 projects.locations.folders API 方法：

API 方法	说明
`create`	创建新文件夹。
`get`	获取文件夹的属性。
`patch`	更新文件夹的属性，例如其名称。
`queryFolderContents`	列出文件夹中的项目。
`move`	将文件夹及其整个子树移至新的包含文件夹。移动操作是原子操作，也就是说，只有当文件夹子树中的所有资源都已正确移动且没有出现部分失败时，移动操作才会成功。
`delete`	删除文件夹。仅当文件夹为空时才会成功。
`setIamPolicy`	向文件夹授予角色。授予的角色会自动传播到文件夹的整个子树。

以下示例演示了如何创建根级文件夹：

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"

替换以下内容：

DISPLAY_NAME：资源的用户可见名称。
PROJECT_ID：您的 Google Cloud 项目 ID。
LOCATION：创建资源的数据源所在 Dataform 代码库的位置。

以下示例演示了如何创建嵌套在另一个文件夹中的文件夹：

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"

替换以下内容：

DISPLAY_NAME：资源的用户可见名称。
PROJECT_ID：您的 Google Cloud 项目 ID。
LOCATION：创建资源的数据源所在 Dataform 代码库的位置。
PARENT_FOLDER_ID：您要在其中创建新文件夹的现有文件夹的 ID。

以下示例演示了如何将文件夹移至另一个文件夹：

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"

替换以下内容：

PROJECT_ID：您的 Google Cloud 项目 ID。
LOCATION：Dataform 代码库的位置。
DESTINATION_PARENT_FOLDER_ID：您要将目标文件夹移动到的文件夹的 ID。
FOLDER_ID_TO_MOVE：您要移动的文件夹的 ID。

团队文件夹资源

下表介绍了主要的 projects.locations.teamFolders API 方法：

API 方法	说明
`create`	创建新的团队文件夹。
`get`	获取团队文件夹的属性。
`patch`	更新团队文件夹的属性，例如其名称。
`queryContents`	列出团队文件夹中的项目。
`delete`	删除团队文件夹。仅当团队文件夹为空时，此操作才会成功。
`setIamPolicy`	向团队文件夹授予角色。授予的角色会自动传播到团队文件夹的整个子树。

以下示例演示了如何查询团队文件夹的内容：

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"

替换以下内容：

PROJECT_ID：您的 Google Cloud 项目 ID。
LOCATION：Dataform 资源所在的位置。
TEAM_FOLDER_ID：您要查询的特定 Dataform 团队文件夹的 ID。

代码库资源

您可以使用文件夹节点中的 containing_folder 字段，在文件夹和团队文件夹资源中整理现有代码库资源。

下表介绍了适用于代码库的 API 方法：

下表介绍了主要的 projects.locations.repositories API 方法：

API 方法	说明
`create`	创建新代码库。
`get`	获取代码库的属性。
`patch`	更新代码库的属性，例如其名称。
`move`	将仓库移至新的包含文件夹。
`delete`	删除代码库。
`setIamPolicy`	向代码库授予角色。授予的角色会自动传播到存储区的整个子树。

以下示例演示了如何在用户根节点中创建代码库，同时将 setAuthenticatedUserAdmin 设置为 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"

替换以下内容：

REPOSITORY_DISPLAY_NAME：代码库的简单易记的名称。
PROJECT_ID：您的 Google Cloud 项目 ID。
LOCATION：相应仓库的位置。
REPOSITORY_ID：新代码库的 ID。

以下示例演示了如何在团队文件夹中创建代码库：

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"

替换以下内容：

PROJECT_ID：您的 Google Cloud 项目 ID。
LOCATION：创建资源的位置。此位置必须与 CONTAINING_TEAM_FOLDER_ID 的位置相同。
CONTAINING_TEAM_FOLDER_ID：您要放置新代码库的特定团队文件夹的 ID。
REPOSITORY_ID：新代码库的 ID。

以下示例演示了如何将代码库移至根文件夹：

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"

替换以下内容：

PROJECT_ID：您的 Google Cloud 项目 ID。
LOCATION：代码库所在的位置。
REPOSITORY_ID：您要移至根级别的代码库的 ID。

繁忙资源

如果文件夹、团队文件夹或代码库正积极参与移动操作（无论是作为要移动的对象还是移动的目标位置），则表示该文件夹、团队文件夹或代码库处于“忙碌”状态。系统会限制繁忙资源执行以下操作，以确保迁移期间的数据完整性：

成为另一项移动操作的对象。
成为另一项移动操作的目标。
是移动对象的祖先。
成为删除操作的对象。

后续步骤

如需了解如何在 BigQuery 中整理代码资产，请参阅使用文件夹整理代码资产和创建和管理文件夹。
如需详细了解如何管理 Dataform 资源的权限，请参阅使用 IAM 控制访问权限。
如需查看 Dataform API 方法的完整详细信息，请参阅 Dataform API。

使用文件夹和代码库整理代码资产 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

所需的角色

所需权限

IAM 政策继承

在创建资源时授予的 IAM 角色

限制

整理资源

文件夹资源

团队文件夹资源

代码库资源

繁忙资源

后续步骤

使用文件夹和代码库整理代码资产