Riferimento ai filtri CEL per le operazioni batch di archiviazione

Questa pagina descrive la sintassi del Common Expression Language (CEL) e le operazioni supportate quando crei filtri avanzati per il job delle operazioni batch di archiviazione in base ai campi del set di dati di Storage Insights.

Puoi utilizzare i filtri avanzati per valutare le condizioni e automatizzare le azioni di gestione su milioni di file in base ai campi del set di dati di Storage Insights. I filtri supportati utilizzano le regole CEL direttamente sui metadati degli oggetti.

Fornisci le regole di filtro utilizzando i flag --bucket-filters e --object-filters in Google Cloud CLI o i campi bucketFilters e objectFilters nell'API JSON quando crei un job. Questa opzione elimina la necessità di eseguire manualmente query su BigQuery, esportare elenchi di oggetti in formato CSV e caricare nuovamente i manifest nei bucket. Quando utilizzi i filtri dei set di dati per la selezione degli oggetti, le operazioni batch di archiviazione hanno come target gli oggetti attivi e aggiornati al momento dello snapshot del set di dati selezionato. Di conseguenza, il job include solo gli oggetti che hanno un valore NULL sia per softDeleteTime che per timeDeleted al momento dello snapshot.

Operatori e funzioni supportati

I filtri avanzati supportano le condizioni unite da istruzioni AND logiche (&&). Utilizza i seguenti operatori per creare le stringhe dei criteri:

Operatore Utilizzo di CEL Sintassi GoogleSQL equivalente Descrizione
StartsWith name.startsWith("prefix") STARTS_WITH(name, "prefix") Trova gli oggetti con un attributo stringa che inizia con un prefisso specifico.
EndsWith name.endsWith(".pdf") ENDS_WITH(name, ".pdf") Trova gli oggetti con un attributo stringa che termina con un suffisso specifico.
Uguale a == = Trova gli oggetti con un attributo uguale a un valore specifico.
Non uguale != != Escludi gli oggetti con un attributo che corrisponde esattamente a un valore specifico.
Maggiore di > > Trova gli oggetti con un attributo di tipo numero intero o timestamp che supera una soglia.
Maggiore o uguale a >= >= Trova gli oggetti con un attributo di tipo numero intero o timestamp uguale o superiore a una soglia.
Minore di < < Trova gli oggetti con un attributo di tipo numero intero o timestamp inferiore a una soglia.
Minore o uguale a <= <= Trova gli oggetti con un attributo di tipo numero intero o timestamp uguale o inferiore a una soglia.
Contiene name.contains("substring") STRPOS(name, "substring") != 0 Trova gli oggetti con un attributo di stringa contenente la sottostringa.
In name in ['a', 'b'] name IN UNNEST(ARRAY<STRING>['a', 'b']) Trova gli oggetti con un attributo presente nell'elenco fornito.
NOT logico ! NOT Inverti una regola per filtrare gli oggetti che non corrispondono alle condizioni.
Timestamp timestamp("2025-01-01T00:00:00Z") TIMESTAMP "2025-01-01 00:00:00 UTC" Esegui il cast delle stringhe di date formattate in RFC 3339 in un timestamp. Questa funzione supporta la precisione al microsecondo per soddisfare gli standard del tipo TIMESTAMP di BigQuery.
Esistente contexts.exists(c, c.key == "env") EXISTS(SELECT c FROM UNNEST(contexts) AS c WHERE c.key = "env" LIMIT 1) Trova gli oggetti in cui almeno un elemento all'interno di un attributo di tipo record ripetuto soddisfa una condizione specifica.

Identificatori supportati

Quando crei espressioni di filtro, puoi fare riferimento sia ai campi a livello di bucket sia ai campi a livello di oggetto. I seguenti identificatori vengono mappati ai campi riconosciuti negli schemi delle tabelle dei set di dati di Storage Insights:

Attributi del bucket

Puoi utilizzare i seguenti campi a livello di bucket per filtrare i bucket inclusi nei job delle operazioni batch di archiviazione.

Campo Tipo Descrizione
name STRING Il nome del bucket.
autoclass RECORD Contiene i metadati enabled e toggleTime.
autoclass.enabled BOOLEANO Indica se Autoclass è abilitata per il bucket.
autoclass.toggleTime TIMESTAMP La data e l'ora dell'ultima attivazione o disattivazione di Autoclass.
labels REPEATED RECORD Contiene mappe chiave-valore standard.
location STRING Identificatore della località del bucket.
softDeletePolicy RECORD Contiene retentionDurationSeconds e effectiveTime.
softDeletePolicy.retentionDurationSeconds INTEGER Il periodo di conservazione dell'eliminazione temporanea, in secondi.
softDeletePolicy.effectiveTime TIMESTAMP La data e l'ora in cui la politica di cancellazione temporanea è diventata effettiva.

Attributi degli oggetti

Puoi utilizzare i seguenti attributi per filtrare i job di operazioni batch di archiviazione in base ai campi a livello di oggetto:

