יצירה וניהול של משימות של פעולות בחבילות

המסוף

1. במסוף Cloud de Confiance , נכנסים לדף Buckets של Cloud Storage.
   

   כניסה לדף Buckets

2. ברשימת הקטגוריות, לוחצים על שם הקטגוריה שמכילה את האובייקטים שרוצים לבצע בהם פעולות באצווה.

   הדף Bucket details נפתח עם הכרטיסייה Objects שנבחרה.

3. לוחצים על יצירת פעולות באצווה.
4. בחלונית בחירת פעולה, בוחרים את סוג הפעולה:
   • ‫Manage object holds: בוחרים באפשרות Temporary hold או Event-based hold. מידע נוסף זמין במאמר השהיות אובייקטים.
   • עדכון המטא-נתונים של האובייקט: כדי להוסיף מטא-נתונים של אובייקט, מבצעים את הפעולות הבאות:
     • כדי להוסיף מטא-נתונים מותאמים אישית:
       1. בשדה מפתח, מזינים שם למפתח.
       2. בשדה ערך, מזינים ערך למפתח הזה.
       3. אופציונלי: לוחצים על + הוספת פריט כדי להוסיף עוד צמדי מפתח/ערך.
     • כדי לעדכן מטא-נתונים עם מַפְתח קבוע:
       1. כדי להרחיב את הקטע Update fixed-key metadata, לוחצים על החץ expand_more.
       2. ברשימה Select one or more metadata to update, בוחרים את פריטי המטא-נתונים שרוצים לערוך.
   • ‫Update/Rotate encryption key: כדי להשתמש במפתח ההצפנה של האובייקטים או לעדכן אותו:
     1. ברשימה Select a Cloud KMS key, בוחרים מפתח הצפנה בניהול הלקוח (CMEK).
     2. אופציונלי: בוחרים באפשרות Switch project כדי לבחור מפתח מפרויקט אחר, או באפשרות Enter key manually כדי למלא את הפרטים.
   • מחיקת אובייקטים: כדי למחוק אובייקטים, מבצעים את הפעולות הבאות:
     1. בדיקה אם התכונה "ניהול גרסאות של אובייקטים" מופעלת.

     2. אם התכונה "ניהול גרסאות של אובייקטים" מופעלת, בוחרים באחת מאפשרויות המחיקה הבאות:

        • בוחרים באפשרות Delete all versions of the objects כדי להסיר גם גרסאות פעילות וגם גרסאות לא עדכניות.
        • כדי להסיר רק את הגרסה הפעילה, לוחצים על מחיקה סופית של גרסאות פעילות.

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

5. לוחצים על הבא.
6. בחלונית Name operation & specify objects:
   1. בשדה Name, מזינים שם.
   2. אופציונלי: בשדה Description, מזינים תיאור.
   3. בקטע Specify objects, מגדירים קריטריון לעיבוד אובייקטים מהקטגוריה. בוחרים אחת מהאפשרויות הבאות:
      • Select all objects: כולל את כל האובייקטים בקטגוריה.
      • בחירת אובייקטים באמצעות מסנני תחיליות: כדי להגדיר את רשימת האובייקטים באמצעות מסנני תחיליות, מבצעים את הפעולות הבאות:
        1. בשדה Enter Prefixes of the objects to be included, מזינים קידומת.
        2. אופציונלי: לוחצים על + הוספת קידומת כדי לציין קידומות נוספות.
      • העלאת רשימות של אובייקטים באמצעות קובצי מניפסט בפורמט CSV: כדי להשתמש בקובץ מניפסט לבחירת אובייקטים, מבצעים את הפעולות הבאות:

        1. מעלים את קובץ המניפסט בפורמט CSV לקטגוריה. הקובץ הזה צריך להכיל כותרות ל-Bucket name, ל-Object key ול-Generation number.
        2. ברשימה Select manifest file mode, בוחרים אחת מהאפשרויות הבאות:
           • אם בוחרים באפשרות Select a manifest file from Cloud Storage, לוחצים על Browse בשדה Select a manifest file from Cloud Storage. בתיבת הדו-שיח Select object שמופיעה, עוברים לקובץ המניפסט בפורמט CSV ולוחצים על Select.
           • אם בוחרים באפשרות Select multiple manifest files using wildcard, מזינים את נתיב הקובץ בשדה Enter manifest file location using wildcard. לדוגמה, bucket-name/folder/manifest_*.
7. לוחצים על יצירה.

שורת הפקודה

כדי להגדיר את רשימת האובייקטים למשימה של פעולות באצווה, אתם יכולים לבחור אחת מהגדרות המקור הבאות:

• פרויקט כמקור: הגדרת אובייקטים לפרויקט באמצעות הגדרת מערך נתונים של Storage Insights. במקום לציין קטגוריות או קידומות ספציפיות, אתם יכולים לציין פרמטרים של סינון מתקדם, כמו --insights-dataset-config,‏ --target-project,‏ --bucket-filters ו---object-filters. פרטים נוספים זמינים במאמר יצירת משימה באמצעות מסננים מתקדמים.
• קטגוריות כמקור: טירגוט אובייקטים בקטגוריות ספציפיות. צריך לציין אחד מהדגלים הבאים:
  • ‫--bucket או --bucket-list כדי להגדיר את קטגוריות היעד.
  • קובץ מניפסט בפורמט CSV‏ (--manifest-location) או קידומות של אובייקטים (--included-object-prefixes) כדי להגדיר את אובייקטי היעד.

1. מפעילים את Cloud Shell במסוף Cloud de Confiance .

   הפעלת Cloud Shell

   בחלק התחתון של מסוף Cloud de Confiance יתחיל סשן של Cloud Shell ותופיע הודעה של שורת הפקודה. Cloud Shell היא סביבת מעטפת שבה ה-CLI של Google Cloud מותקן ומוגדרים ערכים לפרויקט הקיים. הסשן יופעל תוך כמה שניות.

2. משתמשים ב-Google Cloud CLI בגרסה 516.0.0 ואילך.

3. כדי להגדיר את פרויקט ברירת המחדל, מריצים את הפקודה gcloud config set project:

   gcloud config set project PROJECT_ID

   כאשר PROJECT_ID הוא מזהה הפרויקט.

4. אופציונלי: מריצים משימת הרצת בדיקה. לפני שמפעילים משימה, מומלץ להריץ אותה במצב הרצה על ריק כדי לאמת את הקריטריונים לבחירת אובייקטים ולבדוק אם יש שגיאות. הרצת בדיקה לא משנה אובייקטים.

   בסביבת הפיתוח, מריצים את הפקודה gcloud storage batch-operations jobs create עם הדגל --dry-run:

   gcloud storage batch-operations jobs create DRY_RUN_JOB_NAME \
   {--bucket=BUCKET | --bucket-list=BUCKET_LIST} OBJECT_SELECTION_FLAG JOB_TYPE_FLAG \
   --dry-run

   כאשר:

   • ‫DRY_RUN_JOB_NAME הוא השם של משימת הרצת הבדיקה של פעולות רבות על פריטי אחסון.

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

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

