Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Übertragung von einem Dateisystem in Cloud Storage

Auf dieser Seite wird beschrieben, wie Sie Übertragungsjobs zwischen einem Dateisystem (entweder lokal oder in der Cloud) und Cloud Storage erstellen.

Übertragungen von Dateisystemen zu Cloud Storage sind agentenbasiert. Das bedeutet, dass Sie Software-Agents auf einem Computer mit Zugriff auf Ihr Dateisystem installieren, um die Übertragung zu orchestrieren.

Berechtigungen konfigurieren

Bevor Sie eine Übertragung erstellen, müssen Sie Berechtigungen für die folgenden Entitäten konfigurieren:

	Das Nutzerkonto , das zum Erstellen der Übertragung verwendet wird. Dies ist das Konto, mit dem Sie in der Google Cloud Console angemeldet sind, oder das Konto, das bei der Authentifizierung bei der `gcloud` CLI angegeben wird. Das Nutzerkonto kann ein reguläres Nutzerkonto oder ein nutzerverwaltetes Dienstkonto sein.
	Das von Google verwaltete Dienstkonto, auch als Dienst Agent bezeichnet, das vom Storage Transfer Service verwendet wird. Dieses Konto wird in der Regel durch seine E-Mail-Adresse identifiziert, die das Format `project-PROJECT_NUMBER@storage-transfer-service.iam.gserviceaccount.com` hat.
	Das Übertragungs-Agent-Konto , das Google Cloud Berechtigungen für Übertragungs-Agents bereitstellt. Übertragungs-Agent-Konten verwenden die Anmeldedaten des Nutzers, der sie installiert, oder die Anmeldedaten eines nutzerverwalteten Dienstkontos zur Authentifizierung.

Eine Anleitung finden Sie unter Berechtigungen für agentenbasierte Übertragungen.

Agents in einem Agent-Pool installieren

Bei agentenbasierten Übertragungen werden Software-Agents verwendet, um Übertragungen zu orchestrieren. Diese Agents müssen auf einem Computer mit Zugriff auf das Dateisystem installiert sein, das an der Übertragung beteiligt ist.

Der Name des Agent-Pools oder das Präfix der Agent-ID darf keine vertraulichen Informationen wie personenidentifizierbare Informationen oder Sicherheitsdaten enthalten. Ressourcennamen können an die Namen anderer Google Cloud-Ressourcen weitergegeben und für Google-interne Systeme außerhalb Ihres Projekts sichtbar gemacht werden.

Erstellen Sie einen Agent-Pool. Verwenden Sie für diese Aktion Ihr Nutzerkonto .
Installieren Sie Agents im Agent-Pool. Verwenden Sie für diese Aktion Ihr Übertragungs-Agent-Konto .

Wir empfehlen, mit drei Agents in Ihrem Quell-Agent-Pool zu beginnen. Sobald die Übertragung läuft, beobachten Sie die Übertragungsgeschwindigkeit. Sie können dem Pool weitere Agents hinzufügen, während die Übertragung läuft.

Wir empfehlen eine VM pro Agent mit mindestens 4 CPUs und 8 GiB RAM.

Übertragungsoptionen

Die folgenden Storage Transfer Service-Funktionen sind für Übertragungen von Dateisystemen zu Cloud Storage verfügbar.

Bestimmte Dateien mithilfe eines Manifests übertragen

Sie können eine Liste von Dateien übergeben, die vom Storage Transfer Service verarbeitet werden sollen. Weitere Informationen finden Sie unter Bestimmte Dateien oder Objekte mithilfe eines Manifests übertragen.

Speicherklasse angeben

Sie können die Cloud Storage-Speicherklasse angeben, die für Ihre Daten im Ziel Bucket verwendet werden soll. Weitere Informationen zu den StorageClass-Optionen für REST finden Sie unter StorageClass oder verwenden Sie das Flag --custom-storage-class mit der Google Cloud CLI.

Alle Einstellungen für die Speicherklasse werden ignoriert, wenn für den Ziel Bucket Autoclass aktiviert ist. Wenn Autoclass aktiviert ist, werden Objekte, die in den Bucket übertragen werden, anfänglich auf Standard Storage festgelegt.

Metadaten beibehalten

