Bestimmte Dateien oder Objekte mithilfe eines Manifests übertragen

Storage Transfer Service unterstützt die Übertragung bestimmter Dateien oder Objekte, die mithilfe eines Manifests angegeben werden. Ein Manifest ist eine CSV-Datei, die in Cloud Storage hochgeladen wird und eine Liste von Dateien oder Objekten enthält, auf denen Storage Transfer Service Aktionen ausführen kann.

Ein Manifest kann für die folgenden Übertragungen verwendet werden:

  • Von AWS S3, S3-kompatiblem Speicher, Azure Blobstore oder Cloud Storage in einen Cloud Storage-Bucket.

  • Von einem Dateisystem in einen Cloud Storage-Bucket.

  • Von einem Cloud Storage-Bucket in ein Dateisystem.

  • Zwischen zwei Dateisystemen.

  • Von einer öffentlich zugänglichen HTTP/HTTPS-Quelle zu einem Cloud Storage-Bucket. Folgen Sie der Anleitung unter URL-Liste erstellen, da das Manifestformat für URL-Listen eindeutig ist.

Manifest erstellen

Für Manifestdateien gelten die folgenden Anforderungen:

  • Manifeste müssen im CSV-Format vorliegen.
  • Sie können beliebige UTF-8-Zeichen enthalten.
  • Die erste Spalte muss ein Dateiname oder Objektname sein. Der Name ist relativ zum Stammpfad oder zum Bucket und Ordner, die im Übertragungsjob angegeben sind. Weitere Informationen finden Sie unter Dateisystemübertragungen und Objektspeicherübertragungen.
  • Manifestdateien unterstützen keine Platzhalter. Ordnernamen ohne Datei- oder Objektnamen werden nicht unterstützt.
  • Wenn ein Datei- oder Objektname ein Komma enthält, muss der Name in doppelte Anführungszeichen gesetzt werden. Beispiel: "doe,john.txt".
  • Die Größe der Manifestdatei ist nicht begrenzt.

Wir empfehlen, die Übertragung mit einer kleinen Teilmenge von Dateien oder Objekten zu testen, um unnötige API-Aufrufe aufgrund von Konfigurationsfehlern zu vermeiden.

Sie können den Status von Dateiübertragungen auf der Seite „Übertragungsjobs“ überwachen. Dateien oder Objekte, die nicht übertragen werden sollen, werden in den Übertragungslogs aufgeführt.

Dateisystemübertragungen

Wenn Sie ein Manifest von Dateien in einem Dateisystem erstellen möchten, erstellen Sie eine CSV-Datei mit einer einzelnen Spalte, die die Dateipfade relativ zum Stammverzeichnis enthält, das beim Erstellen des Übertragungsjobs angegeben wurde.

Beispiel für die Übertragung der folgenden Dateisystemdateien:

Dateipfad
rootdir/dir1/subdir1/file1.txt
rootdir/file2.txt
rootdir/dir2/subdir1/file3.txt

Ihr Manifest sollte wie im folgenden Beispiel aussehen:

dir1/subdir1/file1.txt
file2.txt
dir2/subdir1/file3.txt

Speichern Sie die Manifestdatei mit einem beliebigen Dateinamen und der Erweiterung .csv.

Objektspeicherübertragungen

Wenn Sie ein Manifest von Objekten erstellen möchten, erstellen Sie eine CSV-Datei, deren erste Spalte die Objektnamen relativ zum Bucket-Namen und Pfad enthält, die bei der Erstellung des Übertragungsjobs angegeben wurden. Alle Objekte müssen sich im selben Bucket befinden.

Sie können auch eine optionale zweite Spalte mit der Cloud Storage-Generierungsnummer der spezifischen Version angeben, die übertragen werden soll.

Sie können beispielsweise die folgenden Objekte übertragen:

Objektpfad Cloud Storage-Generierungsnummer
SOURCE_PATH/object1.pdf 1664826685911832
SOURCE_PATH/object2.pdf
SOURCE_PATH/object3.pdf 1664826610699837

Ihr Manifest sollte wie im folgenden Beispiel aussehen:

