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

Trasferimento da un file system a Cloud Storage

Questa pagina mostra come creare job di trasferimento tra un file system (on-premise o nel cloud) e Cloud Storage.

I trasferimenti dai file system a Cloud Storage sono basati su agenti, il che significa che installerai agenti software su una macchina con accesso al file system per orchestrare il trasferimento.

Configura autorizzazioni

Prima di creare un trasferimento, devi configurare le autorizzazioni per le seguenti entità:

	L'account utente utilizzato per creare il trasferimento. Questo è l' account con cui hai eseguito l'accesso alla Google Cloud console o l'account specificato durante l'autenticazione a gcloud CLI. L'account utente può essere un account utente normale o un account di servizio gestito dall'utente.
	Il service account gestito da Google, noto anche come service agent, utilizzato da Storage Transfer Service. Questo account è generalmente identificato dal suo indirizzo email, che utilizza il formato `project-PROJECT_NUMBER@storage-transfer-service.iam.gserviceaccount.com`.
	L'account dell'agente di trasferimento che fornisce le autorizzazioni Google Cloud per gli agenti di trasferimento. Gli account degli agenti di trasferimento utilizzano le credenziali dell'utente che li installa o le credenziali di un account di servizio gestito dall'utente per l'autenticazione.

Per istruzioni, consulta Autorizzazioni di trasferimento basate su agenti.

Installa gli agenti in un pool di agenti

I trasferimenti basati su agenti utilizzano agenti software per orchestrare i trasferimenti. Questi agenti devono essere installati su una macchina con accesso al file system coinvolto nel trasferimento.

Non includere informazioni sensibili come quelle che consentono l'identificazione personale (PII) oppure dati di sicurezza nel nome del pool di agenti o nel prefisso dell'ID agente. I nomi delle risorse potrebbero essere propagati ai nomi di altre risorse Google Cloud e potrebbero essere esposti a sistemi interni di Google al di fuori del tuo progetto.

Crea un pool di agenti. Utilizza il tuo account utente per questa azione.
Installa gli agenti nel pool di agenti. Utilizza il tuo account dell'agente di trasferimento per questa azione.

Ti consigliamo di iniziare con 3 agenti nel pool di agenti di origine. Una volta avviato il trasferimento è in corso, monitora la velocità di trasferimento; puoi aggiungere altri agenti al pool mentre il trasferimento è in corso.

Consigliamo una VM per agente, ciascuna con un minimo di 4 CPU e 8 GiB di RAM.

Opzioni di trasferimento

Le seguenti funzionalità di Storage Transfer Service sono disponibili per i trasferimenti dai file system a Cloud Storage.

Trasferisci file specifici utilizzando un manifest

Puoi passare un elenco di file su cui Storage Transfer Service deve agire. Per i dettagli, consulta Trasferisci file o oggetti specifici utilizzando un manifest.

Specifica la classe di archiviazione

Puoi specificare la classe di archiviazione Cloud Storage da utilizzare per i dati nel bucket di destinazione. Per i dettagli REST, consulta le StorageClass opzioni o utilizza il --custom-storage-class flag con Google Cloud CLI.

Tieni presente che le impostazioni della classe di archiviazione vengono ignorate se il bucket di destinazione ha Autoclass abilitato. Se Autoclass è abilitato, gli oggetti trasferiti nel bucket vengono inizialmente impostati su Standard Storage.

Conservazione dei metadati

Quando trasferisce file dai file system, Storage Transfer Service può facoltativamente conservare determinati attributi come metadati personalizzati. Se questi file vengono successivamente scritti di nuovo in un file system, Storage Transfer Service può convertire i metadati conservati in attributi POSIX.

Per informazioni dettagliate sui metadati che possono essere conservati e su come configurare il trasferimento, consulta la sezione Trasferimenti di file system POSIX di Conservazione dei metadati.

Gestisci la larghezza di banda di rete