Wenn Sie Dateien aus Dateisystemen übertragen, kann Storage Transfer Service optional bestimmte Attribute als benutzerdefinierte Metadaten beibehalten. Wenn diese Dateien später in ein Dateisystem zurückgeschrieben werden, kann Storage Transfer Service die beibehaltenen Metadaten zurück in POSIX-Attribute umwandeln.

Weitere Informationen dazu, welche Metadaten beibehalten werden können und wie Sie die Übertragung konfigurieren, finden Sie im Abschnitt Übertragungen von POSIX-Dateisystemen unter Metadaten beibehalten.

Netzwerkbandbreite verwalten

Standardmäßig verwendet Storage Transfer Service so viel Bandbreite wie verfügbar, um Dateien aus Ihrem Dateisystem zu übertragen. Sie können ein Bandbreitenlimit festlegen, um zu verhindern, dass sich eine Übertragung auf anderen Netzwerkverkehr auswirkt. Bandbreitenlimits werden auf Agent-Poolebene angewendet.

Weitere Informationen finden Sie unter Manage Netzwerkbandbreite.

Ihr Nutzerkonto benötigt die Rolle Storage Transfer-Administrator (roles/storagetransfer.admin), um Bandbreitenlimits festzulegen oder zu ändern.

Logging

Storage Transfer Service unterstützt Cloud Logging für Storage Transfer Service (empfohlen) sowie agentenbasierte Übertragungsprotokolle.

Übertragung erstellen

Der Name des Übertragungsjobs darf keine vertraulichen Informationen wie personenidentifizierbare Informationen oder Sicherheitsdaten enthalten. Ressourcennamen können an die Namen anderer Google Cloud-Ressourcen weitergegeben und für Google-interne Systeme außerhalb Ihres Projekts sichtbar gemacht werden.

Storage Transfer Service bietet mehrere Schnittstellen, über die Sie eine Übertragung erstellen können.

Google Cloud Console

Rufen Sie in der Google Cloud Console die Seite Storage Transfer Service auf.

Storage Transfer Service aufrufen
Klicken Sie auf Übertragung erstellen. Die Seite Übertragungsjob erstellen wird angezeigt.
Wählen Sie POSIX-Dateisystem als Quelle aus.
Wählen Sie Cloud Storage als Zieltyp aus und klicken Sie auf Nächster Schritt.
Wählen Sie einen vorhandenen Agent-Pool aus oder wählen Sie Agent-Pool erstellen aus und folgen Sie der Anleitung zum Erstellen eines neuen Pools.
Geben Sie den voll qualifizierten Pfad des Dateisystemverzeichnisses an.
Klicken Sie auf Nächster Schritt.
Geben Sie im Feld Bucket oder Ordner den Ziel-Bucket und optional den Ordnernamen ein. Sie können auch auf Durchsuchen klicken, um einen Bucket aus einer Liste der vorhandenen Buckets im aktuellen Projekt auszuwählen. Zum Erstellen eines neuen Buckets klicken Sie auf Neuen Bucket erstellen.
Klicken Sie auf Nächster Schritt.
Wählen Sie die gewünschten Zeitplanoptionen aus.

Hinweis: Storage Transfer Service zeigt Zeitpläne für Übertragungsjobs in Ihrer lokalen Zeitzone an, speichert diese Uhrzeiten jedoch in UTC (koordinierter Weltzeit). Wenn an Ihrem Standort die Sommerzeit gilt, ändert sich der Zeitplan für Übertragungsjobs möglicherweise zu Beginn bzw. am Ende der Sommerzeit.
Klicken Sie auf Nächster Schritt.
Wählen Sie die Einstellungen für den Übertragungsjob aus.
- Geben Sie im Feld Beschreibung eine Beschreibung der Übertragung ein. Geben Sie als Best Practice eine aussagekräftige Beschreibung ein, damit Sie die Jobs unterscheiden können.
- Verwenden Sie unter Metadatenoptionen die Standardoptionen, oder aktualisieren Sie einen oder mehrere Werte. Weitere Informationen finden Sie unter Metadaten beibehalten.
- Wählen Sie unter Wann überschreiben? eine der folgenden Optionen aus:
  - Nie: Storage Transfer Service überspringt alle Dateien aus der Quelle, die denselben Namen wie eine Datei im Ziel haben.
  - Falls unterschiedlich: Überschreibt Zieldateien, wenn die Quelldatei mit demselben Namen unterschiedliche ETags oder Prüfsummenwerte hat.
  - Immer: Zieldateien werden immer geschrieben, wenn die Quelldatei denselben Namen hat, auch wenn sie identisch sind.
