שימוש בהקשרים של אובייקטים

שורת הפקודה

כדי לצרף הקשרים כשמעלים אובייקטים באמצעות הפקודה gcloud alpha storage cp, משתמשים בדגל --custom-contexts:

gcloud alpha storage cp OBJECT_LOCATION gs://DESTINATION_BUCKET_NAME --custom-contexts=KEY=VALUE,...

כאשר:

• ‫OBJECT_LOCATION הוא הנתיב המקומי לאובייקט. לדוגמה, Desktop/dog.png.
• ‫DESTINATION_BUCKET_NAME הוא שם הקטגוריה שאליה מעלים את האובייקט. לדוגמה, my-bucket.
• ‫KEY הוא מפתח ההקשר לצירוף לאובייקט. לדוגמה, Department. אפשר לציין כמה צמדים של מפתח/ערך ולהפריד ביניהם באמצעות פסיקים.
• ‫VALUE הוא הערך שרוצים לשייך למפתח ההקשר. לדוגמה, Human resources.

אפשר גם ליצור קובץ JSON שמכיל את ההקשרים שרוצים לצרף לאובייקטים, ולהשתמש בדגל --custom-contexts-file:

  {
    "KEY": {
      "value": "VALUE"
    },
    ...
  }

כאשר:

• ‫KEY הוא מפתח ההקשר לצירוף לאובייקט. לדוגמה, Department. אפשר לציין כמה צמדים של מפתח/ערך.
• ‫VALUE הוא הערך שרוצים לשייך למפתח ההקשר. לדוגמה, Human resources.

כדי לצרף הקשרים כשמעלים ספריות באמצעות הפקודה gcloud alpha storage rsync, משתמשים בדגל --custom-contexts או בדגל --custom-contexts-file:

gcloud alpha storage rsync DIRECTORY_LOCATION gs://DESTINATION_BUCKET_NAME --recursive --custom-contexts=KEY=VALUE,...

כאשר:

• ‫DIRECTORY_LOCATION הוא הנתיב המקומי לספרייה. לדוגמה, ~/my_directory.
• ‫DESTINATION_BUCKET_NAME הוא שם הקטגוריה שאליה מעלים את הספרייה. לדוגמה, my-bucket.
• ‫KEY הוא מפתח ההקשר לצירוף לאובייקטים. לדוגמה, Department. אפשר לציין כמה צמדים של מפתח/ערך ולהפריד ביניהם באמצעות פסיקים.
• ‫VALUE הוא הערך שרוצים לשייך למפתח ההקשר. לדוגמה, Human resources.

API ל-JSON

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

• העלאות מרובות חלקים

• העלאות שניתן להמשיך

כחלק מהמטא-נתונים של האובייקט בפורמט JSON, כוללים את השדה contexts:

  {
    "contexts": {
      "custom": {
        "KEY": {
          "value": "VALUE"
        },
        ...
      }
    }
  }

כאשר:

• ‫KEY הוא מפתח ההקשר לצירוף לאובייקט. לדוגמה, Department. אפשר לציין כמה צמדים של מפתח/ערך באובייקט custom.
• ‫VALUE הוא הערך שרוצים לשייך למפתח ההקשר. לדוגמה, Human resources.

שורת הפקודה

משתמשים בפקודה gcloud alpha storage objects update:

gcloud alpha storage objects update gs://BUCKET_NAME/OBJECT_NAME CUSTOM_CONTEXTS_FLAG

כאשר:

• ‫BUCKET_NAME הוא שם הקטגוריה שמכילה את האובייקט שרוצים לערוך את ההקשר שלו. לדוגמה, my-bucket.
• ‫OBJECT_NAME הוא שם האובייקט. לדוגמה, pets/dog.png.

