查看和修改对象元数据

概念

本页面介绍了如何查看和修改与存储在 Cloud Storage 中的对象关联的元数据。

本页面没有介绍如何查看或修改 Identity and Access Management (IAM) 政策或对象访问控制列表 (ACL)（均可以控制能够访问您的数据的人员）。如需介绍如何完成这些任务的指南，请参阅使用 IAM 权限以及创建和管理 ACL。

所需的角色

为了获得查看和修改对象元数据所需的权限，请让您的管理员向您授予存储桶的 Storage Object User (roles/storage.objectUser) 角色。

此角色包含查看和修改对象元数据所需的权限。如需查看所需的确切权限，请展开所需权限部分：

所需权限

  • storage.buckets.list
    • 仅当您计划使用 Google Cloud 控制台执行本页面上的任务时，才需要此权限。
  • storage.objects.get
  • storage.objects.getIamPolicy
    • 只有在您希望返回对象的 IAM 政策时，才需要此权限。
  • storage.objects.list
  • storage.objects.setRetention
    • 只有在您想要设置对象的保留配置时，才需要此权限。
  • storage.objects.update

您也可以使用其他预定义角色或自定义角色来获取这些权限。

如需了解如何授予存储桶的角色，请参阅将 IAM 与存储桶搭配使用。

查看对象元数据

请完成以下说明中规定的操作，以查看与对象关联的元数据：

控制台

  1. 在 Google Cloud 控制台中，进入 Cloud Storage 存储桶页面。

    进入“存储桶”

  2. 在存储桶列表中，找到包含要查看其元数据的对象的存储桶，并点击其名称。

    此时会打开“存储桶详情”页面，其中“对象”标签页已选中。

  3. 找到到可能位于文件夹中的对象。

    某些对象元数据值（例如对象的大小和存储类别）会随对象名称显示。

  4. 点击对象的名称。

    此时会打开对象详情页面，其中显示其他对象元数据。

  5. 点击修改元数据。

    出现的叠加窗口中会显示更多对象元数据键（包括自定义元数据）的当前值。

如需了解如何在 Google Cloud 控制台中获取有关失败的 Cloud Storage 操作的详细错误信息，请参阅问题排查。

命令行

使用 gcloud storage objects describe 命令：

gcloud storage objects describe gs://BUCKET_NAME/OBJECT_NAME

其中：

  • BUCKET_NAME 是包含要查看其元数据的对象的存储桶的名称，例如 my-awesome-bucket。
  • OBJECT_NAME 是要查看其元数据的对象的名称，例如 cat.jpeg。

如果成功，响应类似于以下示例：

bucket: my-awesome-bucket
content_type: image/png
crc32c_hash: pNKjPQ==
creation_time: 2024-01-26T21:33:04+0000
custom_fields:
  Animal: Cat
  Type: Cute
custom_time: 1970-01-01T00:00:00+0000
etag: CMXyydSA/IMDEAE=
generation: '1706304784726341'
md5_hash: KCbI3PYk1aHfekIvf/osrw==
metageneration: 1
name: kitten.png
size: 168276
storage_class: STANDARD
storage_class_update_time: 2024-01-26T21:33:04+0000
storage_url: gs://nstocktest8/kitten.png#1706304784726341
update_time: 2024-01-26T21:33:04+0000

客户端库

C++

如需了解详情，请参阅 Cloud Storage C++ API 参考文档。

如需向 Cloud Storage 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

namespace gcs = ::google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string const& bucket_name,
   std::string const& object_name) {
  StatusOr<gcs::ObjectMetadata> object_metadata =
      client.GetObjectMetadata(bucket_name, object_name);
  if (!object_metadata) throw std::move(object_metadata).status();

  std::cout << "The metadata for object " << object_metadata->name()
            << " in bucket " << object_metadata->bucket() << " is "
            << *object_metadata << "\n";
}

C#

如需了解详情，请参阅 Cloud Storage C# API 参考文档。

如需向 Cloud Storage 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 


using Google.Cloud.Storage.V1;
using System;

