Halaman ini diterjemahkan oleh Cloud Translation API.

Mentransfer dari sistem file ke Cloud Storage

Halaman ini menunjukkan cara membuat tugas transfer antarsistem file (baik lokal atau cloud) dan Cloud Storage.

Transfer dari sistem file ke Cloud Storage adalah transfer berbasis agen, yang berarti Anda akan menginstal agen perangkat lunak pada komputer dengan akses ke sistem file untuk mengorkestrasi transfer.

Konfigurasikan izin

Sebelum membuat transfer, Anda harus mengonfigurasi izin untuk entitas:

	Akun pengguna yang digunakan untuk membuat transfer. Ini adalah yang login ke Konsol Google Cloud, atau akun yang yang ditentukan saat mengautentikasi ke CLI `gcloud`. Akun pengguna dapat akun pengguna biasa, atau akun layanan yang dikelola pengguna.
	Akun layanan yang dikelola Google, juga dikenal sebagai layanan , yang digunakan oleh Storage Transfer Service. Akun ini umumnya diidentifikasi oleh alamat emailnya, yang menggunakan format `project-PROJECT_NUMBER@storage-transfer-service.`.
	Akun agen transfer yang menyediakan Google Cloud untuk agen transfer. Akun agen transfer menggunakan kredensial pengguna yang menginstalnya, atau kredensial pengguna akun layanan yang dikelola pengguna, untuk melakukan otentikasi.

Lihat Izin transfer berbasis agen untuk melihat petunjuk.

Menginstal agen ke dalam kumpulan agen

Transfer berbasis agen menggunakan agen software untuk mengorkestrasi transfer. Agen-agen ini harus diinstal pada komputer dengan akses ke sistem file yang terlibat dalam transfer data.

Jangan sertakan informasi sensitif seperti informasi identitas pribadi (PII) atau data keamanan di nama kumpulan agen atau awalan ID agen Anda. Nama resource mungkin disebarkan ke nama resource Google Cloud lainnya dan dapat diekspos ke sistem internal Google di luar project Anda.

Buat kumpulan agen. Gunakan akun pengguna untuk tindakan ini.
Menginstal agen ke dalam kumpulan agen. Gunakan akun agen transfer untuk tindakan ini.

Sebaiknya mulai dengan 3 agen di kumpulan agen sumber Anda. Setelah transfer sedang berlangsung, pantau kecepatan transfer; Anda dapat menambahkan agen lainnya ke dalam kumpulan saat transfer berlangsung.

Kami merekomendasikan satu VM per agen, masing-masing dengan minimal 4 CPU dan RAM 8 GiB.

Opsi transfer

Fitur Storage Transfer Service berikut tersedia untuk transfer dari sistem file ke Cloud Storage.

Mentransfer file tertentu menggunakan manifes

Anda dapat meneruskan daftar file agar Storage Transfer Service dapat ditindaklanjuti. Lihat Mentransfer file tertentu atau menggunakan manifes untuk mengetahui detailnya.

Menentukan kelas penyimpanan

Anda dapat menentukan Kelas penyimpanan Cloud Storage yang akan digunakan untuk data Anda di tujuan direktori VM dengan bucket. Lihat StorageClass opsi untuk detail REST, atau gunakan --custom-storage-class dengan Google Cloud CLI.

Perhatikan bahwa setelan kelas penyimpanan apa pun akan diabaikan jika tujuan bucket mengaktifkan Autoclass. Jika Autoclass diaktifkan, objek yang ditransfer ke dalam bucket pada awalnya akan ke Standard Storage.

Penyimpanan metadata

Saat mentransfer file dari sistem file, Storage Transfer Service dapat secara opsional mempertahankan atribut tertentu sebagai metadata khusus. Jika file ini kemudian ditulis kembali ke sistem file, Storage Transfer Service dapat mengonversi metadata yang dipertahankan kembali ke atribut POSIX.

Lihat bagian transfer sistem file POSIX dari Metadata penyimpanan untuk mengetahui detail tentang metadata mana yang dapat dipertahankan, dan cara mengkonfigurasi transfer Anda.