• ‫CUSTOM_CONTEXTS_FLAG הוא אחד מהדגלים הבאים:

  • כדי להחליף את כל ההקשרים הקיימים, משתמשים בפקודה --custom-contexts=KEY=VALUE,... או --custom-contexts-file=CUSTOM_CONTEXTS_FILE.

    כאשר:

    • ‫KEY הוא מפתח ההקשר לצירוף לאובייקט. לדוגמה, Department. אפשר לציין כמה צמדים של מפתח/ערך ולהפריד ביניהם באמצעות פסיקים.
    • ‫VALUE הוא הערך שרוצים לשייך למפתח ההקשר. לדוגמה, Human resources.
    • ‫CUSTOM_CONTEXTS_FILE הוא הנתיב לקובץ JSON או YAML שמכיל את ההקשרים שרוצים לצרף לאובייקט.

  • כדי למחוק את כל ההקשרים הקיימים, משתמשים ב---clear-custom-contexts.

  • כדי להוסיף, לשנות או למחוק הקשרים ספציפיים, משתמשים בשילוב של --update-custom-contexts=KEY=VALUE,... ו---remove-custom-contexts=KEY,...

    כאשר:

    • ‫KEY הוא מפתח ההקשר שרוצים לצרף לאובייקט או למחוק ממנו. לדוגמה, Department.
    • ‫VALUE הוא הערך שרוצים לשייך למפתח ההקשר שרוצים לצרף לאובייקט. לדוגמה, Human resources.

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

Patching gs://my-bucket/pets/dog.png#1560574162144861...
  Completed 1

ספריות לקוח

import com.google.cloud.storage.Blob;
import com.google.cloud.storage.BlobId;
import com.google.cloud.storage.BlobInfo;
import com.google.cloud.storage.BlobInfo.ObjectContexts;
import com.google.cloud.storage.BlobInfo.ObjectCustomContextPayload;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;
import com.google.common.collect.Maps;
import java.util.Map;

public class SetObjectContexts {
  public static void setObjectContexts(
      String projectId, String bucketName, String objectName, String key, String value)
      throws Exception {
    // The ID of your GCP project
    // String projectId = "your-project-id";

    // The ID of your GCS bucket
    // String bucketName = "your-unique-bucket-name";

    // The ID of your GCS object
    // String objectName = "your-object-name";

    // The context key-value you want to add
    // String key = "your-context-key";
    // String value = "your-context-value";

    try (Storage storage =
        StorageOptions.newBuilder().setProjectId(projectId).build().getService()) {
      BlobId blobId = BlobId.of(bucketName, objectName);
      Blob blob = storage.get(blobId);
      if (blob == null) {
        System.out.println("The object " + objectName + " was not found in " + bucketName);
        return;
      }

      // Recommended: Set a generation-match precondition to avoid potential race
      // conditions and data corruptions. The request to update returns a 412 error if
      // the object's generation number does not match your precondition.
      Storage.BlobTargetOption precondition = Storage.BlobTargetOption.generationMatch();

      // This section demonstrates how to upsert, delete all, and delete a specific context.

      // To upsert a context (if the key already exists, its value is replaced;
      // otherwise, a new key-value pair is added):
      ObjectCustomContextPayload payload =
          ObjectCustomContextPayload.newBuilder().setValue(value).build();
      Map<String, ObjectCustomContextPayload> custom = Maps.newHashMap();
      custom.put(key, payload);
      ObjectContexts contexts = ObjectContexts.newBuilder().setCustom(custom).build();

      /*
       * To delete all existing contexts:
       * ObjectContexts contexts = ObjectContexts.newBuilder().setCustom(null).build();
       */

      /*
       * To delete a specific key from the context:
       * Map<String, ObjectCustomContextPayload> custom = Maps.newHashMap();
       * custom.put(key, null);
       * ObjectContexts contexts = ObjectContexts.newBuilder().setCustom(custom).build();
       */
      BlobInfo pendingUpdate = blob.toBuilder().setContexts(contexts).build();
      storage.update(pendingUpdate, precondition);

      System.out.println(
          "Updated custom contexts for object " + objectName + " in bucket " + bucketName);
    }
  }
}

