폴더 및 저장소로 코드 애셋 구성

이 문서에서는 폴더 및 저장소 시스템의 개념 개요를 설명합니다. 또한 폴더 및 저장소 작업에 사용되는 Dataform API 필드와 메서드를 요약합니다.

Dataform API는 일반적인 운영체제 파일 시스템과 유사한 계층 구조로 코드 애셋을 구성하는 데 사용할 수 있는 리소스를 제공합니다. 이 구조는 Identity and Access Management (IAM) 정책 상속도 지원하므로 권한이 경로를 따라 전파될 수 있습니다.

다음 목록에서는 폴더 및 저장소 시스템을 설명하는 데 사용되는 주요 용어를 정의합니다.

폴더: 폴더는 표준 파일 시스템 폴더와 마찬가지로 리소스를 구성할 수 있는 기본 컨테이너입니다. 다른 폴더와 저장소를 정리할 수 있으며 리소스를 폴더 안팎으로 이동할 수 있습니다. 폴더 노드에서 권한을 부여하면 모든 콘텐츠에 권한이 전파됩니다.
사용자 루트 폴더: 사용자 루트 폴더는 사용자의 개인 공간을 나타냅니다. 여기에는 사용자가 만들거나 액세스하는 모든 폴더와 저장소가 포함됩니다. 사용자 루트 폴더는 팀 폴더의 하위 트리에 포함되지 않습니다. 사용자 루트 폴더는 연결된 API 리소스가 없는 가상 개념입니다.
팀 폴더: 팀 폴더는 폴더와 비슷하지만 Google Drive의 공유 드라이브와 마찬가지로 팀 공동작업을 위해 설계되었습니다. 핵심 코드 애셋을 위한 전용 공간을 제공하고 팀의 핵심 애셋에 대한 더 엄격한 공유 및 액세스 권한을 지원합니다.
파일: 이 폴더 구조의 컨텍스트에서 파일은 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`)	프로젝트	프로젝트 내에 새 팀 폴더를 만들 수 있는 권한을 부여합니다.

역할 부여에 대한 상세 설명은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

이러한 사전 정의된 역할에는 이 문서의 작업을 완료하는 데 필요한 권한이 포함되어 있습니다. 필요한 정확한 권한을 보려면 필수 권한 섹션을 확장하세요.

필수 권한

폴더를 만듭니다.
- 상위 사용자 폴더, 팀 폴더 또는 프로젝트에 대한 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 뷰어 (roles/dataform.viewer)

IAM 정책 상속

폴더 및 저장소 리소스의 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 역할

제한사항

리소스 정리

폴더 리소스

팀 폴더 리소스

저장소 리소스

사용 중인 리소스

다음 단계

폴더 및 저장소로 코드 애셋 구성