public class GetMetadataSample
{
    public Google.Apis.Storage.v1.Data.Object GetMetadata(
        string bucketName = "your-unique-bucket-name",
        string objectName = "your-object-name")
    {
        var storage = StorageClient.Create();
        var storageObject = storage.GetObject(bucketName, objectName, new GetObjectOptions { Projection = Projection.Full });
        Console.WriteLine($"Bucket:\t{storageObject.Bucket}");
        Console.WriteLine($"CacheControl:\t{storageObject.CacheControl}");
        Console.WriteLine($"ComponentCount:\t{storageObject.ComponentCount}");
        Console.WriteLine($"ContentDisposition:\t{storageObject.ContentDisposition}");
        Console.WriteLine($"ContentEncoding:\t{storageObject.ContentEncoding}");
        Console.WriteLine($"ContentLanguage:\t{storageObject.ContentLanguage}");
        Console.WriteLine($"ContentType:\t{storageObject.ContentType}");
        Console.WriteLine($"Crc32c:\t{storageObject.Crc32c}");
        Console.WriteLine($"ETag:\t{storageObject.ETag}");
        Console.WriteLine($"Generation:\t{storageObject.Generation}");
        Console.WriteLine($"Id:\t{storageObject.Id}");
        Console.WriteLine($"Kind:\t{storageObject.Kind}");
        Console.WriteLine($"KmsKeyName:\t{storageObject.KmsKeyName}");
        Console.WriteLine($"Md5Hash:\t{storageObject.Md5Hash}");
        Console.WriteLine($"MediaLink:\t{storageObject.MediaLink}");
        Console.WriteLine($"Metageneration:\t{storageObject.Metageneration}");
        Console.WriteLine($"Name:\t{storageObject.Name}");
        Console.WriteLine($"Size:\t{storageObject.Size}");
        Console.WriteLine($"StorageClass:\t{storageObject.StorageClass}");
        Console.WriteLine($"TimeCreated:\t{storageObject.TimeCreated}");
        Console.WriteLine($"Updated:\t{storageObject.Updated}");
        bool eventBasedHold = storageObject.EventBasedHold ?? false;
        Console.WriteLine("Event-based hold enabled? {0}", eventBasedHold);
        bool temporaryHold = storageObject.TemporaryHold ?? false;
        Console.WriteLine("Temporary hold enabled? {0}", temporaryHold);
        Console.WriteLine($"RetentionExpirationTime\t{storageObject.RetentionExpirationTime}");
        if (storageObject.Metadata != null)
        {
            Console.WriteLine("Metadata: ");
            foreach (var metadata in storageObject.Metadata)
            {
                Console.WriteLine($"{metadata.Key}:\t{metadata.Value}");
            }
        }
        Console.WriteLine($"CustomTime:\t{storageObject.CustomTime}");
        return storageObject;
    }
}

Go

如需了解详情，请参阅 Cloud Storage Go API 参考文档。

如需向 Cloud Storage 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

import (
	"context"
	"fmt"
	"io"
	"time"

	"cloud.google.com/go/storage"
)

// getMetadata prints all of the object attributes.
func getMetadata(w io.Writer, bucket, object string) (*storage.ObjectAttrs, error) {
	// bucket := "bucket-name"
	// object := "object-name"
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		return nil, fmt.Errorf("storage.NewClient: %w", err)
	}
	defer client.Close()

	ctx, cancel := context.WithTimeout(ctx, time.Second*10)
	defer cancel()

	o := client.Bucket(bucket).Object(object)
	attrs, err := o.Attrs(ctx)
	if err != nil {
		return nil, fmt.Errorf("Object(%q).Attrs: %w", object, err)
	}
	fmt.Fprintf(w, "Bucket: %v\n", attrs.Bucket)
	fmt.Fprintf(w, "CacheControl: %v\n", attrs.CacheControl)
	fmt.Fprintf(w, "ContentDisposition: %v\n", attrs.ContentDisposition)
	fmt.Fprintf(w, "ContentEncoding: %v\n", attrs.ContentEncoding)
	fmt.Fprintf(w, "ContentLanguage: %v\n", attrs.ContentLanguage)
	fmt.Fprintf(w, "ContentType: %v\n", attrs.ContentType)
	fmt.Fprintf(w, "Crc32c: %v\n", attrs.CRC32C)
	fmt.Fprintf(w, "Generation: %v\n", attrs.Generation)
	fmt.Fprintf(w, "KmsKeyName: %v\n", attrs.KMSKeyName)
	fmt.Fprintf(w, "Md5Hash: %v\n", attrs.MD5)
	fmt.Fprintf(w, "MediaLink: %v\n", attrs.MediaLink)
	fmt.Fprintf(w, "Metageneration: %v\n", attrs.Metageneration)
	fmt.Fprintf(w, "Name: %v\n", attrs.Name)
	fmt.Fprintf(w, "Size: %v\n", attrs.Size)
	fmt.Fprintf(w, "StorageClass: %v\n", attrs.StorageClass)
	fmt.Fprintf(w, "TimeCreated: %v\n", attrs.Created)
	fmt.Fprintf(w, "Updated: %v\n", attrs.Updated)
	fmt.Fprintf(w, "Event-based hold enabled? %t\n", attrs.EventBasedHold)
	fmt.Fprintf(w, "Temporary hold enabled? %t\n", attrs.TemporaryHold)
	fmt.Fprintf(w, "Retention expiration time %v\n", attrs.RetentionExpirationTime)
	fmt.Fprintf(w, "Custom time %v\n", attrs.CustomTime)
	fmt.Fprintf(w, "\n\nMetadata\n")
	for key, value := range attrs.Metadata {
		fmt.Fprintf(w, "\t%v = %v\n", key, value)
	}
	return attrs, nil
}

