Referensi filter CEL untuk operasi batch penyimpanan

Halaman ini menjelaskan sintaksis Common Expression Language (CEL) dan operasi yang didukung saat Anda membuat filter lanjutan untuk tugas operasi batch penyimpanan berdasarkan kolom set data Insight Penyimpanan.

Anda dapat menggunakan filter lanjutan untuk mengevaluasi kondisi dan mengotomatiskan tindakan pengelolaan di jutaan file berdasarkan kolom dalam set data Insight Penyimpanan Anda. Filter yang didukung menggunakan aturan CEL langsung pada metadata objek.

Berikan aturan filter menggunakan flag --bucket-filters dan --object-filters di Google Cloud CLI, atau kolom bucketFilters dan objectFilters di JSON API saat Anda membuat tugas. Opsi ini menghilangkan kebutuhan untuk mengkueri BigQuery secara manual, mengekspor daftar objek ke CSV, dan mengupload manifes kembali ke bucket Anda. Saat Anda menggunakan filter set data untuk pemilihan objek, storage batch operations menargetkan objek yang aktif dan terbaru pada snapshot set data yang dipilih. Akibatnya, tugas hanya menyertakan objek yang memiliki nilai NULL untuk softDeleteTime dan timeDeleted pada saat snapshot.

Operator dan fungsi yang didukung

Filter lanjutan mendukung kondisi yang digabungkan dengan pernyataan AND (&&) logis. Gunakan operator berikut untuk membuat string kriteria:

Operator Penggunaan CEL Sintaksis GoogleSQL yang setara Deskripsi
StartsWith name.startsWith("prefix") STARTS_WITH(name, "prefix") Mencocokkan objek dengan atribut string yang diawali dengan awalan tertentu.
EndsWith name.endsWith(".pdf") ENDS_WITH(name, ".pdf") Mencocokkan objek dengan atribut string yang diakhiri dengan akhiran tertentu.
Sama dengan == = Mencocokkan objek dengan atribut yang sama dengan nilai tertentu.
Tidak sama dengan != != Mengecualikan objek dengan atribut yang sama persis dengan nilai tertentu.
Lebih dari > > Mencocokkan objek dengan atribut bilangan bulat atau stempel waktu yang melebihi nilai minimum.
Lebih dari atau sama dengan >= >= Mencocokkan objek dengan atribut bilangan bulat atau stempel waktu yang sama dengan atau melebihi nilai minimum.
Kurang dari < < Mencocokkan objek dengan atribut bilangan bulat atau stempel waktu di bawah nilai minimum.
Kurang dari atau sama dengan <= <= Mencocokkan objek dengan atribut bilangan bulat atau stempel waktu yang sama dengan atau di bawah nilai minimum.
Berisi name.contains("substring") STRPOS(name, "substring") != 0 Mencocokkan objek dengan atribut string yang berisi substring.
Dalam name in ['a', 'b'] name IN UNNEST(ARRAY<STRING>['a', 'b']) Mencocokkan objek dengan atribut yang ada dalam daftar yang disediakan.
Logika NOT ! NOT Balikkan aturan untuk memfilter objek yang tidak cocok dengan kondisi.
Stempel waktu timestamp("2025-01-01T00:00:00Z") TIMESTAMP "2025-01-01 00:00:00 UTC" Transmisikan string tanggal yang diformat dalam RFC 3339 ke stempel waktu. Fungsi ini mendukung presisi mikrodetik agar sesuai dengan standar jenis TIMESTAMP BigQuery.
Ada contexts.exists(c, c.key == "env") EXISTS(SELECT c FROM UNNEST(contexts) AS c WHERE c.key = "env" LIMIT 1) Mencocokkan objek yang setidaknya satu item dalam atribut jenis data berulang memenuhi kondisi tertentu.

ID yang didukung

Saat membuat ekspresi filter, Anda dapat mereferensikan kolom level bucket dan kolom level objek. ID berikut dipetakan ke kolom yang dikenali dalam skema tabel set data Insight Penyimpanan:

Atribut bucket

Anda dapat menggunakan kolom tingkat bucket berikut untuk memfilter bucket mana yang disertakan dalam tugas storage batch operation Anda.

Kolom Jenis Deskripsi
name STRING Nama bucket.
autoclass RECORD Berisi metadata enabled dan toggleTime.
autoclass.enabled BOOLEAN Menunjukkan apakah Autoclass diaktifkan untuk bucket.
autoclass.toggleTime TIMESTAMP Waktu saat Autoclass terakhir diaktifkan atau dinonaktifkan.
labels REPEATED RECORD Berisi key-value map standar.
location STRING ID lokasi bucket.
softDeletePolicy RECORD Berisi retentionDurationSeconds dan effectiveTime.
softDeletePolicy.retentionDurationSeconds INTEGER Periode retensi penghapusan sementara, dalam detik.
softDeletePolicy.effectiveTime TIMESTAMP Waktu saat kebijakan penghapusan sementara mulai berlaku.

Atribut objek

Anda dapat menggunakan atribut berikut untuk memfilter tugas storage batch operation berdasarkan kolom tingkat objek:

Kolom Jenis Deskripsi
name STRING Nama objek.
contexts REPEATED RECORD Konteks yang dilampirkan ke objek.
contexts.key STRING Kunci konteks kustom.
contexts.value STRING Nilai kunci konteks kustom.
contexts.type STRING Jenis konteks kustom.
contexts.createTime TIMESTAMP Waktu pembuatan kunci konteks kustom.
contexts.updateTime TIMESTAMP Waktu saat kunci konteks kustom diperbarui.
contentType STRING Kategorisasi konten jenis MIME.
customTime TIMESTAMP Stempel waktu yang ditentukan pengguna.
generation INTEGER ID pembuatan objek.
metadata REPEATED RECORD Metadata kustom.
metadata.key STRING Kunci metadata kustom.
metadata.value STRING Nilai metadata kustom.
metageneration INTEGER ID pembuatan metadata.
retentionExpirationTime TIMESTAMP Waktu saat retensi objek berakhir.
securityInsights RECORD Berisi insight akses publik untuk objek.
securityInsights.publicAccessInsight RECORD Memberikan status aksesibilitas publik objek.
securityInsights.publicAccessInsight.readPublicAccess STRING Status keterbacaan publik objek. Nilai yang didukung adalah PUBLIC, NOT_PUBLIC, UNSUPPORTED, dan ERROR.
securityInsights.publicAccessInsight.readPublicAccessSource STRING Jika readPublicAccess adalah PUBLIC, menampilkan sumber izin baca publik. Nilai yang didukung adalah Object, Bucket, dan ERROR.
securityInsights.publicAccessInsight.writePublicAccess STRING Status kemampuan penulisan publik objek. Nilai yang didukung adalah PUBLIC, NOT_PUBLIC, UNSUPPORTED, dan ERROR.
size INTEGER Ukuran objek dalam byte.
storageClass STRING Kelas penyimpanan yang ditetapkan.
temporaryHold BOOLEAN Status pemblokiran aktif mencegah rilis.
timeCreated TIMESTAMP Jam pendaftaran pembuatan awal.
timeStorageClassUpdated TIMESTAMP Waktu saat kelas penyimpanan terakhir diperbarui.
updated TIMESTAMP Waktu saat objek terakhir diperbarui.

Aturan format ekspresi

Untuk membantu tugas Anda berjalan dalam skala besar, mesin kueri menerapkan aturan pemformatan berikut:

  1. Kondisi filter: Anda hanya dapat menggabungkan kondisi filter menggunakan operator AND (&&) logis. Mesin kueri tidak mendukung operator OR logis (||).
  2. Penempatan argumen: Anda harus menempatkan kolom metadata target di sisi kiri fungsi. Misalnya, gunakan name.startsWith("live-"), bukan "live-".startsWith(name).
  3. Metode array: Anda dapat memanggil makro exists langsung di kolom berulang, seperti contexts.exists(...) atau metadata.exists(...).
  4. Batas bucket: Satu tugas storage batch operations dapat beroperasi pada hingga 1.000 bucket. Jika ekspresi filter Anda secara dinamis cocok dengan lebih dari 1.000 bucket dalam set data, pembuatan tugas akan gagal. Gunakan kolom tingkat bucket tertentu (misalnya, pemfilteran lokasi seperti location == "us-central1" atau pencocokan nama seperti name.startsWith("prod-")) untuk mempersempit cakupan kueri dan memenuhi batas ini.
  5. Batas karakter: Filter bucket dan filter objek masing-masing dibatasi hingga maksimum 150 karakter.

Contoh

Contoh berikut menunjukkan filter gabungan umum yang dapat Anda gunakan untuk menargetkan resource di seluruh project. Tentukan cuplikan filter secara langsung sebagai flag dalam perintah gcloud storage batch-operations jobs create:

  • Menargetkan bucket tertentu: Terapkan tindakan ke objek di bucket tertentu: 

    --bucket-filters="name in ['bucket-1', 'bucket-2']"

  • Periksa kelas penyimpanan dan lokasi bucket: Terapkan tindakan ke objek di kelas penyimpanan Standard Storage di lokasi US: 

    --bucket-filters="location.startsWith('us')" 
    
--object-filters="storageClass == 'STANDARD'"

  • Filter menurut retensi penghapusan sementara: Terapkan tindakan ke objek dalam bucket yang mengaktifkan penghapusan sementara selama minimal 7 hari: 

    --bucket-filters="softDeletePolicy.retentionDurationSeconds >= 604800"

  • Memfilter menurut ukuran dan ekstensi objek: Menemukan objek PDF yang lebih besar dari 5 KiB: 

    --object-filters="size >= 5120 && name.endsWith('.pdf')"

  • Memeriksa kunci konteks kustom: Terapkan tindakan ke objek yang memiliki kunci konteks kustom env: 

    --object-filters="contexts.exists(context, context.key == 'env')"

  • Cocokkan pasangan nilai kunci konteks kustom: Terapkan tindakan ke objek yang memiliki kunci konteks kustom env dengan nilai prod: 

    --object-filters="contexts.exists(context, context.key == 'env' && context.value == 'prod')"

  • Mencocokkan nilai konteks kustom berdasarkan awalan dan akhiran: Terapkan tindakan ke objek dengan nilai konteks kustom yang diawali dengan awalan prod dan diakhiri dengan akhiran .txt: 

    --object-filters="contexts.exists(context, context.value.startsWith('prod') && context.value.endsWith('.txt'))"

  • Mengidentifikasi kunci konteks yang tidak ada: Terapkan tindakan ke objek yang tidak memiliki kunci konteks kustom env: 

    --object-filters="!contexts.exists(context, context.key == 'env')"

Langkah berikutnya