Quellobjekte nach Präfix filtern

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.gz lautet das richtige Präfix logs/2025/requests.gz.

  • Teilweise Übereinstimmungen: Präfixe funktionieren über teilweise Übereinstimmungen. Beispiel: Das Präfix path stimmt sowohl mit path_1/ als auch mit path_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 auch data/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 path beispielsweise ein Präfix für den Einschluss ist, könnten path/b oder pathway gü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:

  1. Präfixe einschließen: Schränkt die zu berücksichtigenden Objekte ein.
  2. 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.
  3. 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/beta wird korrekt ausgeschlossen.

Falsch

  • Quellpfad: gs://bucketA/alpha
  • Präfix ausschließen: alpha/beta/
  • Ergebnis: Hier wird ein Filter für gs://bucketA/alpha/alpha/beta falsch 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_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

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_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

Teilweise Übereinstimmungen werden unterstützt. Beispiel:

path

Die folgenden Objekte werden übertragen:

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

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_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

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_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

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_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

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_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

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/