Java

如需了解详情，请参阅 Cloud Storage Java API 参考文档。

如需向 Cloud Storage 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 


import com.google.cloud.storage.Blob;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageException;
import com.google.cloud.storage.StorageOptions;
import java.util.Date;
import java.util.Map;

public class GetObjectMetadata {
  public static void getObjectMetadata(String projectId, String bucketName, String blobName)
      throws StorageException {
    // 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";

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

    // Select all fields
    // Fields can be selected individually e.g. Storage.BlobField.CACHE_CONTROL
    Blob blob =
        storage.get(bucketName, blobName, Storage.BlobGetOption.fields(Storage.BlobField.values()));

    // Print blob metadata
    System.out.println("Bucket: " + blob.getBucket());
    System.out.println("CacheControl: " + blob.getCacheControl());
    System.out.println("ComponentCount: " + blob.getComponentCount());
    System.out.println("ContentDisposition: " + blob.getContentDisposition());
    System.out.println("ContentEncoding: " + blob.getContentEncoding());
    System.out.println("ContentLanguage: " + blob.getContentLanguage());
    System.out.println("ContentType: " + blob.getContentType());
    System.out.println("CustomTime: " + blob.getCustomTime());
    System.out.println("Crc32c: " + blob.getCrc32c());
    System.out.println("Crc32cHexString: " + blob.getCrc32cToHexString());
    System.out.println("ETag: " + blob.getEtag());
    System.out.println("Generation: " + blob.getGeneration());
    System.out.println("Id: " + blob.getBlobId());
    System.out.println("KmsKeyName: " + blob.getKmsKeyName());
    System.out.println("Md5Hash: " + blob.getMd5());
    System.out.println("Md5HexString: " + blob.getMd5ToHexString());
    System.out.println("MediaLink: " + blob.getMediaLink());
    System.out.println("Metageneration: " + blob.getMetageneration());
    System.out.println("Name: " + blob.getName());
    System.out.println("Size: " + blob.getSize());
    System.out.println("StorageClass: " + blob.getStorageClass());
    System.out.println("TimeCreated: " + new Date(blob.getCreateTime()));
    System.out.println("Last Metadata Update: " + new Date(blob.getUpdateTime()));
    System.out.println("Object Retention Policy: " + blob.getRetention());
    Boolean temporaryHoldIsEnabled = (blob.getTemporaryHold() != null && blob.getTemporaryHold());
    System.out.println("temporaryHold: " + (temporaryHoldIsEnabled ? "enabled" : "disabled"));
    Boolean eventBasedHoldIsEnabled =
        (blob.getEventBasedHold() != null && blob.getEventBasedHold());
    System.out.println("eventBasedHold: " + (eventBasedHoldIsEnabled ? "enabled" : "disabled"));
    if (blob.getRetentionExpirationTime() != null) {
      System.out.println("retentionExpirationTime: " + new Date(blob.getRetentionExpirationTime()));
    }
    if (blob.getMetadata() != null) {
      System.out.println("\n\n\nUser metadata:");
      for (Map.Entry<String, String> userMetadata : blob.getMetadata().entrySet()) {
        System.out.println(userMetadata.getKey() + "=" + userMetadata.getValue());
      }
    }
  }
}

Node.js

如需了解详情，请参阅 Cloud Storage Node.js API 参考文档。

如需向 Cloud Storage 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// The ID of your GCS bucket
// const bucketName = 'your-unique-bucket-name';

// The ID of your GCS file
// const fileName = 'your-file-name';

// Imports the Google Cloud client library
const {Storage} = require('@google-cloud/storage');

// Creates a client
const storage = new Storage();