5. אחרי הרצת בדיקה מוצלחת, מריצים את הפקודה gcloud storage batch-operations jobs create.

   gcloud storage batch-operations jobs create JOB_NAME \
   {--bucket=BUCKET | --bucket-list=BUCKET_LIST} OBJECT_SELECTION_FLAG JOB_TYPE_FLAG

   אלה הפרמטרים:

   • ‫JOB_NAME הוא השם של המשימה לביצוע פעולות רבות על פריטי אחסון.

   • ‫--bucket: BUCKET הוא שם הקטגוריה שמכילה את האובייקטים שרוצים לעבד.

   • ‫--bucket-list: BUCKET_LIST היא רשימה מופרדת בפסיקים של שם קטגוריה אחד או יותר, שמכילה את האובייקטים שרוצים לעבד. אפשר לציין עד 1,000 קטגוריות מכל פרויקט, כל עוד כל קטגוריה רשומה בתוכנית Storage Intelligence.

   • ‫OBJECT_SELECTION_FLAG הוא אחד מהדגלים הבאים שצריך לציין:

     • ‫--included-object-prefixes: מציינים תחילית אחת או יותר של אובייקטים. לדוגמה:

       • כדי להתאים קידומת אחת, משתמשים ב---included-object-prefixes='prefix1'.
       • כדי להתאים כמה קידומות, משתמשים ברשימת קידומות שמופרדות בפסיקים: --included-object-prefixes='prefix1,prefix2'.
       • כדי לכלול את כל האובייקטים, משתמשים בקידומת ריקה: --included-object-prefixes=''.

     • ‫--manifest-location: מציינים את המיקום של המניפסט. לדוגמה, gs://bucket_name/path/object_name.csv.

   • ‫JOB_TYPE_FLAG הוא אחד מהדגלים הבאים שצריך לציין, בהתאם לסוג העבודה.

     • ‫--delete-object: מחיקה של אובייקט אחד או יותר.

       • אם ניהול גרסאות של אובייקטים מופעל בקטגוריה, האובייקטים הנוכחיים עוברים למצב לא עדכני, והמערכת מדלגת על אובייקטים לא עדכניים.

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

     • ‫--enable-permanent-object-deletion: מחיקה סופית של אובייקטים. משתמשים בדגל הזה יחד עם הדגל --delete-object כדי למחוק באופן סופי גם אובייקטים פעילים וגם אובייקטים לא עדכניים בקטגוריה, בלי קשר להגדרת ניהול הגרסאות של האובייקטים בקטגוריה.

     • ‫--rewrite-object: עדכון מפתחות ההצפנה בניהול הלקוח של אובייקט אחד או יותר. אפשר גם להשתמש בדגל הזה כדי לשנות את סוג האחסון של האובייקט, על ידי ציון המפתח storage-class. סוגי האחסון הנתמכים כוללים את STANDARD,‏ NEARLINE,‏ COLDLINE ו-ARCHIVE. לדוגמה, --rewrite-object=storage-class=NEARLINE.

     • ‫--set-object-acls-from-file: תיקון רשימות של בקרת גישה (ACL) לאובייקטים. צריך לספק קובץ JSON או YAML עם הרשאות להוספה או לעדכון של ישויות כמו allUsers או allAuthenticatedUsers. לדוגמה: --set-object-acls-from-file=acl-updates.yaml או --set-object-acls-from-file=acl-updates.json.

       זה המבנה של קובץ ה-YAML לעדכונים:

       grants:
         - entity: allAuthenticatedUsers
           role: READER
         remove_entities:
         - allUsers
       

       זה המבנה של קובץ ה-JSON לעדכונים:

       {
       "grants": [
         {
           "entity": "allAuthenticatedUsers",
           "role": "READER"
         }
       ],
       "remove_entities": [
         "allUsers"
       ]
       }

     • ‫--put-object-event-based-hold: הפעלה של החזקות אובייקטים מבוססות-אירועים.

     • ‫--no-put-object-event-based-hold: השבתת החזקות אובייקטים מבוססות-אירועים.

     • ‫--put-object-temporary-hold: הפעלה של השהיות זמניות של אובייקטים.

     • ‫--no-put-object-temporary-hold: השבתת החזקות אובייקטים זמניות.

       בדוגמה הבאה מוסבר איך ליצור משימה לעדכון המטא-נתונים של Content-Language ל-en בכל האובייקטים שרשומים ב-manifest.csv.

       gcloud storage batch-operations jobs create my-job \
       --bucket=my-bucket \
       --manifest-location=gs://my-bucket/manifest.csv \
       --put-metadata=Content-Language=en

       בדוגמה הבאה אפשר לראות איך יוצרים משימה שמטרגטת כמה קטגוריות כדי לעדכן את Content-Language ל-en-us:

       gcloud storage batch-operations jobs create my-job \
       --bucket-list=bucket1,bucket2 \
       --included-object-prefixes='' \
       --put-metadata=Content-Language=en-us

     • --put-metadata: עדכון המטא-נתונים של האובייקט. מציינים את צמד המפתח/ערך של המטא-נתונים של האובייקט שרוצים לשנות. אפשר לציין צמד מפתח/ערך אחד או יותר כרשימה. אפשר גם להגדיר שמירת אובייקטים באמצעות הדגל --put-metadata. כדי לעשות את זה, צריך לציין את פרמטרי השימור באמצעות השדות Retain-Until ו-Retention-Mode. לדוגמה,

       gcloud storage batch-operations jobs create my-job \
       --bucket=my-bucket \
       --manifest-location=gs://my-bucket/manifest.csv \
       --put-metadata=Retain-Until=RETAIN_UNTIL_TIME,Retention-Mode=RETENTION_MODE

       כאשר:

       • ‫RETAIN_UNTIL_TIME הוא התאריך והשעה, בפורמט RFC 3339, שעד אליהם האובייקט נשמר. לדוגמה: 2025-10-09T10:30:00Z. כדי להגדיר את מדיניות שמירת הנתונים באובייקט, צריך להפעיל את מדיניות שמירת הנתונים בקטגוריה שמכילה את האובייקט.

       • ‫RETENTION_MODE הוא מצב שמירת הנתונים, Unlocked או Locked.

         כששולחים בקשה לעדכן את השדות RETENTION_MODE ו-RETAIN_UNTIL_TIME, חשוב להביא בחשבון את הדברים הבאים:

         • כדי לעדכן את הגדרת שמירת האובייקטים, צריך לספק ערכים לא ריקים לשדות RETENTION_MODE ו-RETAIN_UNTIL_TIME. אם מגדירים רק אחד מהם, תתקבל השגיאה INVALID_ARGUMENT.
         • אפשר להרחיב את הערך של RETAIN_UNTIL_TIME לאובייקטים במצב Unlocked או במצב Locked.
         • כדי לבצע את הפעולות הבאות, שמירת האובייקט צריכה להיות במצב Unlocked:
           • מפחיתים את הערך של RETAIN_UNTIL_TIME.
           • מסירים את הגדרת השמירה. כדי להסיר את ההגדרה, צריך להשאיר את השדות RETENTION_MODE ו-RETAIN_UNTIL_TIME ריקים.
         • אם משמיטים את השדות RETENTION_MODE ו-RETAIN_UNTIL_TIME, הגדרת השמירה לא משתנה.

     • ‫--clear-all-object-custom-contexts: מחיקת כל ההקשרים הקיימים של האובייקטים.

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

       gcloud storage batch-operations jobs create my-job \
       --bucket=my-bucket \
       --manifest-location=gs://my-bucket/manifest.csv \
       --clear-all-object-custom-contexts

     • ‫--clear-object-custom-contexts: הסרת הקשרים עם מפתחות ספציפיים. אפשר גם לעדכן הקשרים ספציפיים ולהסיר מפתחות באמצעות הדגל --clear-object-custom-contexts ואחד מהדגלים הבאים:

       • ‫--update-object-custom-contexts: מפה של צמדי מפתח/ערך.

         בדוגמה הבאה מוסבר איך ליצור משימה להסרת ההקשר עם המפתח temp-id, ולעדכן או להוסיף הקשר עם המפתחות project-id ו-cost-center לכל האובייקטים שרשומים ב-manifest.csv:

         gcloud storage batch-operations jobs create my-job \
         --bucket=my-bucket \
         --manifest-location=gs://my-bucket/manifest.csv \
         --clear-object-custom-contexts=temp-id \
         --update-object-custom-contexts=project-id=project-A,cost-center=engineering

       • ‫--update-object-custom-contexts-file: הנתיב לקובץ JSON או YAML עם צמדי מפתח/ערך.

         בדוגמה הבאה מוסבר איך ליצור משימה לעיבוד אובייקטים שמוגדרים ב-manifest.csv. המשימה מבצעת את הפעולות הבאות:

         • הסרת כל ההקשרים עם המפתח temp-id.

         • עדכון של הקשרים קיימים באמצעות המפתחות project-id ו-cost-center שמוגדרים בקובץ /tmp/context_updates.json.

         gcloud storage batch-operations jobs create my-job \
         --bucket=my-bucket \
         --manifest-location=gs://my-bucket/manifest.csv \
         --clear-object-custom-contexts=temp-id \
         --update-object-custom-contexts-file=/tmp/context_updates.json

         כאשר /tmp/context_updates.json מכיל את ההקשרים הבאים של האובייקט:

         {
         "project-id": {"value": "project-A"},
         "cost-center": {"value": "engineering"}
         }

