Mengatur aset kode dengan folder dan repositori

Dokumen ini menyajikan ringkasan konseptual tentang sistem folder dan repositori. Dokumen ini juga merangkum kolom dan metode Dataform API yang digunakan untuk bekerja dengan folder dan repositori.

Dataform API menyediakan resource yang dapat Anda gunakan untuk mengatur aset kode dalam struktur hierarkis yang mirip dengan sistem file sistem operasi pada umumnya. Struktur ini juga memungkinkan pewarisan kebijakan Identity and Access Management (IAM), sehingga izin dapat diteruskan ke bawah jalur.

Daftar berikut mendefinisikan istilah utama yang digunakan untuk menjelaskan sistem folder dan repositori:

Folder
Folder adalah penampung dasar untuk mengatur resource, mirip dengan folder sistem file standar. Anda dapat mengatur folder dan repositori lain, serta memindahkan resource ke dalam dan ke luar folder. Anda dapat memberikan izin di node folder, dan izin ini akan diterapkan ke semua konten.
Folder root pengguna
Folder root pengguna mewakili ruang pribadi pengguna. Direktori ini berisi semua folder dan repositori yang dibuat atau diakses pengguna. Folder root pengguna bukan bagian dari subpohon folder tim. Folder root pengguna adalah konsep virtual yang tidak memiliki resource API terkait.
Folder tim
Folder tim mirip dengan folder, tetapi dirancang untuk kolaborasi tim, seperti drive bersama di Google Drive. Ruang ini menyediakan ruang khusus untuk aset kode inti dan mendukung izin akses dan berbagi yang lebih ketat untuk aset inti tim.
File
Dalam konteks struktur folder ini, file direpresentasikan oleh resource repositori Dataform. Setiap repositori berisi satu aset file, seperti notebook, kueri tersimpan, kanvas data, atau penyiapan data.

Peran yang diperlukan

Untuk mendapatkan izin yang Anda perlukan untuk menyelesaikan tugas dalam dokumen ini, minta administrator Anda untuk memberi Anda peran IAM yang sesuai di project, folder, atau resource.

Izin yang diberikan pada folder akan diteruskan ke semua folder dan file yang ada di dalamnya.

Peran berikut berlaku untuk folder dan file:

Peran Diberikan pada Izin dan kasus penggunaan
Pemilik Kode (roles/dataform.codeOwner) Folder atau file Memberikan kontrol penuh atas resource untuk mengelola aset kode. Pengguna dengan peran ini dapat melakukan semua tindakan, termasuk menghapus resource, menyetel kebijakan IAM-nya, dan memindahkannya.
Editor Kode (roles/dataform.codeEditor) Folder atau file Memungkinkan pengeditan dan pengelolaan konten. Pengguna dengan peran ini dapat menambahkan konten ke folder, mengedit file, dan mendapatkan kebijakan IAM untuk folder atau file. Peran ini juga diperlukan di folder tujuan saat memindahkan resource.
Pemberi Komentar Kode (roles/dataform.codeCommenter) Folder atau file Memungkinkan pemberian komentar pada aset atau folder kode.
Code Viewer (roles/dataform.codeViewer) Folder atau file Memberikan akses hanya baca. Pengguna dengan peran ini dapat membuat kueri konten folder dan file.
Pembuat Kode (roles/dataform.codeCreator) Project Memberikan izin untuk membuat folder dan file baru dalam project.

Peran berikut khusus untuk mengelola folder tim:

Peran Diberikan pada Izin dan kasus penggunaan
Pemilik Folder Tim (roles/dataform.teamFolderOwner) Folder tim Memberikan kontrol penuh atas folder tim untuk mengelola aset kode. Pengguna dengan peran ini dapat menghapus folder tim dan menetapkan kebijakan IAM-nya.
Kontributor Folder Tim (roles/dataform.teamFolderContributor) Folder tim Memungkinkan pengelolaan konten dalam folder tim. Pengguna dengan peran ini dapat memperbarui folder tim.
Pengomentar Folder Tim (roles/dataform.teamFolderCommenter) Folder tim Memungkinkan pemberian komentar pada folder tim dan aset kode yang ada di dalamnya.
Team Folder Viewer (roles/dataform.teamFolderViewer) Folder tim Memberikan akses hanya baca ke folder tim dan isinya. Pengguna dengan peran ini dapat melihat folder tim dan mendapatkan kebijakan IAM-nya.
Pembuat Folder Tim (roles/dataform.teamFolderCreator) Project Memberikan izin untuk membuat folder tim baru dalam project.

