此页面由 Cloud Translation API 翻译。

使用对象上下文

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

获取所需的角色

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

创建具有上下文的对象： Storage Object Creator (roles/storage.objectCreator)
附加、更新、查看和删除对象的上下文： Storage Object User (roles/storage.objectUser)
查看附加到对象的上下文键和值： Storage Object Viewer (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。

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


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

安装并初始化 gcloud CLI，以便为 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，通过 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 对象请求。

查看对象上下文

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

命令行

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


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

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

使用 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"
        }
      }
    }
  }

按上下文过滤对象

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

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

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

命令行

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 属性中为目标对象指定新上下文。

后续步骤

如需了解对象上下文属性，请参阅 Cloud Storage API 文档。

使用对象上下文 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

获取所需的角色

所需权限

将上下文附加到新对象

命令行

JSON API

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

命令行

客户端库

Java

JSON API

查看对象上下文

命令行

客户端库

Java

JSON API

按上下文过滤对象

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

命令行

JSON API

后续步骤

使用对象上下文