Filtrer les objets sources par préfixe

Ce guide explique comment utiliser les préfixes d'inclusion et d'exclusion pour contrôler les fichiers transférés.

Présentation

Le service de transfert de stockage permet de filtrer les données provenant des sources Amazon S3, Microsoft Azure Blob Storage et Cloud Storage à l'aide de préfixes. Un préfixe est une chaîne de caractères au début d'un chemin d'accès qui spécifie un ensemble d'objets.

Vous pouvez utiliser les filtres de préfixe de trois manières :

  • Inclure les préfixes : seuls les objets correspondant aux préfixes spécifiés sont transférés.

  • Exclure les préfixes : les objets correspondant aux préfixes spécifiés sont exclus du transfert.

  • Les deux à la fois : vous pouvez utiliser les préfixes d'inclusion et d'exclusion simultanément pour un contrôle plus précis. Lorsqu'ils sont utilisés ensemble, chaque préfixe d'exclusion doit commencer par l'un des préfixes d'inclusion spécifiés.

Si vous ne spécifiez aucun préfixe, tous les objets du bucket source sont transférés.

Les filtres de préfixe peuvent être combinés avec des schémas glob, des filtres d'heure de dernière modification et des filtres de classe de stockage S3.

Règles

Les règles suivantes s'appliquent aux préfixes :

  • Pas de barre oblique au début : n'incluez pas de barre oblique au début d'un préfixe. Pour le chemin d'accès s3://my-bucket/logs/2025/requests.gz, le préfixe correct est logs/2025/requests.gz.

  • Correspondances partielles : les préfixes fonctionnent par correspondance partielle. Par exemple, le préfixe path correspond à path_1/ et à path_2/.

  • Pas de caractères génériques : les caractères génériques ne sont pas acceptés.

  • Relatif au dossier source : si votre source de transfert inclut un chemin d'accès ou un dossier, les préfixes sont relatifs à ce chemin d'accès ou à ce dossier. Pour en savoir plus, consultez Interaction avec le chemin ou le dossier source.

  • Préfixes d'inclusion distincts : chaque préfixe d'inclusion doit définir une partie unique de l'espace de noms de l'objet. Vous ne pouvez pas utiliser un préfixe d'inclusion déjà couvert par un autre préfixe d'inclusion. Par exemple, vous ne pouvez pas spécifier à la fois data/ et data/reports/ comme préfixes d'inclusion.

  • Dépendance du préfixe d'exclusion : lorsque vous utilisez les préfixes d'inclusion et d'exclusion ensemble, chaque préfixe d'exclusion doit commencer par l'un des préfixes d'inclusion spécifiés. Par exemple, si path est un préfixe d'inclusion, les préfixes d'exclusion valides peuvent être path/b ou pathway. Cette règle ne s'applique pas si vous n'utilisez que des préfixes d'exclusion.

  • Maximum de 1 000 préfixes : une même tâche de transfert peut accepter jusqu'à 1 000 préfixes. Vous pouvez diviser un transfert en plusieurs tâches si des préfixes supplémentaires sont nécessaires.

Pour plus d'informations générales sur les préfixes, consultez la page Liste hiérarchique de clés grâce au préfixe et au délimiteur dans la documentation d'Amazon S3 ou la méthode de création d'une liste d'objets pour Cloud Storage.

Interaction avec d'autres types de filtres

Lorsque vous utilisez plusieurs filtres, le service de transfert de stockage les applique dans l'ordre suivant :

  1. Inclure les préfixes : limite les objets à prendre en compte.

  2. Conditions d'objet (schéma glob, heure de la dernière modification et classe de stockage S3) : filtre les objets correspondant au préfixe d'inclusion. Un objet doit correspondre à toutes les conditions d'objet spécifiées pour être inclus dans le transfert.

  3. Exclure les préfixes : supprime les objets du résultat.

En savoir plus sur le filtrage avec les expressions glob, l'heure de la dernière modification et la classe de stockage S3

Interaction avec le chemin d'accès ou le dossier source

Les filtres d'inclusion et d'exclusion sont relatifs à tout chemin ou dossier que vous spécifiez pour la source.

Par exemple, si votre source est gs://bucketA/alpha et que vous souhaitez spécifier un filtre pour gs://bucketA/alpha/beta :

