Transférer des données d'un système de fichiers vers Cloud Storage

Cette page explique comment créer des tâches de transfert entre un système de fichiers (sur site ou dans le cloud) et Cloud Storage.

Les transferts de systèmes de fichiers vers Cloud Storage sont basés sur des agents. En d'autres termes, vous devez installer des agents logiciels sur une machine ayant accès à votre système de fichiers pour orchestrer le transfert.

Configurer les autorisations

Avant de créer un transfert, vous devez configurer des autorisations pour les entités suivantes:

Compte utilisateur utilisé pour créer le transfert. Il s'agit du compte connecté à la console Google Cloud ou du compte spécifié lors de l'authentification auprès de la CLI gcloud. Il peut s'agir d'un compte utilisateur standard ou d'un compte de service géré par l'utilisateur.
Compte de service géré par Google, également appelé agent de service, utilisé par le service de transfert de stockage. Ce compte est généralement identifié par son adresse e-mail, qui utilise le format project-PROJECT_NUMBER@storage-transfer-service.iam.gserviceaccount.com.
Le compte d'agent de transfert qui fournit les autorisations Google Cloud aux agents de transfert. Pour s'authentifier, les comptes d'agent de transfert utilisent les identifiants de l'utilisateur qui les a installés ou ceux d'un compte de service géré par l'utilisateur.

Consultez la section Autorisations de transfert basées sur l'agent pour obtenir des instructions.

Installer des agents dans un pool d'agents

Les transferts basés sur des agents utilisent des agents logiciels pour orchestrer les transferts. Ces agents doivent être installés sur une machine ayant accès au système de fichiers impliqué dans le transfert.

N'incluez pas d'informations sensibles telles que des informations permettant d'identifier personnellement l'utilisateur ou des données de sécurité dans le nom du pool d'agents ou le préfixe de l'ID de l'agent. Les noms de ressources peuvent être propagés aux noms d'autres ressources Google Cloud et exposés aux systèmes internes de Google en dehors de votre projet.
  1. Créez un pool d'agents. Utilisez votre compte utilisateur Symbole de compte utilisateur pour cette action.
  2. Installez des agents dans le pool d'agents. Utilisez votre compte d'agent de transfert pour cette action.

Nous vous recommandons de commencer avec trois agents dans votre pool d'agents source. Une fois le transfert en cours, surveillez la vitesse de transfert. Vous pouvez ajouter d'autres agents au pool pendant que le transfert est en cours.

Nous vous recommandons d'utiliser une VM par agent, chacune disposant d'au moins 4 processeurs et 8 Gio de RAM.

Options de transfert

Les fonctionnalités suivantes du service de transfert de stockage sont disponibles pour les transferts depuis des systèmes de fichiers vers Cloud Storage.

Transférer des fichiers spécifiques à l'aide d'un fichier manifeste
Vous pouvez transmettre une liste de fichiers sur lesquels le service de transfert de stockage doit agir. Pour en savoir plus, consultez la section Transférer des fichiers ou des objets spécifiques à l'aide d'un fichier manifeste.
Spécifier une classe de stockage
Vous pouvez spécifier la classe de stockage Cloud Storage à utiliser pour vos données dans le bucket de destination. Consultez les options StorageClass pour en savoir plus sur REST, ou utilisez l'option --custom-storage-class avec la Google Cloud CLI.

Notez que tous les paramètres de classe de stockage sont ignorés si la fonctionnalité Autoclass est activée sur le bucket de destination. Si la classe automatique est activée, les objets transférés dans le bucket sont initialement définis sur le stockage standard.

Conservation des métadonnées

Lors du transfert de fichiers à partir de systèmes de fichiers, le service de transfert de stockage peut éventuellement conserver certains attributs en tant que métadonnées personnalisées. Si ces fichiers sont ensuite réécrits dans un système de fichiers, le service de transfert de stockage peut reconvertir les métadonnées préservées en attributs POSIX.