async function getMetadata() {
  // Gets the metadata for the file
  const [metadata] = await storage
    .bucket(bucketName)
    .file(fileName)
    .getMetadata();

  console.log(`Bucket: ${metadata.bucket}`);
  console.log(`CacheControl: ${metadata.cacheControl}`);
  console.log(`ComponentCount: ${metadata.componentCount}`);
  console.log(`ContentDisposition: ${metadata.contentDisposition}`);
  console.log(`ContentEncoding: ${metadata.contentEncoding}`);
  console.log(`ContentLanguage: ${metadata.contentLanguage}`);
  console.log(`ContentType: ${metadata.contentType}`);
  console.log(`CustomTime: ${metadata.customTime}`);
  console.log(`Crc32c: ${metadata.crc32c}`);
  console.log(`ETag: ${metadata.etag}`);
  console.log(`Generation: ${metadata.generation}`);
  console.log(`Id: ${metadata.id}`);
  console.log(`KmsKeyName: ${metadata.kmsKeyName}`);
  console.log(`Md5Hash: ${metadata.md5Hash}`);
  console.log(`MediaLink: ${metadata.mediaLink}`);
  console.log(`Metageneration: ${metadata.metageneration}`);
  console.log(`Name: ${metadata.name}`);
  console.log(`Size: ${metadata.size}`);
  console.log(`StorageClass: ${metadata.storageClass}`);
  console.log(`TimeCreated: ${new Date(metadata.timeCreated)}`);
  console.log(`Last Metadata Update: ${new Date(metadata.updated)}`);
  console.log(`TurboReplication: ${metadata.rpo}`);
  console.log(
    `temporaryHold: ${metadata.temporaryHold ? 'enabled' : 'disabled'}`
  );
  console.log(
    `eventBasedHold: ${metadata.eventBasedHold ? 'enabled' : 'disabled'}`
  );
  if (metadata.retentionExpirationTime) {
    console.log(
      `retentionExpirationTime: ${new Date(metadata.retentionExpirationTime)}`
    );
  }
  if (metadata.metadata) {
    console.log('\n\n\nUser metadata:');
    for (const key in metadata.metadata) {
      console.log(`${key}=${metadata.metadata[key]}`);
    }
  }
}

getMetadata().catch(console.error);

PHP

如需了解详情，请参阅 Cloud Storage PHP API 参考文档。

如需向 Cloud Storage 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

use Google\Cloud\Storage\StorageClient;

/**
 * List object metadata.
 *
 * @param string $bucketName The name of your Cloud Storage bucket.
 *        (e.g. 'my-bucket')
 * @param string $objectName The name of your Cloud Storage object.
 *        (e.g. 'my-object')
 */
function object_metadata(string $bucketName, string $objectName): void
{
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);
    $object = $bucket->object($objectName);
    $info = $object->info();
    if (isset($info['name'])) {
        printf('Blob: %s' . PHP_EOL, $info['name']);
    }
    if (isset($info['bucket'])) {
        printf('Bucket: %s' . PHP_EOL, $info['bucket']);
    }
    if (isset($info['storageClass'])) {
        printf('Storage class: %s' . PHP_EOL, $info['storageClass']);
    }
    if (isset($info['id'])) {
        printf('ID: %s' . PHP_EOL, $info['id']);
    }
    if (isset($info['size'])) {
        printf('Size: %s' . PHP_EOL, $info['size']);
    }
    if (isset($info['updated'])) {
        printf('Updated: %s' . PHP_EOL, $info['updated']);
    }
    if (isset($info['generation'])) {
        printf('Generation: %s' . PHP_EOL, $info['generation']);
    }
    if (isset($info['metageneration'])) {
        printf('Metageneration: %s' . PHP_EOL, $info['metageneration']);
    }
    if (isset($info['etag'])) {
        printf('Etag: %s' . PHP_EOL, $info['etag']);
    }
    if (isset($info['crc32c'])) {
        printf('Crc32c: %s' . PHP_EOL, $info['crc32c']);
    }
    if (isset($info['md5Hash'])) {
        printf('MD5 Hash: %s' . PHP_EOL, $info['md5Hash']);
    }
    if (isset($info['contentType'])) {
        printf('Content-type: %s' . PHP_EOL, $info['contentType']);
    }
    if (isset($info['temporaryHold'])) {
        printf('Temporary hold: %s' . PHP_EOL, ($info['temporaryHold'] ? 'enabled' : 'disabled'));
    }
    if (isset($info['eventBasedHold'])) {
        printf('Event-based hold: %s' . PHP_EOL, ($info['eventBasedHold'] ? 'enabled' : 'disabled'));
    }
    if (isset($info['retentionExpirationTime'])) {
        printf('Retention Expiration Time: %s' . PHP_EOL, $info['retentionExpirationTime']);
    }
    if (isset($info['retention'])) {
        printf('Retention mode: %s' . PHP_EOL, $info['retention']['mode']);
        printf('Retain until time is: %s' . PHP_EOL, $info['retention']['retainUntilTime']);
    }
    if (isset($info['customTime'])) {
        printf('Custom Time: %s' . PHP_EOL, $info['customTime']);
    }
    if (isset($info['metadata'])) {
        printf('Metadata: %s' . PHP_EOL, print_r($info['metadata'], true));
    }
}