Per impostazione predefinita, Storage Transfer Service utilizza tutta la larghezza di banda disponibile per trasferire i file dal file system. Puoi impostare un limite di larghezza di banda per impedire che un trasferimento influisca su altro traffico di rete. I limiti di larghezza di banda vengono applicati a livello di pool di agenti.

Per saperne di più, consulta Gestisci la larghezza di banda di rete.

Il tuo account utente richiede il ruolo Amministratore di Storage Transfer (roles/storagetransfer.admin) per impostare o modificare i limiti di larghezza di banda.

Logging

Storage Transfer Service supporta Cloud Logging per Storage Transfer Service (consigliato) e i log di trasferimento basati su agenti.

Crea un trasferimento

Non includere informazioni sensibili come quelle che consentono l'identificazione personale (PII) oppure dati di sicurezza nel nome del job di trasferimento. I nomi delle risorse potrebbero essere propagati ai nomi di altre risorse Google Cloud e potrebbero essere esposti a sistemi interni di Google al di fuori del tuo progetto.

Storage Transfer Service fornisce più interfacce tramite cui creare un trasferimento.

Google Cloud Console

Vai alla pagina Storage Transfer Service nella Google Cloud console.

Vai a Storage Transfer Service
Fai clic su Crea job di trasferimento. Viene visualizzata la pagina Crea un job di trasferimento.
Scegli File system POSIX come origine.
Seleziona Cloud Storage come tipo di destinazione e fai clic su Passaggio successivo.
Seleziona un pool di agenti esistente o seleziona Crea pool di agenti e segui le istruzioni per creare un nuovo pool.
Specifica il percorso completo della directory del file system.
Fai clic su Passaggio successivo.
Nel campo Bucket o cartella , inserisci il nome del bucket di destinazione e (facoltativamente) della cartella oppure fai clic su Sfoglia per selezionare un bucket da un elenco di bucket esistenti nel progetto corrente. Per creare un nuovo bucket, fai clic su Crea nuovo bucket.
Fai clic su Passaggio successivo.
Scegli le opzioni di pianificazione.

Nota: Storage Transfer Service visualizza le pianificazioni dei job di trasferimento nel tuo fuso orario locale, ma memorizza questi orari in UTC (Coordinated Universal Time). Se sei interessato dall'ora legale, potresti riscontrare una modifica della pianificazione del job di trasferimento quando inizia o termina l'ora legale.
Fai clic su Passaggio successivo.
Scegli le impostazioni per il job di trasferimento.
- Nel campo Descrizione, inserisci una descrizione del trasferimento. Come best practice, inserisci una descrizione significativa e univoca in modo da poter distinguere i job.
- In Opzioni metadati, utilizza le opzioni predefinite, o aggiorna uno o più valori. Per i dettagli, consulta Conservazione dei metadati.
- In Quando sovrascrivere, seleziona una delle seguenti opzioni:
  - Mai: Storage Transfer Service salta il trasferimento di tutti i file dall'origine che hanno lo stesso nome di un file presente nella destinazione.
  - Se diverso: sovrascrive i file di destinazione se il file di origine con lo stesso nome ha valori di ETag o checksum diversi.
  - Sempre: sovrascrive sempre i file di destinazione quando il file di origine ha lo stesso nome, anche se sono identici.
- In Quando eliminare, seleziona una delle seguenti opzioni:
  - Mai: non eliminare mai i file dall'origine o dalla destinazione.
  - Elimina i file dall'origine dopo il trasferimento: elimina i file dall'origine dopo il trasferimento alla destinazione. Se un file di origine non viene trasferito, ad esempio perché esiste già nella destinazione, il file di origine non viene eliminato.
    
    Importante: se non hai un backup locale, questa opzione è un'azione non reversibile.
  - Elimina i file dalla destinazione se non sono presenti anche nell'origine: se i file nel bucket Cloud Storage di destinazione non sono presenti anche nell' origine, elimina i file dal bucket Cloud Storage di destinazione.
    
    Questa opzione garantisce che il bucket Cloud Storage di destinazione corrisponda esattamente all'origine.
