Mengelola kode dengan repositori Git BigQuery Studio

Pratinjau

Produk atau fitur ini tunduk pada "Persyaratan Penawaran Pra-GA" di bagian Persyaratan Layanan Umum dari Persyaratan Khusus Layanan. Produk dan fitur pra-GA tersedia "sebagaimana adanya" dan mungkin memiliki dukungan terbatas. Untuk mengetahui informasi selengkapnya, lihat deskripsi tahap peluncuran.

Catatan: Untuk memberikan masukan atau mengajukan pertanyaan terkait fitur Pratinjau ini, hubungi [e-mail].

Repositori Git BigQuery Studio memungkinkan Anda mengontrol versi skrip SQL, notebook, dan aset kode lainnya langsung di file browser BigQuery Studio. Anda dapat meng-clone repositori Git jarak jauh, mengelola cabang, dan melakukan operasi Git tanpa keluar dari konsol Google Cloud .

Dibandingkan dengan repositori klasik, integrasi ini memberikan pengalaman berbasis folder yang disederhanakan di bagian folder root pengguna di panel kiri. Anda dapat berinteraksi dengan aset kode seperti file dan direktori standar sambil mempertahankan koneksi ke repositori Git jarak jauh.

Batasan

• Repositori Git BigQuery Studio dibatasi untuk konteks folder root pengguna dan ditujukan untuk penggunaan pribadi. Jangan bagikan repositori ini kepada pengguna lain. Meskipun repositori ini muncul di folder root pengguna Anda—yang merupakan representasi virtual aset Anda dalam project—repositori ini secara teknis dibuat di level project.
• Operasi sistem file dalam lokasi pemasangan menggunakan kuota Dataform.
• Repositori dengan jumlah file yang besar, ukuran file yang besar, banyak cabang, atau histori commit yang mendalam dan kompleks memerlukan waktu lebih lama untuk di-clone. Operasi cloning mungkin melebihi waktu tunggu operasi, sehingga repositori tidak dapat berhasil dibuat. Untuk mengurangi waktu cloning repositori dengan histori commit yang mendalam, Anda dapat membuat shallow clone. Anda dapat mengambil lebih banyak commit nanti sesuai kebutuhan.
• Ukuran file notebook yang disimpan di pemasangan repositori Git BigQuery Studio tidak boleh melebihi 30 MB. Jika file Anda berukuran lebih dari 30 MB, simpan file tersebut ke penyimpanan lokal runtime Colab di luar lokasi yang terpasang.

• Saat Anda membuat perubahan pada repositori Git di luar pemasangan—misalnya, dengan mengedit atau mengganti nama file di panel kiri—perubahan tersebut dapat memerlukan waktu hingga 60 detik agar terlihat dalam pemasangan di runtime notebook Anda. Anda dapat menyesuaikan durasi ini dengan meneruskan parameter CACHE_TTL_SECONDS ke konstruktor:

    FuseWidget(CACHE_TTL_SECONDS=NUMBER)
  

  Ganti NUMBER dengan jumlah detik agar cache tetap valid. Mengurangi nilai ini akan meningkatkan frekuensi sinkronisasi dan menghabiskan kuota Dataform lebih cepat.

Sebelum memulai

Aktifkan Developer Connect API di project Google Cloud Anda.

Mengaktifkan API

Peran yang diperlukan

Untuk mendapatkan izin yang Anda perlukan untuk mengelola kode dengan repositori Git BigQuery Studio, minta administrator untuk memberi Anda peran IAM Developer Connect OAuth User (roles/developerconnect.oauthUser) di 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 mengelola kode dengan repositori Git BigQuery Studio. Untuk melihat izin yang benar-benar diperlukan, perluas bagian Izin yang diperlukan:

Izin yang diperlukan

Izin berikut diperlukan untuk mengelola kode dengan repositori Git BigQuery Studio:

• resourcemanager.projects.get
• resourcemanager.projects.list
• developerconnect.operations.list
• developerconnect.operations.get
• developerconnect.locations.list
• developerconnect.locations.get
• developerconnect.users.startOAuth
• developerconnect.users.finishOAuth
• developerconnect.users.fetchAccessToken
• developerconnect.users.getSelf
• developerconnect.users.deleteSelf
• developerconnect.accountConnectors.get
• developerconnect.accountConnectors.list
• developerconnect.accountConnectors.gitProxyUse
• developerconnect.accountConnectors.httpProxyUse
• developerconnect.accountConnectors.gitProxyRead
• developerconnect.accountConnectors.gitProxyWrite
• developerconnect.accountConnectors.httpProxyRead
• developerconnect.accountConnectors.httpProxyWrite
• developerconnect.accountConnectors.fetchUserRepositories

Anda mungkin juga bisa mendapatkan izin ini dengan peran khusus atau peran bawaan lainnya.

Pertimbangan keamanan untuk repositori

Karena aset kode di BigQuery didukung oleh Dataform, Anda harus mempertimbangkan implikasi keamanan berikut bagi pengguna yang memiliki akses ke aset ini:

• Visibilitas untuk aset kode diatur oleh izin Dataform level project. Pengguna dengan izin dataform.repositories.list—yang disertakan dalam peran BigQuery standar seperti BigQuery Job User, BigQuery Studio User, dan BigQuery User—dapat melihat semua aset kode di panel Explorer dari project Google Cloud , terlepas dari apakah mereka membuat aset ini atau aset ini dibagikan kepada mereka. Untuk membatasi visibilitas, Anda dapat membuat peran khusus yang mengecualikan izin dataform.repositories.list.
• Setiap secret yang dibagikan kepada agen layanan Dataform berpotensi diakses oleh pengguna yang dapat mengedit aset ini. Untuk mengamankan kredensial Anda, batasi akses pembuatan dan pengeditan kepada pengguna tepercaya, serta batasi secret yang dapat diakses oleh agen layanan Dataform. Untuk mengetahui informasi selengkapnya, lihat Akses secret selama penginstalan paket.

Untuk mengetahui informasi selengkapnya, lihat Pertimbangan keamanan untuk izin Dataform.

Rekomendasi keamanan untuk izin Developer Connect

Repositori Git BigQuery Studio menggunakan Developer Connect untuk terhubung ke repositori jarak jauh. Selain itu, peran BigQuery dan Dataform yang telah ditetapkan mencakup izin Developer Connect. Karena fitur keamanan ini, sebaiknya Anda melakukan hal berikut:

• Gunakan peran khusus untuk menerapkan pemisahan tugas: jika organisasi Anda memerlukan pemisahan yang ketat antara tugas analisis data dan pengelolaan kode sumber, deploy peran khusus yang menghilangkan izin Developer Connect. Peran bawaan seperti BigQuery User (roles/bigquery.user) dan BigQuery Studio User (roles/bigquery.studioUser) mencakup izin Developer Connect, yang memungkinkan pengguna yang diberi peran ini memulai alur OAuth dan mem-proxy traffic Git.
• Terapkan batasan dengan kebijakan penolakan IAM: terapkan kebijakan penolakan tingkat organisasi untuk mencegah tindakan sensitif bagi grup analisis yang luas. Pertimbangkan untuk menolak izin developerconnect.googleapis.com/gitRepositoryLinks.fetchReadWriteToken untuk mencegah ekstraksi token, dan izin developerconnect.googleapis.com/accountConnectors.gitProxyWrite untuk mencegah akses tulis yang tidak diinginkan ke repositori. Peran administratif seperti BigQuery Admin (roles/bigquery.admin) dan BigQuery Studio Admin (roles/bigquery.studioAdmin) mencakup izin pengakses token yang memungkinkan akun utama mengambil token pengelolaan kode sumber (SCM) pihak ketiga teks biasa yang aktif, seperti token penginstalan Aplikasi GitHub.
• Isolasi project CI/CD yang sensitif: simpan pipeline CI/CD yang sensitif, seperti Cloud Build atau Vertex AI, dalam project Google Cloud khusus yang terpisah dari lingkungan analisis data umum. Karena izin Developer Connect dicakup di level project, pengguna BigQuery dalam project bersama multi-tenant dapat mencantumkan dan menggunakan koneksi Developer Connect apa pun dalam project tersebut untuk mem-proxy permintaan Git, yang mungkin memberikan akses ke repositori yang dikonfigurasi untuk CI/CD atau otomatisasi infrastruktur.
• Membatasi akses resource menggunakan IAM Conditions: lampirkan IAM Conditions ke binding peran untuk membatasi izin Developer Connect ke resource tertentu. Anda dapat membatasi akses berdasarkan awalan nama resource atau mencakup akses ke resource Connection dan GitRepositoryLink tertentu. Hal ini memastikan bahwa pengguna hanya dapat berinteraksi dengan koneksi Developer Connect yang ditujukan untuk alur kerja mereka.
• Lindungi metadata sensitif dalam nama resource: jangan menyematkan kredensial sensitif, namakode project, atau informasi rahasia dalam nama repositori, nama cabang, atau ID koneksi. Izin yang diperlukan untuk mencantumkan resource ini (developerconnect.connections.list dan developerconnect.accountConnectors.list) diberikan ke peran BigQuery standar. Siapa pun yang memiliki akses project dasar dapat menghitung resource ini dan menemukan metadata sensitif.