Untuk mengetahui informasi selengkapnya tentang cara memberikan peran, lihat Mengelola akses ke project, folder, dan organisasi.

Peran bawaan ini berisi izin yang diperlukan untuk menyelesaikan tugas dalam dokumen ini. Untuk melihat izin yang benar-benar diperlukan, luaskan bagian Izin yang diperlukan:

Izin yang diperlukan

  • Membuat folder:
    • folders.create di folder pengguna induk, folder tim, atau project
    • folders.addContents di folder induk atau folder tim
  • Mengambil properti folder: folders.get di folder
  • Kueri konten folder atau folder tim: folders.queryContents pada folder
  • Memperbarui folder: folders.update pada folder
  • Menghapus folder: folders.delete pada folder
  • Mendapatkan kebijakan IAM untuk folder: folders.getIamPolicy di folder tersebut
  • Tetapkan kebijakan IAM untuk folder: folders.setIamPolicy di folder
  • Memindahkan folder:
    • folders.move pada folder yang dipindahkan
    • folders.addContents di folder tujuan atau folder tim (tidak diperlukan jika memindahkan ke folder root)
  • Buat folder tim: teamFolders.create pada project
  • Menghapus folder tim: teamFolders.delete di folder tim
  • Mendapatkan kebijakan IAM untuk folder tim: teamFolders.getIamPolicy di folder tim
  • Tetapkan kebijakan IAM untuk folder tim: teamFolders.setIamPolicy di folder tim
  • Mengambil properti folder tim: teamFolders.get di folder tim
  • Memperbarui folder tim: teamFolders.update di folder tim
  • Buat repositori:
    • repositories.create di folder pengguna induk, folder tim, atau project
    • folders.addContents di folder induk atau folder tim
  • Membaca repositori: repositories.readFile di repositori
  • Menulis ke repositori: repositories.commit di repositori
  • Memindahkan repositori:
    • repositories.move pada repositori yang dipindahkan
    • folders.addContents di folder pengguna induk tujuan, folder tim, atau project (tidak diperlukan jika dipindahkan ke folder root)
  • Mengambil properti repositori: repositories.get di repositori
  • Memperbarui repositori: repositories.update di repositori
  • Menghapus repositori: repositories.delete di repositori

Anda mungkin juga bisa mendapatkan izin ini dengan peran khusus atau peran yang telah ditetapkan lainnya.

Untuk mendapatkan akses penuh dalam mengelola aset kode di project Anda, minta administrator Anda untuk memberi Anda peran IAM berikut di project:

Pewarisan kebijakan IAM

Akses IAM untuk resource folder dan repositori memanfaatkan struktur hierarkis. Hierarki ini memastikan bahwa kebijakan akses diwarisi dari folder induk ke kontennya.

Jika kebijakan IAM ditetapkan pada folder, izin yang diberikan oleh kebijakan tersebut juga berlaku untuk semua repositori dan subfolder bertingkat di subpohon folder. Hal ini memiliki konsekuensi berikut:

  • Izin diwarisi melalui hierarki folder. Jika pengguna diberi peran tertentu di folder tingkat tinggi, mereka akan memiliki izin yang disertakan dalam peran tersebut untuk semua resource yang ada di folder tersebut dan subfoldernya.
  • Izin yang dimiliki pengguna pada resource terdiri dari kebijakan yang ditetapkan langsung pada resource tersebut dan semua kebijakan yang diwarisi dari setiap folder di jalurnya hingga ke root.

Akibatnya, Anda tidak memerlukan izin tingkat project untuk melakukan tindakan pada resource yang berada jauh di dalam struktur folder. Anda hanya memerlukan izin yang tepat di folder mana pun di jalur ke resource tersebut. Misalnya, jika Anda ingin membuat repositori di subfolder, Anda memerlukan izin yang diperlukan di subfolder tertentu atau folder induknya, yang mencakup folder tingkat teratas.

