Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

העברה ממערכת קבצים אל Cloud Storage

בדף הזה מוסבר איך ליצור משימות העברה בין מערכת קבצים (במקום או בענן) לבין Cloud Storage.

העברות ממערכות קבצים אל Cloud Storage הן העברות מבוססות-סוכן, כלומר תצטרכו להתקין סוכני תוכנה במכונה עם גישה למערכת הקבצים כדי לתזמן את ההעברה.

הגדרת ההרשאות

לפני שיוצרים העברה, צריך להגדיר הרשאות לישויות הבאות:

	חשבון המשתמש שמשמש ליצירת ההעברה. זהו החשבון שמחוברים אליו במסוף Google Cloud או החשבון שמצוין כשמתבצע אימות ל-CLI של gcloud. חשבון המשתמש יכול להיות חשבון משתמש רגיל או חשבון שירות שמנוהל על ידי משתמש.
	חשבון השירות בניהול Google, שנקרא גם סוכן השירות, שמשמש את Storage Transfer Service. בדרך כלל, החשבון הזה מזוהה באמצעות כתובת האימייל שלו, בפורמט `project-PROJECT_NUMBER@storage-transfer-service.iam.gserviceaccount.com`.
	חשבון סוכן ההעברה שמספק הרשאות Google Cloud לסוכני העברה. חשבונות של סוכני העברה משתמשים בפרטי הכניסה של המשתמש שמתקין אותם, או בפרטי הכניסה של חשבון שירות שמנוהל על ידי משתמש, כדי לבצע אימות.

הוראות מפורטות זמינות במאמר בנושא הרשאות להעברה מבוססת-סוכן.

התקנת סוכנים במאגר סוכנים

העברות שמבוססות על סוכנים משתמשות בסוכני תוכנה כדי לתזמן העברות. הסוכנים האלה צריכים להיות מותקנים במכונה עם גישה למערכת הקבצים שמעורבת בהעברה.

אסור לכלול בשם של מאגר הסוכנים או בקידומת של מזהה הסוכן מידע רגיש כמו פרטים אישיים מזהים (PII) או נתוני אבטחה. יכול להיות ששמות המשאבים יועברו לשמות של משאבים אחרים ב-Google Cloud, ויוצגו למערכות פנימיות של Google מחוץ לפרויקט שלכם.

יוצרים מאגר סוכנים. צריך להשתמש בחשבון המשתמש כדי לבצע את הפעולה הזו.
התקנת סוכנים במאגר הסוכנים. צריך להשתמש בחשבון של סוכן העברות כדי לבצע את הפעולה הזו.

מומלץ להתחיל עם 3 סוכנים במאגר הסוכנים של המקור. במהלך ההעברה, עוקבים אחרי מהירות ההעברה. אפשר להוסיף עוד סוכנים למאגר בזמן שההעברה מתבצעת.

מומלץ להשתמש במכונה וירטואלית אחת לכל סוכן, עם לפחות 4 ליבות CPU ו-8GB RAM.

אפשרויות העברה

התכונות הבאות של Storage Transfer Service זמינות להעברות ממערכות קבצים אל Cloud Storage.

העברת קבצים ספציפיים באמצעות מניפסט

אפשר להעביר רשימה של קבצים ל-Storage Transfer Service כדי לבצע פעולות עליהם. פרטים נוספים זמינים במאמר בנושא העברה של קבצים או אובייקטים ספציפיים באמצעות מניפסט.

ציון סוג האחסון (storage class)

אתם יכולים לציין את סוג האחסון (storage class) ב-Cloud Storage שבו ישתמשו עבור הנתונים שלכם בקטגוריית היעד. אפשר לעיין באפשרויות של StorageClass כדי לראות פרטים על REST, או להשתמש בדגל --custom-storage-class של Google Cloud CLI.

שימו לב: המערכת מתעלמת מהגדרות של סוגי אחסון אם התכונה סיווג אוטומטי מופעלת בקטגוריית היעד. אם התכונה סיווג אוטומטי מופעלת, האובייקטים שמועברים לקטגוריה מוגדרים בהתחלה כ-Standard Storage.