Python

如需了解详情，请参阅 Cloud Storage Python API 参考文档。

如需向 Cloud Storage 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

from google.cloud import storage


def blob_metadata(bucket_name, blob_name):
    """Prints out a blob's metadata."""
    # bucket_name = 'your-bucket-name'
    # blob_name = 'your-object-name'

    storage_client = storage.Client()
    bucket = storage_client.bucket(bucket_name)

    # Retrieve a blob, and its metadata, from Google Cloud Storage.
    # Note that `get_blob` differs from `Bucket.blob`, which does not
    # make an HTTP request.
    blob = bucket.get_blob(blob_name)

    print(f"Blob: {blob.name}")
    print(f"Bucket: {blob.bucket.name}")
    print(f"Storage class: {blob.storage_class}")
    print(f"ID: {blob.id}")
    print(f"Size: {blob.size} bytes")
    print(f"Updated: {blob.updated}")
    print(f"Generation: {blob.generation}")
    print(f"Metageneration: {blob.metageneration}")
    print(f"Etag: {blob.etag}")
    print(f"Owner: {blob.owner}")
    print(f"Component count: {blob.component_count}")
    print(f"Crc32c: {blob.crc32c}")
    print(f"md5_hash: {blob.md5_hash}")
    print(f"Cache-control: {blob.cache_control}")
    print(f"Content-type: {blob.content_type}")
    print(f"Content-disposition: {blob.content_disposition}")
    print(f"Content-encoding: {blob.content_encoding}")
    print(f"Content-language: {blob.content_language}")
    print(f"Metadata: {blob.metadata}")
    print(f"Medialink: {blob.media_link}")
    print(f"Custom Time: {blob.custom_time}")
    print("Temporary hold: ", "enabled" if blob.temporary_hold else "disabled")
    print(
        "Event based hold: ",
        "enabled" if blob.event_based_hold else "disabled",
    )
    if blob.retention_expiration_time:
        print(
            f"retentionExpirationTime: {blob.retention_expiration_time}"
        )

Ruby

如需了解详情，请参阅 Cloud Storage Ruby API 参考文档。

如需向 Cloud Storage 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

def get_metadata bucket_name:, file_name:
  # The ID of your GCS bucket
  # bucket_name = "your-unique-bucket-name"

  # The ID of your GCS object
  # file_name = "your-file-name"

  require "google/cloud/storage"

  storage = Google::Cloud::Storage.new
  bucket  = storage.bucket bucket_name
  file    = bucket.file file_name

  puts "Name: #{file.name}"
  puts "Bucket: #{bucket.name}"
  puts "Storage class: #{bucket.storage_class}"
  puts "ID: #{file.id}"
  puts "Size: #{file.size} bytes"
  puts "Created: #{file.created_at}"
  puts "Updated: #{file.updated_at}"
  puts "Generation: #{file.generation}"
  puts "Metageneration: #{file.metageneration}"
  puts "Etag: #{file.etag}"
  puts "Owners: #{file.acl.owners.join ','}"
  puts "Crc32c: #{file.crc32c}"
  puts "md5_hash: #{file.md5}"
  puts "Cache-control: #{file.cache_control}"
  puts "Content-type: #{file.content_type}"
  puts "Content-disposition: #{file.content_disposition}"
  puts "Content-encoding: #{file.content_encoding}"
  puts "Content-language: #{file.content_language}"
  puts "KmsKeyName: #{file.kms_key}"
  puts "Event-based hold enabled?: #{file.event_based_hold?}"
  puts "Temporary hold enaled?: #{file.temporary_hold?}"
  puts "Retention Expiration: #{file.retention_expires_at}"
  puts "Custom Time: #{file.custom_time}"
  puts "Metadata:"
  file.metadata.each do |key, value|
    puts " - #{key} = #{value}"
  end
end

Terraform

您可以使用 Terraform 资源查看对象的元数据。

# Get object metadata
data "google_storage_bucket_object" "default" {
  name   = google_storage_bucket_object.default.name
  bucket = google_storage_bucket.static.id
}

output "object_metadata" {
  value = data.google_storage_bucket_object.default
}

REST API