Mengelola bandwidth jaringan

Storage Transfer Service secara default menggunakan bandwidth sebanyak yang tersedia untuknya untuk mentransfer file dari sistem file Anda. Anda dapat menetapkan batas bandwidth ke mencegah transfer mempengaruhi lalu lintas jaringan lainnya. Batas bandwidth diterapkan pada tingkat kumpulan agen.

Lihat Mengelola jaringan untuk mempelajari lebih lanjut.

Akun pengguna Anda memerlukan Storage Transfer Admin (roles/storagetransfer.admin) peran yang akan ditetapkan atau diubah batas bandwidth.

Logging

Storage Transfer Service mendukung Cloud Logging untuk Storage Transfer Service (direkomendasikan) serta berbasis agen mentransfer log.

Buat transfer

Jangan sertakan informasi sensitif seperti informasi identitas pribadi (PII) atau data keamanan dalam nama tugas transfer Anda. Nama resource mungkin disebarkan ke nama resource Google Cloud lainnya dan dapat diekspos ke sistem internal Google di luar project Anda.

Storage Transfer Service menyediakan beberapa antarmuka untuk membuat transfer data.

Konsol Google Cloud

Buka halaman Storage Transfer Service di Konsol Google Cloud.

Buka Storage Transfer Service
Klik Buat tugas transfer. Halaman Buat tugas transfer ditampilkan.
Pilih sistem file POSIX sebagai sumbernya.
Pilih Cloud Storage sebagai jenis tujuan, lalu klik Langkah berikutnya.
Pilih kumpulan agen yang ada, atau pilih Buat kumpulan agen, ikuti petunjuk untuk membuat kumpulan baru.
Tentukan jalur direktori sistem file yang sepenuhnya memenuhi syarat.
Klik Next step.
Di kolom Bucket or folder, masukkan bucket tujuan dan (opsional) nama folder, atau klik Jelajahi untuk memilih bucket dari daftar bucket yang ada di project saat ini. Untuk membuat bucket baru, klik Buat bucket baru.
Klik Next step.
Pilih opsi penjadwalan.

Catatan: Storage Transfer Service menampilkan jadwal tugas transfer di zona waktu lokal, tetapi menyimpan waktu tersebut dalam Waktu Universal Terkoordinasi (UTC). Jika terpengaruh oleh Waktu Musim Panas (DST), Anda mungkin mengalami perubahan jadwal tugas transfer saat DST dimulai atau berakhir.
Klik Next step.
Pilih setelan untuk tugas transfer.
- Di kolom Description, masukkan deskripsi transfer data. Sebagai praktik terbaik, masukkan deskripsi yang bermakna dan unik sehingga Anda dapat membedakan tugas-tugasnya.
- Di bagian Metadata options, gunakan opsi default, atau perbarui satu atau beberapa nilai. Lihat Preservasi metadata untuk mengetahui detailnya.
- Di bagian Kapan harus menimpa, pilih salah satu dari opsi berikut:
  - Tidak pernah: Storage Transfer Service melewati transfer file apa pun dari sumber yang memiliki nama yang sama dengan file yang ada di tujuan.
  - Jika berbeda: Timpa file tujuan jika file sumbernya dengan nama yang sama memiliki nilai Etag atau {i>checksum<i} yang berbeda.
  - Always: Selalu menimpa file tujuan saat file sumber memiliki nama yang sama, meskipun identik.
- Di bagian Kapan harus dihapus, pilih salah satu opsi berikut:
  - Tidak pernah: Jangan pernah menghapus file dari sumber atau tujuan.
  - Hapus file dari sumber setelah ditransfer: Menghapus file dari sumber setelah ditransfer ke tujuan.
    
    Penting: Jika Anda tidak memiliki cadangan lokal, opsi ini adalah tindakan non-reversibel.
  - Hapus file dari tujuan jika file juga tidak ada di sumber: Jika file di bucket Cloud Storage tujuan juga tidak ada di sumbernya, lalu menghapus file dari Cloud Storage direktori VM dengan bucket.
    
    Opsi ini memastikan bahwa bucket Cloud Storage tujuan sama persis dengan sumber.
