Transférer des fichiers ou des objets spécifiques à l'aide d'un fichier manifeste

Le service de transfert de stockage permet de transférer des fichiers ou des objets spécifiques, qui sont spécifiés à l'aide d'un manifest. Un fichier manifeste est un fichier CSV importé dans Cloud Storage qui contient une liste de fichiers ou d'objets sur lesquels le service de transfert de stockage peut agir.

Un fichier manifeste peut être utilisé pour les transferts suivants:

• depuis AWS S3, Azure Blobstore ou Cloud Storage vers un bucket Cloud Storage.

• D'un système de fichiers vers un bucket Cloud Storage

• Du stockage compatible S3 vers un bucket Cloud Storage.

• D'un bucket Cloud Storage vers un système de fichiers

• Entre deux systèmes de fichiers.

• D'une source HTTP/HTTPS accessible au public vers un bucket Cloud Storage. Suivez les instructions de la section Créer une liste d'URL, car le format du fichier manifeste est unique pour les listes d'URL.

Créer un fichier manifeste

Les fichiers manifestes doivent être au format CSV et peuvent contenir n'importe quels caractères UTF-8. La première colonne doit être un nom de fichier ou un nom d'objet spécifié sous forme de chaîne.

Les fichiers manifestes n'acceptent pas les caractères génériques. La valeur doit être un nom de fichier ou d'objet spécifique. Les noms de dossiers sans nom de fichier ou d'objet ne sont pas acceptés.

La taille maximale du fichier manifeste est de 1 Go, ce qui correspond à environ un million de lignes. Si vous devez transférer un fichier manifeste de plus de 1 Go, vous pouvez le diviser en plusieurs fichiers et exécuter plusieurs tâches de transfert.

Si un nom de fichier ou d'objet contient des virgules, il doit être placé entre guillemets doubles, conformément aux normes CSV. Exemple :"object1,a.txt"

Nous vous recommandons de tester votre transfert avec un petit sous-ensemble de fichiers ou d'objets afin d'éviter d'effectuer des appels d'API inutiles en raison d'erreurs de configuration.

Vous pouvez surveiller l'état des transferts de fichiers depuis la page Tâches de transfert. Les fichiers ou objets dont le transfert échoue sont répertoriés dans les journaux de transfert.

Transferts du système de fichiers

Pour créer un fichier manifeste de fichiers sur un système de fichiers, créez un fichier CSV avec une seule colonne contenant les chemins de fichiers relatifs au répertoire racine spécifié lors de la création de la tâche de transfert.

Par exemple, vous pouvez transférer les fichiers de système de fichiers suivants:

Chemin d'accès au fichier
rootdir/dir1/subdir1/file1.txt
rootdir/file2.txt
rootdir/dir2/subdir1/file3.txt

Votre fichier manifeste doit ressembler à l'exemple suivant:

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

Transferts de stockage d'objets

Pour créer un fichier manifeste d'objets, créez un fichier CSV dont la première colonne contient les noms d'objet relatifs au nom et au chemin d'accès du bucket spécifiés lors de la création de la tâche de transfert. Tous les objets doivent se trouver dans le même bucket.

Vous pouvez également spécifier une deuxième colonne (facultative) avec le numéro de génération Cloud Storage de la version spécifique à transférer.

Par exemple, vous pouvez transférer les objets suivants:

Chemin d'accès à l'objet	Numéro de génération Cloud Storage
SOURCE_PATH/object1.pdf	1664826685911832
SOURCE_PATH/object2.pdf
SOURCE_PATH/object3.pdf	1664826610699837

Votre fichier manifeste doit ressembler à l'exemple suivant:

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

Enregistrez le fichier manifeste avec un nom de fichier au choix et une extension .csv.

Transferts HTTP/HTTPS

Pour transférer des fichiers spécifiques à partir d'une source HTTP ou HTTPS, consultez les instructions de la section Créer une liste d'URL.

Publier le fichier manifeste

Une fois le fichier manifeste créé, vous devez le mettre à la disposition du service de transfert de stockage. Le service de transfert de stockage peut accéder au fichier dans un bucket Cloud Storage ou dans votre système de fichiers.

Importer le fichier manifeste dans Cloud Storage

Vous pouvez stocker le fichier manifeste dans n'importe quel bucket Cloud Storage.

