CEL-Filterreferenz für Speicher-Batchvorgänge

Auf dieser Seite werden die CEL-Syntax (Common Expression Language) und die unterstützten Vorgänge beschrieben, wenn Sie erweiterte Filter für einen Storage-Batchvorgangsjob basierend auf Storage Insights-Dataset-Feldern erstellen.

Mit erweiterten Filtern können Sie Bedingungen auswerten und Verwaltungsaktionen für Millionen von Dateien basierend auf Feldern in Ihrem Storage Insights-Dataset automatisieren. Unterstützte Filter verwenden CEL-Regeln direkt für Objektmetadaten.

Geben Sie Filterregeln mit den Flags --bucket-filters und --object-filters in der Google Cloud CLI oder den Feldern bucketFilters und objectFilters in der JSON API an, wenn Sie einen Job erstellen. Mit dieser Option müssen Sie BigQuery nicht mehr manuell abfragen, Objektlisten in CSV exportieren und Manifeste wieder in Ihre Buckets hochladen. Wenn Sie Dataset-Filter für die Objektauswahl verwenden, werden bei Storage-Batchvorgängen Objekte berücksichtigt, die zum Zeitpunkt des ausgewählten Dataset-Snapshots live und aktuell sind. Daher enthält der Job nur Objekte, die zum Zeitpunkt des Snapshots sowohl für softDeleteTime als auch für timeDeleted den Wert NULL haben.

Unterstützte Operatoren und Funktionen

Erweiterte Filter unterstützen Bedingungen, die durch logische AND-Anweisungen (&&) verbunden sind. Verwenden Sie die folgenden Operatoren, um Ihre Kriterienstrings zu erstellen:

Operator CEL-Verwendung Entsprechende GoogleSQL-Syntax Beschreibung
StartsWith name.startsWith("prefix") STARTS_WITH(name, "prefix") Objekte mit einem Stringattribut abgleichen, das mit einem bestimmten Präfix beginnt.
EndsWith name.endsWith(".pdf") ENDS_WITH(name, ".pdf") Objekte mit einem Stringattribut abgleichen, das mit einem bestimmten Suffix endet.
Ist gleich == = Objekte mit einem Attribut abgleichen, das einem bestimmten Wert entspricht.
Ist nicht gleich != != Objekte mit einem Attribut ausschließen, das genau mit einem bestimmten Wert übereinstimmt.
Größer als > > Objekte mit einem Ganzzahl- oder Zeitstempelattribut abgleichen, das einen Schwellenwert überschreitet.
Größer als oder gleich >= >= Objekte mit einem Ganzzahl- oder Zeitstempelattribut abgleichen, das einen Schwellenwert erreicht oder überschreitet.
Kleiner als < < Objekte mit einem Ganzzahl- oder Zeitstempelattribut unter einem Schwellenwert abgleichen.
Kleiner als oder gleich <= <= Objekte mit einem Ganzzahl- oder Zeitstempelattribut abgleichen, das kleiner oder gleich einem Schwellenwert ist.
Enthält name.contains("substring") STRPOS(name, "substring") != 0 Objekte mit einem Stringattribut abgleichen, das den Teilstring enthält.
In name in ['a', 'b'] name IN UNNEST(ARRAY<STRING>['a', 'b']) Objekte mit einem Attribut abgleichen, das in der bereitgestellten Liste vorhanden ist.
Logisches NOT ! NOT Regel umkehren, um Objekte zu filtern, die nicht den Bedingungen entsprechen.
Zeitstempel timestamp("2025-01-01T00:00:00Z") TIMESTAMP "2025-01-01 00:00:00 UTC" Wandelt Datumsstrings im RFC 3339-Format in einen Zeitstempel um. Diese Funktion unterstützt eine Mikrosekundenpräzision, die den BigQuery-TIMESTAMP-Typstandards entspricht.
Vorhanden contexts.exists(c, c.key == "env") EXISTS(SELECT c FROM UNNEST(contexts) AS c WHERE c.key = "env" LIMIT 1) Objekte abgleichen, bei denen mindestens ein Element innerhalb eines Attributs vom Typ „Wiederholter Eintrag“ eine bestimmte Bedingung erfüllt.