ספריות לקוח

[](google::cloud::storagebatchoperations_v1::StorageBatchOperationsClient
       client,
   std::string const& project_id, std::string const& job_id,
   std::string const& target_bucket_name, std::string const& object_prefix) {
  auto const parent =
      std::string{"projects/"} + project_id + "/locations/global";
  namespace sbo = google::cloud::storagebatchoperations::v1;
  sbo::Job job;
  sbo::BucketList* bucket_list = job.mutable_bucket_list();
  sbo::BucketList::Bucket* bucket_config = bucket_list->add_buckets();
  bucket_config->set_bucket(target_bucket_name);
  sbo::PrefixList* prefix_list_config = bucket_config->mutable_prefix_list();
  prefix_list_config->add_included_object_prefixes(object_prefix);
  sbo::DeleteObject* delete_object_config = job.mutable_delete_object();
  delete_object_config->set_permanent_object_deletion_enabled(false);
  auto result = client.CreateJob(parent, job, job_id).get();
  if (!result) throw result.status();
  std::cout << "Created job: " << result->name() << "\n";
}

use Google\Cloud\StorageBatchOperations\V1\Client\StorageBatchOperationsClient;
use Google\Cloud\StorageBatchOperations\V1\CreateJobRequest;
use Google\Cloud\StorageBatchOperations\V1\Job;
use Google\Cloud\StorageBatchOperations\V1\BucketList;
use Google\Cloud\StorageBatchOperations\V1\BucketList\Bucket;
use Google\Cloud\StorageBatchOperations\V1\PrefixList;
use Google\Cloud\StorageBatchOperations\V1\DeleteObject;

/**
 * Create a new batch job.
 *
 * @param string $projectId Your Google Cloud project ID.
 *        (e.g. 'my-project-id')
 * @param string $jobId A unique identifier for this job.
 *        (e.g. '94d60cc1-2d95-41c5-b6e3-ff66cd3532d5')
 * @param string $bucketName The name of your Cloud Storage bucket to operate on.
 *        (e.g. 'my-bucket')
 * @param string $objectPrefix The prefix of objects to include in the operation.
 *        (e.g. 'prefix1')
 */
function create_job(string $projectId, string $jobId, string $bucketName, string $objectPrefix): void
{
    // Create a client.
    $storageBatchOperationsClient = new StorageBatchOperationsClient();

    $parent = $storageBatchOperationsClient->locationName($projectId, 'global');

    $prefixListConfig = new PrefixList(['included_object_prefixes' => [$objectPrefix]]);
    $bucket = new Bucket(['bucket' => $bucketName, 'prefix_list' => $prefixListConfig]);
    $bucketList = new BucketList(['buckets' => [$bucket]]);

    $deleteObject = new DeleteObject(['permanent_object_deletion_enabled' => false]);

    $job = new Job(['bucket_list' => $bucketList, 'delete_object' => $deleteObject]);

    $request = new CreateJobRequest([
        'parent' => $parent,
        'job_id' => $jobId,
        'job' => $job,
    ]);
    $response = $storageBatchOperationsClient->createJob($request);

    printf('Created job: %s', $response->getName());
}

‫API בפורמט JSON

כדי להגדיר את רשימת האובייקטים למשימה של פעולות באצווה, אתם יכולים לבחור אחת מהגדרות המקור הבאות:

• פרויקט כמקור: מטרגט אובייקטים ברמת הפרויקט באמצעות הגדרת projectSource. במקום לציין קטגוריות או קידומות ספציפיות, אתם מציינים פרמטרים של סינון מתקדם כדי לשלוח שאילתות דינמיות למטא-נתונים של תובנות לגבי האחסון. מידע נוסף זמין בכרטיסייה "API בפורמט JSON" במאמר יצירת משימה באמצעות מסננים מתקדמים.
• קטגוריות כמקור: טירגוט אובייקטים בקטגוריות ספציפיות באמצעות הגדרת bucketList. צריך לציין את קטגוריות היעד וקובץ מניפסט בפורמט CSV‏ (manifest_location) או תחיליות של אובייקטים (include_object_prefixes).

