In dieser Anleitung wird beschrieben, wie Sie mit ein- und ausschließenden Präfixen steuern, welche Dateien übertragen werden.
Übersicht
Mit dem Storage Transfer Service können Sie Daten aus Amazon S3-, Microsoft Azure Blob Storage- und Cloud Storage-Quellen mithilfe von Präfixen filtern. Ein Präfix ist eine Zeichenfolge am Anfang eines Pfads, die eine Gruppe von Objekten angibt.
Sie haben drei Möglichkeiten, Präfixfilter zu verwenden:
Präfixe einschließen: Es werden nur Objekte übertragen, die mit den angegebenen Präfixen übereinstimmen.
Präfixe ausschließen: Objekte, die den angegebenen Präfixen entsprechen, werden bei der Übertragung ausgelassen.
Beide zusammen: Sie können einschließende und ausschließende Präfixe gleichzeitig verwenden, um die Steuerung zu optimieren. Wenn sie zusammen verwendet werden, muss jedes Ausschlusspräfix mit einem der angegebenen Einschlusspräfixe beginnen.
Wenn Sie keine Präfixe angeben, werden alle Objekte im Quell-Bucket übertragen.
Regeln
Für Präfixe gelten die folgenden Regeln:
Keine Schrägstriche am Anfang: Lassen Sie bei der Eingabe eines Präfixes den Schrägstrich am Anfang weg. Für den Pfad
s3://my-bucket/logs/2025/requests.gzist das richtige Präfixlogs/2025/requests.gz.Teilweise Übereinstimmungen: Präfixe funktionieren durch teilweise Übereinstimmung. Das Präfix
pathentspricht beispielsweise sowohlpath_1/als auchpath_2/.Keine Platzhalter: Platzhalter werden nicht unterstützt.
Relativ zum Quellordner: Wenn Ihre Übertragungsquelle ein bestimmter Ordner ist, werden Präfixe relativ zu diesem Ordner ausgewertet. Bei einer Quelle von
gs://my-bucket/data/entspricht ein einschließendes Präfix vonreportsallen Dateien untergs://my-bucket/data/reports.Eindeutige Include-Präfixe: Jedes Include-Präfix muss einen eindeutigen Teil des Objekt-Namespace definieren. Sie können kein includePrefix verwenden, das bereits von einem anderen includePrefix abgedeckt wird. Sie können beispielsweise nicht sowohl
data/als auchdata/reports/als einschließende Präfixe angeben.Abhängigkeit von ausschließenden Präfixen: Wenn Sie einschließende und ausschließende Präfixe zusammen verwenden, muss jedes ausschließende Präfix mit einem der angegebenen einschließenden Präfixe beginnen. Wenn
pathbeispielsweise ein einschließendes Präfix ist, können die ausschließenden Präfixepath/boderpathwaylauten. Diese Regel gilt nicht, wenn Sie nur ausschließende Präfixe verwenden.Maximal 1.000 Präfixe: Ein einzelner Übertragungsjob unterstützt bis zu 1.000 Präfixe. Sie können eine Übertragung in mehrere Jobs aufteilen, wenn zusätzliche Präfixe erforderlich sind.
Allgemeine Informationen zu Präfixen finden Sie in der Amazon S3-Dokumentation unter Hierarchische Auflistung von Schlüsseln mit einem Präfix und einem Trennzeichen oder in der Objektlistemethode für Cloud Storage.
Präfixe angeben
Cloud Console
Wenn Sie Ein- und Ausschlusspräfixe über die Cloud Console angeben möchten, geben Sie die Werte beim Erstellen einer neuen Übertragung oder beim Aktualisieren einer vorhandenen Übertragung ein.
gcloud-CLI
Wenn Sie Ein- und Ausschlusspräfixe mit der gcloud CLI angeben möchten, übergeben Sie die Flags --include-prefixes und --exclude-prefixes an den Befehl gcloud transfer jobs create oder den Befehl gcloud transfer jobs update:
gcloud transfer jobs create SOURCE DESTINATION \
--include-prefixes="path_1/,path_2/" --exclude-prefixes="path_1/subpath_2/"
Trennen Sie mehrere Präfixe durch Kommas, ohne Leerzeichen nach den Kommas.
Beispiel: --include-prefixes="foo,bar".
REST
Wenn Sie Ein- und Ausschlusspräfixe über die REST API angeben möchten, verwenden Sie die Felder includePrefixes[] und 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"
]
}
}
}
Weitere Informationen finden Sie in der Referenz zu ObjectConditions.
Beispielobjekte und -pfade
In den folgenden Beispielen wird diese Beispielliste von Objekten verwendet:
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
Präfixe für Einbeziehung verwenden
Wenn Sie nur Objekte unter path_1/ übertragen möchten, verwenden Sie das folgende Präfix:
path_1/
Dazu gehören Objekte unter path_1/. Die folgenden Objekte sind in der Übertragung enthalten:
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
Sie können mehrere Pfade angeben, die einbezogen werden sollen. Sie können beispielsweise Folgendes übergeben:
path_1/subpath_2/ path_1/subpath_3/
In diesem Fall umfasst die Übertragung die folgenden Objekte:
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
Teilweise Übereinstimmungen werden unterstützt. Beispiel:
path
Die folgenden Objekte werden übertragen:
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
Wenn Sie einschließende Präfixe verwenden, werden Pfade, die Sie nicht explizit einschließen, nicht in den Cloud Storage-Ziel-Bucket übertragen.
Präfixe ausschließen
Wenn Sie beim Erstellen einer Übertragung auszuschließende Präfixe verwenden, wird der Storage Transfer Service angewiesen, die aufgeführten Pfade für die Übertragung zu ignorieren.
Wenn Sie Objekte unter path_1/ ausschließen möchten, übergeben Sie das folgende Präfix:
path_1/
Dadurch werden Objekte unter path_1/ ausgeschlossen. In diesem Fall sind die folgenden Objekte in der Übertragung enthalten:
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
Sie können mehrere auszuschließende Pfade angeben. Sie können beispielsweise Folgendes übergeben:
path_1/subpath_2/
path_2/subpath_3/
In diesem Fall umfasst die Übertragung die folgenden Objekte:
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
Gleichzeitig Pfade ein- und ausschließen
Sie können ein ausschließendes und ein einschließendes Präfix zusammen anwenden. In diesem Fall wird mit dem ausschließenden Präfix begrenzt, was das einschließende Präfix in die Übertragung einschließt.
Wenn Sie beide Arten von Präfix angeben, muss jedes Ausschlusspräfix mit einem Pfad beginnen, der in einem Einschlusspräfix angegeben ist.
Wenn Sie beispielsweise Objekte unter path_1/ einschließen und Objekte unter subpath_1/ ausschließen möchten, übergeben Sie Folgendes:
include: path_1/
exclude: path_1/subpath_1/
In diesem Fall umfasst die Übertragung die folgenden Objekte:
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
Wenn Sie alle Objekte unter path_1/ und path_2/ einschließen möchten, außer Elemente in path_1/subpath_1/ oder path_2/subpath_3/, übergeben Sie Folgendes:
include: path_1/
path_2/
exclude: path_1/subpath_1/
path_2/subpath_3/
In diesem Fall umfasst die Übertragung die folgenden Objekte:
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
Zu vermeidende häufige Fehler
Hier finden Sie Beispiele für falsche Konfigurationen und Informationen dazu, wie Sie diese beheben können.
Pfad einschließen, der in einem anderen includePrefix verwendet wird
Ein Include-Präfix darf kein Unterverzeichnis eines anderen Include-Präfix sein.
Falsch: Das Präfix path_1/subpath_1 wird bereits durch path_1/ abgedeckt.
include: path_1/
path_1/subpath_1
Richtig: Entfernen Sie das redundante, spezifischere Präfix, um das Problem zu beheben.
include: path_1/
Das excludePrefix stimmt nicht mit einem includePrefix überein
Wenn Sie sie zusammen verwenden, muss ein ausschließendes Präfix mit einem der einschließenden Präfixe beginnen.
Falsch: Das Präfix „subpath_1“ beginnt weder mit path_1/ noch mit path_2/.
include: path_1/
path_2/
exclude: subpath_1
Richtig: Das Ausschlusspräfix muss den vollständigen Pfad eines Einschlusspräfixes enthalten.
include: path_1/
path_2/
exclude: path_1/subpath_1/