Unterstützte IDs

Beim Erstellen von Filterausdrücken können Sie sowohl auf Felder auf Bucket-Ebene als auch auf Felder auf Objektebene verweisen. Die folgenden Kennungen sind den erkannten Feldern in den Tabellenschemas des Storage Insights-Datasets zugeordnet:

Bucket-Attribute

Mit den folgenden Feldern auf Bucket-Ebene können Sie filtern, welche Buckets in Ihre Storage-Batchvorgangsjobs einbezogen werden.

Feld Typ Beschreibung
name STRING Der Name des Buckets.
autoclass RECORD Enthält enabled- und toggleTime-Metadaten.
autoclass.enabled BOOLEAN Gibt an, ob Autoclass für den Bucket aktiviert ist.
autoclass.toggleTime TIMESTAMP Der Zeitpunkt, zu dem Autoclass zuletzt aktiviert oder deaktiviert wurde.
labels REPEATED RECORD Enthält Standard-Schlüssel/Wert-Zuordnungen.
location STRING Bucket-Standort-ID.
softDeletePolicy RECORD Enthält retentionDurationSeconds und effectiveTime.
softDeletePolicy.retentionDurationSeconds INTEGER Die Aufbewahrungsdauer für das vorläufige Löschen in Sekunden.
softDeletePolicy.effectiveTime TIMESTAMP Der Zeitpunkt, zu dem die Richtlinie für vorläufiges Löschen in Kraft getreten ist.

Objektattribute

Sie können die folgenden Attribute verwenden, um Storage-Batchvorgangsjobs nach Feldern auf Objektebene zu filtern:

Feld Typ Beschreibung
name STRING Der Name des Objekts.
contexts REPEATED RECORD Kontexte, die an ein Objekt angehängt sind.
contexts.key STRING Der Schlüssel für den benutzerdefinierten Kontext.
contexts.value STRING Der Wert des Schlüssels für den benutzerdefinierten Kontext.
contexts.type STRING Der benutzerdefinierte Kontexttyp.
contexts.createTime TIMESTAMP Der Zeitpunkt, zu dem der benutzerdefinierte Kontextschlüssel erstellt wurde.
contexts.updateTime TIMESTAMP Der Zeitpunkt, zu dem der benutzerdefinierte Kontextschlüssel aktualisiert wurde.
contentType STRING Inhaltskategorisierung nach MIME-Typ.
customTime TIMESTAMP Benutzerdefinierter Zeitstempel.
generation INTEGER ID der Objektgenerierung.
metadata REPEATED RECORD Benutzerdefinierte Metadaten.
metadata.key STRING Der benutzerdefinierte Metadatenschlüssel.
metadata.value STRING Der benutzerdefinierte Metadatenwert.
metageneration INTEGER ID für die Metadatengenerierung.
retentionExpirationTime TIMESTAMP Zeitpunkt, zu dem die Objektaufbewahrung abläuft.
securityInsights RECORD Enthält Statistiken zum öffentlichen Zugriff auf das Objekt.
securityInsights.publicAccessInsight RECORD Gibt den Status der öffentlichen Zugänglichkeit des Objekts an.
securityInsights.publicAccessInsight.readPublicAccess STRING Der Status der öffentlichen Lesbarkeit des Objekts. Unterstützte Werte sind PUBLIC, NOT_PUBLIC, UNSUPPORTED und ERROR.
securityInsights.publicAccessInsight.readPublicAccessSource STRING Wenn readPublicAccess den Wert PUBLIC hat, wird die Quelle der öffentlichen Leseberechtigung zurückgegeben. Unterstützte Werte sind Object, Bucket, und ERROR.
securityInsights.publicAccessInsight.writePublicAccess STRING Der Status der öffentlichen Schreibbarkeit des Objekts. Unterstützte Werte sind PUBLIC, NOT_PUBLIC, UNSUPPORTED und ERROR.
size INTEGER Objektgröße in Byte.
storageClass STRING Die zugewiesene Speicherklasse.
temporaryHold BOOLEAN Aktiver Blockierungsstatus, der die Veröffentlichung verhindert.
timeCreated TIMESTAMP Uhrzeit der Registrierung der ersten Erstellung.
timeStorageClassUpdated TIMESTAMP Zeitpunkt, zu dem die Speicherklasse zuletzt aktualisiert wurde.
updated TIMESTAMP Zeitpunkt, zu dem das Objekt zuletzt aktualisiert wurde.