Pour savoir quelles métadonnées peuvent être conservées et comment configurer votre transfert, consultez la section Transferts de systèmes de fichiers POSIX de la page Conservation des métadonnées.

Gérer la bande passante réseau
Par défaut, le service de transfert de stockage utilise autant de bande passante que disponible pour transférer des fichiers à partir de votre système de fichiers. Vous pouvez définir une limite de bande passante pour empêcher un transfert d'affecter le reste du trafic réseau. Les limites de bande passante sont appliquées au niveau du pool d'agents.

Pour en savoir plus, consultez la section Gérer la bande passante réseau.

Votre compte utilisateur doit disposer du rôle Administrateur de transfert de stockage (roles/storagetransfer.admin) pour définir ou modifier des limites de bande passante.

Journalisation
Le service de transfert de stockage est compatible avec Cloud Logging pour le service de transfert de stockage (recommandé) ainsi qu'avec les journaux de transfert basés sur un agent.

Créer un transfert

N'incluez pas d'informations sensibles telles que des informations permettant d'identifier personnellement l'utilisateur ou des données de sécurité dans le nom de la tâche de transfert. Les noms de ressources peuvent être propagés aux noms d'autres ressources Google Cloud et exposés aux systèmes internes de Google en dehors de votre projet.

Le service de transfert de stockage fournit plusieurs interfaces permettant de créer un transfert.

Console Google Cloud

  1. Accédez à la page Service de transfert de stockage dans Google Cloud Console.

    Accéder au service de transfert de stockage

  2. Cliquez sur Créer une tâche de transfert. La page Créer une tâche de transfert s'affiche.

  3. Sélectionnez la source Système de fichiers POSIX.

  4. Sélectionnez Cloud Storage comme type de destination, puis cliquez sur Étape suivante.

  5. Sélectionnez un pool d'agents existant ou sélectionnez Créer un pool d'agents et suivez les instructions pour créer un pool d'agents.

  6. Spécifiez le chemin d'accès complet du répertoire du système de fichiers.

  7. Cliquez sur Étape suivante.

  8. Dans le champ Bucket ou dossier, saisissez le nom du bucket de destination et (éventuellement) le nom du dossier, ou cliquez sur Parcourir pour sélectionner un bucket dans une liste existante de buckets de votre projet actuel. Pour créer un bucket, cliquez sur Icône Bucket Créer un bucket.

  9. Cliquez sur Étape suivante.

  10. Choisissez vos options de planification.

  11. Cliquez sur Étape suivante.

  12. Sélectionnez les paramètres de la tâche de transfert.

    • Dans le champ Description, saisissez une description du transfert. Nous vous recommandons de saisir une description pertinente et unique afin de distinguer les tâches.

    • Sous Options de métadonnées, utilisez les options par défaut, ou mettez à jour une ou plusieurs valeurs. Pour en savoir plus, consultez la section Conservation des métadonnées.

    • Sous Écrasement, sélectionnez l'une des options suivantes :

      • Jamais: le service de transfert de stockage ignore le transfert des fichiers depuis la source qui portent le même nom qu'un fichier présent dans la destination.

      • S'ils sont différents : écrase les fichiers de destination si le fichier source du même nom contient d'autres ETags ou valeurs de somme de contrôle.

      • Toujours : écrit toujours les fichiers de destination lorsque le fichier source porte le même nom, même s'ils sont identiques.

    • Sous Dans quel contexte effectuer des suppressions, sélectionnez l'une des options suivantes :

      • Jamais : ne supprime jamais les fichiers de la source ou de la destination.

      • Supprimer les fichiers de la source après leur transfert : supprime les fichiers de la source après leur transfert vers la destination.

      • Supprimer les fichiers de la destination s'ils ne figurent pas dans la source : si les fichiers du bucket Cloud Storage de destination ne figurent pas dans la source, supprimez-les du bucket.

        Cette option garantit que le bucket Cloud Storage de destination correspond exactement à votre source.

    • Indiquez si vous souhaitez activer la journalisation dans Cloud Storage ou activer la journalisation dans Cloud Logging. Pour en savoir plus, consultez les pages Journaux de transfert du système de fichiers et Cloud Logging pour le service de transfert de stockage.

  13. Pour créer votre tâche de transfert, cliquez sur Créer.