Bonne réponse

  • Chemin de la source : gs://bucketA/alpha
  • Préfixe d'exclusion : beta/
  • Résultat : gs://bucketA/alpha/beta est correctement exclu.

Mauvaise réponse

  • Chemin de la source : gs://bucketA/alpha
  • Préfixe d'exclusion : alpha/beta/
  • Résultat : cela définit de manière incorrecte un filtre pour gs://bucketA/alpha/alpha/beta

Spécifier des préfixes

Cloud Console

Pour spécifier des préfixes d'inclusion et d'exclusion à l'aide de la console Google Cloud, saisissez les valeurs lorsque vous créez un transfert ou lorsque vous mettez à jour un transfert existant.

CLI gcloud

Pour spécifier les préfixes à inclure et à exclure à l'aide de la CLI gcloud, transmettez les options --include-prefixes et --exclude-prefixes à la commande gcloud transfer jobs create ou à la commande gcloud transfer jobs update :

gcloud transfer jobs create SOURCE DESTINATION \
  --include-prefixes="path_1/,path_2/" --exclude-prefixes="path_1/subpath_2/"

Séparez les différents préfixes par une virgule, sans laisser d'espace après la virgule. Par exemple, --include-prefixes="foo,bar".

REST

Pour spécifier des préfixes d'inclusion et d'exclusion à l'aide de l'API REST, utilisez les champs includePrefixes[] et excludePrefixes[] :

{
    "description": "Transfer with prefixes",
    "status": "ENABLED",
    "projectId": "PROJECT_ID",
    "schedule": {
        "scheduleStartDate": {
            "day": 1,
            "month": 1,
            "year": 2015
        },
        "startTimeOfDay": {
            "hours": 1,
            "minutes": 1
        }
    },
    "transferSpec": {
        "gcsDataSource": {
            "bucketName": "SOURCE_BUCKET"
        },
        "gcsDataSink": {
            "bucketName": "DESTINATION_BUCKET"
        },
        "transferOptions": {
            "deleteObjectsFromSourceAfterTransfer": true
        },
        "objectConditions": {
            "includePrefixes": [
                "path_1/",
                "path_2/"
            ],
            "excludePrefixes": [
                "path_1/subpath_2/object_5"
            ]
        }
    }
}

Pour en savoir plus, consultez la documentation de référence sur ObjectConditions.

Exemples d'objets et de chemins d'accès

Les exemples suivants utilisent cet exemple de liste d'objets :

xx://bucketname/object_1
xx://bucketname/object_2
xx://bucketname/path_1/object_3
xx://bucketname/path_1/subpath_1/object_4
xx://bucketname/path_1/subpath_2/object_5
xx://bucketname/path_2/object_6
xx://bucketname/path_2/subpath_3/object_7
xx://bucketname/path_2/subpath_4/object_8

Utiliser des préfixes d'inclusion

Pour transférer uniquement les objets sous path_1/, utilisez le préfixe suivant :

path_1/

Cela inclut les objets sous path_1/. Les objets suivants sont inclus dans le transfert :

xx://bucketname/object_1
xx://bucketname/object_2
xx://bucketname/path_1/object_3
xx://bucketname/path_1/subpath_1/object_4
xx://bucketname/path_1/subpath_2/object_5
xx://bucketname/path_2/object_6
xx://bucketname/path_2/subpath_3/object_7
xx://bucketname/path_2/subpath_4/object_8

Vous pouvez spécifier plusieurs chemins à inclure. Par exemple, vous pouvez transmettre les éléments suivants :

path_1/subpath_2/
path_1/subpath_3/

Dans ce cas, le transfert inclut les objets suivants :

xx://bucketname/object_1
xx://bucketname/object_2
xx://bucketname/path_1/object_3
xx://bucketname/path_1/subpath_1/object_4
xx://bucketname/path_1/subpath_2/object_5
xx://bucketname/path_2/object_6
xx://bucketname/path_2/subpath_3/object_7
xx://bucketname/path_2/subpath_4/object_8

Les correspondances partielles sont acceptées. Exemple :

path

Les objets suivants sont transférés :

xx://bucketname/object_1
xx://bucketname/object_2
xx://bucketname/path_1/object_3
xx://bucketname/path_1/subpath_1/object_4
xx://bucketname/path_1/subpath_2/object_5
xx://bucketname/path_2/object_6
xx://bucketname/path_2/subpath_3/object_7
xx://bucketname/path_2/subpath_4/object_8