Membuat repositori Git BigQuery Studio

Saat membuat repositori Git, pertimbangkan persyaratan berikut:

• Menghubungkan repositori Git jarak jauh ke repositori Git dapat gagal jika repositori jarak jauh tidak terbuka untuk internet publik, misalnya, jika berada di balik firewall. Dalam hal ini, tambahkan rentang alamat IP egress Dataform yang diperlukan ke aturan firewall Anda untuk mengaktifkan koneksi ke repositori jarak jauh yang dilindungi.
• Untuk membuat repositori Git yang terhubung ke repositori Git jarak jauh yang tidak diizinkan dalam kebijakan organisasi dataform.restrictGitRemotes, tambahkan repositori Git jarak jauh terlebih dahulu ke daftar allowedValues dalam kebijakan, lalu buat repositori Git. Untuk mengetahui informasi selengkapnya, lihat Membatasi repositori jarak jauh.

Untuk membuat repositori Git, lakukan hal berikut:

1. Di konsol Google Cloud , buka halaman BigQuery.

   Buka BigQuery

2. Di panel kiri, klik Files untuk membuka file browser.

   Jika Anda tidak melihat panel kiri, klik Luaskan panel kiri untuk membuka panel.

3. Di samping node root pengguna, klik View actions > Create > Git repository.

4. Masukkan URL untuk repositori Git jarak jauh Anda.

5. BigQuery Studio mendeteksi apakah konektor akun Developer Connect yang ada tersedia. Anda memiliki opsi berikut ini:

   • Jika konektor akun ditemukan, nama tampilan untuk repositori Git akan diisi otomatis. Anda dapat mengedit nilai ini.
   • Jika konektor akun tidak ada, klik Create account connector untuk membuat konektor akun baru.

   • Jika Anda memilih untuk tidak menggunakan konektor akun Developer Connect, klik Gunakan jenis koneksi lain untuk terhubung menggunakan HTTPS atau SSH.

     Catatan: Repositori Git BigQuery Studio menggunakan konektor akun Developer Connect, bukan koneksi repositori Git. Untuk mengetahui informasi selengkapnya, lihat Perbedaan antara koneksi repositori Git dan konektor akun.

6. Opsional: Untuk membuat repositori shallow clone dengan histori commit terbatas, klik Advanced options, lalu centang kotak Shallow clone.

   1. Di kolom Depth, masukkan jumlah commit yang akan diambil dalam histori commit terbatas.

7. Klik Hubungkan.

Mengedit file

Untuk mengedit file, klik node file—seperti skrip SQL atau notebook—untuk membuka file di tab editor baru.

Setiap perubahan yang Anda buat akan otomatis disimpan.

Kelola file

Anda dapat melakukan tugas pengelolaan standar menggunakan menu tindakan yang terkait dengan setiap item. Untuk mengakses opsi ini, klik View actions di samping direktori atau file mana pun.