1. להתקין ולהפעיל את ה-CLI של gcloud, כדי שתוכלו ליצור אסימון גישה לכותרת Authorization.

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

   {
           "Description": "JOB_DESCRIPTION",
           "BucketList":
           {
           "Buckets":
           [
            {
              "Bucket": "BUCKET_NAME",
              "Manifest": {
                 "manifest_location": "MANIFEST_LOCATION"
                  }
              "PrefixList": {
                 "include_object_prefixes": "OBJECT_PREFIXES"
                  }
            }
           ]
           },
           "DeleteObject":
           {
           "permanent_object_deletion_enabled": OBJECT_DELETION_VALUE
            }
           "RewriteObject": {
             "kms_key":"KMS_KEY_VALUE",
             "storage_class":"STORAGE_CLASS_VALUE"
             }
           "PutMetadata":{
             "METADATA_KEY": "METADATA_VALUE",
             ...,
             "objectRetention": {
                 "retainUntilTime": "RETAIN_UNTIL_TIME",
                 "mode": "RETENTION_MODE"
                }
              }
           "PutObjectHold": {
             "temporary_hold": TEMPORARY_HOLD_VALUE,
             "event_based_hold": EVENT_BASED_HOLD_VALUE
           },
           "updateObjectCustomContext": {
              "customContextUpdates": {
                 "updates": {
                    "CONTEXT_KEY": { "value": "CONTEXT_VALUE" }
                 },
                 "keysToClear": ["CONTEXT_KEY_TO_CLEAR"]
              },
              "clearAll": CLEAR_ALL_VALUE
           },
           "SetObjectAcls": {
              "accessControlsUpdates": {
                 "grants": [
                    { "entity": "allUsers", "role": "READER" }
                 ],
                 "removeEntities": ["allAuthenticatedUsers"]
              }
           },
           "dryRun": DRY_RUN_VALUE
           }
            

   Where:
   

   • ‫JOB_NAME הוא השם של המשימה לביצוע פעולות רבות על פריטי אחסון.

   • ‫JOB_DESCRIPTION הוא התיאור של משימת הפעולות הרבות על פריטי אחסון.

   • ‫BUCKET_NAME הוא שם הקטגוריה שמכילה אובייקט אחד או יותר שרוצים לעבד.

   • כדי לציין את האובייקטים שרוצים לעבד, משתמשים באחד מהמאפיינים הבאים בקובץ ה-JSON:

     • ‫MANIFEST_LOCATION הוא המיקום של קובץ המניפסט. לדוגמה, gs://bucket_name/path/object_name.csv.

     • ‫OBJECT_PREFIXES היא רשימה מופרדת בפסיקים שמכילה קידומת אחת או יותר של אובייקטים. כדי להתאים לכל האובייקטים, צריך להשתמש ברשימה ריקה.

   • בהתאם למשימה שרוצים לעבד, מציינים אחת מהאפשרויות הבאות:

     • מחיקת אובייקטים:

       "DeleteObject":
         {
         "permanent_object_deletion_enabled": OBJECT_DELETION_VALUE
         }

       ‫OBJECT_DELETION_VALUE הוא TRUE כדי למחוק אובייקטים.

     • מעדכנים את מפתח ההצפנה בניהול הלקוח לאובייקטים:

       "RewriteObject":
         {
         "kms_key": KMS_KEY_VALUE
         }

       כאשר KMS_KEY_VALUE הוא הערך של מפתח ה-KMS של האובייקט שרוצים לעדכן.

     • עדכון סוג האחסון (storage class) של אובייקטים:

       "RewriteObject":
         {
         "storage_class": STORAGE_CLASS_VALUE
         }

       כאשר STORAGE_CLASS_VALUE הוא סוג האחסון החדש שאליו רוצים להעביר את האובייקטים. סוגי האחסון הנתמכים כוללים את STANDARD,‏ NEARLINE,‏ COLDLINE ו-ARCHIVE.

     • עדכון מטא-נתונים של אובייקטים:

       "PutMetadata": {
            "METADATA_KEY": "METADATA_VALUE",
            ...,
           "objectRetention": {
              "retainUntilTime": "RETAIN_UNTIL_TIME",
              "mode": "RETENTION_MODE"
            }
          }

       כאשר:

       • ‫METADATA_KEY/VALUE הוא צמד המפתח/ערך של המטא-נתונים של האובייקט. אפשר לציין זוג אחד או יותר.
       • ‫RETAIN_UNTIL_TIME הוא התאריך והשעה, בפורמט RFC 3339, שעד אליהם האובייקט נשמר. לדוגמה, 2025-10-09T10:30:00Z. כדי להגדיר את שמירת הנתונים באובייקט, צריך להפעיל את שמירת הנתונים בקטגוריה שמכילה את האובייקט.
       • ‫RETENTION_MODE הוא מצב שמירת הנתונים, Unlocked או Locked.

         כששולחים בקשה לעדכן את השדות RETENTION_MODE ו-RETAIN_UNTIL_TIME, חשוב להביא בחשבון את הדברים הבאים:

         • כדי לעדכן את הגדרת שמירת האובייקטים, צריך לספק ערכים לא ריקים לשדות RETENTION_MODE ו-RETAIN_UNTIL_TIME. אם מגדירים רק אחד מהם, תתקבל השגיאה INVALID_ARGUMENT.
         • אפשר להרחיב את הערך של RETAIN_UNTIL_TIME לאובייקטים במצב Unlocked או במצב Locked.
         • כדי לבצע את הפעולות הבאות, שמירת האובייקט צריכה להיות במצב Unlocked:
           • מפחיתים את הערך של RETAIN_UNTIL_TIME.
           • מסירים את הגדרת השמירה. כדי להסיר את ההגדרה, צריך להשאיר את השדות RETENTION_MODE ו-RETAIN_UNTIL_TIME ריקים.
         • אם משמיטים את השדות RETENTION_MODE ו-RETAIN_UNTIL_TIME, הגדרת השמירה לא משתנה.

       • עדכון החזקות אובייקטים:

         "PutObjectHold": {
             "temporary_hold": TEMPORARY_HOLD_VALUE,
             "event_based_hold": EVENT_BASED_HOLD_VALUE
           }

         כאשר:

         • ‫TEMPORARY_HOLD_VALUE משמש להפעלה או להשבתה של דגל object hold זמני. הערך 1 מפעיל את ההחזקה, והערך 2 משבית את ההחזקה.

         • ‫EVENT_BASED_HOLD_VALUE משמש להפעלה או להשבתה של השהיית אובייקטים מבוססת-אירועים. הערך 1 מפעיל את ההחזקה, והערך 2 משבית את ההחזקה.

       • מעדכנים את הקשרי האובייקטים:

         "updateObjectCustomContext": {
             "customContextUpdates": {
               "updates": {
                 "CONTEXT_KEY": { "value": "CONTEXT_VALUE" }
               },
               "keysToClear": ["CONTEXT_KEY_TO_CLEAR"]
             },
             "clearAll": CLEAR_ALL_VALUE
           }

         כאשר:

         • ‫CONTEXT_KEY הוא מפתח ההקשר של האובייקט שרוצים להוסיף או לעדכן.
         • ‫CONTEXT_VALUE הוא ערך ההקשר של האובייקט בשביל המפתח.
         • ‫CONTEXT_KEY_TO_CLEAR הוא המפתח שרוצים להסיר.
         • ‫CLEAR_ALL_VALUE מוגדר ל-true כדי למחוק את כל ההקשרים הקיימים של האובייקטים.

       • עדכון רשימות של בקרת גישה (ACL) לאובייקטים:

         "SetObjectAcls": {
             "accessControlsUpdates": {
                "grants": [
                   { "entity": "ENTITY_NAME", "role": "ROLE_NAME" }
                ],
                "removeEntities": ["ENTITY_TO_REMOVE"]
             }
           }

         כאשר:

         • ‫ENTITY_NAME היא הישות שרוצים להוסיף או לעדכן את הרשאת הגישה שלה. לדוגמה, allUsers,‏ allAuthenticatedUsers או משתמש או קבוצה ספציפיים.
         • ‫ROLE_NAME הוא התפקיד שרוצים לתת. לדוגמה, READER, OWNER.
         • ‫ENTITY_TO_REMOVE היא הישות שאת פרטי הכניסה שלה רוצים להסיר.

     • ‫DRY_RUN_VALUE הוא ערך בוליאני אופציונלי. מגדירים את הערך true כדי להריץ את המשימה במצב הרצת ניסיון. ערך ברירת המחדל הוא false.

     1. משתמשים ב-curl כדי לשלוח קריאה ל-API בפורמט JSON באמצעות בקשת משימה של פעולות רבות על פריטי אחסון POST:

        curl -X POST --data-binary @JSON_FILE_NAME \
         -H "Authorization: Bearer $(gcloud auth print-access-token)" \
         -H "Content-Type: application/json" \
         "https://storagebatchoperations.googleapis.com/v1/projects/PROJECT_ID/locations/global/jobs?job_id=JOB_NAME"

        כאשר:

        • ‫JSON_FILE_NAME הוא השם של קובץ ה-JSON.
        • ‫PROJECT_ID הוא המזהה או המספר של הפרויקט. לדוגמה, my-project.

        • ‫JOB_NAME הוא השם של המשימה לביצוע פעולות רבות על פריטי אחסון.

המסוף

1. במסוף Cloud de Confiance , נכנסים לדף Buckets של Cloud Storage.
   

   כניסה לדף Buckets

2. ברשימת הקטגוריות, לוחצים על שם הקטגוריה שמשויכת לפעולה.
3. בדף Bucket details, לוחצים על הכרטיסייה Operations.
4. ברשימת הפעולות, לוחצים על Operation ID של המשימה שרוצים לראות.
5. בדף הפרטים מוצגים מדדים של המשימה בכרטיסייה סקירה כללית, כמו אובייקטים שהתגלו, אובייקטים שעובדו ושגיאות שהתרחשו.
6. בטבלה Error summary, בודקים את פרטי השגיאות בהפעלה או לוחצים על View in Cloud Logging כדי לראות את הרשומות.
7. כדי לראות את הגדרות התצורה של המשימה, לוחצים על הכרטיסייה Configuration.

שורת הפקודה

1. מפעילים את Cloud Shell במסוף Cloud de Confiance .

   הפעלת Cloud Shell

   בחלק התחתון של מסוף Cloud de Confiance יתחיל סשן של Cloud Shell ותופיע הודעה של שורת הפקודה. Cloud Shell היא סביבת מעטפת שבה ה-CLI של Google Cloud מותקן ומוגדרים ערכים לפרויקט הקיים. הסשן יופעל תוך כמה שניות.

2. בסביבת הפיתוח, מריצים את הפקודה gcloud storage batch-operations jobs describe.

   gcloud storage batch-operations jobs describe JOB_NAME

   כאשר:

   ‫JOB_NAME הוא השם של המשימה לביצוע פעולות רבות על פריטי אחסון.

   כשמריצים משימה באופן יבש, הפלט כולל את השדות הבאים:

   • ‫totalObjectCount: מספר האובייקטים שתואמים לקריטריונים שבחרתם.
   • ‫errorSummaries: רשימה של שגיאות שנמצאו במהלך הרצת הבדיקה, כמו בעיות בהרשאות או הגדרות לא תקינות.
   • ‫totalBytesFound: הגודל הכולל של האובייקטים המושפעים. השדה הזה מופיע רק כשמשתמשים בתחיליות של אובייקטים לבחירת אובייקטים.

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

     bucketList:
       buckets:
       - bucket: my-bucket
         manifest:
           manifestLocation: gs://my-bucket/manifest.csv
     completeTime: '2025-10-27T23:56:32Z'
     counters:
       totalObjectCount: '4'
     createTime: '2025-10-27T23:56:22.243528568Z'
     dryRun: true
     name: projects/my-project/locations/global/jobs/my-job
     putMetadata:
       contentLanguage: en
     state: SUCCEEDED
   

   תגובה תקינה של משימה משמיטה את השדה dryRun ומחזירה את המדדים הבאים בשדה counters:

   • סה"כ האובייקטים שנמצאו.
   • מספר הבייטים הכולל שנמצאו כשמשתמשים בתחיליות של אובייקטים.
   • שינויי צורה מוצלחים של אובייקטים.
   • טרנספורמציות של אובייקטים שנכשלו, אם רלוונטי.
   • הקשרים של אובייקטים שנוצרו, אם רלוונטי.
   • ההקשרים של האובייקטים נמחקו, אם רלוונטי.
   • ההקשרים של האובייקטים עודכנו, אם רלוונטי. המונה הזה עוקב אחרי עדכונים שבוצעו במפתחות הקשר קיימים.

   התגובה להרצה של משימה אמיתית דומה לדוגמה הבאה:

     bucketList:
       buckets:
       - bucket: my-bucket
         manifest:
           manifestLocation: gs://my-bucket/manifest.csv
     completeTime: '2025-10-31T20:19:42.357826655Z'
     counters:
       succeededObjectCount: '4'
       totalObjectCount: '4'
     createTime: '2025-10-31T20:19:22.016517077Z'
     name: projects/my-project/locations/global/jobs/my-job
     putMetadata:
       contentLanguage: en
     state: SUCCEEDED
     