object1.pdf,1664826685911832
object2.pdf
object3.pdf,1664826610699837

Speichern Sie die Manifestdatei mit einem beliebigen Dateinamen und der Erweiterung .csv.

HTTP/HTTPS-Übertragungen

Wenn Sie bestimmte Dateien von einer HTTP- oder HTTPS-Quelle übertragen möchten, folgen Sie der Anleitung unter URL-Liste erstellen.

Manifest veröffentlichen

Nachdem Sie das Manifest erstellt haben, müssen Sie es für Storage Transfer Service verfügbar machen. Der Storage Transfer Service kann auf die Datei in einem Cloud Storage-Bucket oder in Ihrem Dateisystem zugreifen.

Manifest in Cloud Storage hochladen

Sie können die Manifestdatei in einem beliebigen Cloud Storage-Bucket speichern.

Der Dienst-Agent, der die Übertragung ausführt, muss die Berechtigung storage.objects.get für den Bucket haben, der das Manifest enthält. Eine Anleitung zum Ermitteln der Dienst-Agent-ID und zum Erteilen von Berechtigungen für diesen Dienst-Agent für einen Bucket finden Sie unter Erforderliche Berechtigungen erteilen.

Eine Anleitung zum Hochladen des Manifests in einen Bucket finden Sie in der Cloud Storage-Dokumentation unter Objekte hochladen.

Wenn Sie beispielsweise die gcloud-Befehlszeile verwenden möchten, um eine Datei in Cloud Storage hochzuladen, verwenden Sie den Befehl gcloud storage cp:

gcloud storage cp MANIFEST.CSV gs://DESTINATION_BUCKET_NAME/

Ersetzen Sie Folgendes:

  • MANIFEST.CSV ist der lokale Pfad zu Ihrer Manifestdatei. Beispiel: Desktop/manifest01.csv.

  • DESTINATION_BUCKET_NAME ist der Name des Buckets, in den Sie das Objekt hochladen. Beispiel: my-bucket

Wenn der Vorgang erfolgreich ausgeführt wurde, sieht die Antwort in etwa so aus:

Completed files 1/1 | 164.3kiB/164.3kiB

Sie können ein Manifest oder den Bucket, der es enthält, mit vom Kunden verwalteten Cloud KMS-Verschlüsselungsschlüsseln verschlüsseln. Weisen Sie in diesem Fall die Rolle Cloud KMS CryptoKey Encrypter/Decrypter (roles/cloudkms.cryptoKeyEncrypterDecrypter) für den Cloud KMS-Schlüssel, der zum Verschlüsseln des Manifests verwendet wird, den beiden folgenden Dienst-Agents zu:

  • Der Storage Transfer Service-Dienst-Agent project-PROJECT_NUMBER@storage-transfer-service..
  • Der Cloud Storage-Dienst-Agent für das Projekt, das den Manifest-Bucket service-PROJECT_NUMBER@gs-project-accounts. enthält.

Eine Anleitung zum Zuweisen dieser Rolle finden Sie unter Cloud KMS-Schlüssel einem Dienst-Agent zuweisen. Vom Kunden bereitgestellte Verschlüsselungsschlüssel werden nicht unterstützt.

Manifest in einem Dateisystem speichern

Sie können die Manifestdatei im Quell- oder Zieldateisystem speichern.

Der Speicherort der Datei muss für die Übertragungs-Agents zugänglich sein. Wenn Sie den Verzeichniszugriff für Ihre Agents einschränken, muss sich die Manifestdatei in einem bereitgestellten Verzeichnis befinden.

Übertragung starten

Ändern Sie die Manifestdatei erst, wenn ein Übertragungsvorgang abgeschlossen ist. Wir empfehlen, die Manifestdatei während einer Übertragung zu sperren.

Cloud Console

So starten Sie eine Übertragung mit einem Manifest über die Cloud Console:

  1. Folgen Sie der Anleitung unter Übertragungen erstellen, um Quelle, Ziel und Optionen auszuwählen.

  2. Wählen Sie im letzten Schritt Einstellungen auswählen das Kästchen Liste der zu übertragenden Dateien über Manifestdatei angeben aus.

  3. Geben Sie den Speicherort der Manifestdatei ein.