JSON API

  1. 从 OAuth 2.0 Playground 获取授权访问令牌。将 Playground 配置为使用您自己的 OAuth 凭据。如需了解相关说明，请参阅 API 身份验证。

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

    curl -X GET \
  -H "Authorization: Bearer OAUTH2_TOKEN" \
  "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME"

    其中：

    • OAUTH2_TOKEN 是您在第 1 步中生成的访问令牌。
    • BUCKET_NAME 是包含要查看其元数据的对象的存储桶的名称，例如 my-bucket。
    • OBJECT_NAME 是要查看其元数据的对象的网址编码名称。例如，pets/dog.png 的网址编码为 pets%2Fdog.png。

XML API

  1. 从 OAuth 2.0 Playground 获取授权访问令牌。将 Playground 配置为使用您自己的 OAuth 凭据。如需了解相关说明，请参阅 API 身份验证。

  2. 使用 cURL，通过 HEAD Object 请求调用 XML API：

    curl -I HEAD \
  -H "Authorization: Bearer OAUTH2_TOKEN" \
  "https://storage.googleapis.com/BUCKET_NAME/OBJECT_NAME"

    其中：

    • OAUTH2_TOKEN 是您在第 1 步中生成的访问令牌。
    • BUCKET_NAME 是包含要查看其元数据的对象的存储桶的名称，例如 my-bucket。
    • OBJECT_NAME 是要查看其元数据的对象的网址编码名称。例如，pets/dog.png 的网址编码为 pets%2Fdog.png。

修改对象元数据

请完成以下步骤以修改与对象关联的元数据：

控制台

  1. 在 Google Cloud 控制台中，进入 Cloud Storage 存储桶页面。

    进入“存储桶”

  2. 在存储桶列表中，找到包含要为其修改元数据的对象的存储桶，并点击其名称。

    此时会打开“存储桶详情”页面，其中“对象”标签页已选中。

  3. 找到到可能位于文件夹中的对象。

  4. 点击对象的名称。

    此时会打开对象详情页面，其中显示对象元数据。

  5. 如果页面上显示您要修改的元数据以及关联的铅笔图标，请点击该图标。

  6. 否则，请点击修改元数据以访问其他可修改的元数据。

    在出现的叠加窗口中，根据需要修改元数据。

    • 对于标准元数据字段，请修改“值”。

    • 点击 添加项按钮添加您自己的自定义元数据。

    • 您可以修改自定义元数据的“键”和“值”。

    • 点击关联的 X 符号以删除自定义元数据。

    在叠加窗口中修改完元数据后，点击保存。

如需了解如何在 Google Cloud 控制台中获取有关失败的 Cloud Storage 操作的详细错误信息，请参阅问题排查。

命令行

使用 gcloud storage objects update 命令：

gcloud storage objects update gs://BUCKET_NAME/OBJECT_NAME METADATA_FLAG

其中：

  • BUCKET_NAME 是包含您要修改其元数据的对象的存储桶的名称，例如 my-bucket。
  • OBJECT_NAME 是您要修改其元数据的对象的名称，例如 pets/dog.png。
  • METADATA_FLAG 是要修改的元数据的标志。例如 --content-type=image/png。

如果成功，则响应类似如下示例：

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

如需查看可使用此命令更新的元数据的完整列表，请参阅命令参考页面。

客户端库

C++

如需了解详情，请参阅 Cloud Storage C++ API 参考文档。

如需向 Cloud Storage 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

namespace gcs = ::google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string const& bucket_name,
   std::string const& object_name, std::string const& key,
   std::string const& value) {
  StatusOr<gcs::ObjectMetadata> object_metadata =
      client.GetObjectMetadata(bucket_name, object_name);
  if (!object_metadata) throw std::move(object_metadata).status();

  gcs::ObjectMetadata desired = *object_metadata;
  desired.mutable_metadata().emplace(key, value);

  StatusOr<gcs::ObjectMetadata> updated =
      client.UpdateObject(bucket_name, object_name, desired,
                          gcs::Generation(object_metadata->generation()));

  if (!updated) throw std::move(updated).status();
  std::cout << "Object updated. The full metadata after the update is: "
            << *updated << "\n";
}

C#

如需了解详情，请参阅 Cloud Storage C# API 参考文档。

如需向 Cloud Storage 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 


using Google.Cloud.Storage.V1;
using System;
using System.Collections.Generic;

public class SetObjectMetadataSample
{
    public Google.Apis.Storage.v1.Data.Object SetObjectMetadata(
        string bucketName = "your-bucket-name",
        string objectName = "your-object-name",
        string key = "key-to-add",
        string value = "value-to-add")
    {
        var storage = StorageClient.Create();
        var file = storage.GetObject(bucketName, objectName);

        if (file.Metadata == null)
        {
            file.Metadata = new Dictionary<string, string>();
        }
        file.Metadata.Add(key, value);

        file = storage.UpdateObject(file);
        Console.WriteLine($"Updated custom metadata for object {objectName} in bucket {bucketName}");
        return file;
    }
}

