Filtrare gli oggetti di origine in base al prefisso

Questa guida spiega come utilizzare i prefissi di inclusione ed esclusione per controllare quali file vengono trasferiti.

Panoramica

Storage Transfer Service supporta il filtraggio dei dati dalle origini Amazon S3, Microsoft Azure Blob Storage e Cloud Storage utilizzando i prefissi. Un prefisso è una stringa di caratteri all'inizio di un percorso che specifica un insieme di oggetti.

Puoi utilizzare i filtri dei prefissi in tre modi:

  • Includi prefissi: vengono trasferiti solo gli oggetti che corrispondono ai prefissi specificati.

  • Escludi prefissi: gli oggetti che corrispondono ai prefissi specificati vengono omessi dal trasferimento.

  • Entrambi: puoi utilizzare contemporaneamente i prefissi di inclusione ed esclusione per un controllo più granulare. Se utilizzati insieme, ogni prefisso di esclusione deve iniziare con uno dei prefissi di inclusione specificati.

Se non specifichi alcun prefisso, vengono trasferiti tutti gli oggetti nel bucket di origine.

I filtri per prefisso possono essere combinati con pattern glob, filtri per ora dell'ultima modifica e filtri per classe di archiviazione S3.

Regole

Ai prefissi si applicano le seguenti regole:

  • Nessuna barra iniziale: non includere una barra iniziale in un prefisso. Per il percorso s3://my-bucket/logs/2025/requests.gz, il prefisso corretto è logs/2025/requests.gz.

  • Corrispondenze parziali: i prefissi funzionano tramite corrispondenza parziale. Ad esempio, il prefisso path corrisponde sia a path_1/ sia a path_2/.

  • Nessun carattere jolly: i caratteri jolly non sono supportati.

  • Relativo alla cartella di origine: se l'origine del trasferimento include un percorso o una cartella, i prefissi sono relativi a quel percorso o a quella cartella. Per maggiori dettagli, consulta Interazione con il percorso o la cartella di origine.

  • Prefissi distinti: ogni prefisso di inclusione deve definire una parte univoca dello spazio dei nomi dell'oggetto. Non puoi utilizzare un prefisso di inclusione già coperto da un altro prefisso di inclusione. Ad esempio, non puoi specificare sia data/ che data/reports/ come prefissi di inclusione. La stessa regola si applica ai prefissi di esclusione.

  • Dipendenza del prefisso di esclusione: quando utilizzi i prefissi di inclusione ed esclusione insieme, ogni prefisso di esclusione deve iniziare con uno dei prefissi di inclusione specificati. Ad esempio, se path è un prefisso di inclusione, i prefissi di esclusione validi potrebbero essere path/b o pathway. Questa regola non si applica se utilizzi solo prefissi di esclusione.

  • Massimo 1000 prefissi di ogni tipo: un singolo job di trasferimento supporta fino a 1000 prefissi di inclusione e fino a 1000 prefissi di esclusione. Se sono necessari prefissi aggiuntivi, puoi suddividere un trasferimento in più job.

Per informazioni più generali sui prefissi, consulta Listing Keys Hierarchically Using a Prefix and Delimiter nella documentazione di Amazon S3 o il metodo Objects list per Cloud Storage.

Interazione con altri tipi di filtri

Quando utilizzi più filtri, Storage Transfer Service li applica nel seguente ordine:

  1. Includi prefissi: restringe gli oggetti da considerare.
  2. Condizioni degli oggetti (pattern glob, ora dell'ultima modifica e classe di archiviazione S3): filtra gli oggetti che corrispondono al prefisso di inclusione. Un oggetto deve soddisfare tutte le condizioni specificate per essere incluso nel trasferimento.
  3. Escludi prefissi: rimuove gli oggetti dal risultato.

Scopri di più sui filtri con pattern glob, ora dell'ultima modifica e classe di archiviazione S3.

Interazione con il percorso o la cartella di origine

I filtri di inclusione ed esclusione sono relativi a qualsiasi percorso o cartella specificato per l'origine.

Ad esempio, se l'origine è gs://bucketA/alpha e vuoi specificare un filtro per gs://bucketA/alpha/beta:

Risposta esatta

  • Percorso di origine: gs://bucketA/alpha
  • Prefisso da escludere: beta/
  • Risultato: gs://bucketA/alpha/beta viene escluso correttamente

Risposta errata

  • Percorso di origine: gs://bucketA/alpha
  • Prefisso da escludere: alpha/beta/
  • Risultato: questo definisce in modo errato un filtro per gs://bucketA/alpha/alpha/beta

Specifica i prefissi

Console Google Cloud

Per specificare i prefissi di inclusione ed esclusione utilizzando la consoleGoogle Cloud , inserisci i valori quando crei un nuovo trasferimento o quando aggiorni un trasferimento esistente.

gcloud CLI

Per specificare i prefissi di inclusione ed esclusione utilizzando l'interfaccia a riga di comando gcloud, passa i flag --include-prefixes e --exclude-prefixes al comando gcloud transfer jobs create o al comando gcloud transfer jobs update:

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

Separa più prefissi con virgole, omettendo gli spazi dopo le virgole. Ad esempio, --include-prefixes="foo,bar".

REST

Per specificare i prefissi di inclusione ed esclusione utilizzando l'API REST, utilizza i campi includePrefixes[] e 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"
            ]
        }
    }
}