Di tingkat direktori, Anda dapat melakukan tugas berikut:

• Create in repository: membuat aset kode baru termasuk kueri SQL, notebook, kanvas data, persiapan data, file, atau subdirektori.
• Upload ke repositori: mengimpor file yang ada dari komputer lokal Anda ke direktori yang dipilih.
• Ganti nama: mengubah nama direktori.
• Move: memindahkan direktori. Anda hanya dapat memindahkan direktori ke lokasi lain dalam repositori Git yang sama. Untuk mengetahui informasi selengkapnya, lihat Memindahkan direktori atau file.
• Delete: menghapus direktori dan semua kontennya secara permanen dari ruang kerja lokal Anda. Untuk mengetahui informasi selengkapnya, lihat Menghapus direktori atau file.

Di tingkat file, Anda dapat melakukan tugas berikut:

• Open atau Open in: melihat file di editor default atau aplikasi tertentu, misalnya, lingkungan notebook tertentu.
• Ganti nama: mengubah nama file.
• Salin: membuat duplikat file. Anda hanya dapat menyalin file ke direktori dalam repositori Git yang sama. Untuk mengetahui informasi selengkapnya, lihat Menyalin file.
• Move: memindahkan file ke direktori lain dalam repositori Git yang sama. Untuk mengetahui informasi selengkapnya, lihat Memindahkan direktori atau file.
• Download: menyimpan salinan file ke komputer lokal Anda.
• Hapus: menghapus file dari ruang kerja Anda. Untuk mengetahui informasi selengkapnya, lihat Menghapus direktori atau file.

Memindahkan direktori atau file

Untuk memindahkan direktori atau file di repositori Git BigQuery Studio, lakukan hal berikut:

1. Di konsol Google Cloud , buka halaman BigQuery.

   Buka BigQuery

2. Di panel kiri, klik Files untuk membuka file browser.

3. Bergantung pada jumlah resource yang ingin Anda pindahkan, lakukan salah satu hal berikut:

   • Untuk memindahkan satu resource, di file browser, pilih direktori atau file yang ingin Anda pindahkan, lalu klik View actions > Move.
   • Untuk memindahkan beberapa resource, di tampilan folder, centang kotak di samping setiap resource yang ingin Anda pindahkan, lalu klik Move.

4. Dalam dialog pemindahan resource, pilih direktori target dalam repositori Git yang sama. Anda hanya dapat memindahkan resource ke lokasi dalam repositori Git yang sama.

5. Klik Pindahkan.

Catatan: Operasi pemindahan massal bersifat independen. Jika satu resource gagal dipindahkan, operasi akan tetap mencoba menyelesaikan pemindahan untuk semua resource terpilih lainnya.

Menyalin file

Untuk menyalin file di repositori Git BigQuery Studio, lakukan hal berikut:

1. Di konsol Google Cloud , buka halaman BigQuery.

   Buka BigQuery

2. Di panel kiri, klik Files untuk membuka file browser.

3. Pilih file yang ingin disalin.

4. Klik Lihat tindakan > Salin.

5. Dalam dialog salin resource, pilih direktori target dalam repositori Git yang sama. Anda hanya dapat menyalin file ke lokasi dalam repositori Git yang sama.

6. Klik Copy.

Menghapus direktori atau file

Untuk menghapus direktori atau file di repositori Git BigQuery Studio, lakukan hal berikut:

1. Di konsol Google Cloud , buka halaman BigQuery.

   Buka BigQuery

2. Di panel kiri, klik Files untuk membuka file browser.

3. Bergantung pada jumlah resource yang ingin Anda hapus, lakukan salah satu hal berikut:

   • Untuk menghapus satu resource, di file browser, pilih direktori atau file yang ingin Anda hapus, lalu klik View actions > Delete.
   • Untuk menghapus beberapa resource, di tampilan folder, centang kotak di samping setiap resource yang ingin Anda hapus, lalu klik Delete.

4. Di dialog konfirmasi penghapusan, klik Delete.

Menyimpan data (commit) dan mendorong perubahan