Go

如需了解详情，请参阅 Cloud Storage Go API 参考文档。

如需向 Cloud Storage 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

import (
	"context"
	"fmt"
	"io"
	"time"

	"cloud.google.com/go/storage"
)

// setMetadata sets an object's metadata.
func setMetadata(w io.Writer, bucket, object string) error {
	// bucket := "bucket-name"
	// object := "object-name"
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("storage.NewClient: %w", err)
	}
	defer client.Close()

	ctx, cancel := context.WithTimeout(ctx, time.Second*10)
	defer cancel()

	o := client.Bucket(bucket).Object(object)

	// Optional: set a metageneration-match precondition to avoid potential race
	// conditions and data corruptions. The request to update is aborted if the
	// object's metageneration does not match your precondition.
	attrs, err := o.Attrs(ctx)
	if err != nil {
		return fmt.Errorf("object.Attrs: %w", err)
	}
	o = o.If(storage.Conditions{MetagenerationMatch: attrs.Metageneration})

	// Update the object to set the metadata.
	objectAttrsToUpdate := storage.ObjectAttrsToUpdate{
		Metadata: map[string]string{
			"keyToAddOrUpdate": "value",
		},
	}
	if _, err := o.Update(ctx, objectAttrsToUpdate); err != nil {
		return fmt.Errorf("ObjectHandle(%q).Update: %w", object, err)
	}
	fmt.Fprintf(w, "Updated custom metadata for object %v in bucket %v.\n", object, bucket)
	return nil
}

Node.js

如需了解详情，请参阅 Cloud Storage Node.js API 参考文档。

如需向 Cloud Storage 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

// Imports the Google Cloud client library
const {Storage} = require('@google-cloud/storage');

// Creates a client
const storage = new Storage();

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// The ID of your GCS bucket
// const bucketName = 'your-unique-bucket-name';

// The ID of your GCS file
// const fileName = 'your-file-name';

async function setFileMetadata() {
  // Optional: set a meta-generation-match precondition to avoid potential race
  // conditions and data corruptions. The request to set metadata is aborted if the
  // object's metageneration number does not match your precondition.
  const options = {
    ifMetagenerationMatch: metagenerationMatchPrecondition,
  };

  // Set file metadata.
  const [metadata] = await storage
    .bucket(bucketName)
    .file(fileName)
    .setMetadata(
      {
        // Predefined metadata for server e.g. 'cacheControl', 'contentDisposition',
        // 'contentEncoding', 'contentLanguage', 'contentType'
        contentDisposition:
          'attachment; filename*=utf-8\'\'"anotherImage.jpg"',
        contentType: 'image/jpeg',

        // A note or actionable items for user e.g. uniqueId, object description,
        // or other useful information.
        metadata: {
          description: 'file description...',
          modified: '1900-01-01',
        },
      },
      options
    );

  console.log(
    'Updated metadata for object',
    fileName,
    'in bucket ',
    bucketName
  );
  console.log(metadata);
}

setFileMetadata().catch(console.error);

PHP

如需了解详情，请参阅 Cloud Storage PHP API 参考文档。

如需向 Cloud Storage 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

use Google\Cloud\Storage\StorageClient;

/**
 * Set a metadata key and value on the specified object.
 *
 * @param string $bucketName The name of your Cloud Storage bucket.
 *        (e.g. 'my-bucket')
 * @param string $objectName The name of your Cloud Storage object.
 *        (e.g. 'my-object')
 */
function set_metadata(string $bucketName, string $objectName): void
{
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);
    $object = $bucket->object($objectName);
    $object->update([
        'metadata' => [
            'keyToAddOrUpdate' => 'value',
        ]
    ]);

    printf('Updated custom metadata for object %s in bucket %s', $objectName, $bucketName);
}

Python

如需了解详情，请参阅 Cloud Storage Python API 参考文档。

如需向 Cloud Storage 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

from google.cloud import storage


def set_blob_metadata(bucket_name, blob_name):
    """Set a blob's metadata."""
    # bucket_name = 'your-bucket-name'
    # blob_name = 'your-object-name'

    storage_client = storage.Client()
    bucket = storage_client.bucket(bucket_name)
    blob = bucket.get_blob(blob_name)
    metageneration_match_precondition = None

    # Optional: set a metageneration-match precondition to avoid potential race
    # conditions and data corruptions. The request to patch is aborted if the
    # object's metageneration does not match your precondition.
    metageneration_match_precondition = blob.metageneration

    metadata = {'color': 'Red', 'name': 'Test'}
    blob.metadata = metadata
    blob.patch(if_metageneration_match=metageneration_match_precondition)

    print(f"The metadata for the blob {blob.name} is {blob.metadata}")