שמירה על מטא-נתונים

כשמעבירים קבצים ממערכות קבצים, אפשר להגדיר את Storage Transfer Service כך שישמור מאפיינים מסוימים כמטא נתונים מותאמים אישית. אם הקבצים האלה ייכתבו חזרה למערכת קבצים בשלב מאוחר יותר, שירות העברת נתונים (Storage Transfer Service) יוכל להמיר את המטא-נתונים שנשמרו בחזרה למאפייני POSIX.

בקטע העברות של מערכת קבצים מסוג POSIX במאמר שמירה של מטא-נתונים מפורט אילו מטא-נתונים אפשר לשמור ואיך להגדיר את ההעברה.

ניהול רוחב הפס של הרשת

כברירת מחדל, Storage Transfer Service משתמש בכל רוחב הפס שזמין לו כדי להעביר קבצים ממערכת הקבצים. אפשר להגדיר מגבלת רוחב פס כדי למנוע מההעברה להשפיע על תנועת רשת אחרת. מגבלות רוחב הפס מוחלות ברמת מאגר הסוכנים.

מידע נוסף מופיע במאמר בנושא ניהול רוחב פס ברשת.

כדי להגדיר או לשנות את מגבלות רוחב הפס, בחשבון המשתמש שלך צריכה להיות מוגדרת ההרשאה אדמין של העברת נתונים (roles/storagetransfer.admin).

רישום ביומן

Storage Transfer Service תומך ב- Cloud Logging for Storage Transfer Service (מומלץ) וגם ביומני העברה מבוססי-סוכן.

יצירת העברה

אל תכללו בשם של עבודת ההעברה מידע רגיש כמו פרטים אישיים מזהים (PII) או נתוני אבטחה. יכול להיות ששמות המשאבים יועברו לשמות של משאבים אחרים ב-Google Cloud, ויוצגו למערכות פנימיות של Google מחוץ לפרויקט שלכם.

שירות העברת הנתונים (Storage Transfer Service) מספק כמה ממשקים שדרכם אפשר ליצור העברה.

מסוף Google Cloud

נכנסים לדף Storage Transfer Service במסוף Google Cloud .

מעבר אל Storage Transfer Service
לוחצים על Transfer. מוצג הדף Create a transfer job.
בוחרים באפשרות POSIX file system (מערכת קבצים של POSIX) כמקור.
בוחרים באפשרות Cloud Storage כסוג היעד ולוחצים על השלב הבא.
בוחרים מאגר סוכנים קיים או בוחרים באפשרות יצירת מאגר סוכנים ופועלים לפי ההוראות ליצירת מאגר חדש.
מציינים את הנתיב המלא, המוגדר במלואו, של ספריית מערכת הקבצים.
לוחצים על השלב הבא.
בשדה Bucket or folder, מזינים את קטגוריית היעד ואת שם התיקייה (אופציונלי), או לוחצים על Browse כדי לבחור קטגוריה מתוך רשימת הקטגוריות הקיימות בפרויקט הנוכחי. כדי ליצור מאגר חדש, לוחצים על יצירת מאגר חדש.
לוחצים על השלב הבא.
בוחרים את אפשרויות התזמון.

הערה: ב-Storage Transfer Service, לוחות הזמנים של העברות מוצגים לפי אזור הזמן המקומי, אבל השעות נשמרות לפי זמן אוניברסלי מתואם (UTC). אם אתם מושפעים משעון הקיץ (DST), יכול להיות שתחוו שינוי בלוח הזמנים של העברת הנתונים כשתקופת שעון הקיץ מתחילה או מסתיימת.
לוחצים על השלב הבא.
בוחרים את ההגדרות של עבודת ההעברה.
- בשדה Description (תיאור), מזינים תיאור של ההעברה. מומלץ להזין תיאור משמעותי וייחודי כדי להבדיל בין המשרות.
- בקטע אפשרויות מטא-נתונים, משתמשים באפשרויות ברירת המחדל או מעדכנים ערך אחד או יותר. פרטים נוספים זמינים במאמר בנושא שמירת מטא-נתונים.
- בקטע When to overwrite (מתי להחליף), בוחרים באחת מהאפשרויות הבאות:
  - אף פעם: Storage Transfer Service מדלג על העברה של קבצים מהמקור שיש להם שם זהה לקובץ שקיים ביעד.
  - אם שונה: מחליף את קובצי היעד אם לקובץ המקור עם אותו שם יש ערכי Etags או סיכום ביקורת שונים.
  - תמיד: תמיד מחליף את קובצי היעד כששם קובץ המקור זהה, גם אם הם זהים.
