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

בדף הזה מוסבר איך לצרף הקשרים לאובייקטים ב-Cloud Storage ולנהל אותם בצורה של צמדי מפתח/ערך.

קבלת התפקידים הנדרשים

כדי לקבל את ההרשאות שדרושות ליצירה ולניהול של הקשרים של אובייקטים, צריך לבקש מהאדמין להקצות לכם את תפקידי ה-IAM הבאים באובייקט:

יצירת אובייקטים עם הקשרים: Storage Object Creator (roles/storage.objectCreator)
צירוף, עדכון, צפייה ומחיקה של הקשרים מאובייקטים: משתמש באובייקטים באחסון (roles/storage.objectUser)
צפייה במפתחות וערכים של הקשר שמצורפים לאובייקטים: צפייה באובייקטים באחסון (roles/storage.objectViewer)

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

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

ההרשאות הנדרשות

כדי ליצור ולנהל הקשרים של אובייקטים, צריך את ההרשאות הבאות:

יצירת אובייקט עם הקשרים של האובייקט:
- storage.objects.create
- storage.objects.createContext
צירוף, עדכון ומחיקה של הקשרים של אובייקטים:
- storage.objects.update
- storage.objects.createContext
- storage.objects.updateContext
- storage.objects.deleteContext
הצגת הקשרים של האובייקט:
- storage.objects.get
- storage.objects.list

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

צירוף הקשרים לאובייקטים חדשים

כשמעלים אובייקטים חדשים לקטגוריות של Cloud Storage, אפשר לצרף להם הקשרים. כל הקשר מורכב ממפתח ומערך.

שורת הפקודה

כדי לצרף הקשרים כשמעלים אובייקטים באמצעות הפקודה 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.

צירוף הקשרים לאובייקט קיים או שינוי שלהם

אתם יכולים לצרף הקשרים חדשים לאובייקטים הקיימים שלכם בקטגוריות של Cloud Storage.

שורת הפקודה

משתמשים בפקודה 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

ספריות לקוח

Java

למידע נוסף, קראו את מאמרי העזרה של Cloud Storage Java API.

כדי לבצע אימות ב-Cloud Storage, אתם צריכים להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לספריות לקוח.


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

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

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

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

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

כאשר:

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

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

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

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

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

כאשר:

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

משתמשים ב- 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.googleapis.com/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

ספריות לקוח

Java

למידע נוסף, קראו את מאמרי העזרה של Cloud Storage Java API.

כדי לבצע אימות ב-Cloud Storage, אתם צריכים להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לספריות לקוח.


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

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

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

curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://storage.googleapis.com/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.

המאמרים הבאים

מידע על מאפייני ההקשר של האובייקט מופיע במאמרי העזרה של Cloud Storage API.

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

קבלת התפקידים הנדרשים

ההרשאות הנדרשות

צירוף הקשרים לאובייקטים חדשים

שורת הפקודה

API ל-JSON

צירוף הקשרים לאובייקט קיים או שינוי שלהם

שורת הפקודה

ספריות לקוח

Java

API ל-JSON

הצגת הקשרים של אובייקטים

שורת הפקודה

ספריות לקוח

Java

API ל-JSON

סינון אובייקטים לפי הקשרים

ניהול הקשרים של אובייקטים במהלך פעולות על אובייקטים

שורת הפקודה

API ל-JSON

המאמרים הבאים

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