- Wählen Sie unter Löschzeitpunkt eine der folgenden Optionen aus:
  - Nie: Dateien werden niemals aus der Quelle oder dem Ziel gelöscht.
  - Datei nach der Übertragung aus der Quelle löschen: Dateien werden aus der Quelle gelöscht, nachdem sie an das Ziel übertragen wurden. Wenn eine Quelldatei nicht übertragen wird, z. B. weil sie bereits im Ziel vorhanden ist, wird die Quelldatei nicht gelöscht.
    
    **Wichtig**: Wenn Sie keine lokale Sicherung haben, kann diese Option nicht rückgängig gemacht werden.
  - Dateien aus dem Ziel löschen, wenn sie nicht auch in der Quelle sind: Wenn sich Dateien im Cloud Storage-Ziel-Bucket nicht auch in der Quelle befinden, löschen Sie die Dateien aus dem Cloud Storage-Bucket.
    
    Mit dieser Option wird sichergestellt, dass der Cloud Storage-Ziel-Bucket genau mit Ihrer Quelle übereinstimmt.
- Wählen Sie aus, ob Logging in Cloud Storage aktivieren und/oder Logging in Cloud Logging aktivieren ausgewählt werden soll. Weitere Informationen finden Sie unter Protokolle für Dateisystemübertragungen und Cloud Logging für Storage Transfer Service.
Klicken Sie zum Erstellen des Übertragungsjobs auf Erstellen.

`gcloud`

Bevor Sie gcloud-Befehle verwenden, installieren Sie die Google Cloud CLI.

Verwenden Sie zum Erstellen eines neuen Übertragungsjobs den Befehl gcloud transfer jobs create. Das Erstellen eines neuen Jobs initiiert die angegebene Übertragung, sofern weder ein Zeitplan noch --do-not-run angegeben ist.

gcloud transfer jobs create \
  posix:///SOURCE \
  gs://DESTINATION/ \
  --source-agent-pool=SOURCE_POOL_NAME

Ersetzen Sie Folgendes:

SOURCE ist ein absoluter Pfad vom Stammverzeichnis des Dateisystems. Er hat das Präfix posix://, sodass der endgültige Wert drei Schrägstriche enthält. Beispiel: posix:///tmp/data/.
DESTINATION ist der Name eines Cloud Storage-Bucket und, optional ein Ordnerpfad, gefolgt von einem Schrägstrich. Beispiel: gs://example-bucket/data/.
--source-agent-pool gibt den für diese Übertragung zu verwendenden Quell-Agent-Pool an.

Weitere Optionen:

--do-not-run verhindert, dass Storage Transfer Service nach dem Senden des Befehls den Job ausführt. Zum Ausführen des Jobs aktualisieren Sie ihn, um einen Zeitplan hinzuzufügen, oder verwenden Sie jobs run, um ihn manuell zu starten.
--manifest-file gibt den Pfad zu einer CSV-Datei in Cloud Storage an, die eine Liste der Dateien enthält, die von Ihrer Quelle übertragen werden sollen. Informationen zur Formatierung von Manifestdateien finden Sie unter Bestimmte Dateien oder Objekte mithilfe eines Manifests übertragen.
Jobinformationen: Sie können --name und --description angeben.
Zeitplan: Geben Sie --schedule-starts, --schedule-repeats-every und --schedule-repeats-until oder --do-not-run an.
Übertragungsoptionen: Bestimmen Sie, ob Zieldateien überschrieben werden sollen (--overwrite-when=different oder always) und ob bestimmte Dateien während oder nach der Übertragung gelöscht werden sollen (--delete-from=destination-if-unique oder source-after-transfer); welche Metadatenwerte beibehalten werden (--preserve-metadata); und legen Sie optional eine Speicherklasse für übertragene Objekte fest (--custom-storage-class).

Führen Sie gcloud transfer jobs create --help aus oder sehen Sie sich die gcloud-Referenzdokumentation an, um alle Optionen aufzurufen. Beachten Sie, dass nicht alle Optionen für agentenbasierte Übertragungen unterstützt werden. Nicht unterstützte Optionen enthalten in ihrem Hilfetext einen entsprechenden Hinweis.

REST

