In diesem Leitfaden wird erläutert, wie Sie mit einschließenden und ausschließenden Präfixen steuern, welche Dateien übertragen werden.
Übersicht
Der Storage Transfer Service unterstützt das Filtern von Daten aus Amazon S3-, Microsoft Azure Blob Storage- und Cloud Storage-Quellen mithilfe von Präfixen. Ein Präfix ist eine Zeichenfolge am Anfang eines Pfads, die eine Reihe von Objekten angibt.
Sie können Präfixfilter auf drei Arten verwenden:
Präfixe einschließen: Es werden nur Objekte übertragen, die den angegebenen Präfixen entsprechen.
Präfixe ausschließen: Objekte, die den angegebenen Präfixen entsprechen, werden von der Übertragung ausgeschlossen.
Beide zusammen: Sie können einschließende und ausschließende Präfixe gleichzeitig verwenden, um die Steuerung noch genauer zu gestalten. 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.
Präfixfilter können mit Glob-Mustern, Filtern für die letzte Änderung und S3-Speicherklassenfiltern kombiniert werden.
Regeln
Für Präfixe gelten die folgenden Regeln:
Keine vorangestellten Schrägstriche: Verwenden Sie keinen vorangestellten Schrägstrich in einem Präfix. Für den Pfad
s3://my-bucket/logs/2025/requests.gzlautet das richtige Präfixlogs/2025/requests.gz.Teilweise Übereinstimmungen: Präfixe funktionieren über teilweise Übereinstimmungen. Beispiel: Das Präfix
pathstimmt sowohl mitpath_1/als auch mitpath_2/überein.Keine Platzhalter: Platzhalter werden nicht unterstützt.
Relativ zum Quellordner: Wenn Ihre Übertragungsquelle einen Pfad oder Ordner enthält, sind die Präfixe relativ zu diesem Pfad oder Ordner. Weitere Informationen finden Sie unter Interaktion mit Quellpfad oder ‑ordner.
Eindeutige Präfixe: Jedes Include-Präfix muss einen eindeutigen Teil des Objekt-Namespace definieren. Sie können kein Präfix für den Einschluss verwenden, das bereits von einem anderen Präfix für den Einschluss abgedeckt ist. Sie können beispielsweise nicht sowohl
data/als auchdata/reports/als Präfixe für den Einschluss angeben. Dieselbe Regel gilt für ausschließende Präfixe.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 Präfix für den Einschluss ist, könntenpath/boderpathwaygültige Präfixe für den Ausschluss sein. Diese Regel gilt nicht, wenn Sie nur ausschließende Präfixe verwenden.Maximal 1.000 Präfixe pro Typ: Ein einzelner Übertragungsjob unterstützt bis zu 1.000 einschließende Präfixe und bis zu 1.000 ausschließende 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.
Interaktion mit anderen Filtertypen
Wenn Sie mehrere Filter verwenden, wendet der Storage Transfer Service sie in der folgenden Reihenfolge an:
- Präfixe einschließen: Schränkt die zu berücksichtigenden Objekte ein.
- Objektbedingungen (Glob-Muster, Zeitpunkt der letzten Änderung und S3-Speicherklasse): Filtert die Objekte, die mit dem Einschlusspräfix übereinstimmen. Ein Objekt muss alle angegebenen Objektbedingungen erfüllen, um in die Übertragung einbezogen zu werden.
- Präfixe ausschließen: Entfernt Objekte aus dem Ergebnis.
Weitere Informationen zum Filtern mit Glob-Mustern, Zeitpunkt der letzten Änderung und S3-Speicherklasse.
Interaktion mit Quellpfad oder ‑ordner
„Einschließen“- und „Ausschließen“-Filter beziehen sich auf den Pfad oder Ordner, den Sie für die Quelle angeben.
Wenn Ihre Quelle beispielsweise gs://bucketA/alpha ist und Sie einen Filter für gs://bucketA/alpha/beta angeben möchten:
Richtig
- Quellpfad:
gs://bucketA/alpha - Präfix ausschließen:
beta/ - Ergebnis:
gs://bucketA/alpha/betawird korrekt ausgeschlossen.
Falsch
- Quellpfad:
gs://bucketA/alpha - Präfix ausschließen:
alpha/beta/ - Ergebnis: Hier wird ein Filter für
gs://bucketA/alpha/alpha/betafalsch definiert.
Präfixe angeben
Google Cloud Console
Wenn Sie Präfixe für Ein- und Ausschlüsse mit derGoogle 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 Präfixe für Ein- und Ausschlüsse mit der gcloud-Befehlszeile angeben möchten, übergeben Sie die Flags --include-prefixes und --exclude-prefixes an den Befehl gcloud transfer jobs create oder 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
Verwenden Sie die Felder includePrefixes[] und excludePrefixes[], um einschließende und ausschließende Präfixe mit der REST API anzugeben:
{
"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"
]
}
}
}
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 den Einschluss verwenden
Wenn Sie nur Objekte unter path_1/ übertragen möchten, verwenden Sie das folgende Präfix:
path_1/
Dazu gehören auch 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_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_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 ausdrücklich 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/
Objekte unter path_1/ sind ausgeschlossen. In diesem Fall werden die folgenden Objekte übertragen:
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 Pfade angeben, die ausgeschlossen werden sollen. 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 Ausschlusspräfix und ein Einschlusspräfix zusammen anwenden. In diesem Fall schränkt das Ausschlusspräfix ein, was das Einschlusspräfix in die Übertragung einbezieht.
Wenn Sie beide Arten von Präfixen 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 fehlerhafte Konfigurationen und wie Sie diese beheben können.
Einen Pfad angeben, der in einem anderen einschließenden Präfix verwendet wird
Ein Präfix für den Einschluss darf kein Unterverzeichnis eines anderen Präfixes für den Einschluss sein.
Falsch: Das Präfix path_1/subpath_1 ist bereits durch path_1/ abgedeckt.
include: path_1/
path_1/subpath_1
Richtig: Entfernen Sie das redundante, spezifischere Präfix, um dieses Problem zu beheben.
include: path_1/
Das Ausschlusspräfix stimmt nicht mit einem Einschlusspräfix überein
Wenn sie zusammen verwendet werden, 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 ausschließende Präfix muss den vollständigen Pfad eines einschließenden Präfixes enthalten.
include: path_1/
path_2/
exclude: path_1/subpath_1/