Untuk menyinkronkan hasil edit lokal dengan repositori jarak jauh, lakukan hal berikut:

1. Di konsol Google Cloud , buka halaman BigQuery.

   Buka BigQuery

2. Di panel kiri, klik Source control.

3. Opsional: Arahkan kursor ke file yang diubah, lalu klik Show diff untuk melihat perbandingan baris demi baris antara versi lokal dan versi terakhir yang di-commit.

4. Di kolom Commit message, masukkan deskripsi perubahan Anda.

5. Klik Commit. Perubahan Anda disimpan ke histori Git cabang lokal Anda.

6. Klik Push to remote. Perubahan Anda disinkronkan dengan repositori jarak jauh.

Melihat cabang baru

Anda dapat mengelola cabang lokal dan membuat cabang lokal baru berdasarkan cabang pelacakan lokal atau jarak jauh yang ada.

Di panel Source control, di bagian Branches, Anda dapat melihat cabang lokal yang di-checkout. Label CURRENT menunjukkan cabang aktif Anda, dan label DEFAULT menunjukkan cabang default repositori.

Catatan: Anda tidak dapat memeriksa cabang baru atau beralih cabang jika memiliki perubahan yang belum di-commit di ruang kerja. Anda harus meng-commit perubahan sebelum beralih atau memeriksa cabang.

Untuk memeriksa cabang baru, lakukan hal berikut:

1. Di konsol Google Cloud , buka halaman BigQuery.

   Buka BigQuery

2. Di panel kiri, klik Source control.

3. Di bagian Branches, di samping Branches, klik Actions > Check out new branch.

4. Di menu Source branch, pilih cabang yang ingin Anda jadikan dasar untuk cabang baru, misalnya, origin/main.

5. Di kolom Branch name, masukkan nama untuk cabang baru.

   Catatan: Jika Anda memilih cabang pelacakan jarak jauh sebagai sumber, kolom Branch name akan diisi otomatis dengan nama cabang yang sesuai.

6. Klik Checkout branch. BigQuery Studio akan memeriksa cabang sumber terlebih dahulu. Jika nama cabang yang diberikan menunjukkan cabang baru, cabang tersebut akan dibuat berdasarkan sumber tersebut. Cabang baru menjadi cabang aktif, dan konten repositori Git Anda otomatis diperbarui untuk mencerminkan status cabang yang di-checkout.

Untuk beralih ke cabang yang ada, lakukan tindakan berikut:

1. Di panel Source control, luaskan bagian Branches.
2. Di samping cabang yang ingin Anda gunakan, klik Actions > Switch to BRANCH_NAME.

Melihat histori commit

Anda dapat melihat histori commit untuk cabang aktif. Jika repositori Anda dibuat sebagai shallow clone, panel Branch commit history akan menampilkan banner informasi yang menunjukkan bahwa repositori memiliki histori commit terbatas. Anda dapat memperluas histori lokal dengan mengambil lebih banyak commit.

Untuk melihat histori commit, lakukan hal berikut:

1. Di konsol Google Cloud , buka halaman BigQuery.

   Buka BigQuery

2. Di panel kiri, klik Source control.

3. Di samping tombol tindakan kontrol versi utama, klik drop-down panah , lalu klik View commit history.

   Panel Branch commit history akan terbuka, menampilkan histori commit untuk cabang aktif Anda.

4. Opsional: Untuk mengambil commit dari repositori jarak jauh, lakukan salah satu hal berikut:

   • Di samping tombol tindakan kontrol versi utama, klik drop-down panah , lalu klik Fetch from remote.
   • Di panel Branch commit history, klik Fetch.

   Untuk repositori shallow clone, dalam dialog Fetch (shallow clone), di kolom Additional commits to fetch, masukkan jumlah commit tambahan yang akan diambil dari histori repositori.

   Jika Anda memasukkan 0, tidak ada commit historis tambahan yang diambil, tetapi BigQuery Studio akan melakukan pengambilan standar untuk menyinkronkan referensi dan metadata jarak jauh.

5. Klik Ambil.

   Anda dapat mengulangi pengambilan sesuai kebutuhan hingga semua commit diambil.