- Scegli se abilitare il logging in Cloud Storage e/o abilitare il logging in Cloud Logging. Per ulteriori informazioni, consulta Log di trasferimento del file system e Cloud Logging per Storage Transfer Service.
Per creare il job di trasferimento, fai clic su Crea.

`gcloud`

Prima di utilizzare gcloud comandi, installa Google Cloud CLI.

Per creare un nuovo job di trasferimento, utilizza il comando gcloud transfer jobs create. La creazione di un nuovo job avvia il trasferimento specificato, a meno che non venga specificata una pianificazione o --do-not-run.

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

Sostituisci quanto segue:

SOURCE è un percorso assoluto dalla radice del file system. È preceduto da posix://, quindi il valore finale includerà 3 barre. Ad esempio, posix:///tmp/data/.
DESTINATION è il nome di un bucket Cloud Storage e, facoltativamente, un percorso di cartella seguito da una barra finale. Ad esempio, gs://example-bucket/data/.
--source-agent-pool specifica il pool di agenti di origine da utilizzare per questo trasferimento.

Altre opzioni sono:

--do-not-run impedisce a Storage Transfer Service di eseguire il job al momento dell'invio del comando. Per eseguire il job, aggiornalo per aggiungere una pianificazione o utilizza jobs run per avviarlo manualmente.
--manifest-file specifica il percorso di un file CSV in Cloud Storage contenente un elenco di file da trasferire dall'origine. Per la formattazione del file manifest, consulta Trasferisci file o oggetti specifici utilizzando un manifest.
Informazioni sul job: puoi specificare --name e --description.
Pianificazione: specifica --schedule-starts, --schedule-repeats-every e --schedule-repeats-until oppure --do-not-run.
Opzioni di trasferimento: specifica se sovrascrivere i file di destinazione (--overwrite-when=different o always) e se eliminare determinati file durante o dopo il trasferimento (--delete-from=destination-if-unique o source-after-transfer); specifica quali valori dei metadati conservare (--preserve-metadata); e, facoltativamente, imposta una classe di archiviazione sugli oggetti trasferiti (--custom-storage-class).

Per visualizzare tutte le opzioni, esegui gcloud transfer jobs create --help o consulta la gcloud documentazione di riferimento. Tieni presente che non tutte le opzioni sono supportate per i trasferimenti basati su agenti; le opzioni non supportate contengono una nota in questo senso nel testo della guida.

REST

L'esempio seguente mostra come utilizzare Storage Transfer Service tramite l'API REST.

Quando configuri o modifichi i job di trasferimento utilizzando l'API Storage Transfer Service, l'ora deve essere in formato UTC. Per ulteriori informazioni sulla specifica della pianificazione di un job di trasferimento, consulta Pianificazione.

Per spostare i file da un file system POSIX a un bucket Cloud Storage, utilizza transferJobs.create con un posixDataSource:

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/"
     },
  }
}

Il campo schedule è facoltativo; se non è incluso, il job di trasferimento deve essere avviato con una richiesta transferJobs.run.

Per controllare lo stato del trasferimento dopo la creazione di un job, utilizza transferJobs.get:

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

Librerie client

Gli esempi seguenti mostrano come utilizzare Storage Transfer Service a livello di programmazione con Go, Java, Node.js e Python.

Quando configuri o modifichi i job di trasferimento a livello di programmazione, l'ora deve essere in formato UTC. Per ulteriori informazioni sulla specifica della pianificazione di un job di trasferimento, consulta Pianificazione.

Per ulteriori informazioni sulle librerie client di Storage Transfer Service, consulta Guida introduttiva alle librerie client di Storage Transfer Service.

Per spostare i file da un file system POSIX a un bucket Cloud Storage:

Vai


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