ספריות לקוח

[](google::cloud::storagebatchoperations_v1::StorageBatchOperationsClient
       client,
   std::string const& project_id, std::string const& job_id) {
  auto const parent =
      std::string{"projects/"} + project_id + "/locations/global";
  auto const name = parent + "/jobs/" + job_id;
  auto job = client.GetJob(name);
  if (!job) throw job.status();
  std::cout << "Got job: " << job->name() << "\n";
}

use Google\Cloud\StorageBatchOperations\V1\Client\StorageBatchOperationsClient;
use Google\Cloud\StorageBatchOperations\V1\GetJobRequest;

/**
 * Gets a batch job.
 *
 * @param string $projectId Your Google Cloud project ID.
 *        (e.g. 'my-project-id')
 * @param string $jobId A unique identifier for this job.
 *        (e.g. '94d60cc1-2d95-41c5-b6e3-ff66cd3532d5')
 */
function get_job(string $projectId, string $jobId): void
{
    // Create a client.
    $storageBatchOperationsClient = new StorageBatchOperationsClient();

    $parent = $storageBatchOperationsClient->locationName($projectId, 'global');
    $formattedName = $parent . '/jobs/' . $jobId;

    $request = new GetJobRequest([
        'name' => $formattedName,
    ]);

    $response = $storageBatchOperationsClient->getJob($request);

    printf('Got job: %s', $response->getName());
}

‫API בפורמט JSON

1. להתקין ולהפעיל את ה-CLI של gcloud, כדי שתוכלו ליצור אסימון גישה לכותרת Authorization.

2. משתמשים ב-cURL כדי לשלוח קריאה ל-API בפורמט JSON באמצעות בקשת משימה של פעולות רבות על פריטי אחסון GET:

   curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://storagebatchoperations.googleapis.com/v1/projects/PROJECT_ID/locations/global/jobs/JOB_NAME"

   כאשר:

   • ‫PROJECT_ID הוא המזהה או המספר של הפרויקט. לדוגמה, my-project.
   • ‫JOB_NAME הוא השם של המשימה לביצוע פעולות רבות על פריטי אחסון.

   כשמריצים משימה באופן יבש, הפלט כולל את השדות הבאים:

   • ‫totalObjectCount: מספר האובייקטים שתואמים לקריטריונים שבחרתם.
   • ‫errorSummaries: רשימה של שגיאות שנמצאו במהלך הרצת הבדיקה, כמו בעיות בהרשאות או הגדרות לא תקינות.
   • ‫totalBytesFound: הגודל הכולל של האובייקטים המושפעים. השדה הזה מופיע רק כשמשתמשים בתחיליות של אובייקטים לבחירת אובייקטים.

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

   {
     "name": "projects/my-project/locations/global/jobs/my-job",
     "description": "dry-run-job",
     "deleteObject": {
       "permanent_object_deletion_enabled": true
        },
     "createTime": "2025-10-28T00:26:53.900882459Z",
     "completeTime": "2025-10-28T00:27:04.101663275Z",
     "counters": {
         "totalObjectCount": "5",
         "totalBytesFound": "203"
       },
     "state": "SUCCEEDED",
     "bucketList": {
       "buckets": [
         {
           "bucket": "my-bucket",
           "prefixList": {
             "includedObjectPrefixes": [
               ""
             ]
           }
         }
       ]
     },
     "dryRun": true
   }
   

   תגובה תקינה של משימה משמיטה את השדה dryRun ומחזירה את המדדים הבאים בשדה counters:

   • סה"כ האובייקטים שנמצאו.
   • מספר הבייטים הכולל שנמצאו כשמשתמשים בתחיליות של אובייקטים.
   • שינויי צורה מוצלחים של אובייקטים.
   • טרנספורמציות של אובייקטים שנכשלו, אם רלוונטי.
   • הקשרים של אובייקטים שנוצרו, אם רלוונטי.
   • ההקשרים של האובייקטים נמחקו, אם רלוונטי.

   • ההקשרים של האובייקטים עודכנו, אם רלוונטי. המונה הזה עוקב אחרי עדכונים שבוצעו במפתחות הקשר קיימים.

     התגובה להרצה של משימה אמיתית דומה לדוגמה הבאה:

     {
     "name": "my-job",
     "description": "my-delete-objects-job",
     "deleteObject": {
       "permanent_object_deletion_enabled": true
     },
     "createTime": "2025-10-28T00:26:53.900882459Z",
     "completeTime": "2025-10-28T00:27:04.101663275Z",
     "counters": {
       "succeededObjectCount: "5"
       "totalObjectCount": "5",
       "totalBytesFound": "203"
     },
     "state": "SUCCEEDED",
     "bucketList": {
       "buckets": [
         {
           "bucket": "my-bucket",
           "prefixList": {
             "includedObjectPrefixes": [
               ""
             ]
           }
         }
       ]
     }
     }
     

המסוף

1. במסוף Cloud de Confiance , נכנסים לדף Buckets של Cloud Storage.
   

   כניסה לדף Buckets

2. ברשימת הקטגוריות, לוחצים על שם הקטגוריה שמשויכת לפעולה.
3. בדף Bucket details, לוחצים על הכרטיסייה Operations. בדף Operations מוצגת רשימה של הפעולות שמתבצעות כרגע.

שורת הפקודה

1. מפעילים את Cloud Shell במסוף Cloud de Confiance .

   הפעלת Cloud Shell

   בחלק התחתון של מסוף Cloud de Confiance יתחיל סשן של Cloud Shell ותופיע הודעה של שורת הפקודה. Cloud Shell היא סביבת מעטפת שבה ה-CLI של Google Cloud מותקן ומוגדרים ערכים לפרויקט הקיים. הסשן יופעל תוך כמה שניות.

2. בסביבת הפיתוח, מריצים את הפקודה gcloud storage batch-operations jobs list.

   gcloud storage batch-operations jobs list

ספריות לקוח

[](google::cloud::storagebatchoperations_v1::StorageBatchOperationsClient
       client,
   std::string const& project_id) {
  auto const parent =
      std::string{"projects/"} + project_id + "/locations/global";
  for (auto const& job : client.ListJobs(parent)) {
    if (!job) throw job.status();
    std::cout << job->name() << "\n";
  }
}

use Google\Cloud\StorageBatchOperations\V1\Client\StorageBatchOperationsClient;
use Google\Cloud\StorageBatchOperations\V1\ListJobsRequest;

/**
 * List Jobs in a given project.
 *
 * @param string $projectId Your Google Cloud project ID.
 *        (e.g. 'my-project-id')
 */
function list_jobs(string $projectId): void
{
    // Create a client.
    $storageBatchOperationsClient = new StorageBatchOperationsClient();

    $parent = $storageBatchOperationsClient->locationName($projectId, 'global');

    $request = new ListJobsRequest([
        'parent' => $parent,
    ]);

    $jobs = $storageBatchOperationsClient->listJobs($request);

    foreach ($jobs as $job) {
        printf('Job name: %s' . PHP_EOL, $job->getName());
    }
}

‫API בפורמט JSON

1. להתקין ולהפעיל את ה-CLI של gcloud, כדי שתוכלו ליצור אסימון גישה לכותרת Authorization.