Lorsque vous utilisez des préfixes d'inclusion, les chemins que vous n'incluez pas spécifiquement ne sont pas transférés vers le bucket de destination Cloud Storage.

Exclure des préfixes

L'utilisation de préfixes d'exclusion lors de la création d'un transfert indique au service de transfert de stockage d'ignorer les chemins d'accès répertoriés pour le transfert.

Pour exclure des objets sous path_1/, transmettez le préfixe suivant :

path_1/

Cela exclut les objets sous path_1/. Dans ce cas, les objets suivants sont inclus dans le transfert :

xx://bucketname/object_1
xx://bucketname/object_2
xx://bucketname/path_1/object_3
xx://bucketname/path_1/subpath_1/object_4
xx://bucketname/path_1/subpath_2/object_5
xx://bucketname/path_2/object_6
xx://bucketname/path_2/subpath_3/object_7
xx://bucketname/path_2/subpath_4/object_8

Vous pouvez spécifier plusieurs chemins d'accès à exclure. Par exemple, vous pouvez transmettre les éléments suivants :

path_1/subpath_2/
path_2/subpath_3/

Dans ce cas, le transfert inclut les objets suivants :

xx://bucketname/object_1
xx://bucketname/object_2
xx://bucketname/path_1/object_3
xx://bucketname/path_1/subpath_1/object_4
xx://bucketname/path_1/subpath_2/object_5
xx://bucketname/path_2/object_6
xx://bucketname/path_2/subpath_3/object_7
xx://bucketname/path_2/subpath_4/object_8

Inclure et exclure simultanément des chemins d'accès

Vous pouvez appliquer conjointement un préfixe d'exclusion et un préfixe d'inclusion, auquel cas le préfixe d'exclusion limite ce que le préfixe d'inclusion inclut dans le transfert.

Lorsque vous spécifiez les deux types de préfixes, chaque préfixe d'exclusion doit commencer par un chemin d'accès spécifié dans un préfixe d'inclusion.

Par exemple, pour inclure des objets sous path_1/ et exclure des objets sous subpath_1/, transmettez ce qui suit :

include: path_1/
exclude: path_1/subpath_1/

Dans ce cas, le transfert inclut les objets suivants :

xx://bucketname/object_1
xx://bucketname/object_2
xx://bucketname/path_1/object_3
xx://bucketname/path_1/subpath_1/object_4
xx://bucketname/path_1/subpath_2/object_5
xx://bucketname/path_2/object_6
xx://bucketname/path_2/subpath_3/object_7
xx://bucketname/path_2/subpath_4/object_8

Pour inclure tous les objets sous path_1/ et path_2/, à l'exception des éléments dans path_1/subpath_1/ ou path_2/subpath_3/, transmettez ce qui suit :

include: path_1/
         path_2/
exclude: path_1/subpath_1/
         path_2/subpath_3/

Dans ce cas, le transfert inclut les objets suivants :

xx://bucketname/object_1
xx://bucketname/object_2
xx://bucketname/path_1/object_3
xx://bucketname/path_1/subpath_1/object_4
xx://bucketname/path_1/subpath_2/object_5
xx://bucketname/path_2/object_6
xx://bucketname/path_2/subpath_3/object_7
xx://bucketname/path_2/subpath_4/object_8

Erreurs courantes à éviter

Voici des exemples de configurations incorrectes et comment les corriger.

Inclure un chemin d'accès utilisé dans un autre préfixe "include-prefix"

Un préfixe d'inclusion ne peut pas être un sous-répertoire d'un autre préfixe d'inclusion.

Incorrect : Le préfixe path_1/subpath_1 est déjà couvert par path_1/.

include: path_1/
         path_1/subpath_1

Correct : pour résoudre ce problème, supprimez le préfixe redondant et plus spécifique.

include: path_1/

Le préfixe d'exclusion ne correspond pas à un préfixe d'inclusion

Lorsqu'ils sont utilisés ensemble, un préfixe d'exclusion doit commencer par l'un des préfixes d'inclusion.

Incorrect : le préfixe subpath_1 ne commence pas par path_1/ ni par path_2/.

include: path_1/
         path_2/
exclude: subpath_1

Correct : assurez-vous que le préfixe d'exclusion contient le chemin d'accès complet à partir d'un préfixe d'inclusion.

include: path_1/
         path_2/
exclude: path_1/subpath_1/