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 vous 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.
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 estlogs/2025/requests.gz.Correspondances partielles : les préfixes fonctionnent par correspondance partielle. Par exemple, le préfixe
pathcorrespond à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 est un dossier spécifique, les préfixes sont évalués par rapport à ce dossier. Pour une source
gs://my-bucket/data/, un préfixe d'inclusionreportscorrespond à tous les fichiers sousgs://my-bucket/data/reports.Préfixes d'inclusion distincts : chaque préfixe d'inclusion doit définir une partie unique de l'espace de noms d'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/etdata/reports/comme préfixes d'inclusion.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.1 000 préfixes maximum : 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.
Spécifier des préfixes
Cloud Console
Pour spécifier des préfixes d'inclusion et d'exclusion à l'aide de la console Cloud, saisissez les valeurs lorsque vous créez un transfert ou lorsque vous mettez à jour un transfert existant.
gcloud CLI
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 des virgules, sans laisser d'espace après les virgules.
Par exemple, --include-prefixes="foo,bar".
REST
Pour spécifier les préfixes d'inclusion et d'exclusion à l'aide de l'API REST, utilisez les champs includePrefixes[] et excludePrefixes[] :
{
"description": "YOUR DESCRIPTION",
"status": "ENABLED",
"projectId": "PROJECT_ID",
"schedule": {
"scheduleStartDate": {
"day": 1,
"month": 1,
"year": 2015
},
"startTimeOfDay": {
"hours": 1,
"minutes": 1
}
},
"transferSpec": {
"gcsDataSource": {
"bucketName": "GCS_SOURCE_NAME"
},
"gcsDataSink": {
"bucketName": "GCS_SINK_NAME"
},
"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_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_1/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 que vous n'incluez pas spécifiquement ne sont pas transférés vers le bucket de destination Cloud Storage.
Exclure les 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_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 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_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 "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 d'un préfixe d'inclusion.
include: path_1/
path_2/
exclude: path_1/subpath_1/