Im folgenden Beispiel wird gezeigt, wie Sie den Storage Transfer Service über die REST API verwenden.

Wenn Sie Übertragungsjobs mithilfe der Storage Transfer Service API konfigurieren oder bearbeiten, muss die Zeit in UTC angegeben werden. Weitere Informationen zum Angeben des Zeitplans eines Übertragungsjobs finden Sie unter Zeitplan.

Verwenden Sie transferJobs.create mit einem posixDataSource, um Dateien aus einem POSIX-Dateisystem in einen Cloud Storage-Bucket zu verschieben:

POST https://storagetransfer.googleapis.com/v1/transferJobs
{
 "name":"transferJobs/sample_transfer",
 "description": "My First Transfer",
 "status": "ENABLED",
 "projectId": "my_transfer_project_id",
 "schedule": {
     "scheduleStartDate": {
         "year": 2022,
         "month": 5,
         "day": 2
     },
     "startTimeOfDay": {
         "hours": 22,
         "minutes": 30,
         "seconds": 0,
         "nanos": 0
     }
     "scheduleEndDate": {
         "year": 2022,
         "month": 12,
         "day": 31
     },
     "repeatInterval": {
         "259200s"
     },
 },
 "transferSpec": {
     "posixDataSource": {
          "rootDirectory": "/bar/",
     },
     "sourceAgentPoolName": "my_example_pool",
     "gcsDataSink": {
          "bucketName": "destination_bucket"
          "path": "foo/bar/"
     },
  }
}

Das schedule Feld ist optional. Ist dies nicht der Fall, muss der Übertragungsjob mit einer transferJobs.run-Anfrage gestartet werden.

Mit transferJobs.get können Sie den Status Ihrer Übertragung nach dem Erstellen eines Jobs prüfen:

GET https://storagetransfer.googleapis.com/v1/transferJobs/sample_transfer?project_id=my_transfer_project_id

Clientbibliotheken

Die folgenden Beispiele zeigen, wie Sie Storage Transfer Service programmatisch mit Go, Java, Node.js und Python verwenden.

Wenn Sie Übertragungsjobs programmatisch konfigurieren oder bearbeiten, muss die Zeit in UTC angegeben werden. Weitere Informationen zum Angeben des Zeitplans eines Übertragungsjobs finden Sie unter Zeitplan.

Weitere Informationen zu den Storage Transfer Service-Clientbibliotheken finden Sie unter Erste Schritte mit Storage Transfer Service-Clientbibliotheken.

So verschieben Sie Dateien aus einem POSIX-Dateisystem in einen Cloud Storage-Bucket:

Go


import (
	"context"
	"fmt"
	"io"

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

func transferFromPosix(w io.Writer, projectID string, sourceAgentPoolName string, rootDirectory string, gcsSinkBucket 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"

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

	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},
				},
			},
			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 with name %v", rootDirectory, gcsSinkBucket, 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.TransferSpec;
import java.io.IOException;

public class TransferFromPosix {

  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";

    transferFromPosix(projectId, sourceAgentPoolName, rootDirectory, gcsSinkBucket);
  }

  public static void transferFromPosix(
      String projectId, String sourceAgentPoolName, String rootDirectory, String gcsSinkBucket)
      throws IOException {
    TransferJob transferJob =
        TransferJob.newBuilder()
            .setProjectId(projectId)
            .setTransferSpec(
                TransferSpec.newBuilder()
                    .setSourceAgentPoolName(sourceAgentPoolName)
                    .setPosixDataSource(
                        PosixFilesystem.newBuilder().setRootDirectory(rootDirectory).build())
                    .setGcsDataSink(GcsData.newBuilder().setBucketName(gcsSinkBucket).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 a transfer job from "
              + rootDirectory
              + " to "
              + gcsSinkBucket
              + " 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'

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

/**
 * Creates a request to transfer from the local file system to the sink bucket
 */
async function transferDirectory() {
  const createRequest = {
    transferJob: {
      projectId,
      transferSpec: {
        sourceAgentPoolName,
        posixDataSource: {
          rootDirectory,
        },
        gcsDataSink: {bucketName: gcsSinkBucket},
      },
      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}' with name ${transferJob.name}`
  );
}

transferDirectory();

Python

from google.cloud import storage_transfer


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

    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 sink bucket name
    # sink_bucket = 'my-gcs-sink-bucket'

    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},
                },
            }
        }
    )

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