API ל-JSON

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

2. יוצרים קובץ JSON עם ההגדרות של האובייקט, שחייבות לכלול את שדות ההגדרה contexts של האובייקט.

   כדי להוסיף, לשנות או להחליף הקשרים קיימים, צריך להשתמש בפורמט הבא:

     {
       "contexts": {
         "custom": {
           "KEY": {
             "value": "VALUE"
           },
           ...
         }
       }
     }

   כאשר:

   • ‫KEY הוא מפתח ההקשר לצירוף לאובייקט. לדוגמה, Department. אפשר לציין כמה צמדים של מפתח/ערך באובייקט custom.
   • ‫VALUE הוא הערך שרוצים לשייך למפתח ההקשר. לדוגמה, Human resources.

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

     {
       "contexts": {
         "custom": null
       }
     }

   כדי למחוק מפתח ספציפי מההקשר, צריך להשתמש בפורמט הבא:

     {
       "contexts": {
         "custom": {
           "KEY": null,
           ...
         }
       }
     }

   כאשר:

   ‫KEY הוא מפתח ההקשר שרוצים למחוק מאובייקט. לדוגמה, Department. אפשר לציין כמה מפתחות למחיקה מהאובייקט custom.

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

   curl -X PATCH --data-binary @JSON_FILE_NAME \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     "https://storage.s3nsapis.fr/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME"

   כאשר:

   • ‫JSON_FILE_NAME הוא הנתיב לקובץ שכולל את פרטי ההקשר של האובייקט.
   • ‫BUCKET_NAME הוא שם הקטגוריה שמכילה את האובייקט שרוצים לערוך את ההקשר שלו. לדוגמה, my-bucket.
   • ‫OBJECT_NAME הוא שם האובייקט עם קידוד כתובת URL. לדוגמה, pets/dog.png יותאם לקידודי התווים שמתאימים לכתובות URL באופן הבא: pets%2Fdog.png.

אפשר גם להחליף את ההקשר של אובייקט באמצעות בקשת PUTאובייקט. בקשת האובייקט PUT מחליפה גם מטא-נתונים אחרים של האובייקט. לכן, לא מומלץ להשתמש בבקשת האובייקט PUT.

שורת הפקודה

משתמשים בפקודה gcloud alpha storage objects describe:

gcloud alpha storage objects describe gs://BUCKET_NAME/OBJECT_NAME

כאשר:

• ‫BUCKET_NAME הוא שם הקטגוריה שמכילה את האובייקט שרוצים לצפות בהקשר שלו. לדוגמה, my-bucket.
• ‫OBJECT_NAME הוא שם האובייקט שרוצים לצפות בהקשר שלו. לדוגמה, pets/dog.png.

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

bucket: my-bucket
contexts:
  Department:
    createTime: '2023-01-01T00:00:00.000000+00:00'
    type: CUSTOM
    updateTime: '2023-01-01T00:00:00.000000+00:00'
    value: HR
  DataClassification:
    createTime: '2023-01-01T00:00:00.000000+00:00'
    type: CUSTOM
    updateTime: '2023-01-01T00:00:00.000000+00:00'
    value: Confidential
name: employees.txt

ספריות לקוח

import com.google.cloud.storage.Blob;
import com.google.cloud.storage.BlobInfo.ObjectContexts;
import com.google.cloud.storage.BlobInfo.ObjectCustomContextPayload;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;
import java.util.Map;

