CEL-Filterreferenz für Speicher-Batchvorgänge

Auf dieser Seite werden die Syntax der Common Expression Language (CEL) und die unterstützten Vorgänge beschrieben, wenn Sie erweiterte Filter für Speicherbatchvorgänge-Jobs basierend auf den Feldern des Storage Insights Datasets 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 Objekt Metadaten.

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

Unterstützte Operatoren und Funktionen

Erweiterte Filter unterstützen Bedingungen, die durch logische AND (&&) Anweisungen verknüpft 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 einem bestimmten Wert entspricht.
Größer als > > Objekte mit einem Attribut vom Typ „Ganzzahl“ oder „Zeitstempel“ abgleichen, das einen bestimmten Schwellenwert überschreitet.
Größer als oder gleich >= >= Objekte mit einem Attribut vom Typ „Ganzzahl“ oder „Zeitstempel“ abgleichen, das einem bestimmten Schwellenwert entspricht oder ihn überschreitet.
Kleiner als < < Objekte mit einem Attribut vom Typ „Ganzzahl“ oder „Zeitstempel“ abgleichen, das unter einem bestimmten Schwellenwert liegt.
Kleiner als oder gleich <= <= Objekte mit einem Attribut vom Typ „Ganzzahl“ oder „Zeitstempel“ abgleichen, das einem bestimmten Schwellenwert entspricht oder darunter liegt.
Enthält name.contains("substring") STRPOS(name, "substring") != 0 Objekte mit einem Stringattribut abgleichen, das die Teilstring enthält.
In name in ['a', 'b'] name IN UNNEST(ARRAY<STRING>['a', 'b']) Objekte mit einem Attribut abgleichen, das in der angegebenen Liste vorhanden ist.
Logisches NOT ! NOT Eine 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" Datumsstrings, die im RFC 3339-Format formatiert sind, in einen Zeitstempel umwandeln. Diese Funktion unterstützt die Mikrosekundengenauigkeit, um den Standards für den BigQuery-Zeitstempeltyp zu entsprechen.
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 in einem wiederholten Attribut vom Typ „Datensatz“ eine bestimmte Bedingung erfüllt.

Unterstützte IDs

Beim Erstellen von Filterausdrücken können Sie sowohl Felder auf Bucket- als auch auf Objektebene referenzieren. Die folgenden IDs werden 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 Speicherbatchvorgänge-Jobs einbezogen werden.

Feld Typ Beschreibung
name STRING Der Name des Buckets.
autoclass RECORD Enthält die Metadaten enabled und toggleTime.
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 Standardschlüssel/Wert-Zuordnungen.
location STRING Bucket-Standort-ID.
softDeletePolicy RECORD Enthält retentionDurationSeconds und effectiveTime.
softDeletePolicy.retentionDurationSeconds INTEGER Der Aufbewahrungszeitraum für vorläufiges Löschen in Sekunden.
softDeletePolicy.effectiveTime TIMESTAMP Der Zeitpunkt, zu dem die Richtlinie zum vorläufigen Löschen in Kraft getreten ist.

Objektattribute

Mit den folgenden Attributen können Sie Speicherbatchvorgänge-Jobs nach Feldern auf Objektebene 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 benutzerdefinierten Kontextschlüssels.
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 MIME-Typ-Inhaltskategorisierung.
customTime TIMESTAMP Benutzerdefinierter Zeitstempel.
generation INTEGER Objekt-Generierungs-ID.
metadata REPEATED RECORD Benutzerdefinierte Metadaten.
metadata.key STRING Der benutzerdefinierte Metadatenschlüssel.
metadata.value STRING Der benutzerdefinierte Metadatenwert.
metageneration INTEGER Metadaten-Generierungs-ID.
retentionExpirationTime TIMESTAMP Zeitpunkt, zu dem die Aufbewahrung des Objekts abläuft.
securityInsights RECORD Enthält Informationen 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 Sperrstatus, der die Freigabe verhindert.
timeCreated TIMESTAMP Zeitpunkt der Registrierung der ersten Generation.
timeStorageClassUpdated TIMESTAMP Zeitpunkt, zu dem die Speicherklasse zuletzt aktualisiert wurde.
updated TIMESTAMP Zeitpunkt, zu dem das Objekt zuletzt aktualisiert wurde.

Regeln für das Ausdrucksformat

Damit Ihre Jobs in großem Maßstab 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 OR-Operator (||) nicht.
  2. Argumentpositionierung: Sie müssen das Zielmetadatenfeld auf der linken Seite der Funktionen platzieren. Verwenden Sie beispielsweise name.startsWith("live-") anstelle von "live-".startsWith(name).
  3. Array-Methoden: Sie können das Makro exists direkt für wiederholte Felder aufrufen, z. B. contexts.exists(...) oder metadata.exists(...).
  4. Bucket-Limit: Ein einzelner Speicherbatchvorgänge-Job kann für bis zu 1.000 Buckets ausgeführt werden. Wenn Ihre Filterausdrücke dynamisch mehr als 1.000 Buckets in Ihrem Dataset abgleichen, schlägt die Job-Erstellung fehl. Verwenden Sie bestimmte Felder auf Bucket-Ebene (z. B. Standortfilterung wie location == "us-central1" oder Namensabgleich wie name.startsWith("prod-")), um den Abfragebereich einzugrenzen und dieses Limit einzuhalten.
  5. Zeichenbeschränkung: Bucket-Filter und Objektfilter sind jeweils auf ein Maximum von 150 Zeichen begrenzt.

Beispiele

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

  • Bestimmte Buckets ausrichten: Aktionen auf Objekte in bestimmten Buckets anwenden: 

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

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

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

  • Nach Aufbewahrungsdauer für vorläufiges Löschen filtern: Aktionen auf Objekte in Buckets anwenden, für die das vorläufige Löschen seit mindestens 7 Tagen aktiviert ist: 

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

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

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

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

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

  • Benutzerdefinierte Schlüssel/Wert-Paare für den Kontext abgleichen: Aktionen auf Objekte anwenden, 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: Aktionen auf Objekte mit einem benutzerdefinierten Kontextwert anwenden, 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: Aktionen auf Objekte anwenden, die keinen benutzerdefinierten Kontextschlüssel env haben: 

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

Nächste Schritte