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
pathcorrisponde sia apath_1/sia apath_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/chedata/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 esserepath/bopathway. 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:
- Includi prefissi: restringe gli oggetti da considerare.
- 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.
- 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/betaviene 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_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
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_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
Sono supportate le corrispondenze parziali. Ad esempio:
path
Vengono trasferiti i seguenti oggetti:
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
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_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
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_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
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_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
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_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
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/