Riferimento ai filtri CEL per le operazioni batch di archiviazione

Questa pagina descrive la sintassi di Common Expression Language (CEL) e le operazioni supportate quando crei filtri avanzati per i job di operazioni batch di archiviazione basati sui campi del set di dati 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 Storage Insights. I filtri supportati utilizzano CEL 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 CSV e caricare di nuovo i manifest nei bucket. Quando utilizzi i filtri del set di dati per la selezione degli oggetti, le operazioni batch di archiviazione hanno come target gli oggetti attivi e attuali 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 sia 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") Applica una regola agli oggetti con un attributo stringa che inizia con un prefisso specifico.
EndsWith name.endsWith(".pdf") ENDS_WITH(name, ".pdf") Applica una regola agli oggetti con un attributo stringa che termina con un suffisso specifico.
Equals == = Applica una regola agli oggetti con un attributo uguale a un valore specifico.
Not equals != != Escludi gli oggetti con un attributo che corrisponde esattamente a un valore specifico.
Greater than > > Applica una regola agli oggetti con un attributo intero o timestamp che supera una soglia.
Greater than or equal to >= >= Applica una regola agli oggetti con un attributo intero o timestamp uguale o superiore a una soglia.
Less than < < Applica una regola agli oggetti con un attributo intero o timestamp inferiore a una soglia.
Less than or equal to <= <= Applica una regola agli oggetti con un attributo intero o timestamp uguale o inferiore a una soglia.
Contains name.contains("substring") STRPOS(name, "substring") != 0 Applica una regola agli oggetti con un attributo stringa che contiene la sottostringa.
In name in ['a', 'b'] name IN UNNEST(ARRAY<STRING>['a', 'b']) Applica una regola agli oggetti con un attributo presente nell'elenco fornito.
Logical NOT ! 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 data formattate in RFC 3339 in un timestamp. Questa funzione supporta la precisione in microsecondi per soddisfare gli standard del tipo TIMESTAMP di BigQuery.
Exists contexts.exists(c, c.key == "env") EXISTS(SELECT c FROM UNNEST(contexts) AS c WHERE c.key = "env" LIMIT 1) Applica una regola agli 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 in gli schemi delle tabelle del set di dati Storage Insights:

Attributi del bucket

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

Campo Tipo Descrizione
name STRING Il nome del bucket.
autoclass RECORD Contiene i metadati enabled e toggleTime.
autoclass.enabled BOOLEAN Indica se Autoclass è abilitato per il bucket.
autoclass.toggleTime TIMESTAMP L'ora in cui Autoclass è stato abilitato o disabilitato l'ultima volta.
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 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 L'ora in cui è stata creata la chiave del contesto personalizzato.
contexts.updateTime TIMESTAMP 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 personalizzata.
metadata.value STRING Il valore dei metadati personalizzato.
metageneration INTEGER Identificatore della generazione dei metadati.
retentionExpirationTime TIMESTAMP L'ora in cui scade la conservazione dell'oggetto.
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 ed ERROR.
securityInsights.publicAccessInsight.writePublicAccess STRING Lo stato di scrivibilità pubblica dell'oggetto. I valori supportati sono PUBLIC, NOT_PUBLIC, UNSUPPORTED e ERROR.
size INTEGER Le dimensioni dell'oggetto in byte.
storageClass STRING La classe di archiviazione assegnata.
temporaryHold BOOLEAN Stato di blocco attivo che impedisce il rilascio.
timeCreated TIMESTAMP Orologio di registrazione della generazione iniziale.
timeStorageClassUpdated TIMESTAMP L'ora dell'ultimo aggiornamento della classe di archiviazione.
updated TIMESTAMP L'ora dell'ultimo aggiornamento dell'oggetto.

Regole di formato 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 AND logico (&&). Il motore di query non supporta l'operatore OR logico (||).
  2. Posizionamento degli argomenti: devi inserire il campo dei metadati di destinati sul lato sinistro delle funzioni. Ad esempio, utilizza name.startsWith("live-") anziché "live-".startsWith(name).
  3. Metodi array: puoi chiamare la macro exists direttamente sui campi ripetuti, ad esempio contexts.exists(...) o metadata.exists(...).
  4. Limite dei 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 riesce. Utilizza campi specifici a livello di bucket (ad esempio, il filtro per località come location == "us-central1" o la 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 i filtri 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 a livello di progetto. Specifica direttamente gli snippet di filtro 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 azioni agli oggetti nella classe di archiviazione Standard Storage nelle località US: 

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

  • Filtra in base alla conservazione dell'eliminazione temporanea: applica azioni agli oggetti nei bucket in cui l'eliminazione temporanea è abilitata da almeno 7 giorni: 

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

  • Filtra in base alle dimensioni e alle estensioni degli oggetti: trova gli oggetti PDF di dimensioni superiori a 5 KiB: 

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

  • Controlla le chiavi del contesto personalizzato: applica azioni agli oggetti con una chiave del contesto personalizzato env: 

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

  • Applica una regola alle coppie chiave-valore del contesto personalizzato: applica azioni agli oggetti con una chiave del contesto personalizzato env con un valore prod: 

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

  • Applica una regola ai valori del contesto personalizzato in base a prefisso e suffisso: applica azioni agli oggetti con un valore del 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 del contesto mancanti: applica azioni agli oggetti che non hanno una chiave del contesto personalizzato env: 

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

Passaggi successivi