使用資料夾和存放區整理程式碼資產

本文將從概念上概略介紹資料夾和存放區系統。本文也會摘要說明用於處理資料夾和存放區的 Dataform API 欄位和方法。

Dataform API 提供的資源可讓您以階層式結構整理程式碼資產，類似於一般作業系統的檔案系統。這個結構也支援 Identity and Access Management (IAM) 政策的沿用，可讓權限沿著路徑向下傳播。

以下清單定義了用於說明資料夾和存放區系統的重要字詞：

資料夾: 資料夾是整理資源的基本容器，類似於標準檔案系統資料夾。您可以在其中整理其他資料夾和存放區，並將資源移入及移出資料夾。您可以在資料夾節點授予權限，這些權限會傳播至所有內容。
使用者根資料夾: 使用者根資料夾代表使用者的個人空間。其中包含使用者建立或存取的所有資料夾和存放區。使用者根資料夾不屬於團隊資料夾的子樹狀結構。使用者根資料夾是虛擬概念，沒有相關聯的 API 資源。
團隊資料夾: 團隊資料夾與一般資料夾類似，但專為團隊協作而設計，類似於 Google 雲端硬碟中的共用雲端硬碟。可為核心程式碼資產提供專屬空間，並支援為團隊核心資產設定更嚴格的共用和存取權限。
檔案: 在這個資料夾結構中，檔案是由 Dataform 存放區資源表示。每個存放區都包含單一檔案資產，例如筆記本、已儲存的查詢、資料畫布或資料準備。

必要的角色

如要取得完成本文中工作所需的權限，請要求管理員在專案、資料夾或資源中授予您適當的 IAM 角色。

在資料夾授予的權限會傳播至其中的所有資料夾和檔案。

下列角色適用於資料夾和檔案：

角色	授權日期	權限和應用實例
程式碼擁有者 (`roles/dataform.codeOwner`)	資料夾或檔案	可授予資源的完整控制權，用於管理程式碼資產。具備這個角色的使用者可以執行所有動作，包括刪除資源、設定 IAM 政策及移動資源。
程式碼編輯器 (`roles/dataform.codeEditor`)	資料夾或檔案	可編輯及管理內容。具備這個角色的使用者可以將內容新增至資料夾、編輯檔案，以及取得資料夾或檔案的 IAM 政策。移動資源時，目的地資料夾也必須具備這個角色。
程式碼註解者 (`roles/dataform.codeCommenter`)	資料夾或檔案	可對程式碼資產或資料夾加上註解。
程式碼檢視者 (`roles/dataform.codeViewer`)	資料夾或檔案	提供唯讀存取權。具備這個角色的使用者可以查詢資料夾和檔案的內容。
程式碼建立者 (`roles/dataform.codeCreator`)	專案	授予在專案中建立新資料夾和檔案的權限。

下列角色專門用於管理團隊資料夾：

角色	授權日期	權限和應用實例
團隊資料夾擁有者 (`roles/dataform.teamFolderOwner`)	團隊資料夾	授予團隊資料夾的完整控制權，以便管理程式碼資產。具備這個角色的使用者可以刪除團隊資料夾，並設定其 IAM 政策。
團隊資料夾協作者 (`roles/dataform.teamFolderContributor`)	團隊資料夾	可管理團隊資料夾中的內容。具備這個角色的使用者可以更新團隊資料夾。
團隊資料夾加註者 (`roles/dataform.teamFolderCommenter`)	團隊資料夾	可對團隊資料夾和當中程式碼資產加上註解。
團隊資料夾檢視者 (`roles/dataform.teamFolderViewer`)	團隊資料夾	具備團隊資料夾及其內容的唯讀存取權，具備這個角色的使用者可以查看團隊資料夾並取得其 IAM 政策。
團隊資料夾建立者 (`roles/dataform.teamFolderCreator`)	專案	授予在專案中建立新團隊資料夾的權限。

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和機構的存取權」。

這些預先定義的角色具備完成本文工作所需的權限。如要查看確切的必要權限，請展開「Required permissions」(必要權限) 部分：

所需權限

建立資料夾：
- 父項使用者資料夾、團隊資料夾或專案上的 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 管理員 (roles/dataform.admin)
Dataform 編輯者 (roles/dataform.editor)
Dataform Viewer (roles/dataform.viewer)

IAM 政策沿用

資料夾和存放區資源的身分與存取權管理存取權採用階層式結構。這個階層可確保存取政策會從上層資料夾沿用至內容。

在資料夾上設定 IAM 政策後，該政策授予的權限也會套用至資料夾子樹狀結構中的所有存放區和巢狀子資料夾。這會產生下列結果：

權限是透過資料夾階層繼承，如果使用者在頂層資料夾中獲派特定角色，就能以該角色存取資料夾及其子資料夾中的所有資源。
使用者在資源上擁有的權限，包括直接在該資源上設定的政策，以及從路徑中每個資料夾沿用的所有政策 (直到根目錄為止)。

因此，您不需要專案層級的權限，就能對位於資料夾結構深處的資源執行動作。您只需要路徑中任何資料夾的適當權限，即可存取該資源。舉例來說，如要在子資料夾中建立存放區，您必須擁有特定子資料夾或任何上層資料夾的必要權限，包括頂層資料夾。

以下是在資料夾和存放區套用 IAM 政策的最佳做法：

在階層中最高的資料夾套用 IAM 政策，統一設定權限。舉例來說，如果團隊需要存取團隊目錄中的所有資料，請在團隊資料夾層級授予必要角色，而不是在個別專案子資料夾層級授予。
請務必只授予使用者或服務執行工作所需的最低權限。盡量避免授予廣泛的角色，改用更具體的資料夾層級角色和權限。

在資源建立時授予的 IAM 角色

建立資源時，系統會自動授予下列角色：

如果使用者建立的資料夾不在團隊資料夾子樹狀結構中，系統會自動將這些資料夾的Dataform 管理員角色 (roles/dataform.admin) 指派給使用者。
根團隊資料夾的建立者會自動取得該團隊資料夾的 Dataform 管理員角色 (roles/dataform.admin)。
在projects.locations.repositories 資源中將 setAuthenticatedUserAdmin 設為 true 時，在使用者根節點中建立存放區的使用者，會自動獲得存放區的 Dataform 管理員角色 (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 角色

限制

整理資源

資料夾資源

團隊資料夾資源

存放區資源

忙碌的資源

後續步驟

使用資料夾和存放區整理程式碼資產