使用对象上下文

本页介绍了如何以键值对的形式在 Cloud Storage 对象上附加和管理上下文。

获取所需的角色

如需获得创建和管理对象上下文所需的权限，请让您的管理员为您授予对象的以下 IAM 角色：

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

这些预定义角色可提供创建和管理对象上下文所需的权限。如需查看所需的确切权限，请展开所需权限部分：

所需权限

创建和管理对象上下文需要以下权限：

  • 创建具有对象上下文的对象：
    • 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。

JSON API

如需在上传新对象时将上下文附加到对象，请使用以下任意方法：

在 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 进行身份验证，请设置应用默认凭证。如需了解详情，请参阅为客户端库设置身份验证。

在运行代码示例之前，请将 GOOGLE_CLOUD_UNIVERSE_DOMAIN 环境变量设置为 s3nsapis.fr。 


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

JSON API

  1. 安装并初始化 gcloud CLI，以便为 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，通过 PATCH Object 请求调用 JSON API：

    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 是对象的网址编码名称。例如，pets/dog.png 的网址编码为 pets%2Fdog.png。

或者，您也可以使用 PUT Object 请求替换对象的上下文。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 进行身份验证，请设置应用默认凭证。如需了解详情，请参阅为客户端库设置身份验证。

在运行代码示例之前，请将 GOOGLE_CLOUD_UNIVERSE_DOMAIN 环境变量设置为 s3nsapis.fr。 


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());
        }
      }
    }
  }
}

JSON API

  1. 安装并初始化 gcloud CLI，以便为 Authorization 标头生成访问令牌。

  2. 使用 cURL，通过 GET Object 请求调用 JSON API：

    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 是要查看其上下文的对象的网址编码名称。例如，pets/dog.png 的网址编码为 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 标志为目标对象指定新上下文。

JSON API

  • 如需在 复制或重写对象操作期间修改上下文，请在请求正文中添加 contexts.custom 属性。如果您未添加此属性，系统会默认保留来源对象中的上下文。

  • 当您组合对象时，默认情况下，源对象中的上下文会合并到目标对象中。Cloud Storage 通过优先处理稍后处理的源对象中的上下文来解决冲突。如需详细了解在组合操作期间的对象上下文行为，请参阅复合对象上下文。您还可以在 destination.contexts.custom 属性中为目标对象指定新上下文。

后续步骤