Per saperne di più, consulta il riferimento ObjectConditions.

Esempi di oggetti e percorsi

Gli esempi seguenti utilizzano questo elenco di oggetti di esempio:

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

Utilizza i prefissi di inclusione

Per trasferire solo gli oggetti in path_1/, utilizza il seguente prefisso:

path_1/

Sono inclusi gli oggetti in path_1/. I seguenti oggetti sono inclusi nel trasferimento:

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

Puoi specificare più percorsi da includere. Ad esempio, puoi passare quanto segue:

path_1/subpath_2/
path_2/subpath_3/

In questo caso, il trasferimento include i seguenti oggetti:

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

Sono supportate le corrispondenze parziali. Ad esempio:

path

Vengono trasferiti i seguenti oggetti:

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

Quando utilizzi i prefissi di inclusione, i percorsi che non includi in modo specifico non vengono trasferiti al bucket Cloud Storage di destinazione.

Escludi prefissi

L'utilizzo di prefissi da escludere durante la creazione di un trasferimento indica a Storage Transfer Service di ignorare i percorsi elencati per il trasferimento.

Per escludere gli oggetti in path_1/, passa il seguente prefisso:

path_1/

Sono esclusi gli oggetti in path_1/. In questo caso, i seguenti oggetti sono inclusi nel trasferimento:

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

Puoi specificare più percorsi da escludere. Ad esempio, puoi passare quanto segue:

path_1/subpath_2/
path_2/subpath_3/

In questo caso, il trasferimento include i seguenti oggetti:

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

Inclusione ed esclusione simultanea dei percorsi

Puoi applicare un prefisso di esclusione e un prefisso di inclusione insieme. In questo caso, il prefisso di esclusione limita ciò che il prefisso di inclusione include nel trasferimento.

Quando specifichi entrambi i tipi di prefisso, ogni prefisso di esclusione deve iniziare con un percorso specificato in un prefisso di inclusione.

Ad esempio, per includere gli oggetti in path_1/ ed escludere gli oggetti in subpath_1/, passa quanto segue:

include: path_1/
exclude: path_1/subpath_1/

In questo caso, il trasferimento include i seguenti oggetti:

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

Per includere tutti gli oggetti in path_1/ e path_2/, ad eccezione degli elementi in path_1/subpath_1/ o path_2/subpath_3/, passa quanto segue:

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

In questo caso, il trasferimento include i seguenti oggetti:

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

Errori comuni da evitare

Ecco alcuni esempi di configurazioni errate e come risolverle.

Inclusione di un percorso utilizzato in un altro prefisso di inclusione

Un prefisso di inclusione non può essere una sottodirectory di un altro prefisso di inclusione.

Non corretto: il prefisso path_1/subpath_1 è già coperto da path_1/.

include: path_1/
         path_1/subpath_1

Corretto: per risolvere il problema, rimuovi il prefisso ridondante più specifico.

include: path_1/

Il prefisso di esclusione non corrisponde a un prefisso di inclusione

Se utilizzati insieme, un prefisso di esclusione deve iniziare con uno dei prefissi di inclusione.

Non corretto: il prefisso subpath_1 non inizia con path_1/ o path_2/.

include: path_1/
         path_2/
exclude: subpath_1

Corretto: assicurati che il prefisso di esclusione contenga il percorso completo di un prefisso di inclusione.

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