Berikut adalah praktik terbaik untuk menerapkan kebijakan IAM ke folder dan repositori:

  • Terapkan kebijakan IAM ke folder tertinggi dalam hierarki tempat izin diperlukan secara seragam. Misalnya, jika tim memerlukan akses ke semua data di direktori tim, berikan peran yang diperlukan di level folder tim, bukan di level subfolder project individual.
  • Selalu berikan serangkaian izin minimum yang diperlukan bagi pengguna atau layanan untuk menjalankan tugasnya. Hindari pemberian peran luas jika Anda dapat menggunakan peran dan izin tingkat folder yang lebih spesifik.

Peran IAM yang diberikan saat pembuatan resource

Peran berikut diberikan secara otomatis saat pembuatan resource:

  • Pengguna yang membuat folder yang tidak ada di subpohon folder tim akan otomatis menerima peran Admin Dataform (roles/dataform.admin) di folder tersebut.
  • Pembuat folder tim root akan otomatis menerima peran Admin Dataform (roles/dataform.admin) di folder tim tersebut.
  • Saat Anda menyetel setAuthenticatedUserAdmin ke true di resource projects.locations.repositories, pengguna yang membuat repositori di node root pengguna akan otomatis menerima peran Dataform Admin (roles/dataform.admin) di repositori.

Anda dapat menggunakan Config API untuk memberikan peran tertentu saat pembuatan resource.

Anda tidak otomatis menerima peran apa pun saat membuat folder atau repositori baru dalam subpohon folder tim.

Batasan

Folder dan repositori memiliki batasan berikut:

  • Anda hanya dapat menyusun folder bertingkat hingga 5 tingkat.
  • Setelah memindahkan repositori ke dalam folder, repositori dan resource turunannya tidak terlihat di Inventaris Aset Cloud.
  • Maksimum 100 resource dapat berpartisipasi dalam satu operasi pemindahan.
  • Memiliki folder dalam jumlah yang sangat besar (ratusan ribu) akan memperlambat performa saat bekerja dengan folder.

Mengatur resource

Bagian berikut menjelaskan cara Anda dapat mengatur folder, folder tim, dan resource repositori dengan Dataform API.

Resource folder

Tabel berikut menjelaskan kolom API untuk folder:

Kolom Deskripsi
containing_folder Referensi ke folder induk atau nama folder tim. Anda dapat menyetelnya ke ID folder atau ID folder tim. Jika Anda tidak menyetel kolom ini, ini adalah folder root.
display_name Nama resource yang dapat dilihat pengguna. Kolom display_name harus unik sesuai dengan aturan berikut:
  • Dalam root pengguna, semua folder harus memiliki nama tampilan yang unik. Namun, nama tampilan repositori di root pengguna diizinkan untuk bertabrakan dengan nama repositori dan folder lainnya.
  • Dalam folder, nama tampilan harus unik di semua folder dan repositori dalam folder tersebut.
  • Dalam folder tim, nama tampilan harus unik di semua folder dan repositori dalam folder tim tersebut.
  • Nama tampilan folder tim harus unik di seluruh project.

Tabel berikut menjelaskan metode API projects.locations.folders utama:

Metode API Deskripsi
create Membuat folder baru.
get Mendapatkan properti folder.
patch Memperbarui properti folder, seperti namanya.
queryFolderContents Mencantumkan item dalam folder.
move Memindahkan folder dan seluruh subpohonnya ke folder baru yang berisi. Operasi pemindahan bersifat atomik, yang berarti, operasi ini hanya berhasil jika semua resource di subtree folder dipindahkan dengan benar dan tidak ada kegagalan sebagian.
delete Menghapus folder. Berhasil hanya jika folder kosong.
setIamPolicy Memberikan peran ke folder. Peran yang diberikan secara otomatis diteruskan ke seluruh subpohon folder.

Contoh berikut menunjukkan cara membuat folder tingkat root:

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"

Ganti kode berikut:

  • DISPLAY_NAME: nama yang terlihat oleh pengguna untuk resource.
  • PROJECT_ID: Google Cloud project ID Anda.
  • LOCATION: lokasi repositori Dataform tempat resource dibuat.

