Filtrer par préfixe

Cette page vous explique comment inclure et exclure des chemins dans les correspondances à l'aide de préfixes d'inclusion et d'exclusion.

Pour savoir comment créer un fichier manifeste d'objets spécifiques à transférer, consultez la section Transférer des fichiers ou des objets spécifiques à l'aide d'un fichier manifeste.

Présentation

Le service de transfert de stockage accepte l'utilisation de préfixes pour sélectionner les fichiers à inclure ou à exclure de la source de données. Vous pouvez utiliser des préfixes d'inclusion et/ou d'exclusion.

Le filtrage par préfixe est compatible avec les sources de données Amazon S3, Microsoft Azure Blob Storage et Cloud Storage.

  • N'incluez pas de barre oblique au début d'un préfixe. Par exemple, pour inclure l'objet requests.gz dans un transfert depuis le chemin d'accès au bucket s3://my-aws-bucket/logs/y=2015/requests.gz, spécifiez le préfixe d'inclusion logs/y=2015/requests.gz.

  • Les correspondances partielles sont acceptées pour les préfixes d'inclusion et d'exclusion. Par exemple, path correspond à path_1/ et path_2/.

  • Les caractères génériques ne peuvent pas être utilisés.

  • Si vous avez spécifié un dossier comme emplacement source, les filtres de préfixe sont relatifs à ce dossier. Par exemple, si votre source est gs://my-test-bucket/path/, un filtre d'inclusion de file inclut tous les fichiers commençant par gs://my-test-bucket/path/file.

  • Chaque préfixe d'inclusion doit inclure une partie distincte de l'espace de noms de l'objet. Aucun préfixe d'inclusion ne peut être le préfixe d'un autre préfixe d'inclusion. Par exemple, vous ne pouvez pas spécifier à la fois path_1 et path_1/subpath_2 comme préfixes d'inclusion.

  • Si vous utilisez les préfixes d'inclusion et d'exclusion ensemble, les préfixes d'exclusion doivent commencer par la valeur de l'un des préfixes d'inclusion. Par exemple, si vous spécifiez le préfixe d'inclusion a, les préfixes d'exclusion valides sont a/b, aaa et abc.

  • Si vous n'utilisez que des préfixes d'exclusion, aucune restriction ne s'applique aux préfixes que vous pouvez utiliser.

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

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

console Cloud

Pour spécifier des préfixes d'inclusion et d'exclusion à l'aide de la console Cloud, saisissez les valeurs correspondantes 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, en omettant les espaces après les virgules. 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": "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 de ce document s'appuient sur les exemples d'objets et de chemins d'accès suivants :

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

Inclure des préfixes

Lors de la création d'un transfert, utilisez des préfixes d'inclusion pour indiquer au service de transfert de stockage de prendre en compte les objets se trouvant dans les chemins d'accès répertoriés pour le transfert et d'ignorer les objets ne se trouvant pas dans ces chemins.

Par exemple, pour inclure des objets sous path_1/, utilisez le préfixe suivant:

path_1/

Cela inclut les objets directement sous path_1/, path_1/subpath_1 et path_1/subpath_2/. 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_2/object_4
xx://bucketname/path_1/subpath_1/object_5
xx://bucketname/path_1/subpath_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 à 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_2/object_4
xx://bucketname/path_1/subpath_1/object_5
xx://bucketname/path_1/subpath_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. Par exemple, spécifier path comme valeur d'un préfixe d'inclusion correspond aux objets suivants:

xx://bucketname/object_1
xx://bucketname/object_2
xx://bucketname/path_1/object_3
xx://bucketname/path_2/object_4
xx://bucketname/path_1/subpath_1/object_5
xx://bucketname/path_1/subpath_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 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/, path_1/subpath_1/ et path_1/subpath_2/. 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_2/object_4
xx://bucketname/path_1/subpath_1/object_5
xx://bucketname/path_1/subpath_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_2/object_4
xx://bucketname/path_1/subpath_1/object_5
xx://bucketname/path_1/subpath_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 simultanément un préfixe d'exclusion et un préfixe d'inclusion. Dans ce cas, le préfixe d'exclusion limite ce qu'il 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_2/object_4
xx://bucketname/path_1/subpath_1/object_5
xx://bucketname/path_1/subpath_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_2/object_4
xx://bucketname/path_1/subpath_1/object_5
xx://bucketname/path_1/subpath_2/object_6
xx://bucketname/path_2/subpath_3/object_7
xx://bucketname/path_2/subpath_4/object_8

Exemples d'inclusion ou d'exclusion incorrecte de chemins d'accès

Les sections suivantes incluent des exemples à éviter lors de l'utilisation de l'inclusion ou de l'exclusion de chemins, et indiquent comment les corriger pour aboutir à un fonctionnement correct.

Inclure un chemin utilisé dans un autre préfixe d'inclusion

Chaque préfixe d'inclusion doit spécifier une partie distincte de l'espace de noms de l'objet. L'exemple suivant est incorrect, car la deuxième valeur est déjà incluse dans l'espace de noms de la première valeur :

include: path_1/
         path_1/subpath_1

Dans cet exemple, les valeurs de préfixe d'inclusion ne sont pas valides, car le deuxième préfixe d'inclusion, path_1/subpath_1, est déjà inclus dans path_1/. Pour résoudre ce problème, supprimez l'une des valeurs.

Utiliser un préfixe d'exclusion qui ne commence pas par un préfixe d'inclusion

Chaque préfixe d'exclusion doit commencer par l'une des valeurs de préfixe d'inclusion spécifiées. L'exemple suivant est incorrect, car les valeurs de préfixe d'exclusion ne commencent pas par les valeurs de préfixe d'inclusion spécifiées:

include: path_1/
         path_2/
exclude: subpath_1
         subpath_4

Dans cet exemple, les valeurs de préfixe d'exclusion ne sont pas valides, car elles ne commencent par aucune des valeurs de préfixe d'inclusion. Pour résoudre ce problème, assurez-vous que le préfixe d'exclusion inclut un chemin d'accès complet listé en tant que préfixe d'inclusion:

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

Étapes suivantes