Quellobjekte nach Präfix filtern

In dieser Anleitung wird beschrieben, 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 Gruppe von Objekten angibt.

Sie haben drei Möglichkeiten, Präfixfilter zu 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 bei der Übertragung ausgelassen.

  • Beide zusammen: Sie können einschließende und ausschließende Präfixe gleichzeitig verwenden, um die Kontrolle detaillierter 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.

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

  • Teilweise Übereinstimmungen: Präfixe funktionieren durch teilweisen Abgleich. Das Präfix path entspricht beispielsweise sowohl path_1/ als auch path_2/.

  • Keine Platzhalter: Platzhalter werden nicht unterstützt.

  • Relativ zum Quellordner: Wenn Ihre Übertragungsquelle einen Pfad oder Ordner enthält, sind Präfixe relativ zu diesem Pfad oder Ordner. Weitere Informationen finden Sie unter Interaktion mit Quellpfad oder ‑ordner.

  • 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 auch data/reports/ als einschließende Präfixe angeben.

  • Abhängigkeit von „Ausschließen“-Präfixen: Wenn Sie „Einschließen“- und „Ausschließen“-Präfixe zusammen verwenden, muss jedes „Ausschließen“-Präfix mit einem der angegebenen „Einschließen“-Präfixe beginnen. Wenn path beispielsweise ein einschließendes Präfix ist, können die ausschließenden Präfixe path/b oder pathway lauten. 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.

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 (Zeitpunkt der letzten Änderung): Filtert die Objekte, die mit dem Include-Präfix übereinstimmen. Ein Objekt muss dem Filter „Zuletzt geändert“ entsprechen, damit es im Ergebnis enthalten ist.

  3. Präfixe ausschließen: Entfernt Objekte aus dem Ergebnis.

Interaktion mit Quellpfad oder ‑ordner

„Einschließen“- und „Ausschließen“-Filter beziehen sich auf alle Pfade oder Ordner, die 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 fälschlicherweise ein Filter für gs://bucketA/alpha/alpha/beta definiert.

Präfixe angeben

Google Cloud Console

Wenn Sie Ein- und Ausschlusspräfixe über die Google 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": "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 einschließen

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 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_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 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_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 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_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 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äfixes sein.

Falsch: Der Präfix „path_1/subpath_1“ wird bereits durch „path_1/“ abgedeckt.

include: path_1/
         path_1/subpath_1

Korrektur: 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/