Ruby

如需了解详情，请参阅 Cloud Storage Ruby API 参考文档。

如需向 Cloud Storage 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

def set_metadata bucket_name:, file_name:
  # The ID of your GCS bucket
  # bucket_name = "your-unique-bucket-name"

  # The ID of your GCS object
  # file_name = "your-file-name"

  require "google/cloud/storage"

  storage = Google::Cloud::Storage.new
  bucket  = storage.bucket bucket_name, skip_lookup: true
  file    = bucket.file file_name

  file.update do |file|
    # Fixed key file metadata
    file.content_type = "text/plain"

    # Custom file metadata
    file.metadata["your-metadata-key"] = "your-metadata-value"
  end

  puts "Metadata for #{file_name} has been updated."
end

Java

如需了解详情，请参阅 Cloud Storage Java API 参考文档。

如需向 Cloud Storage 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 


import com.google.cloud.storage.Blob;
import com.google.cloud.storage.BlobId;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;
import java.util.HashMap;
import java.util.Map;

public class SetObjectMetadata {
  public static void setObjectMetadata(String projectId, String bucketName, String objectName) {
    // 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";

    Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();
    Map<String, String> newMetadata = new HashMap<>();
    newMetadata.put("keyToAddOrUpdate", "value");
    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;
    }

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

    // Does an upsert operation, if the key already exists it's replaced by the new value, otherwise
    // it's added.
    blob.toBuilder().setMetadata(newMetadata).build().update(precondition);

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

REST API

JSON API

  1. 从 OAuth 2.0 Playground 获取授权访问令牌。将 Playground 配置为使用您自己的 OAuth 凭据。如需了解相关说明，请参阅 API 身份验证。

  2. 创建一个包含要修改的元数据的 JSON 文件。

    如需添加或修改固定键元数据（例如 contentType），请使用以下格式：

    {
  "STANDARD_METADATA_KEY": "STANDARD_METADATA_VALUE"
}

    其中：

    • STANDARD_METADATA_KEY 是您想要添加或修改的元数据的键，例如 Content-Type。
    • STANDARD_METADATA_VALUE 是您想要添加或修改的元数据的值，例如 image/png。

    如需添加或修改自定义元数据，请使用以下格式：

    {
  "metadata": {
    "CUSTOM_METADATA_KEY": "CUSTOM_METADATA_VALUE"
  }
}

    其中：

    • CUSTOM_METADATA_KEY 是您想要添加或修改的自定义元数据键，例如 dogbreed。
    • CUSTOM_METADATA_VALUE 是您要与自定义元数据键关联的值，例如 shibainu。

    如需删除自定义元数据条目，请使用以下格式：

    {
  "metadata": {
    "CUSTOM_METADATA_KEY": null
  }
}

    其中：

    • CUSTOM_METADATA_KEY 是您想要删除的自定义元数据的键，例如 dogbreed。

  3. 使用 cURL，通过 PATCH Object 请求调用 JSON API：

    curl -X PATCH --data-binary @JSON_FILE_NAME \
  -H "Authorization: Bearer OAUTH2_TOKEN" \
  -H "Content-Type: application/json" \
  "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME"

    其中：

    • JSON_FILE_NAME 是您在第 2 步中创建的文件的路径。
    • OAUTH2_TOKEN 是您在第 1 步中生成的访问令牌的名称。
    • BUCKET_NAME 是包含您要修改其元数据的对象的存储桶的名称，例如 my-bucket。
    • OBJECT_NAME 是要修改其元数据的对象的网址编码名称。例如，pets/dog.png 的网址编码为 pets%2Fdog.png。

请注意，您还可以使用 UPDATE Object 请求更改对象的元数据。使用此方法时，系统会从对象的元数据中移除请求中未明确指定的所有元数据。

XML API

使用 XML API 时，您只能在写入对象时（例如上传、移动或替换对象时）设置元数据。按照说明（比如上传对象）操作，并遵循以下准则：

  • 将 -H "METADATA_KEY:METADATA_VALUE" 添加到您所设置的每个元数据值的请求标头中，例如 -H "Content-Type:image/png"。

  • 在任何自定义元数据值前面加上 x-goog-meta- 前缀。自定义 "METADATA_KEY:METADATA_VALUE" 的一个示例是 "x-goog-meta-dogbreed:shibainu"。

如需了解详情，请参阅使用 XML 上传对象。

后续步骤