Formatierungsregeln für Ausdrücke

Damit Ihre Jobs in großem Umfang ausgeführt werden können, wendet die Abfrage-Engine die folgenden Formatierungsregeln an:

  1. Filterbedingungen: Sie können Filterbedingungen nur mit dem logischen AND-Operator (&&) verknüpfen. Die Abfrage-Engine unterstützt den logischen Operator OR (||) nicht.
  2. Argumentpositionierung: Sie müssen das Zielmetadatenfeld auf der linken Seite der Funktionen platzieren. Verwenden Sie z. B. name.startsWith("live-") statt "live-".startsWith(name).
  3. Array-Methoden: Sie können das Makro exists direkt für wiederkehrende Felder wie contexts.exists(...) oder metadata.exists(...) aufrufen.
  4. Bucket-Limit: Ein einzelner Job für Storage-Batchvorgänge kann bis zu 1.000 Buckets umfassen. Wenn Ihre Filterausdrücke dynamisch mit mehr als 1.000 Buckets in Ihrem Dataset übereinstimmen, schlägt die Joberstellung fehl. Verwenden Sie bestimmte Felder auf Bucket-Ebene (z. B. Standortfilter wie location == "us-central1" oder Namensübereinstimmungen wie name.startsWith("prod-")), um den Abfrageumfang einzugrenzen und dieses Limit einzuhalten.
  5. Zeichenbeschränkung: Bucket- und Objektfilter sind jeweils auf maximal 150 Zeichen beschränkt.

Beispiele

Die folgenden Beispiele zeigen gängige kombinierte Filter, mit denen Sie Ressourcen projektweit filtern können. Geben Sie die Filter-Snippets direkt als Flags im Befehl gcloud storage batch-operations jobs create an:

  • Auf bestimmte Buckets abzielen: Wenden Sie Aktionen auf Objekte in bestimmten Buckets an: 

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

  • Speicherklasse und Bucket-Standort prüfen: Wenden Sie Aktionen auf Objekte in der Speicherklasse „Standard Storage“ an US-Standorten an: 

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

  • Nach Aufbewahrung für vorläufiges Löschen filtern: Wenden Sie Aktionen auf Objekte in Buckets an, für die das vorläufige Löschen mindestens 7 Tage lang aktiviert ist: 

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

  • Nach Objektgröße und Erweiterungen filtern: PDF-Objekte finden, die größer als 5 KiB sind: 

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

  • Benutzerdefinierte Kontextschlüssel prüfen: Wenden Sie Aktionen auf Objekte an, die einen benutzerdefinierten Kontextschlüssel env haben: 

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

  • Benutzerdefinierte Kontext-Schlüssel/Wert-Paare abgleichen: Wenden Sie Aktionen auf Objekte an, die einen benutzerdefinierten Kontextschlüssel env mit dem Wert prod haben: 

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

  • Benutzerdefinierte Kontextwerte nach Präfix und Suffix abgleichen: Wenden Sie Aktionen auf Objekte mit einem benutzerdefinierten Kontextwert an, der mit dem Präfix prod beginnt und mit dem Suffix .txt endet: 

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

  • Fehlende Kontextschlüssel identifizieren: Wenden Sie Aktionen auf Objekte an, die keinen benutzerdefinierten Kontextschlüssel env haben: 

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

Nächste Schritte