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 de 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 des 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 : vous pouvez utiliser simultanément des préfixes d'inclusion et d'exclusion 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 modèles glob, des filtres de date 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 barres obliques 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 estlogs/2025/requests.gz.Correspondances partielles : les préfixes fonctionnent par correspondance partielle. Par exemple, le préfixe
pathcorrespond à la fois àpath_1/et àpath_2/.Pas de caractères génériques : les caractères génériques ne sont pas acceptés.
Par rapport 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 d'accès ou le dossier source.
Préfixes 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 qui est déjà couvert par un autre préfixe d'inclusion. Par exemple, vous ne pouvez pas spécifier à la fois
data/etdata/reports/comme préfixes d'inclusion. La même règle s'applique aux préfixes d'exclusion.Dépendance du préfixe d'exclusion : lorsque vous utilisez des 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
pathest un préfixe d'inclusion, les préfixes d'exclusion valides peuvent êtrepath/boupathway. Cette règle ne s'applique pas si vous n'utilisez que des préfixes d'exclusion.Maximum de 1 000 préfixes de chaque type : un seul job de transfert accepte jusqu'à 1 000 préfixes d'inclusion et jusqu'à 1 000 préfixes d'exclusion. Vous pouvez diviser un transfert en plusieurs jobs si des préfixes supplémentaires sont requis.
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 :
- Inclure des préfixes : permet d'affiner les objets à prendre en compte.
- Conditions d'objet (modèle glob, date de dernière modification et classe de stockage S3) : filtre les objets qui correspondent au préfixe d'inclusion. Un objet doit remplir toutes les conditions spécifiées pour être inclus dans le transfert.
- Exclure les préfixes : supprime des objets du résultat.
En savoir plus sur le filtrage avec des modèles 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 d'accès 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 d'accès source :
gs://bucketA/alpha - Exclure le préfixe :
beta/ - Résultat :
gs://bucketA/alpha/betaest correctement exclu.
Incorrect
- Chemin d'accès source :
gs://bucketA/alpha - Exclure le préfixe :
alpha/beta/ - Résultat : cela définit de manière incorrecte un filtre pour
gs://bucketA/alpha/alpha/beta
Spécifier des préfixes
Console Google Cloud
Pour spécifier des préfixes d'inclusion et d'exclusion à l'aide de la consoleGoogle Cloud , saisissez les valeurs lors de la création d'un transfert ou de la mise à jour d'un transfert existant.
gcloud CLI
Pour spécifier des préfixes d'inclusion et d'exclusion à l'aide de la CLI gcloud, transmettez les options --include-prefixes et --exclude-prefixes à la commande gcloud transfer jobs create ou 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 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 ne transférer que 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_1xx://bucketname/object_2xx://bucketname/path_1/object_3 xx://bucketname/path_1/subpath_1/object_4 xx://bucketname/path_1/subpath_2/object_5xx://bucketname/path_2/object_6xx://bucketname/path_2/subpath_3/object_7xx://bucketname/path_2/subpath_4/object_8
Vous pouvez spécifier plusieurs chemins d'accès à inclure. 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_1xx://bucketname/object_2xx://bucketname/path_1/object_3xx://bucketname/path_1/subpath_1/object_4xx://bucketname/path_1/subpath_2/object_5xx://bucketname/path_2/object_6xx://bucketname/path_2/subpath_3/object_7xx://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_1xx://bucketname/object_2xx://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 d'accès que vous n'incluez pas spécifiquement ne sont pas transférés vers le bucket Cloud Storage de destination.
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 listés pour le transfert.
Pour exclure les 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_2xx://bucketname/path_1/object_3xx://bucketname/path_1/subpath_1/object_4xx://bucketname/path_1/subpath_2/object_5xx://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_4xx://bucketname/path_1/subpath_2/object_5xx://bucketname/path_2/object_6xx://bucketname/path_2/subpath_3/object_7xx://bucketname/path_2/subpath_4/object_8
Inclure et exclure simultanément des chemins d'accès
Vous pouvez appliquer un préfixe d'exclusion et un préfixe d'inclusion ensemble. Dans ce 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_1xx://bucketname/object_2xx://bucketname/path_1/object_3xx://bucketname/path_1/subpath_1/object_4xx://bucketname/path_1/subpath_2/object_5xx://bucketname/path_2/object_6xx://bucketname/path_2/subpath_3/object_7xx://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_1xx://bucketname/object_2xx://bucketname/path_1/object_3xx://bucketname/path_1/subpath_1/object_4xx://bucketname/path_1/subpath_2/object_5 xx://bucketname/path_2/object_6xx://bucketname/path_2/subpath_3/object_7xx://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 d'inclusion
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 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 ni 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/