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

Cette page décrit la syntaxe du langage d'expression commun (CEL, Common Expression Language) et les opérations compatibles lorsque vous créez des filtres avancés pour une tâche d'opérations de stockage par lot basée 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 CEL CEL directement sur les métadonnées d'objet.

Fournissez des règles de filtre à l'aide des options --bucket-filters et --object-filters flags dans Google Cloud CLI, ou des champs bucketFilters et objectFilters dans l'API JSON lorsque vous créez une tâche. Cette option élimine la nécessité d'interroger manuellement BigQuery, d'exporter des listes d'objets au format CSV et d'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 à jour au moment de l'instantané d'ensemble de données sélectionné. Par conséquent, la tâche 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 sont compatibles avec les conditions jointes par des instructions logiques AND (&&). Utilisez les opérateurs suivants pour créer vos chaînes de critères :

Opérateur Utilisation du langage CEL Syntaxe GoogleSQL équivalente Description
StartsWith name.startsWith("prefix") STARTS_WITH(name, "prefix") Correspond aux objets dont un attribut de chaîne commence par un préfixe spécifique.
EndsWith name.endsWith(".pdf") ENDS_WITH(name, ".pdf") Correspond aux objets dont un attribut de chaîne se termine par un suffixe spécifique.
Est égal(e) à == = Correspond aux objets dont un attribut est égal à une valeur spécifique.
Est différent(e) de != != Exclut les objets dont un attribut correspond exactement à une valeur spécifique.
Supérieur à > > Correspond aux objets dont un attribut d'entier ou d'horodatage dépasse un seuil.
Supérieur ou égal à >= >= Correspond aux objets dont un attribut d'entier ou d'horodatage est égal ou supérieur à un seuil.
Moins de < < Correspond aux objets dont un attribut d'entier ou d'horodatage est inférieur à un seuil.
Inférieur ou égal à <= <= Correspond aux objets dont un attribut d'entier ou d'horodatage est égal ou inférieur à 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']) Correspond aux objets dont un attribut existe dans la liste fournie.
Logical NOT (Opérateur logique PAS) ! NOT Inverse 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 mises en forme au format RFC 3339 en horodatage. Cette fonction est compatible avec la précision en microsecondes 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) Correspond aux objets où au moins un élément d'un attribut de type d'enregistrement répété remplit une condition spécifique.

Identifiants compatibles

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 au niveau du bucket suivants pour filtrer les buckets inclus dans vos tâches 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 Heure à laquelle la classe automatique a été activée ou désactivée pour la dernière fois.
labels ENREGISTREMENT RÉPÉTÉ Contient des mappages clé-valeur standards.
location STRING Identifiant de zone géographique du bucket.
softDeletePolicy RECORD Contient retentionDurationSeconds et effectiveTime.
softDeletePolicy.retentionDurationSeconds INTEGER Période de conservation associée à 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 tâches d'opérations de stockage par lot par champs au niveau de l'objet :

Champ Type Description
name STRING Nom de l'objet.
contexts ENREGISTREMENT RÉPÉTÉ 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 à laquelle la clé de contexte personnalisée a été créé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 Horodatage défini par l'utilisateur.
generation INTEGER Identifiant de génération d'objet.
metadata ENREGISTREMENT RÉPÉTÉ Métadonnées personnalisées.
metadata.key STRING Clé de métadonnées personnalisée.
metadata.value STRING Valeur de métadonnées personnalisée.
metageneration INTEGER Identifiant de génération de métadonnées.
retentionExpirationTime TIMESTAMP Heure d'expiration de la conservation de l'objet.
securityInsights RECORD Contient des insights sur l'accès public à l'objet.
securityInsights.publicAccessInsight RECORD Indique 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 d'é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 État de blocage actif empêchant la libération.
timeCreated TIMESTAMP Horloge d'enregistrement de la génération initiale.
timeStorageClassUpdated TIMESTAMP Heure à laquelle la classe de stockage a été mise à jour pour la dernière fois.
updated TIMESTAMP Heure à laquelle l'objet a été mis à jour pour la dernière fois.

Règles de format d'expression

Pour que vos tâches s'exécutent à 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 OR (||).
  2. Positionnement des arguments : vous devez placer le champ de métadonnées cible sur le côté gauche des fonctions. Par exemple, utilisez name.startsWith("live-") au lieu de "live-".startsWith(name).
  3. Méthodes de tableau : vous pouvez appeler directement la macro exists sur des champs répétés, tels que contexts.exists(...) ou metadata.exists(...).
  4. Limite de buckets : une seule tâche d'opérations de stockage par lot peut fonctionner sur un maximum de 1 000 buckets. Si vos expressions de filtre correspondent dynamiquement à plus de 1 000 buckets dans votre ensemble de données, la création de la tâche échoue. Utilisez des champs spécifiques au niveau du bucket (par exemple, le filtrage par zone géographique tel que location == "us-central1" ou la correspondance de noms telle que name.startsWith("prod-")) pour limiter la portée de votre requête et respecter cette limite.
  5. Limite de caractères : les filtres de bucket et les filtres d'objet sont limités à un maximum de 150 caractères chacun.

Exemples

Les exemples suivants présentent des filtres combinés courants que vous pouvez utiliser pour cibler des ressources à l'échelle du projet. Spécifiez directement les extraits de filtre 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 la zone géographique du bucket : appliquez des actions aux objets de la classe de stockage Standard dans les zones géographiques US : 

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

  • Filtrer par conservation associée à 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 extensions d'objet : recherchez les objets PDF de plus de 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')"

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

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

  • Faire correspondre des valeurs de contexte personnalisées par préfixe et suffixe : appliquez des actions aux objets dont une 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')"

Étape suivante