2. משתמשים ב-cURL כדי לשלוח קריאה ל-API בפורמט JSON באמצעות בקשת משימות של פעולות רבות על פריטי אחסון LIST:

   curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://storagebatchoperations.googleapis.com/v1/projects/PROJECT_ID/locations/global/jobs"

   כאשר:

   ‫PROJECT_ID הוא המזהה או המספר של הפרויקט. לדוגמה, my-project.

המסוף

1. במסוף Cloud de Confiance , נכנסים לדף Buckets של Cloud Storage.
   

   כניסה לדף Buckets

2. ברשימת הקטגוריות, לוחצים על שם הקטגוריה שמשויכת לפעולות הרבות על פריטי האחסון שרוצים לבטל.

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

4. ברשימת הפעולות, בוחרים את המשימות שרוצים לבטל ולוחצים על Cancel.

שורת הפקודה

1. מפעילים את Cloud Shell במסוף Cloud de Confiance .

   הפעלת Cloud Shell

   בחלק התחתון של מסוף Cloud de Confiance יתחיל סשן של Cloud Shell ותופיע הודעה של שורת הפקודה. Cloud Shell היא סביבת מעטפת שבה ה-CLI של Google Cloud מותקן ומוגדרים ערכים לפרויקט הקיים. הסשן יופעל תוך כמה שניות.

2. בסביבת הפיתוח, מריצים את הפקודה gcloud storage batch-operations jobs cancel.

   gcloud storage batch-operations jobs cancel JOB_NAME

   כאשר:

   ‫JOB_NAME הוא השם של המשימה לביצוע פעולות רבות על פריטי אחסון.

ספריות לקוח

[](google::cloud::storagebatchoperations_v1::StorageBatchOperationsClient
       client,
   std::string const& project_id, std::string const& job_id) {
  auto const parent =
      std::string{"projects/"} + project_id + "/locations/global";
  auto const name = parent + "/jobs/" + job_id;
  auto response = client.CancelJob(name);
  if (!response) throw response.status();
  std::cout << "Cancelled job: " << name << "\n";
}

use Google\Cloud\StorageBatchOperations\V1\Client\StorageBatchOperationsClient;
use Google\Cloud\StorageBatchOperations\V1\CancelJobRequest;

/**
 * Cancel a batch job.
 *
 * @param string $projectId Your Google Cloud project ID.
 *        (e.g. 'my-project-id')
 * @param string $jobId A unique identifier for this job.
 *        (e.g. '94d60cc1-2d95-41c5-b6e3-ff66cd3532d5')
 */
function cancel_job(string $projectId, string $jobId): void
{
    // Create a client.
    $storageBatchOperationsClient = new StorageBatchOperationsClient();

    $parent = $storageBatchOperationsClient->locationName($projectId, 'global');
    $formattedName = $parent . '/jobs/' . $jobId;

    $request = new CancelJobRequest([
        'name' => $formattedName,
    ]);

    $storageBatchOperationsClient->cancelJob($request);

    printf('Cancelled job: %s', $formattedName);
}

‫API בפורמט JSON

1. להתקין ולהפעיל את ה-CLI של gcloud, כדי שתוכלו ליצור אסימון גישה לכותרת Authorization.

2. משתמשים ב-cURL כדי לשלוח קריאה ל-API בפורמט JSON באמצעות בקשת CANCELמשימה של פעולות רבות על פריטי אחסון:

   curl -X CANCEL \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://storagebatchoperations.googleapis.com/v1/projects/PROJECT_ID/locations/global/jobs/JOB_NAME"

   כאשר:

   • ‫PROJECT_ID הוא המזהה או המספר של הפרויקט. לדוגמה, my-project.

   • ‫JOB_NAME הוא השם של המשימה לביצוע פעולות רבות על פריטי אחסון.

המסוף

1. במסוף Cloud de Confiance , נכנסים לדף Buckets של Cloud Storage.
   

   כניסה לדף Buckets

2. ברשימת הקטגוריות, לוחצים על השם של הקטגוריה שמשויכת לפעולות רבות על פריטי אחסון שרוצים למחוק.

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

4. ברשימת הפעולות, בוחרים את המשימות שרוצים למחוק ולוחצים על Delete.

שורת הפקודה

1. מפעילים את Cloud Shell במסוף Cloud de Confiance .

   הפעלת Cloud Shell

   בחלק התחתון של מסוף Cloud de Confiance יתחיל סשן של Cloud Shell ותופיע הודעה של שורת הפקודה. Cloud Shell היא סביבת מעטפת שבה ה-CLI של Google Cloud מותקן ומוגדרים ערכים לפרויקט הקיים. הסשן יופעל תוך כמה שניות.

2. בסביבת הפיתוח, מריצים את הפקודה gcloud storage batch-operations jobs delete.

   gcloud storage batch-operations jobs delete JOB_NAME

   כאשר:

   ‫JOB_NAME הוא השם של המשימה לביצוע פעולות רבות על פריטי אחסון.

ספריות לקוח

[](google::cloud::storagebatchoperations_v1::StorageBatchOperationsClient
       client,
   std::string const& project_id, std::string const& job_id) {
  auto const parent =
      std::string{"projects/"} + project_id + "/locations/global";
  auto const name = parent + "/jobs/" + job_id;
  auto status = client.DeleteJob(name);
  if (!status.ok()) throw status;
  std::cout << "Deleted job: " << name << "\n";
}

use Google\Cloud\StorageBatchOperations\V1\Client\StorageBatchOperationsClient;
use Google\Cloud\StorageBatchOperations\V1\DeleteJobRequest;

/**
 * Delete a batch job.
 *
 * @param string $projectId Your Google Cloud project ID.
 *        (e.g. 'my-project-id')
 * @param string $jobId A unique identifier for this job.
 *        (e.g. '94d60cc1-2d95-41c5-b6e3-ff66cd3532d5')
 */
function delete_job(string $projectId, string $jobId): void
{
    // Create a client.
    $storageBatchOperationsClient = new StorageBatchOperationsClient();

    $parent = $storageBatchOperationsClient->locationName($projectId, 'global');
    $formattedName = $parent . '/jobs/' . $jobId;

    $request = new DeleteJobRequest([
        'name' => $formattedName,
    ]);

    $storageBatchOperationsClient->deleteJob($request);

    printf('Deleted job: %s', $formattedName);
}

‫API בפורמט JSON

1. להתקין ולהפעיל את ה-CLI של gcloud, כדי שתוכלו ליצור אסימון גישה לכותרת Authorization.

2. משתמשים ב-cURL כדי לשלוח קריאה ל-API בפורמט JSON באמצעות בקשת משימה של פעולות רבות על פריטי אחסון DELETE:

   curl -X DELETE \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://storagebatchoperations.googleapis.com/v1/projects/PROJECT_ID/locations/global/jobs/JOB_NAME"

   כאשר:

   • ‫PROJECT_ID הוא המזהה או המספר של הפרויקט. לדוגמה, my-project.

   • ‫JOB_NAME הוא השם של המשימה לביצוע פעולות רבות על פריטי אחסון.

שורת הפקודה

1. מפעילים את Cloud Shell במסוף Cloud de Confiance .

   הפעלת Cloud Shell

   בחלק התחתון של מסוף Cloud de Confiance יתחיל סשן של Cloud Shell ותופיע הודעה של שורת הפקודה. Cloud Shell היא סביבת מעטפת שבה ה-CLI של Google Cloud מותקן ומוגדרים ערכים לפרויקט הקיים. הסשן יופעל תוך כמה שניות.

