Cette page a été traduite par l'API Cloud Translation.

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 des transferts basés sur des agents. Autrement dit, 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 les 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 à la CLI gcloud. Le compte utilisateur peut être un compte utilisateur standard ou 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`.
	Compte de l'agent de transfert qui fournit des autorisations Google Cloud aux agents de transfert. Les comptes d'agent de transfert utilisent les identifiants de l'utilisateur qui les installe ou les identifiants d'un compte de service géré par l'utilisateur pour s'authentifier.

Pour obtenir des instructions, consultez la section Autorisations de transfert basées sur les agents.

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 de votre pool d'agents ou dans 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 peuvent être exposés à des systèmes internes à Google en dehors de votre projet.

Créez un pool d'agents. Utilisez votre compte utilisateur pour cette action.
Installez des agents dans le pool d'agents. Pour effectuer cette action, utilisez votre compte d'agent de transfert .

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

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

Options de transfert

Les fonctionnalités suivantes du service de transfert de stockage sont disponibles pour les transferts de 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 à traiter par le service de transfert de stockage. Pour en savoir plus, consultez la section Transférer des fichiers ou des objets spécifiques à l'aide d'un fichier manifeste.

Spécifier la classe de stockage

Vous pouvez spécifier la classe de stockage Cloud Storage à utiliser pour vos données dans le bucket de destination. Pour en savoir plus sur REST, consultez les options StorageClass ou utilisez l'option --custom-storage-class avec Google Cloud CLI.

Notez que tous les paramètres de classe de stockage sont ignorés si la classe automatique Autoclass est activée pour 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 réécrits ultérieurement sur un système de fichiers, le service de transfert de stockage peut reconvertir les métadonnées conservées en attributs POSIX.

Consultez la section Transferts à partir de systèmes de fichiers POSIX de la section Conservation des métadonnées pour en savoir plus sur les métadonnées pouvant être conservées et sur la configuration de votre transfert.

Gérer la bande passante réseau

Par défaut, le service de transfert de stockage utilise autant de bande passante que possible 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 d'autres trafics réseau. Les limites de bande passante sont appliquées au niveau du pool d'agents.

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

Votre compte utilisateur nécessite le rôle Storage Transfer Admin (roles/storagetransfer.admin) pour définir ou modifier les 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 des agents.

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 votre tâche de transfert. Les noms de ressources peuvent être propagés aux noms d'autres ressources Google Cloud et peuvent être exposés à des systèmes internes à Google en dehors de votre projet.

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

Console Google Cloud

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

Accéder au service de transfert de stockage
Cliquez sur Créer une tâche de transfert. La page Créer une tâche de transfert s'affiche.
Sélectionnez Système de fichiers POSIX comme source.
Sélectionnez Cloud Storage comme type de destination, puis cliquez sur Étape suivante.
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.
Spécifiez le chemin d'accès complet du répertoire du système de fichiers.
Cliquez sur Étape suivante.
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 Créer un bucket.
Cliquez sur Étape suivante.
Choisissez vos options de planification.

Remarque :Le service de transfert de stockage affiche le calendrier des tâches de transfert dans votre fuseau horaire local, mais il les stocke au format UTC (Universal Time Coordinated). Si vous êtes concerné par l'heure d'été, il est possible que le calendrier soit modifié lors du passage à l'heure d'été ou du retour à l'heure d'hiver.
Cliquez sur Étape suivante.
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 pouvoir différencier 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 de tous les fichiers de la source portant 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.
    
    Important : Si vous ne disposez pas d'une sauvegarde locale, cette option est une action irréversible.
  - 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 et/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.
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. Il est préfixé par posix://, de sorte que la valeur finale inclura trois barres obliques. Par exemple, posix:///tmp/data/.
DESTINATION est le nom d'un bucket Cloud Storage et, facultativement, 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 planification 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 toutes les options ne sont pas compatibles avec les transferts via un agent. Les options non compatibles contiennent une note à cet effet dans leur texte d'aide.

REST

L'exemple suivant 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 en savoir plus sur la spécification de la planification d'une tâche de transfert, consultez la section Planifier.

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 de façon automatisée, l'heure doit être au format UTC. Pour en savoir plus sur la spécification de la planification d'une tâche de transfert, consultez la section Planifier.

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:

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