從檔案系統轉移至 Cloud Storage

本頁面說明如何在地端部署或雲端檔案系統與 Cloud Storage 之間建立移轉工作。

從檔案系統移轉至 Cloud Storage 的作業是代理式移轉作業，也就是說，您必須在可存取檔案系統的機器上安裝軟體代理程式，才能安排移轉作業。

必要條件

設定移轉作業前，請務必先完成下列設定：

  • 使用者權限：確認您的使用者帳戶或使用者自行管理的服務帳戶，有權設定移轉工作和代理程式集區。請參閱「必要的使用者授權」。
  • 代理程式專案層級權限：請務必為服務代理和移轉代理帳戶，設定必要的專案層級角色。請參閱「代理程式專案層級權限」。
  • 來源檔案系統權限：請確認執行代理程式容器的作業系統使用者，具備來源檔案的讀取的權限。請參閱「設定來源存取權：檔案系統」。
  • 目的地 bucket 權限：授予目的地 Cloud Storage bucket 的必要權限。請參閱「設定接收器的存取權：Cloud Storage」。

將代理程式安裝到代理程式集區

代理式移轉作業會使用軟體代理來自動調度管理移轉作業。這些代理程式必須安裝在可存取移轉作業所涉檔案系統的機器上。

請勿在代理程式集區名稱或代理程式 ID 前置字串中，加入個人識別資訊 (PII) 或安全性資料等機密資訊。資源名稱可能會傳播至其他 Google Cloud 資源的名稱，並可能在專案外部向 Google 內部系統公開。
  1. 建立代理程式集區。
  2. 將代理程式安裝到代理程式集區。

建議您先在來源代理程式集區中設定 3 個代理程式。轉移作業開始後，請監控轉移速度。您可以在轉移作業進行期間，將更多代理程式新增至集區。

建議每個代理程式使用一個 VM，每個 VM 至少有 4 個 CPU 和 8 GiB RAM。

轉移作業選項

下列 Storage 移轉服務功能適用於從檔案系統移轉至 Cloud Storage。

使用資訊清單轉移特定檔案
您可以傳遞檔案清單，讓 Storage 移轉服務執行操作。詳情請參閱「使用資訊清單移轉特定檔案或物件」。
指定儲存空間級別
您可以指定目的地 bucket 中資料要使用的 Cloud Storage 儲存空間級別。如要瞭解 REST 詳情，請參閱 StorageClass 選項，或搭配使用 --custom-storage-class 旗標和 Google Cloud CLI。

請注意，如果目的地 bucket 已啟用 Autoclass，系統會忽略所有儲存空間級別設定。如果啟用自動調整級別功能，轉移至 bucket 的物件一開始會設為 Standard Storage。

保存中繼資料

從檔案系統移轉檔案時，Storage 移轉服務可選擇將特定屬性保留為自訂中繼資料。如果這些檔案之後寫回檔案系統，Storage 移轉服務可以將保留的中繼資料轉換回 POSIX 屬性。

如要瞭解可保留的中繼資料，以及如何設定移轉作業，請參閱「中繼資料保留」的「POSIX 檔案系統移轉」一節。

管理網路頻寬
Storage 移轉服務預設會使用所有可用頻寬，從檔案系統移轉檔案。您可以設定頻寬限制，避免移轉作業影響其他網路流量。頻寬限制會套用至代理程式集區層級。

詳情請參閱「管理網路頻寬」。

您的使用者帳戶必須具備 Storage 移轉作業管理員 (roles/storagetransfer.admin) 角色，才能設定或變更頻寬限制。

記錄
Storage 移轉服務支援 Storage 移轉服務適用的 Cloud Logging (建議)，以及代理式移轉作業記錄。

建立移轉作業

請勿在移轉工作名稱中加入機密資訊，例如個人識別資訊 (PII) 或安全性資料。資源名稱可能會傳播至其他 Google Cloud 資源的名稱，並可能在專案外部向 Google 內部系統公開。

Storage 移轉服務提供多個介面，可用來建立移轉作業。

