Filtra per prefisso

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

Panoramica

Storage Transfer Service consente di filtrare i 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 per prefisso 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 insieme: puoi utilizzare contemporaneamente i prefissi di inclusione ed esclusione per un controllo più granulare. Se utilizzati insieme, tutti i prefissi di esclusione devono iniziare con uno dei prefissi di inclusione specificati.

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

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 con la 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.

• Rispetto alla cartella di origine: se l'origine del trasferimento è una cartella specifica, i prefissi vengono valutati rispetto a quella cartella. Per una sorgente di gs://my-bucket/data/, un prefisso di inclusione di reports corrisponde a tutti i file in gs://my-bucket/data/reports.

• Prefissi di inclusione 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 da includere.

• Escludi dipendenza dal prefisso: quando utilizzi insieme i prefissi di inclusione ed esclusione, 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 i prefissi di esclusione.

• Massimo 1000 prefissi: un singolo job di trasferimento supporta fino a 1000 prefissi. Puoi dividere un trasferimento in più job se sono necessari prefissi aggiuntivi.

Per informazioni più generali sui prefissi, consulta Elenco gerarchico delle chiavi utilizzando un prefisso e un delimitatore nella documentazione di Amazon S3 o il metodo di elenco degli oggetti per Cloud Storage.

Come specificare i prefissi

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

{
    "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"
            ]
        }
    }
}

Esempi di oggetti e percorsi

Gli esempi riportati di seguito 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

Utilizzare 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_1/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 di destinazione Cloud Storage.

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, nel trasferimento sono inclusi 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

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

Includere ed escludere i percorsi contemporaneamente

Puoi applicare insieme un prefisso di esclusione e un prefisso di inclusione, nel qual 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 quelli 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 correggerle.

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.

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

include: path_1/
         path_1/subpath_1

Correzione: per risolvere il problema, rimuovi il prefisso ridondante e 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.

Errato: 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 da un prefisso di inclusione.

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