gcloud

Fügen Sie das --manifest-file=MANIFEST_FILE-Flag mit dem gcloud transfer jobs create-Befehl hinzu, um die im Manifest aufgeführten Dateien oder Objekte zu übertragen.

gcloud transfer jobs create SOURCE DESTINATION \
  --manifest-file=MANIFEST_FILE

MANIFEST_FILE kann einer der folgenden Werte sein:

  • Der Pfad zur CSV-Datei in einem Cloud Storage-Bucket:

    --manifest-file=gs://my_bucket/sample_manifest.csv

    Weitere Informationen zu den erforderlichen Berechtigungen, wenn der Bucket oder die Datei nicht öffentlich ist, finden Sie unter Manifest in Cloud Storage hochladen.

  • Der relative Pfad vom Dateisystem SOURCE, einschließlich aller angegebenen Pfade:

    --manifest-file=source://relative_path/sample_manifest.csv

  • Der relative Pfad vom Dateisystem DESTINATION, einschließlich aller angegebenen Pfade:

    --manifest-file=destination://relative_path/sample_manifest.csv

REST + Clientbibliotheken

REST

Um die im Manifest aufgeführten Dateien oder Objekte zu übertragen, führen Sie einen createTransferJob-API-Aufruf aus, der eine transferSpec mit dem hinzugefügten Feld transferManifest angibt. Beispiel:

POST https://storagetransfer.googleapis.com/v1/transferJobs

...
  "transferSpec": {
      "posixDataSource": {
          "rootDirectory": "/home/",
      },
      "gcsDataSink": {
          "bucketName": "GCS_NEARLINE_SINK_NAME",
          "path": "GCS_SINK_PATH",
      },
      "transferManifest": {
          "location": "gs://my_bucket/sample_manifest.csv"
      }
  }

Die Manifestdatei kann in einem Cloud Storage-Bucket oder im Quell- oder Zieldateisystem gespeichert werden. Cloud Storage-Buckets müssen das Präfix gs:// verwenden und den vollständigen Pfad einschließlich des Bucket-Namens enthalten. Dateisystemspeicherorte müssen das Präfix source:// oder destination:// verwenden und sind relativ zur Dateisystemquelle oder zum Dateisystemziel und zum optionalen Stammverzeichnis.

Go


import (
	"context"
	"fmt"
	"io"

	storagetransfer "cloud.google.com/go/storagetransfer/apiv1"
	"cloud.google.com/go/storagetransfer/apiv1/storagetransferpb"
)

func transferUsingManifest(w io.Writer, projectID string, sourceAgentPoolName string, rootDirectory string, gcsSinkBucket string, manifestBucket string, manifestObjectName string) (*storagetransferpb.TransferJob, error) {
	// Your project id
	// projectId := "myproject-id"

	// The agent pool associated with the POSIX data source. If not provided, defaults to the default agent
	// sourceAgentPoolName := "projects/my-project/agentPools/transfer_service_default"

	// The root directory path on the source filesystem
	// rootDirectory := "/directory/to/transfer/source"

	// The ID of the GCS bucket to transfer data to
	// gcsSinkBucket := "my-sink-bucket"

	// The ID of the GCS bucket that contains the manifest file
	// manifestBucket := "my-manifest-bucket"

	// The name of the manifest file in manifestBucket that specifies which objects to transfer
	// manifestObjectName := "path/to/manifest.csv"

	ctx := context.Background()
	client, err := storagetransfer.NewClient(ctx)
	if err != nil {
		return nil, fmt.Errorf("storagetransfer.NewClient: %w", err)
	}
	defer client.Close()

	manifestLocation := "gs://" + manifestBucket + "/" + manifestObjectName
	req := &storagetransferpb.CreateTransferJobRequest{
		TransferJob: &storagetransferpb.TransferJob{
			ProjectId: projectID,
			TransferSpec: &storagetransferpb.TransferSpec{
				SourceAgentPoolName: sourceAgentPoolName,
				DataSource: &storagetransferpb.TransferSpec_PosixDataSource{
					PosixDataSource: &storagetransferpb.PosixFilesystem{RootDirectory: rootDirectory},
				},
				DataSink: &storagetransferpb.TransferSpec_GcsDataSink{
					GcsDataSink: &storagetransferpb.GcsData{BucketName: gcsSinkBucket},
				},
				TransferManifest: &storagetransferpb.TransferManifest{Location: manifestLocation},
			},
			Status: storagetransferpb.TransferJob_ENABLED,
		},
	}

	resp, err := client.CreateTransferJob(ctx, req)
	if err != nil {
		return nil, fmt.Errorf("failed to create transfer job: %w", err)
	}
	if _, err = client.RunTransferJob(ctx, &storagetransferpb.RunTransferJobRequest{
		ProjectId: projectID,
		JobName:   resp.Name,
	}); err != nil {
		return nil, fmt.Errorf("failed to run transfer job: %w", err)
	}
	fmt.Fprintf(w, "Created and ran transfer job from %v to %v using manifest file %v with name %v", rootDirectory, gcsSinkBucket, manifestLocation, resp.Name)
	return resp, nil
}