- Pilih apakah Aktifkan logging di Cloud Storage dan/atau Aktifkan logging di Cloud Logging. Lihat Log transfer sistem file dan Cloud Logging untuk Storage Transfer Service untuk informasi selengkapnya.
Untuk membuat tugas transfer, klik Buat.

`gcloud`

Sebelum menggunakan perintah gcloud, instal Google Cloud CLI.

Untuk membuat tugas transfer baru, gunakan gcloud transfer jobs create perintah. Membuat tugas baru akan memulai transfer yang ditentukan, kecuali jika jadwal atau --do-not-run ditentukan.

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

Dengan keterangan:

SOURCE adalah jalur absolut dari {i>root<i} sistem file. ID ini diawali dengan posix:// sehingga nilai akhir akan menyertakan 3 garis miring. Misalnya, posix:///tmp/data/.
DESTINATION adalah salah satu nama bucket Cloud Storage dan, opsional, jalur folder diikuti dengan garis miring. Contoh, gs://example-bucket/data/.
--source-agent-pool menentukan kumpulan agen sumber yang akan digunakan untuk objek ini transfer data.

Opsi tambahan mencakup:

--do-not-run mencegah Storage Transfer Service menjalankan tugas setelah pengiriman perintah. Untuk menjalankan tugas, perbarui ke tambahkan jadwal, atau gunakan jobs run untuk memulainya secara manual.
--manifest-file menentukan jalur ke file CSV di Cloud Storage yang berisi daftar file yang akan ditransfer dari sumber Anda. Untuk file manifes pemformatan, lihat Mentransfer file atau objek tertentu menggunakan manifes.
Informasi pekerjaan: Anda dapat menetapkan --name dan --description.
Jadwal: Tentukan --schedule-starts, --schedule-repeats-every, dan --schedule-repeats-until, atau --do-not-run.
Opsi transfer: Tentukan apakah akan menimpa tujuan file (--overwrite-when=different atau always) dan apakah akan menghapus file tertentu selama atau setelah transfer (--delete-from=destination-if-unique atau source-after-transfer); sebutkan nilai metadata yang akan dipertahankan (--preserve-metadata); dan secara opsional menetapkan kelas penyimpanan pada objek yang ditransfer (--custom-storage-class).

Untuk melihat semua opsi, jalankan gcloud transfer jobs create --help atau lihat Dokumentasi referensi gcloud. Perlu diketahui bahwa tidak semua opsi didukung untuk transfer berbasis agen; opsi yang tidak didukung mencantumkan catatan tentang efek ini di teks bantuannya.

REST

Contoh berikut menunjukkan cara menggunakan Storage Transfer Service melalui REST Compute Engine API.

Saat Anda mengonfigurasi atau mengedit tugas transfer menggunakan Storage Transfer Service API, waktu harus dalam UTC. Untuk mengetahui informasi selengkapnya tentang yang menentukan jadwal tugas transfer, Jadwal.

Untuk memindahkan file dari sistem file POSIX ke bucket Cloud Storage, Gunakan transferJobs.create dengan 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/"
     },
  }
}

Tujuan schedule isian opsional; jika tidak disertakan, tugas transfer harus dimulai dengan permintaan transferJobs.run.

Untuk memeriksa status transfer setelah membuat tugas, gunakan transferJobs.get:

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

Library klien

Contoh berikut menunjukkan cara menggunakan Storage Transfer Service secara terprogram dengan Go, Java, Node.js, dan Python.

Jika Anda mengonfigurasi atau mengedit tugas transfer secara terprogram, waktunya harus dalam UTC. Untuk mengetahui informasi selengkapnya tentang yang menentukan jadwal tugas transfer, Jadwal.

Untuk informasi selengkapnya tentang library klien Storage Transfer Service, lihat Mulai menggunakan library klien Storage Transfer Service.

Untuk memindahkan file dari sistem file POSIX ke 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}")