Campo Tipo Descrizione
name STRING Il nome dell'oggetto.
contexts REPEATED RECORD Contesti collegati a un oggetto.
contexts.key STRING La chiave del contesto personalizzato.
contexts.value STRING Il valore della chiave del contesto personalizzato.
contexts.type STRING Il tipo di contesto personalizzato.
contexts.createTime TIMESTAMP La data e l'ora in cui è stata creata la chiave di contesto personalizzata.
contexts.updateTime TIMESTAMP La data e l'ora in cui è stata aggiornata la chiave del contesto personalizzato.
contentType STRING Categorizzazione dei contenuti in base al tipo MIME.
customTime TIMESTAMP Timestamp definito dall'utente.
generation INTEGER Identificatore della generazione dell'oggetto.
metadata REPEATED RECORD Metadati personalizzati.
metadata.key STRING La chiave dei metadati personalizzati.
metadata.value STRING Il valore dei metadati personalizzati.
metageneration INTEGER Identificatore della generazione dei metadati.
retentionExpirationTime TIMESTAMP Data e ora di scadenza della conservazione degli oggetti.
securityInsights RECORD Contiene insight sull'accesso pubblico per l'oggetto.
securityInsights.publicAccessInsight RECORD Fornisce lo stato di accessibilità pubblica dell'oggetto.
securityInsights.publicAccessInsight.readPublicAccess STRING Lo stato di leggibilità pubblica dell'oggetto. I valori supportati sono PUBLIC, NOT_PUBLIC, UNSUPPORTED e ERROR.
securityInsights.publicAccessInsight.readPublicAccessSource STRING Se readPublicAccess è PUBLIC, restituisce l'origine dell'autorizzazione in lettura pubblica. I valori supportati sono Object, Bucket e ERROR.
securityInsights.publicAccessInsight.writePublicAccess STRING Lo stato di scrivibilità pubblica dell'oggetto. I valori supportati sono PUBLIC, NOT_PUBLIC, UNSUPPORTED e ERROR.
size INTEGER Dimensioni dell'oggetto in byte.
storageClass STRING La classe di archiviazione assegnata.
temporaryHold BOOLEANO Stato di blocco attivo che impedisce la release.
timeCreated TIMESTAMP Orologio di registrazione della generazione iniziale.
timeStorageClassUpdated TIMESTAMP Data e ora dell'ultimo aggiornamento della classe di archiviazione.
updated TIMESTAMP Data e ora dell'ultimo aggiornamento dell'oggetto.

Regole di formattazione delle espressioni

Per consentire l'esecuzione dei job su larga scala, il motore di query applica le seguenti regole di formattazione:

  1. Condizioni di filtro: puoi unire le condizioni di filtro solo utilizzando l'operatore logico AND (&&). Il motore di query non supporta l'operatore logico OR (||).
  2. Posizionamento degli argomenti: devi posizionare il campo dei metadati di destinazione sul lato sinistro delle funzioni. Ad esempio, utilizza name.startsWith("live-") invece di "live-".startsWith(name).
  3. Metodi di array: puoi chiamare la macro exists direttamente sui campi ripetuti, ad esempio contexts.exists(...) o metadata.exists(...).
  4. Limite di bucket: un singolo job di operazioni batch di archiviazione può operare su un massimo di 1000 bucket. Se le espressioni di filtro corrispondono dinamicamente a più di 1000 bucket nel set di dati, la creazione del job non va a buon fine. Utilizza campi specifici a livello di bucket (ad esempio, filtri di località come location == "us-central1" o corrispondenza dei nomi come name.startsWith("prod-")) per restringere l'ambito della query e soddisfare questo limite.
  5. Limite di caratteri: i filtri dei bucket e degli oggetti sono limitati a un massimo di 150 caratteri ciascuno.

Esempi

Gli esempi seguenti mostrano i filtri combinati comuni che puoi utilizzare per scegliere come target le risorse di destinazione a livello di progetto. Specifica gli snippet di filtro direttamente come flag nel comando gcloud storage batch-operations jobs create:

  • Scegli come target bucket specifici: applica azioni agli oggetti in bucket specifici: 

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

  • Controlla la classe di archiviazione e la località del bucket: applica le azioni agli oggetti nella classe di archiviazione Standard Storage nelle località US: 

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

  • Filtra per conservazione dell'eliminazione temporanea: applica azioni agli oggetti nei bucket con eliminazione temporanea abilitata per almeno 7 giorni: 

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

  • Filtra per dimensioni ed estensioni degli oggetti: trova oggetti PDF di dimensioni superiori a 5 KiB: 

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

  • Controlla le chiavi di contesto personalizzate: applica azioni agli oggetti che hanno una chiave di contesto personalizzata env: 

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

  • Corrispondenza delle coppie chiave-valore del contesto personalizzato: applica azioni agli oggetti che hanno una chiave di contesto personalizzata env con un valore prod: 

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

  • Abbina i valori di contesto personalizzati per prefisso e suffisso: applica azioni agli oggetti con un valore di contesto personalizzato che inizia con il prefisso prod e termina con il suffisso .txt: 

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

  • Identifica le chiavi di contesto mancanti: applica azioni agli oggetti che non hanno una chiave di contesto personalizzata env: 

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

Passaggi successivi