Java


import com.google.storagetransfer.v1.proto.StorageTransferServiceClient;
import com.google.storagetransfer.v1.proto.TransferProto;
import com.google.storagetransfer.v1.proto.TransferTypes.GcsData;
import com.google.storagetransfer.v1.proto.TransferTypes.PosixFilesystem;
import com.google.storagetransfer.v1.proto.TransferTypes.TransferJob;
import com.google.storagetransfer.v1.proto.TransferTypes.TransferManifest;
import com.google.storagetransfer.v1.proto.TransferTypes.TransferSpec;
import java.io.IOException;

public class TransferUsingManifest {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.

    // Your project id
    String projectId = "my-project-id";

    // The agent pool associated with the POSIX data source. If not provided, defaults to the
    // default agent
    String sourceAgentPoolName = "projects/my-project-id/agentPools/transfer_service_default";

    // The root directory path on the source filesystem
    String rootDirectory = "/directory/to/transfer/source";

    // The ID of the GCS bucket to transfer data to
    String gcsSinkBucket = "my-sink-bucket";

    // The ID of the GCS bucket which has your manifest file
    String manifestBucket = "my-bucket";

    // The ID of the object in manifestBucket that specifies which files to transfer
    String manifestObjectName = "path/to/manifest.csv";

    transferUsingManifest(
        projectId,
        sourceAgentPoolName,
        rootDirectory,
        gcsSinkBucket,
        manifestBucket,
        manifestObjectName);
  }

  public static void transferUsingManifest(
      String projectId,
      String sourceAgentPoolName,
      String rootDirectory,
      String gcsSinkBucket,
      String manifestBucket,
      String manifestObjectName)
      throws IOException {
    String manifestLocation = "gs://" + manifestBucket + "/" + manifestObjectName;
    TransferJob transferJob =
        TransferJob.newBuilder()
            .setProjectId(projectId)
            .setTransferSpec(
                TransferSpec.newBuilder()
                    .setSourceAgentPoolName(sourceAgentPoolName)
                    .setPosixDataSource(
                        PosixFilesystem.newBuilder().setRootDirectory(rootDirectory).build())
                    .setGcsDataSink((GcsData.newBuilder().setBucketName(gcsSinkBucket)).build())
                    .setTransferManifest(
                        TransferManifest.newBuilder().setLocation(manifestLocation).build()))
            .setStatus(TransferJob.Status.ENABLED)
            .build();

    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the "close" method on the client to safely clean up any remaining background resources,
    // or use "try-with-close" statement to do this automatically.
    try (StorageTransferServiceClient storageTransfer = StorageTransferServiceClient.create()) {

      // Create the transfer job
      TransferJob response =
          storageTransfer.createTransferJob(
              TransferProto.CreateTransferJobRequest.newBuilder()
                  .setTransferJob(transferJob)
                  .build());

      System.out.println(
          "Created and ran a transfer job from "
              + rootDirectory
              + " to "
              + gcsSinkBucket
              + " using "
              + "manifest file "
              + manifestLocation
              + " with name "
              + response.getName());
    }
  }
}