gcloud

Avant d'utiliser les commandes gcloud, installez Google Cloud CLI.

Pour créer une tâche de transfert, utilisez la commande gcloud transfer jobs create. La création d'une tâche lance le transfert spécifié, sauf si un calendrier ou une valeur --do-not-run est spécifié.

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

Où :

  • SOURCE est un chemin absolu à partir de la racine du système de fichiers. Comme le préfixe posix:// est ajouté, la valeur finale comprend trois barres obliques. Exemple :posix:///tmp/data/

  • DESTINATION est l'un des noms d'un bucket Cloud Storage et, éventuellement, un chemin d'accès au dossier suivi d'une barre oblique finale. Exemple : gs://example-bucket/data/.

  • --source-agent-pool spécifie le pool d'agents sources à utiliser pour ce transfert.

Des options supplémentaires vous sont proposées :

  • --do-not-run empêche le service de transfert de stockage d'exécuter la tâche lors de l'envoi de la commande. Pour exécuter la tâche, mettez-la à jour pour ajouter une programmation ou utilisez jobs run pour la démarrer manuellement.

  • --manifest-file spécifie le chemin d'accès à un fichier CSV dans Cloud Storage contenant une liste des fichiers à transférer depuis votre source. Pour en savoir plus sur la mise en forme du fichier manifeste, consultez la section Transférer des fichiers ou objets spécifiques à l'aide d'un fichier manifeste.

  • Informations sur la tâche: vous pouvez spécifier --name et --description.

  • Programmation: spécifiez --schedule-starts, --schedule-repeats-every, --schedule-repeats-until ou --do-not-run.

  • Options de transfert : indiquez si vous souhaitez remplacer les fichiers de destination (--overwrite-when=different ou always) et si vous souhaitez supprimer certains fichiers pendant ou après le transfert (--delete-from=destination-if-unique ou source-after-transfer) ; indiquez quelles valeurs de métadonnées sont à conserver (--preserve-metadata) ; et éventuellement définissez une classe de stockage sur des objets transférés (--custom-storage-class).

Pour afficher toutes les options, exécutez gcloud transfer jobs create --help ou reportez-vous à la documentation de référence gcloud. Notez que les options ne sont pas toutes compatibles avec les transferts basés sur un agent. Les options non compatibles comportent une remarque à cet effet dans leur texte d'aide.

REST

L'exemple suivant vous montre comment utiliser le service de transfert de stockage via l'API REST.

Lorsque vous configurez ou modifiez des tâches de transfert à l'aide de l'API Storage Transfer Service, l'heure doit être au format UTC. Pour savoir comment spécifier la programmation d'une tâche de transfert, consultez la section Programmation.

Pour déplacer des fichiers d'un système de fichiers POSIX vers un bucket Cloud Storage, utilisez transferJobs.create avec 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/"
     },
  }
}

Le champ schedule est facultatif. S'il n'est pas inclus, la tâche de transfert doit être démarrée avec une requête transferJobs.run.

Pour vérifier l'état de votre transfert après avoir créé une tâche, utilisez transferJobs.get :

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

Bibliothèques clientes

Les exemples suivants vous montrent comment utiliser le service de transfert de stockage de manière automatisée avec Go, Java, Node.js et Python.

Lorsque vous configurez ou modifiez des tâches de transfert par programmation, l'heure doit être indiquée au format UTC. Pour savoir comment spécifier la programmation d'une tâche de transfert, consultez la section Programmation.

Pour en savoir plus sur les bibliothèques clientes du service de transfert de stockage, consultez la page Premiers pas avec les bibliothèques clientes du service de transfert de stockage.

Pour déplacer des fichiers d'un système de fichiers POSIX vers un bucket Cloud Storage, procédez comme suit:

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