Menghapus repositori Git

Menghapus repositori Git BigQuery Studio akan menghapus repositori dan semua kontennya dari lingkungan BigQuery Studio Anda.

Untuk menghapus repositori Git, lakukan hal berikut:

1. Di konsol Google Cloud , buka halaman BigQuery.

   Buka BigQuery

2. Hapus repositori menggunakan salah satu metode berikut:

   • Untuk menghapus repositori dari file browser, di panel kiri, klik Files. Di samping repositori Git yang ingin Anda hapus, klik Lihat tindakan > Hapus.
   • Untuk menghapus repositori dari panel kontrol, di bagian header panel Source control, klik Source control options > Delete REPOSITORY_NAME.

3. Di dialog konfirmasi penghapusan, klik Delete.

Mengakses file notebook di pemasangan repositori Git

Saat mengakses notebook dari dalam repositori Git BigQuery Studio, Anda dapat memasang repositori Git host ke runtime notebook. Pemasangan adalah koneksi yang membuat repositori Git jarak jauh Anda tampak seolah-olah merupakan repositori lokal di runtime notebook Anda. Dengan begitu, notebook Anda dapat langsung mengakses, membaca, dan menulis ke file lain serta membuat skrip kueri dalam repositori yang sama.

Memasang repositori Git

Untuk memasang repositori Git, jalankan kode Python berikut di notebook Anda:

from google_dataform_fuse_widget import FuseWidget
FuseWidget()

Catatan: Sebaiknya jalankan kode ini di sel coretan Colab yang tidak disimpan dengan notebook. Untuk membuat sel coretan, klik Insert > Scratch code cell.

Saat notebook terhubung ke pemasangan, perubahan berikut akan terjadi:

• Direktori kerja saat ini dari sesi notebook diperbarui untuk mencerminkan jalur relatifnya dalam repositori Git. Hal ini memastikan bahwa akses file berbasis jalur berfungsi secara otomatis.
• Jalur repositori Git pada runtime notebook ditambahkan ke jalur sistem Python, yang memungkinkan Anda menggunakan pernyataan impor Python standar untuk memuat skrip dan file kueri dari repositori Git langsung ke notebook.

Mengelola pemasangan dan koneksi

Gunakan kontrol berikut untuk mengelola ruang kerja Anda:

• Mount workspace: memulai proses pemasangan untuk repositori Git. Pemasangan adalah resource bersama, jadi jika beberapa notebook pada runtime Colab yang sama menggunakan repositori Git yang sama, notebook tersebut akan menggunakan pemasangan yang sama.
• Lepas pemasangan ruang kerja: menghentikan proses pemasangan untuk repositori Git. Melepas pemasangan ruang kerja akan membuat pemasangan tidak tersedia untuk semua notebook di runtime Colab yang menggunakannya.
• Hubungkan ruang kerja: memulai koneksi ke pemasangan aktif untuk sesi notebook saat ini. Menghubungkan akan mengupdate direktori kerja dan jalur sistem notebook untuk menyertakan repositori Git, yang memungkinkan Anda mengakses dan mengimpor file.
• Disconnect workspace: mengakhiri koneksi pemasangan untuk sesi notebook saat ini dan meresetnya ke status default. Pemutusan koneksi tidak memengaruhi status koneksi pemasangan untuk sesi notebook aktif lainnya. Untuk mengakhiri koneksi sesi, sebaiknya gunakan tombol Putuskan koneksi ruang kerja.
• Perbaikan: memulihkan pemasangan atau koneksi ke status responsif jika tidak dapat digunakan.

Setelah Anda melakukan inisialisasi pemasangan, lihat panel Status untuk mengetahui kondisi real-time dan jalur aktif pemasangan. Status respons yang mungkin adalah Connected, Mounted, Stopped, dan Unhealthy.

Langkah berikutnya

• Pelajari cara membuat notebook.
• Pelajari cara membuat kueri tersimpan.
• Pelajari cara membuat dan mengelola repositori.
• Pelajari cara mengatur aset kode dengan folder.