Node.js


// Imports the Google Cloud client library
const {
  StorageTransferServiceClient,
} = require('@google-cloud/storage-transfer');

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// Your project id
// const projectId = 'my-project'

// The agent pool associated with the POSIX data source. Defaults to the default agent
// const sourceAgentPoolName = 'projects/my-project/agentPools/transfer_service_default'

// The root directory path on the source filesystem
// const rootDirectory = '/directory/to/transfer/source'

// The ID of the GCS bucket to transfer data to
// const gcsSinkBucket = 'my-sink-bucket'

// Transfer manifest location. Must be a `gs:` URL
// const manifestLocation = 'gs://my-bucket/sample_manifest.csv'

// Creates a client
const client = new StorageTransferServiceClient();

/**
 * Creates a request to transfer from the local file system to the sink bucket
 */
async function transferViaManifest() {
  const createRequest = {
    transferJob: {
      projectId,
      transferSpec: {
        sourceAgentPoolName,
        posixDataSource: {
          rootDirectory,
        },
        gcsDataSink: {bucketName: gcsSinkBucket},
        transferManifest: {
          location: manifestLocation,
        },
      },
      status: 'ENABLED',
    },
  };

  // Runs the request and creates the job
  const [transferJob] = await client.createTransferJob(createRequest);

  const runRequest = {
    jobName: transferJob.name,
    projectId: projectId,
  };

  await client.runTransferJob(runRequest);

  console.log(
    `Created and ran a transfer job from '${rootDirectory}' to '${gcsSinkBucket}' using manifest \`${manifestLocation}\` with name ${transferJob.name}`
  );
}

transferViaManifest();

Python

from google.cloud import storage_transfer


def create_transfer_with_manifest(
    project_id: str,
    description: str,
    source_agent_pool_name: str,
    root_directory: str,
    sink_bucket: str,
    manifest_location: str,
):
    """Create a transfer from a POSIX file system to a GCS bucket using
    a manifest file."""

    client = storage_transfer.StorageTransferServiceClient()

    # The ID of the Google Cloud Platform Project that owns the job
    # project_id = 'my-project-id'

    # A useful description for your transfer job
    # description = 'My transfer job'

    # The agent pool associated with the POSIX data source.
    # Defaults to 'projects/{project_id}/agentPools/transfer_service_default'
    # source_agent_pool_name = 'projects/my-project/agentPools/my-agent'

    # The root directory path on the source filesystem
    # root_directory = '/directory/to/transfer/source'

    # Google Cloud Storage destination bucket name
    # sink_bucket = 'my-gcs-destination-bucket'

    # Transfer manifest location. Must be a `gs:` URL
    # manifest_location = 'gs://my-bucket/sample_manifest.csv'

    transfer_job_request = storage_transfer.CreateTransferJobRequest(
        {
            "transfer_job": {
                "project_id": project_id,
                "description": description,
                "status": storage_transfer.TransferJob.Status.ENABLED,
                "transfer_spec": {
                    "source_agent_pool_name": source_agent_pool_name,
                    "posix_data_source": {
                        "root_directory": root_directory,
                    },
                    "gcs_data_sink": {
                        "bucket_name": sink_bucket,
                    },
                    "transfer_manifest": {"location": manifest_location},
                },
            }
        }
    )

    result = client.create_transfer_job(transfer_job_request)
    print(f"Created transferJob: {result.name}")

Die Objekte oder Dateien im Manifest werden nicht unbedingt in der aufgeführten Reihenfolge übertragen.

Wenn das Manifest Dateien enthält, die bereits im Ziel vorhanden sind, werden diese Dateien übersprungen, es sei denn, die Option Bereits im Ziel vorhandene Objekte überschreiben ist angegeben.

Wenn das Manifest Objekte enthält, die in einer anderen Version am Ziel vorhanden sind, wird das Objekt am Ziel mit der Quellversion des Objekts überschrieben. Wenn das Ziel ein versionierter Bucket ist, wird eine neue Version des Objekts erstellt.

Nächste Schritte