2. מריצים את הפקודה gcloud storage batch-operations jobs create:

   gcloud storage batch-operations jobs create JOB_NAME \
   {--insights-dataset-config=INSIGHTS_DATASET_CONFIG_RESOURCE_NAME --target-project=TARGET_PROJECT [--bucket-filters=BUCKET_FILTER_CEL] [--object-filters=OBJECT_FILTER_CEL] [--target-locations=TARGET_LOCATIONS] [--target-snapshot-time=TARGET_SNAPSHOT_TIME] | --dry-run-job-id=DRY_RUN_JOB_ID} \
   --JOB_TYPE_FLAG

   כאשר:

   • ‫JOB_NAME הוא השם של המשימה של הפעולות הרבות על פריטי אחסון.
   • ‫INSIGHTS_DATASET_CONFIG_RESOURCE_NAME: שם המשאב של הגדרת מערך הנתונים. לדוגמה: projects/{project-id}/locations/{location-id}/datasetConfigs/{dataset_config_id}. צריך לציין את הפרמטר הזה לפני שמשתמשים בדגלים --bucket-filters ו---object-filters.
   • ‫TARGET_PROJECT: מזהה הפרויקט או מספר הפרויקט שמשויכים למשאבי היעד.
   • ‫BUCKET_FILTER_CEL ו-OBJECT_FILTER_CEL (אופציונלי): ביטויי הסינון של CEL שמשמשים לבחירת אובייקטים. לדוגמה:
     • --bucket-filters="name in ['bucket-1', 'bucket-2']"
     • --object-filters="size >= 5000 && name.endsWith('.pdf')" מידע נוסף על שדות, אופרטורים ופונקציות נתמכים זמין בחומר העזר בנושא מסנני CEL.
   • ‫TARGET_LOCATIONS (אופציונלי): רשימה של מיקומים ב-Cloud Storage שמשמשים לצמצום היקף המשימה. לדוגמה: us,us-central1,us-east4. אפשר להשתמש בפרמטר הזה כדי להחריג מיקומים שבהם יש הפסקה זמנית בשירות. אם מציינים רק את TARGET_LOCATIONS ומשמיטים את TARGET_SNAPSHOT_TIME, המשימה בוחרת באופן אוטומטי את חותמת הזמן של תמונת המצב האחרונה שאוכלסה בהצלחה בתצוגות של מאפייני האובייקט והקטגוריה בכל המיקומים שצוינו.
   • ‫TARGET_SNAPSHOT_TIME (אופציונלי): חותמת הזמן לפי שעון UTC של תמונת המצב של מערך הנתונים שבה רוצים להשתמש, בפורמט RFC 3339. לדוגמה, 2026-05-03T16:00:00Z. תמונת המצב הזו צריכה להיות קיימת בתצוגות של מאפייני הקטגוריה והאובייקט. אם מציינים את הפרמטר הזה, צריך לציין גם את הפרמטר TARGET_LOCATIONS.
   • ‫DRY_RUN_JOB_ID: המזהה של משימת הרצה לניסיון שבוצעה בעבר. אם מציינים את הפרמטר הזה, אי אפשר לציין פרמטרים אחרים לבחירת אובייקטים, כולל --insights-dataset-config,‏ --target-project,‏ --bucket-filters,‏ --object-filters,‏ --target-locations ו---target-snapshot-time. המשימה הפעילה דוגמת את כל הקריטריונים לבחירה ישירות מהמשימה של ההרצה לניסיון.
   • ‫JOB_TYPE_FLAG: הדגל שתואם לפעולה בכמות גדולה שרוצים לבצע, כמו --put-metadata או --delete-object.

‫API בפורמט JSON

1. להתקין ולהפעיל את ה-CLI של gcloud, כדי שתוכלו ליצור אסימון גישה לכותרת Authorization.

2. יוצרים קובץ תצורה בפורמט JSON שמציין את המסננים של מערך הנתונים ואת ההגדרות של הפעולות בכמות גדולה. לדוגמה:

   {
       "description": "JOB_DESCRIPTION",
       "projectSource": {
           "project": "projects/TARGET_PROJECT",
           "insightsDatasetConfig": "INSIGHTS_DATASET_CONFIG_RESOURCE_NAME",
           "bucketFilters": {
               "expression": "BUCKET_FILTER_CEL"
           },
           "objectFilters": {
               "expression": "OBJECT_FILTER_CEL"
           },
           "snapshotTime": "SNAPSHOT_TIME",
           "targetLocations": {
               "locations": ["LOCATION_1", "LOCATION_2"]
           }
       },
       "deleteObject": {
           "permanentObjectDeletionEnabled": OBJECT_DELETION_VALUE
       }
    }

   כאשר:

   • ‫JOB_DESCRIPTION הוא תיאור המשימה.
     • ‫TARGET_PROJECT הוא מזהה הפרויקט או מספר הפרויקט שמשויך לאובייקטים לטירגוט.
   • ‫INSIGHTS_DATASET_CONFIG_RESOURCE_NAME הוא שם המשאב המלא של הגדרת מערך הנתונים (לדוגמה, projects/{project-id}/locations/{location-id}/datasetConfigs/{dataset_config_id}).
   • ‫BUCKET_FILTER_CEL הוא ביטוי הסינון של CEL לקטגוריות. לדוגמה, name in ['bucket-1', 'bucket-2']. לפרטים על מילות מפתח, שדות ואופרטורים נתמכים, אפשר לעיין בחומר העזר בנושא מסנני CEL.
   • ‫OBJECT_FILTER_CEL הוא ביטוי הסינון של CEL לאובייקטים. לדוגמה, size >= 5000 && name.endsWith('.pdf').
   • ‫snapshotTime (אופציונלי): חותמת זמן ספציפית לפי שעון UTC בפורמט RFC 3339 (לדוגמה, "2026-05-03T16:00:00Z") שמציינת באיזו תמונת מצב של מערך הנתונים להשתמש. תמונת המצב הזו צריכה להיות קיימת גם בתצוגות של קבוצת הנתונים של הקטגוריה וגם בתצוגות של קבוצת הנתונים של האובייקט בכל מיקומי היעד הגיאוגרפיים. אם מציינים את השדה הזה, צריך לציין גם את השדה targetLocations.
   • ‫targetLocations (אופציונלי): אובייקט JSON שמציין רשימה של מיקומים ב-Cloud Storage (לדוגמה, ["us", "us-central1", "us-east4"]) כדי לסנן את היקף המשימה. אם יש הפסקה זמנית בשירות של יחסי תלות במיקומים ספציפיים, אפשר לצמצם את המשימה למיקומים ספציפיים. אם מציינים רק את targetLocations ומשמיטים את snapshotTime, המשימה בוחרת באופן אוטומטי את חותמת הזמן של תמונת המצב האחרונה שאוכלסה בהצלחה בתצוגות של מאפייני האובייקט והקטגוריה בכל המיקומים שצוינו.
   • ‫OBJECT_DELETION_VALUE הוא הערך הבוליאני שמשמש להחלפה למחיקה סופית. לדוגמה, true או false.

3. שולחים בקשת POST באמצעות cURL כדי להריץ את המשימה:

   curl -X POST \
        -H "Authorization: Bearer OAUTH2_TOKEN" \
        -H "Content-Type: application/json" \
        -d @JSON_FILE_NAME \
        "https://storagebatchoperations.googleapis.com/v1/projects/PROJECT_ID/locations/global/jobs?job_id=JOB_NAME"

   כאשר:

   • ‫JSON_FILE_NAME הוא השם של קובץ ה-JSON.
   • ‫PROJECT_ID הוא המזהה או המספר של הפרויקט. לדוגמה, my-project.
   • ‫JOB_NAME הוא השם של המשימה לביצוע פעולות רבות על פריטי אחסון.

המסוף

1. במסוף Cloud de Confiance , נכנסים לדף Buckets של Cloud Storage.
   

   כניסה לדף Buckets

2. ברשימת הקטגוריות, לוחצים על שם הקטגוריה שמכילה את האובייקטים שרוצים לבצע בהם פעולות באצווה.

   הדף Bucket details נפתח עם הכרטיסייה Objects שנבחרה.

