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 fichier manifeste. 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

• D'un espace de stockage compatible S3 vers un bucket Cloud Storage

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

• Entre deux systèmes de fichiers.

• Depuis 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 quel caractère UTF-8. La première colonne doit contenir un nom de fichier ou un nom d'objet spécifié sous forme de chaîne.

Les fichiers manifestes ne sont pas compatibles avec les caractères génériques. La valeur doit correspondre à un nom de fichier ou d'objet spécifique. Les noms de dossier sans nom de fichier ou d'objet ne sont pas acceptés.

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

Si le nom d'un fichier ou d'un objet contient des virgules, il doit être entouré de guillemets doubles, conformément aux normes CSV. Par exemple, "object1,a.txt".

Nous vous recommandons de tester le transfert avec un petit sous-ensemble de fichiers ou d'objets afin d'éviter les 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 dans un système de fichiers, créez un fichier CSV avec une seule colonne contenant les chemins d'accès aux 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

Le fichier manifeste doit se présenter comme suit:

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'objets relatifs au nom du bucket et au chemin d'accès 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 de l'objet	Numéro de génération Cloud Storage
SOURCE_PATH/object1.pdf	1664826685911832
SOURCE_PATH/object2.pdf
SOURCE_PATH/object3.pdf	1664826610699837

Le fichier manifeste doit se présenter comme suit:

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

Enregistrez le fichier manifeste sous n'importe quel nom et sous l'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 rendre disponible pour le service de transfert de stockage. Le service de transfert de stockage peut accéder au fichier dans un bucket Cloud Storage ou sur 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 dans la documentation de Cloud Storage.

Par exemple, pour utiliser la CLI gcloud afin d'importer un fichier dans Cloud Storage, utilisez la commande gcloud storage cp:

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

Où :

• MANIFEST.CSV est le chemin d'accès local à votre fichier manifeste. Par 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 dans 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 restreignez l'accès au répertoire pour vos agents, assurez-vous que le fichier manifeste se trouve dans un répertoire installé.

Commencer un transfert

Ne modifiez pas le fichier manifeste tant qu'une opération de transfert n'est pas terminée. Nous vous recommandons de verrouiller le fichier manifeste lors d'un transfert.

console Cloud

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, Choose settings (Sélectionner les paramètres), cochez la case Provide list of files to Transfer via manifest file (Fournir une liste de 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 stocké dans un bucket Cloud Storage:

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

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

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

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

• Chemin d'accès relatif à partir du système de fichiers DESTINATION, y compris tout chemin d'accès 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 spécifiant un élément transferSpec avec le champ transferManifest 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 d'accès complet, y compris le nom du bucket. Les emplacements des systèmes 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, ces fichiers sont ignorés, sauf si l'option écraser les objets déjà présents dans le récepteur 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.

Étapes suivantes

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