Référence des filtres CEL pour les opérations de stockage par lot

Cette page décrit la syntaxe CEL (Common Expression Language) et les opérations compatibles lorsque vous créez des filtres avancés pour un job d' opérations de stockage par lot basé sur les champs d'un ensemble de données Storage Insights.

Vous pouvez utiliser des filtres avancés pour évaluer des conditions et automatiser des actions de gestion sur des millions de fichiers en fonction des champs de votre ensemble de données Storage Insights. Les filtres compatibles utilisent des règles CEL directement sur les métadonnées d'objet.

Fournissez des règles de filtrage à l'aide des options --bucket-filters et --object-filters dans la Google Cloud CLI, ou des champs bucketFilters et objectFilters dans l'API JSON lorsque vous créez un job. Cette option vous évite d'avoir à interroger manuellement BigQuery, à exporter des listes d'objets au format CSV et à importer des fichiers manifestes dans vos buckets. Lorsque vous utilisez des filtres d'ensemble de données pour la sélection d'objets, les opérations de stockage par lot ciblent les objets actifs et actuels à partir de l'instantané de l'ensemble de données sélectionné. Par conséquent, le job n'inclut que les objets dont la valeur NULL est définie pour softDeleteTime et timeDeleted au moment de l'instantané.

Opérateurs et fonctions compatibles

Les filtres avancés acceptent les conditions associées par des instructions logiques AND (&&). Utilisez les opérateurs suivants pour créer vos chaînes de critères :

Opérateur Utilisation de CEL Syntaxe GoogleSQL équivalente Description
StartsWith name.startsWith("prefix") STARTS_WITH(name, "prefix") Mettre en correspondance les objets avec un attribut de chaîne commençant par un préfixe spécifique.
EndsWith name.endsWith(".pdf") ENDS_WITH(name, ".pdf") Mettre en correspondance les objets avec un attribut de chaîne se terminant par un suffixe spécifique.
Est égal(e) à == = Mettre en correspondance les objets avec un attribut égal à une valeur spécifique.
Est différent(e) de != != Excluez les objets dont un attribut correspond exactement à une valeur spécifique.
Supérieur à > > Mettre en correspondance les objets avec un attribut d'entier ou d'horodatage dépassant un seuil.
Supérieur ou égal à >= >= Mettre en correspondance les objets avec un attribut d'entier ou d'horodatage supérieur ou égal à un seuil.
Moins de < < Mettre en correspondance les objets avec un attribut d'entier ou d'horodatage inférieur à un seuil.
Inférieur ou égal à <= <= Mettre en correspondance les objets dont l'attribut entier ou code temporel est inférieur ou égal à un seuil.
Contient name.contains("substring") STRPOS(name, "substring") != 0 Correspond aux objets dont un attribut de chaîne contient la sous-chaîne.
Dans name in ['a', 'b'] name IN UNNEST(ARRAY<STRING>['a', 'b']) Faire correspondre les objets avec un attribut qui existe dans la liste fournie.
Logical NOT (Opérateur logique PAS) ! NOT Inversez une règle pour filtrer les objets qui ne correspondent pas aux conditions.
Horodatage timestamp("2025-01-01T00:00:00Z") TIMESTAMP "2025-01-01 00:00:00 UTC" Convertit les chaînes de date au format RFC 3339 en code temporel. Cette fonction accepte une précision à la microseconde pour correspondre aux normes de type TIMESTAMP de BigQuery.
Existe contexts.exists(c, c.key == "env") EXISTS(SELECT c FROM UNNEST(contexts) AS c WHERE c.key = "env" LIMIT 1) Mettre en correspondance les objets dont au moins un élément d'un attribut de type d'enregistrement répété remplit une condition spécifique.

Identifiants acceptés

Lorsque vous créez des expressions de filtre, vous pouvez référencer des champs au niveau du bucket et au niveau de l'objet. Les identifiants suivants correspondent aux champs reconnus dans les schémas de table de l'ensemble de données Storage Insights :

Attributs de bucket

Vous pouvez utiliser les champs suivants au niveau du bucket pour filtrer les buckets inclus dans vos jobs d'opérations de stockage par lot.

Champ Type Description
name STRING Nom du bucket.
autoclass RECORD Contient les métadonnées enabled et toggleTime.
autoclass.enabled BOOLÉEN Indique si la classe automatique est activée pour le bucket.
autoclass.toggleTime TIMESTAMP Date et heure auxquelles la classe automatique a été activée ou désactivée pour la dernière fois.
labels REPEATED RECORD Contient des mappages clé-valeur standards.
location STRING Identifiant de l'emplacement du bucket.
softDeletePolicy RECORD Contient retentionDurationSeconds et effectiveTime.
softDeletePolicy.retentionDurationSeconds INTEGER Durée de conservation de la suppression réversible, en secondes.
softDeletePolicy.effectiveTime TIMESTAMP Heure à laquelle la règle de suppression réversible est entrée en vigueur.

Attributs d'objet

Vous pouvez utiliser les attributs suivants pour filtrer les jobs d'opérations de stockage par lot en fonction de champs au niveau de l'objet :