Contoh berikut menunjukkan cara membuat folder yang berada di dalam folder lain:

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"

Ganti kode berikut:

  • DISPLAY_NAME: nama yang terlihat oleh pengguna untuk resource.
  • PROJECT_ID: Google Cloud project ID Anda.
  • LOCATION: lokasi repositori Dataform tempat resource dibuat.
  • PARENT_FOLDER_ID: ID folder yang ada tempat Anda ingin membuat folder baru.

Contoh berikut menunjukkan cara memindahkan folder ke folder lain:

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"

Ganti kode berikut:

  • PROJECT_ID: Google Cloud project ID Anda.
  • LOCATION: lokasi repositori Dataform.
  • DESTINATION_PARENT_FOLDER_ID: ID folder tempat Anda ingin memindahkan folder target.
  • FOLDER_ID_TO_MOVE: ID folder yang Anda pindahkan.

Referensi folder tim

Tabel berikut menjelaskan metode API projects.locations.teamFolders utama:

Metode API Deskripsi
create Membuat folder tim baru.
get Mendapatkan properti folder tim.
patch Memperbarui properti folder tim, seperti namanya.
queryContents Mencantumkan item dalam folder tim.
delete Menghapus folder tim. Berhasil hanya jika folder tim kosong.
setIamPolicy Memberikan peran ke folder tim. Peran yang diberikan secara otomatis diteruskan ke seluruh subpohon folder tim.

Contoh berikut menunjukkan cara membuat kueri konten folder tim:

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"

Ganti kode berikut:

  • PROJECT_ID: Google Cloud project ID Anda.
  • LOCATION: lokasi resource Dataform.
  • TEAM_FOLDER_ID: ID folder tim Dataform tertentu yang Anda kueri.

Resource repositori

Anda dapat mengatur resource repositori yang ada di folder dan resource folder tim dengan kolom containing_folder di node folder.

Tabel berikut menjelaskan metode API untuk repositori:

Tabel berikut menjelaskan metode API projects.locations.repositories utama:

Metode API Deskripsi
create Membuat repositori baru.
get Mendapatkan properti repositori.
patch Memperbarui properti repositori, seperti namanya.
move Memindahkan repositori ke folder baru yang berisi.
delete Menghapus repositori.
setIamPolicy Memberikan peran ke repositori. Peran yang diberikan akan otomatis diterapkan ke seluruh subpohon repositori.

Contoh berikut menunjukkan cara membuat repositori di node root pengguna sambil menyetel setAuthenticatedUserAdmin ke 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"

Ganti kode berikut:

  • REPOSITORY_DISPLAY_NAME: nama repositori yang mudah digunakan.
  • PROJECT_ID: Google Cloud project ID Anda.
  • LOCATION: lokasi untuk repositori.
  • REPOSITORY_ID: ID repositori baru.

Contoh berikut menunjukkan cara membuat repositori di dalam folder tim:

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"

Ganti kode berikut:

  • PROJECT_ID: Google Cloud project ID Anda.
  • LOCATION: lokasi tempat resource dibuat. Lokasi ini harus sama dengan lokasi CONTAINING_TEAM_FOLDER_ID.
  • CONTAINING_TEAM_FOLDER_ID: ID folder tim tertentu tempat Anda ingin menempatkan repositori baru.
  • REPOSITORY_ID: ID untuk repositori baru.

Contoh berikut menunjukkan cara memindahkan repositori ke folder root:

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"

Ganti kode berikut:

  • PROJECT_ID: Google Cloud project ID Anda.
  • LOCATION: lokasi tempat repositori berada.
  • REPOSITORY_ID: ID repositori yang ingin Anda pindahkan ke tingkat root.

Resource yang sibuk

Folder, folder tim, atau repositori "sibuk" jika sedang aktif terlibat dalam operasi pemindahan, baik sebagai objek yang dipindahkan maupun tujuan pemindahan. Sistem membatasi resource yang sedang digunakan dari tindakan berikut untuk memastikan integritas data selama pemindahan:

  • Menjadi objek operasi pemindahan lain.
  • Menjadi tujuan operasi pemindahan lain.
  • Menjadi ancestor objek pemindahan.
  • Menjadi objek operasi penghapusan.

Langkah berikutnya