- בקטע When to delete (מתי למחוק), בוחרים באחת מהאפשרויות הבאות:
  - אף פעם: הקבצים לא יימחקו מהמקור או מהיעד.
  - Delete file from source after they're transferred: מחיקת קבצים מהמקור אחרי שהם מועברים ליעד. אם קובץ מקור לא מועבר, למשל כי הוא כבר קיים ביעד, קובץ המקור לא נמחק.
    
    חשוב: אם אין לכם גיבוי מקומי, הפעולה הזו היא בלתי הפיכה.
  - מחיקת קבצים מיעד אם הם לא נמצאים גם במקור: אם קבצים בקטגוריה של Cloud Storage ביעד לא נמצאים גם במקור, הקבצים יימחקו מהקטגוריה של Cloud Storage.
    
    האפשרות הזו מבטיחה שקטגוריית היעד של Cloud Storage תהיה זהה למקור.
- בוחרים אם להפעיל רישום ביומן ב-Cloud Storage או להפעיל רישום ביומן ב-Cloud Logging או את שתי האפשרויות. מידע נוסף זמין במאמרים יומני העברה של מערכת קבצים וCloud Logging ל-Storage Transfer Service.
כדי ליצור את עבודת ההעברה, לוחצים על 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, ואפשר גם להוסיף נתיב לתיקייה ואחריו לוכסן. לדוגמה, gs://example-bucket/data/.
‫--source-agent-pool מציין את מאגר הסוכנים של המקור שבו יש להשתמש להעברה הזו.

אפשרויות נוספות:

האפשרות --do-not-run מונעת מ-Storage Transfer Service להריץ את העבודה אחרי שליחת הפקודה. כדי להריץ את העבודה, צריך לעדכן אותה כדי להוסיף לוח זמנים, או להשתמש בפונקציה jobs run כדי להפעיל אותה באופן ידני.
‫--manifest-file מציין את הנתיב לקובץ CSV ב-Cloud Storage שמכיל רשימה של קבצים להעברה מהמקור. למידע על הפורמט של קובץ המניפסט, אפשר לעיין במאמר העברה של קבצים או אובייקטים ספציפיים באמצעות מניפסט.
פרטי המשימה: אפשר לציין --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

בדוגמה הבאה אפשר לראות איך משתמשים ב-Storage Transfer Service דרך REST API.

כשמגדירים או עורכים משימות העברה באמצעות Storage Transfer Service API, צריך לציין את השעה ב-UTC. מידע נוסף על הגדרת לוח הזמנים של עבודת העברה זמין במאמר בנושא תזמון.

כדי להעביר קבצים ממערכת קבצים של POSIX לקטגוריה של Cloud Storage, צריך להשתמש ב-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

ספריות לקוח

בדוגמאות הבאות מוצגות דרכים לשימוש ב-Storage Transfer Service באופן פרוגרמטי באמצעות Go,‏ Java,‏ Node.js ו-Python.

כשמגדירים או עורכים משימות העברה באופן פרוגרמטי, צריך לציין את השעה ב-UTC. מידע נוסף על הגדרת לוח הזמנים של עבודת העברה זמין במאמר בנושא תזמון.

מידע נוסף על ספריות הלקוח של Storage Transfer Service זמין במאמר תחילת העבודה עם ספריות הלקוח של Storage Transfer Service.

כדי להעביר קבצים ממערכת קבצים של POSIX לקטגוריה של 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}")