Google Cloud 控制台

  1. 前往 Google Cloud 控制台的「Storage 移轉服務」頁面。

    前往 Storage 移轉服務

  2. 按一下「建立移轉工作」。系統會顯示「Create a transfer job」(建立移轉工作) 頁面。

  3. 選擇「POSIX file system」(POSIX 檔案系統) 做為來源。

  4. 選取「Cloud Storage」做為目的地類型，然後點選「下一步」。

  5. 選取現有的代理程式集區，或選取「Create agent pool」(建立代理程式集區)，然後按照操作說明建立新的集區。

  6. 指定檔案系統目錄的完整路徑。

  7. 點選「下一步」。

  8. 在「Bucket or folder」(Bucket 或資料夾) 欄位中，輸入目的地 bucket 和資料夾名稱 (選用)，或按一下「Browse」(瀏覽)，從目前專案的現有 bucket 清單中選取 bucket。如要建立新的 bucket，請按一下 「值區」圖示「Create new bucket」(建立新的 bucket)。

  9. 點選「下一步」。

  10. 選擇排程選項。

  11. 點選「下一步」。

  12. 選擇轉移工作的設定。

    • 在「Description」(說明) 欄位中，輸入移轉作業的說明。建議您輸入有意義且不重複的說明，以便區分工作。

    • 在「Metadata options」(中繼資料選項) 下方，使用預設選項，或更新一或多個值。詳情請參閱「中繼資料保留」。

    • 在「覆寫時機」下方，選取下列其中一個選項：

      • 「Never」(一律不)：Storage 移轉服務會略過來源中與目的地檔案同名的檔案，不予移轉。

      • 如果不同：如果同名的來源檔案有不同的 Etag 或核對和值，則覆寫目的地檔案。

      • 一律覆寫：來源檔案與目的地檔案的名稱相同時，一律覆寫目的地檔案，即便檔案內容完全相同。

    • 在「刪除時間」下方，選取下列其中一個選項：

      • 一律不：一律不刪除來源或目的地的檔案。

      • 轉移檔案後，請從來源刪除檔案：檔案轉移至目的地後，從來源刪除檔案。如果來源檔案未轉移 (例如目的地已存在該檔案)，則不會刪除來源檔案。

      • Delete files from destination if they're not also at source：如果目的地 Cloud Storage bucket 中的檔案未同時存在於來源，則從 Cloud Storage bucket 中刪除這些檔案。

        這個選項可確保目的地 Cloud Storage bucket 與來源完全相符。

    • 選取是否要啟用 Cloud Storage 記錄功能和/或啟用 Cloud Logging 記錄功能。詳情請參閱「檔案系統移轉記錄檔」和「Storage 移轉服務的 Cloud Logging」。

  13. 如要建立移轉工作，請按一下「Create」(建立)。

gcloud

使用 gcloud 指令前，請先安裝 Google Cloud CLI。

如要建立新的移轉工作，請使用 gcloud transfer jobs create 指令。建立新工作會啟動指定的移轉作業，除非指定排程或 --do-not-run。

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

更改下列內容：

  • SOURCE 是檔案系統根目錄的絕對路徑。這個值的前置字串為 posix://，因此最終值會包含 3 個正斜線。例如：posix:///tmp/data/。

  • DESTINATION 是 Cloud Storage bucket 的名稱，後面可選擇加上資料夾路徑和斜線。例如：gs://example-bucket/data/。

  • --source-agent-pool 指定這項移轉作業要使用的來源代理集區。

其他選項包括：

  • --do-not-run 可防止 Storage 移轉服務在提交指令後執行工作。如要執行工作，請更新工作並新增排程，或使用 jobs run 手動啟動。

  • --manifest-file 指定 Cloud Storage 中 CSV 檔案的路徑，該檔案包含要從來源轉移的檔案清單。如要瞭解資訊清單檔案格式，請參閱「使用資訊清單移轉特定檔案或物件」。

  • 工作資訊：您可以指定 --name 和 --description。

  • 排程：指定 --schedule-starts、--schedule-repeats-every 和 --schedule-repeats-until，或 --do-not-run。

  • 移轉選項：指定是否要覆寫目的地檔案 (--overwrite-when=different 或 always)，以及是否要在移轉期間或之後刪除特定檔案 (--delete-from=destination-if-unique 或 source-after-transfer)；指定要保留的中繼資料值 (--preserve-metadata)；以及視需要為移轉的物件設定儲存空間級別 (--custom-storage-class)。

如要查看所有選項，請執行 gcloud transfer jobs create --help 或參閱 gcloud 參考文件。請注意，並非所有選項都支援代理程式型移轉作業；不支援的選項會在說明文字中註明。

REST

以下範例說明如何透過 REST API 使用 Storage 移轉服務。

使用 Storage 移轉服務 API 設定或編輯移轉工作時，時間必須採用世界標準時間。如要進一步瞭解如何指定移轉工作的排程，請參閱「排程」。

如要將檔案從 POSIX 檔案系統移至 Cloud Storage bucket，請使用 transferJobs.create，並搭配 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/"
     }
  }
}

schedule 欄位為選填。如未加入，則必須使用 transferJobs.run 要求啟動移轉工作。

如要在建立工作後查看轉移作業狀態，請使用 transferJobs.get：

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

用戶端程式庫

下列範例說明如何透過 Go、Java、Node.js 和 Python，以程式輔助方式使用 Storage 移轉服務。

以程式輔助方式設定或編輯移轉工作時，時間必須採用世界標準時間。如要進一步瞭解如何指定移轉工作的排程，請參閱「排程」。

如要進一步瞭解 Storage 移轉服務用戶端程式庫，請參閱「開始使用 Storage 移轉服務用戶端程式庫」。

如要將檔案從 POSIX 檔案系統移至 Cloud Storage bucket，請按照下列步驟操作：

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