public class GetObjectContexts {
  public static void getObjectContexts(String projectId, String bucketName, String objectName)
      throws Exception {
    // The ID of your GCP project
    // String projectId = "your-project-id";

    // The ID of your GCS bucket
    // String bucketName = "your-unique-bucket-name";

    // The ID of your GCS object
    // String objectName = "your-object-name";

    try (Storage storage =
        StorageOptions.newBuilder().setProjectId(projectId).build().getService()) {

      Blob blob = storage.get(bucketName, objectName);
      if (blob == null) {
        System.out.println("The object " + objectName + " was not found in " + bucketName);
        return;
      }
      ObjectContexts objectContexts = blob.getContexts();

      if (objectContexts != null) {
        Map<String, ObjectCustomContextPayload> customContexts = objectContexts.getCustom();
        if (customContexts == null) {
          System.out.println("No custom contexts found for object: " + objectName);
          return;
        }
        // Print blob's object contexts
        System.out.println("\nCustom Contexts:");
        for (Map.Entry<String, ObjectCustomContextPayload> custom : customContexts.entrySet()) {
          System.out.println(custom.getKey() + "=" + custom.getValue());
        }
      }
    }
  }
}

API ל-JSON

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

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

   curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://storage.s3nsapis.fr/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME"

   כאשר:

   • ‫BUCKET_NAME הוא שם הקטגוריה שמכילה את האובייקט שרוצים לצפות בהקשר שלו. לדוגמה, my-bucket.
   • ‫OBJECT_NAME הוא השם של האובייקט שרוצים לצפות בהקשר שלו, בקידודי תווים שמתאימים לכתובות URL. לדוגמה, pets/dog.png יותאם לקידודי התווים שמתאימים לכתובות URL באופן הבא: pets%2Fdog.png.

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

     {
       "kind": "storage#object",
       "name": "employees.txt",
       "bucket": "my-bucket",
       "contexts": {
         "custom": {
           "Department": {
             "value": "HR",
             "createTime": "2023-01-01T00:00:00.000Z",
             "updateTime": "2023-01-01T00:00:00.000Z"
           },
           "DataClassification": {
             "value": "Confidential",
             "createTime": "2023-01-01T00:00:00.000Z",
             "updateTime": "2023-01-01T00:00:00.000Z"
           }
         }
       }
     }
     

שורת הפקודה

הפקודה gcloud alpha storage cp, הפקודה gcloud alpha storage rsync והפקודה gcloud alpha storage mv שומרות על ההקשרים מאובייקט המקור כברירת מחדל. כדי לשנות את ההקשרים במהלך הפעולות האלה, משתמשים באחד מהדגלים הבאים:

• הדגלים --custom-contexts או --custom-contexts-file כדי להגדיר הקשרים חדשים לאובייקט היעד.
• הדגל --clear-custom-contexts כדי למנוע צירוף הקשרים מאובייקט המקור לאובייקט היעד.
• שילוב של הדגלים --update-custom-contexts ו---remove-custom-contexts כדי לשנות הקשרים ספציפיים מאובייקט המקור לפני שמצרפים אותם לאובייקט היעד.

הפקודה gcloud alpha storage objects compose ממזגת הקשרים מאובייקטי המקור ומצרפת אותם לאובייקטי היעד כברירת מחדל. ב-Cloud Storage, כדי לפתור קונפליקטים, המערכת נותנת עדיפות להקשרים מאובייקטים במקור שעברו עיבוד מאוחר יותר. מידע נוסף על התנהגות ההקשר של האובייקט במהלך פעולת הרכבה זמין במאמר הקשרים של אובייקטים מורכבים. אפשר גם לציין הקשרים חדשים לאובייקט היעד באמצעות הדגלים --custom-contexts או --custom-contexts-file.

API ל-JSON

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

• כשמרכיבים אובייקטים, ההקשרים מאובייקטי המקור מתמזגים עם אובייקט היעד כברירת מחדל. ‫Cloud Storage פותר קונפליקטים על ידי מתן עדיפות להקשרים מאובייקטים של מקור שעברו עיבוד מאוחר יותר. למידע נוסף על התנהגות של הקשר של האובייקט במהלך פעולת הרכבה, אפשר לעיין במאמר הקשרים של אובייקטים מורכבים. אפשר גם לציין הקשרים חדשים לאובייקט היעד במאפיין destination.contexts.custom.