Champ Type Description
name STRING Nom de l'objet.
contexts REPEATED RECORD Contextes associés à un objet.
contexts.key STRING Clé de contexte personnalisée.
contexts.value STRING Valeur de la clé de contexte personnalisée.
contexts.type STRING Type de contexte personnalisé.
contexts.createTime TIMESTAMP Heure de création de la clé de contexte personnalisée.
contexts.updateTime TIMESTAMP Heure à laquelle la clé de contexte personnalisée a été mise à jour.
contentType STRING Catégorisation du contenu par type MIME.
customTime TIMESTAMP Code temporel défini par l'utilisateur.
generation INTEGER Identifiant de génération d'objet.
metadata REPEATED RECORD Métadonnées personnalisées
metadata.key STRING Clé de métadonnées personnalisées.
metadata.value STRING Valeur de métadonnées personnalisée.
metageneration INTEGER Identifiant de génération de métadonnées.
retentionExpirationTime TIMESTAMP Date d'expiration de la conservation de l'objet.
securityInsights RECORD Contient des insights sur les accès publics à l'objet.
securityInsights.publicAccessInsight RECORD Fournit l'état d'accessibilité publique de l'objet.
securityInsights.publicAccessInsight.readPublicAccess STRING État de lisibilité publique de l'objet. Les valeurs acceptées sont PUBLIC, NOT_PUBLIC, UNSUPPORTED et ERROR.
securityInsights.publicAccessInsight.readPublicAccessSource STRING Si readPublicAccess est PUBLIC, renvoie la source de l'autorisation de lecture publique. Les valeurs acceptées sont Object, Bucket et ERROR.
securityInsights.publicAccessInsight.writePublicAccess STRING État de l'accessibilité en écriture publique de l'objet. Les valeurs acceptées sont PUBLIC, NOT_PUBLIC, UNSUPPORTED et ERROR.
size INTEGER Taille de l'objet en octets.
storageClass STRING Classe de stockage attribuée.
temporaryHold BOOLÉEN Un blocage actif empêche la publication.
timeCreated TIMESTAMP Horloge d'enregistrement de la génération initiale.
timeStorageClassUpdated TIMESTAMP Heure de la dernière mise à jour de la classe de stockage.
updated TIMESTAMP Heure de la dernière mise à jour de l'objet.

Règles de format d'expression

Pour faciliter l'exécution de vos jobs à grande échelle, le moteur de requête applique les règles de mise en forme suivantes :

  1. Conditions de filtre : vous ne pouvez joindre des conditions de filtre qu'à l'aide de l'opérateur logique AND (&&). Le moteur de requête n'est pas compatible avec l'opérateur logique OU (||).
  2. Positionnement des arguments : vous devez placer le champ de métadonnées cible à gauche des fonctions. Par exemple, utilisez name.startsWith("live-") au lieu de "live-".startsWith(name).
  3. Méthodes de tableau : vous pouvez appeler la macro exists directement sur des champs répétés, tels que contexts.exists(...) ou metadata.exists(...).
  4. Limite de buckets : un seul job d'opérations de stockage par lot peut s'exécuter sur 1 000 buckets au maximum. Si vos expressions de filtre correspondent de manière dynamique à plus de 1 000 buckets dans votre ensemble de données, la création du job échoue. Utilisez des champs spécifiques au niveau du bucket (par exemple, un filtrage par emplacement tel que location == "us-central1" ou une correspondance de nom telle que name.startsWith("prod-")) pour affiner le champ d'application de votre requête et respecter cette limite.
  5. Nombre maximal de caractères : les filtres de bucket et les filtres d'objets sont limités à 150 caractères maximum chacun.

Exemples

Les exemples suivants montrent des filtres combinés courants que vous pouvez utiliser pour cibler des ressources à l'échelle d'un projet. Spécifiez les extraits de filtre directement en tant qu'options dans la commande gcloud storage batch-operations jobs create :

  • Cibler des buckets spécifiques : appliquez des actions aux objets de buckets spécifiques : 

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

  • Vérifier la classe de stockage et l'emplacement du bucket : appliquez des actions aux objets de la classe de stockage Standard dans les emplacements US : 

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

  • Filtrer par conservation de la suppression réversible : appliquez des actions aux objets des buckets pour lesquels la suppression réversible est activée depuis au moins sept jours : 

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

  • Filtrer par taille et extension d'objet : recherchez les objets PDF d'une taille supérieure à 5 Kio : 

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

  • Vérifier les clés de contexte personnalisées : appliquez des actions aux objets qui ont une clé de contexte personnalisée env : 

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

  • Correspondance avec les paires clé-valeur de contexte personnalisées : appliquez des actions aux objets qui ont une clé de contexte personnalisée env avec une valeur de prod : 

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

  • Mettre en correspondance les valeurs de contexte personnalisées par préfixe et suffixe : appliquez des actions aux objets dont la valeur de contexte personnalisée commence par le préfixe prod et se termine par le suffixe .txt : 

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

  • Identifier les clés de contexte manquantes : appliquez des actions aux objets qui n'ont pas de clé de contexte personnalisée env : 

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

Étapes suivantes