使用对象上下文

本页介绍了如何以键值对的形式在 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 存储桶时，将上下文附加到对象。每个上下文由一个键和一个值组成。

JSON API

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

为现有对象附加或修改上下文

您可以将新上下文附加到 Cloud Storage 存储桶中的现有对象。

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.googleapis.com/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 对象请求。

查看对象上下文

您可以通过列出对象元数据或描述特定对象来查看对象的上下文。

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.googleapis.com/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"
        }
      }
    }
  }

按上下文过滤对象

按对象上下文键的存在情况或其特定值过滤对象。按上下文过滤对象有助于高效地查找和管理特定对象组。如需了解详情，请参阅按对象上下文过滤。

在对象操作期间管理对象上下文

默认情况下，当您复制、重写、组合、移动或恢复对象时，对象上下文会保留。您还可以在复制、重写和合成操作期间修改上下文。

JSON API

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

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

后续步骤