L'agent de service qui exécute le transfert doit disposer de l'autorisation storage.objects.get pour le bucket contenant le fichier manifeste. Consultez la section Accorder les autorisations requises pour savoir comment trouver l'ID de l'agent de service et lui accorder des autorisations sur un bucket.

Pour savoir comment importer le fichier manifeste dans un bucket, consultez la section Importer des objets de la documentation Cloud Storage.

Par exemple, pour importer un fichier dans Cloud Storage à l'aide de la CLI gcloud, utilisez la commande gcloud storage cp:

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

Où :

• MANIFEST.CSV correspond au chemin d'accès local à votre fichier manifeste. Exemple :Desktop/manifest01.csv

• DESTINATION_BUCKET_NAME correspond au nom du bucket dans lequel vous importez votre objet. Exemple : my-bucket.

Si l'opération réussit, la réponse se présente comme suit :

Completed files 1/1 | 164.3kiB/164.3kiB

Vous pouvez chiffrer un fichier manifeste à l'aide de clés de chiffrement Cloud KMS gérées par le client. Dans ce cas, assurez-vous que tous les comptes de service accédant au fichier manifeste se voient attribuer les clés de chiffrement applicables. Les clés fournies par le client ne sont pas acceptées.

Stocker le fichier manifeste sur un système de fichiers

Vous pouvez stocker le fichier manifeste dans votre système de fichiers source ou de destination.

L'emplacement du fichier doit être accessible aux agents de transfert. Si vous limitez l'accès au répertoire pour vos agents, assurez-vous que le fichier manifeste se trouve dans un répertoire monté.

Commencer le transfert

Ne modifiez pas le fichier manifeste tant qu'une opération de transfert est en cours. Nous vous recommandons de verrouiller le fichier manifeste lorsque vous effectuez un transfert.

Cloud Console

Pour démarrer un transfert avec un fichier manifeste à partir de la console Cloud:

1. Suivez les instructions de la section Créer des transferts pour sélectionner votre source, votre destination et vos options.

2. À l'étape finale, Choisir les paramètres, cochez la case Fournir la liste des fichiers à transférer via un fichier manifeste.

3. Indiquez l'emplacement du fichier manifeste.

gcloud

Pour transférer les fichiers ou les objets répertoriés dans le fichier manifeste, incluez l'option --manifest-file=MANIFEST_FILE avec votre commande gcloud transfer jobs create.

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

MANIFEST_FILE peut correspondre à l'une des valeurs suivantes:

• Chemin d'accès au fichier CSV dans un bucket Cloud Storage:

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

  Consultez la section Importer le fichier manifeste dans Cloud Storage pour en savoir plus sur les autorisations requises si le bucket ou le fichier n'est pas public.

• Chemin relatif du système de fichiers SOURCE, y compris tout chemin spécifié:

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

• Chemin relatif du système de fichiers DESTINATION, y compris tout chemin spécifié:

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

REST et bibliothèques clientes

REST

Pour transférer les fichiers ou les objets répertoriés dans le fichier manifeste, effectuez un appel d'API createTransferJob qui spécifie une transferSpec pour laquelle le champ transferManifest est ajouté. Exemple :

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

Le fichier manifeste peut être stocké dans un bucket Cloud Storage, ou sur le système de fichiers source ou de destination. Les buckets Cloud Storage doivent utiliser le préfixe gs:// et inclure le chemin complet, y compris le nom du bucket. Les emplacements du système de fichiers doivent utiliser un préfixe source:// ou destination:// et sont relatifs à la source ou à la destination du système de fichiers, ainsi qu'au répertoire racine facultatif.

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

Les objets ou fichiers spécifiés dans le fichier manifeste ne sont pas nécessairement transférés dans l'ordre indiqué.

Si le fichier manifeste inclut des fichiers qui existent déjà dans la destination, ceux-ci sont ignorés, sauf si l'option Remplacer les objets déjà existants dans le sink est spécifiée.

Si le fichier manifeste comprend des objets qui existent dans une version différente de la destination, l'objet présent dans la destination est remplacé par la version source de l'objet. Si la destination est un bucket avec gestion des versions, une nouvelle version de l'objet est créée.

Étape suivante

• Apprenez à filtrer les objets des transferts.
• Apprenez à planifier des tâches de transfert.