3. לוחצים על יצירת פעולות באצווה.
4. בחלונית בחירת פעולה, בוחרים את סוג הפעולה:
   • ‫Manage object holds: בוחרים באפשרות Temporary hold או Event-based hold. מידע נוסף זמין במאמר השהיות אובייקטים.
   • עדכון המטא-נתונים של האובייקט: כדי להוסיף מטא-נתונים של אובייקט, מבצעים את הפעולות הבאות:
     • כדי להוסיף מטא-נתונים מותאמים אישית:
       1. בשדה מפתח, מזינים שם למפתח.
       2. בשדה ערך, מזינים ערך למפתח הזה.
       3. אופציונלי: לוחצים על + הוספת פריט כדי להוסיף עוד צמדי מפתח/ערך.
     • כדי לעדכן מטא-נתונים עם מַפְתח קבוע:
       1. כדי להרחיב את הקטע Update fixed-key metadata, לוחצים על החץ expand_more.
       2. ברשימה Select one or more metadata to update, בוחרים את פריטי המטא-נתונים שרוצים לערוך.
   • ‫Update/Rotate encryption key: כדי להשתמש במפתח ההצפנה של האובייקטים או לעדכן אותו:
     1. ברשימה Select a Cloud KMS key, בוחרים מפתח הצפנה בניהול הלקוח (CMEK).
     2. אופציונלי: בוחרים באפשרות Switch project כדי לבחור מפתח מפרויקט אחר, או באפשרות Enter key manually כדי למלא את הפרטים.
   • מחיקת אובייקטים: כדי למחוק אובייקטים, מבצעים את הפעולות הבאות:
     1. בדיקה אם התכונה "ניהול גרסאות של אובייקטים" מופעלת.

     2. אם התכונה "ניהול גרסאות של אובייקטים" מופעלת, בוחרים באחת מאפשרויות המחיקה הבאות:

        • בוחרים באפשרות Delete all versions of the objects כדי להסיר גם גרסאות פעילות וגם גרסאות לא עדכניות.
        • כדי להסיר רק את הגרסה הפעילה, לוחצים על מחיקה סופית של גרסאות פעילות.

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

5. לוחצים על הבא.
6. בחלונית Name operation & specify objects:
   1. בשדה Name, מזינים שם.
   2. אופציונלי: בשדה Description, מזינים תיאור.
   3. בקטע Specify objects, בוחרים באפשרות Upload lists of objects using manifest CSV files, ואז מבצעים את הפעולות הבאות:

      1. מעלים את קובץ המניפסט בפורמט CSV לקטגוריה. הקובץ הזה צריך להכיל כותרות ל-Bucket name, ל-Object key ול-Generation number.
      2. ברשימה Select manifest file mode, בוחרים אחת מהאפשרויות הבאות:
         • אם בוחרים באפשרות Select a manifest file from Cloud Storage, לוחצים על Browse בשדה Select a manifest file from Cloud Storage. בתיבת הדו-שיח Select object שמופיעה, עוברים לקובץ המניפסט בפורמט CSV ולוחצים על Select.
         • אם בוחרים באפשרות Select multiple manifest files using wildcard, מזינים את נתיב הקובץ בשדה Enter manifest file location using wildcard. לדוגמה, bucket-name/folder/manifest_*.
7. לוחצים על יצירה.

שורת הפקודה

1. מפעילים את Cloud Shell במסוף Cloud de Confiance .

   הפעלת Cloud Shell

   בחלק התחתון של מסוף Cloud de Confiance יתחיל סשן של Cloud Shell ותופיע הודעה של שורת הפקודה. Cloud Shell היא סביבת מעטפת שבה ה-CLI של Google Cloud מותקן ומוגדרים ערכים לפרויקט הקיים. הסשן יופעל תוך כמה שניות.

2. בסביבת הפיתוח, מריצים את הפקודה gcloud storage batch-operations jobs create:

   gcloud storage batch-operations jobs create \
   JOB_NAME \
   {--bucket=SOURCE_BUCKET | --bucket-list=SOURCE_BUCKET_LIST} \
   --manifest-location=URI \
   JOB_TYPE_FLAG

   כאשר:

   • ‫JOB_NAME הוא השם של המשימה לביצוע פעולות רבות על פריטי אחסון.

   • ‫SOURCE_BUCKET הוא שם הקטגוריה שמכילה את האובייקטים שרוצים לעבד. לדוגמה, my-bucket.

   • ‫SOURCE_BUCKET_LIST היא רשימה מופרדת בפסיקים של שם אחד או יותר של קטגוריות שמכילות את האובייקטים שרוצים לעבד. לדוגמה, bucket1,bucket2.

   • ‫URI הוא ה-URI לקטגוריה שמכילה את המניפסט. לדוגמה, gs://bucket_name/path_to_csv_file/*.csv. כשמשתמשים בתו הכללי לחיפוש *.csv, ‏BigQuery מייצא את התוצאה לכמה קובצי CSV.

   • ‫JOB_TYPE_FLAG הוא אחד מהדגלים הבאים, בהתאם לסוג העבודה.

     • ‫--delete-object: מחיקה של אובייקט אחד או יותר.

     • --put-metadata: עדכון המטא-נתונים של האובייקט. מטא-נתונים של אובייקט מאוחסנים כצמדי מפתח/ערך. מציינים את צמד המפתח/ערך של המטא-נתונים שרוצים לשנות. אפשר לציין צמד מפתח/ערך אחד או יותר כרשימה. אפשר גם לספק הגדרות לשמירת אובייקטים באמצעות הדגל --put-metadata.

     • ‫--rewrite-object: עדכון מפתחות ההצפנה בניהול הלקוח של אובייקט אחד או יותר. אפשר גם להשתמש בדגל הזה כדי לשנות את סוג האחסון של האובייקט, על ידי ציון המפתח storage-class. סוגי האחסון הנתמכים כוללים את STANDARD,‏ NEARLINE,‏ COLDLINE ו-ARCHIVE. לדוגמה: --rewrite-object=storage-class=NEARLINE.

     • ‫--set-object-acls-from-file: תיקון רשימות של בקרת גישה (ACL) לאובייקטים. צריך לציין את הנתיב לקובץ JSON או YAML עם הרשאות להוספה או לעדכון של ישויות כמו allUsers או allAuthenticatedUsers. לדוגמה: --set-object-acls-from-file=acl-updates.yaml.

     • ‫--put-object-event-based-hold: הפעלה של החזקות אובייקטים מבוססות-אירועים.

     • ‫--no-put-object-event-based-hold: השבתת החזקות אובייקטים מבוססות-אירועים.

     • ‫--put-object-temporary-hold: הפעלה של השהיות זמניות של אובייקטים.

     • ‫--no-put-object-temporary-hold: השבתת החזקות אובייקטים זמניות.

     • ‫--clear-all-object-custom-contexts: מחיקת כל הקשרי האובייקטים הקיימים.

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

       gcloud storage batch-operations jobs create my-job \
       --bucket=my-bucket \
       --manifest-location=gs://my-bucket/manifest.csv \
       --clear-all-object-custom-contexts

     • ‫--clear-object-custom-contexts: הסרת הקשרים עם מפתחות ספציפיים. אפשר גם לעדכן הקשרים ספציפיים ולהסיר מפתחות באמצעות הדגל --clear-object-custom-contexts ואחד מהדגלים הבאים:

       • ‫--update-object-custom-contexts: מפה של צמדי מפתח/ערך.

         בדוגמה הבאה מוסבר איך ליצור משימה להסרת ההקשר עם המפתח temp-id, ולעדכן או להוסיף הקשר עם המפתחות project-id ו-cost-center לכל האובייקטים שרשומים ב-manifest.csv:

         gcloud storage batch-operations jobs create my-job \
         --bucket=my-bucket \
         --manifest-location=gs://my-bucket/manifest.csv \
         --clear-object-custom-contexts=temp-id \
         --update-object-custom-contexts=project-id=project-A,cost-center=engineering

       • ‫--update-object-custom-contexts-file: הנתיב לקובץ JSON או YAML עם צמדי מפתח/ערך.

         בדוגמה הבאה מוסבר איך ליצור משימה לעיבוד אובייקטים שמוגדרים ב-manifest.csv. המשימה מבצעת את הפעולות הבאות:

         • הסרת כל ההקשרים עם המפתח temp-id.

         • עדכון של הקשרים קיימים באמצעות המפתחות project-id ו-cost-center שמוגדרים בקובץ /tmp/context_updates.json.

         gcloud storage batch-operations jobs create my-job \
         --bucket=my-bucket \
         --manifest-location=gs://my-bucket/manifest.csv \
         --clear-object-custom-contexts=temp-id \
         --update-object-custom-contexts-file=/tmp/context_updates.json

         כאשר /tmp/context_updates.json מכיל את ההקשרים הבאים של האובייקט:

         {
         "project-id": {"value": "project-A"},
         "cost-center": {"value": "engineering"}
         }