获取存储桶信息

转到概念

本页面介绍了如何获取 Cloud Storage 存储桶大小和元数据的相关信息。

前提条件

前提条件因所使用的工具而异：

控制台

如需使用 Google Cloud Console 完成本指南，您必须拥有适当的 IAM 权限。如果您没有创建要访问的存储桶，则可能需要项目所有者为您提供包含必要权限的角色。

如需查看特定操作所需权限的列表，请参阅 Google Cloud Console 的 IAM 权限。

如需查看相关角色的列表，请参阅 Cloud Storage 角色。或者，您也可以创建一个自定义角色，并为其提供具体受限的权限。

命令行

为使用命令行实用程序完成本指南，您必须拥有适当的 IAM 权限。如果您没有创建要访问的存储桶，则可能需要项目所有者为您提供包含必要权限的角色。

如需查看特定操作所需权限的列表，请参阅 gsutil 命令的 IAM 权限。

如需查看相关角色的列表，请参阅 Cloud Storage 角色。或者，您也可以创建一个自定义角色，并为其提供具体受限的权限。

代码示例

如需使用 Cloud Storage 客户端库完成本指南，您必须拥有适当的 IAM 权限。如果您没有创建要访问的存储桶，则可能需要项目所有者为您提供包含必要权限的角色。除非另有说明，否则客户端库请求通过 JSON API 发出。

如需查看特定操作所需的权限列表，请参阅 JSON 方法的 IAM 权限。

如需查看相关角色的列表，请参阅 Cloud Storage 角色。或者，您也可以创建一个自定义角色，并为其提供具体受限的权限。

REST API

JSON API

如需使用 JSON API 完成本指南，您必须拥有适当的 IAM 权限。如果您没有创建要访问的存储桶，则可能需要项目所有者为您提供包含必要权限的角色。

如需查看特定操作所需的权限列表，请参阅 JSON 方法的 IAM 权限。

如需查看相关角色的列表，请参阅 Cloud Storage 角色。或者，您也可以创建一个自定义角色，并为其提供具体受限的权限。

确定存储桶的大小

控制台

注意：Monitoring 每天测量一次存储桶大小，不会报告空存储桶。如需在给定时刻测量任何存储桶的大小，请改用 gsutil。

如需使用 Metrics Explorer 查看受监控资源的指标，请按照以下步骤操作：

1. 在 Google Cloud Console 中，转到 Monitoring 中的 Metrics Explorer 页面。

转到 Metrics Explorer

2. 在工具栏中，选择浏览器标签页。
3. 选择配置标签页。
4. 展开选择一个指标菜单，在过滤栏中输入 Total bytes，然后使用子菜单选择特定的资源类型和指标：
   1. 在活跃资源菜单中，选择 GCS 存储桶。
   2. 在活跃指标类别菜单中，选择存储空间。
   3. 在活跃指标菜单中，选择总字节数。
   4. 点击应用。
   此指标的完全限定名称为 storage.googleapis.com/storage/total_bytes。
5. 可选：如需配置数据的查看方式，请添加过滤条件并使用分组依据、聚合器和图表类型菜单。例如，您可以按资源或指标标签进行分组。如需了解详情，请参阅使用 Metrics Explorer 时选择指标。
6. 可选：更改图表设置：
   • 对于配额和每天报告一个样本的其他指标，请将时间范围设置为至少一周，并将绘制类型设置为堆积条形图。
   • 对于分布值指标，请将绘制类型设置为热图。

您还可以使用 Metrics Explorer 测量其他存储分区指标，例如 storage.googleapis.com/storage/object_count 和 storage.googleapis.com/storage/total_byte_seconds，这两个指标分别测量每日使用的对象数量和每日使用的存储空间。请参阅 Google Cloud 指标文档，了解可用指标的完整列表，并参阅指标、时间序列和资源，详细了解如何使用 Metrics Explorer。

命令行

注意：gsutil du 命令通过发出一系列对象列表请求来计算当前空间用量，这对于大型存储桶而言，可能需要很长时间。如果存储桶中有数十万或更多对象，或者您要监控存储桶大小随时间变化的情况，请改用 Monitoring，如“控制台”标签页中所述。

使用带有 -s 标志的 gsutil du 命令：

gsutil du -s gs://BUCKET_NAME

其中，BUCKET_NAME 为相关存储桶的名称。

响应如下例所示：

134620      gs://my-bucket

在此示例中，名为 my-bucket 的存储分区的大小为 134620 字节。

显示存储桶的元数据

控制台

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

   进入“存储桶”

2. （可选）：您可以通过点击列显示选项菜单 () 来限制 Google Cloud 控制台存储桶列表中显示的列。

3. 在存储分区列表中，找到您要验证的存储分区，然后检查其列标题以获取要查看的元数据。

命令行

使用以下 gsutil ls 命令：

gsutil ls -L -b gs://BUCKET_NAME

其中，BUCKET_NAME 为相关存储桶的名称。

响应如下例所示：

gs://my-bucket/ :
  Storage class:         STANDARD
  Location constraint:   US
  ...

代码示例

C++

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

在 GitHub 上查看 反馈

namespace gcs = ::google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string const& bucket_name) {
  StatusOr<gcs::BucketMetadata> bucket_metadata =
      client.GetBucketMetadata(bucket_name);

  if (!bucket_metadata) {
    throw std::runtime_error(bucket_metadata.status().message());
  }

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

C#

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

在 GitHub 上查看 反馈

using Google.Apis.Storage.v1.Data;
using Google.Cloud.Storage.V1;
using System;

public class GetBucketMetadataSample
{
    public Bucket GetBucketMetadata(string bucketName = "your-unique-bucket-name")
    {
        var storage = StorageClient.Create();
        var bucket = storage.GetBucket(bucketName, new GetBucketOptions { Projection = Projection.Full });
        Console.WriteLine($"Bucket:\t{bucket.Name}");
        Console.WriteLine($"Acl:\t{bucket.Acl}");
        Console.WriteLine($"Billing:\t{bucket.Billing}");
        Console.WriteLine($"Cors:\t{bucket.Cors}");
        Console.WriteLine($"DefaultEventBasedHold:\t{bucket.DefaultEventBasedHold}");
        Console.WriteLine($"DefaultObjectAcl:\t{bucket.DefaultObjectAcl}");
        Console.WriteLine($"Encryption:\t{bucket.Encryption}");
        if (bucket.Encryption != null)
        {
            Console.WriteLine($"KmsKeyName:\t{bucket.Encryption.DefaultKmsKeyName}");
        }
        Console.WriteLine($"Id:\t{bucket.Id}");
        Console.WriteLine($"Kind:\t{bucket.Kind}");
        Console.WriteLine($"Lifecycle:\t{bucket.Lifecycle}");
        Console.WriteLine($"Location:\t{bucket.Location}");
        Console.WriteLine($"LocationType:\t{bucket.LocationType}");
        Console.WriteLine($"Logging:\t{bucket.Logging}");
        Console.WriteLine($"Metageneration:\t{bucket.Metageneration}");
        Console.WriteLine($"Owner:\t{bucket.Owner}");
        Console.WriteLine($"ProjectNumber:\t{bucket.ProjectNumber}");
        Console.WriteLine($"RetentionPolicy:\t{bucket.RetentionPolicy}");
        Console.WriteLine($"SelfLink:\t{bucket.SelfLink}");
        Console.WriteLine($"StorageClass:\t{bucket.StorageClass}");
        Console.WriteLine($"TimeCreated:\t{bucket.TimeCreated}");
        Console.WriteLine($"Updated:\t{bucket.Updated}");
        Console.WriteLine($"Versioning:\t{bucket.Versioning}");
        Console.WriteLine($"Website:\t{bucket.Website}");
        Console.WriteLine($"TurboReplication:\t{bucket.Rpo}");
        if (bucket.Labels != null)
        {
            Console.WriteLine("Labels:");
            foreach (var label in bucket.Labels)
            {
                Console.WriteLine($"{label.Key}:\t{label.Value}");
            }
        }
        return bucket;
    }
}

Go

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

在 GitHub 上查看 反馈

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

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

// getBucketMetadata gets the bucket metadata.
func getBucketMetadata(w io.Writer, bucketName string) (*storage.BucketAttrs, error) {
	// bucketName := "bucket-name"
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		return nil, fmt.Errorf("storage.NewClient: %v", err)
	}
	defer client.Close()

	ctx, cancel := context.WithTimeout(ctx, time.Second*10)
	defer cancel()
	attrs, err := client.Bucket(bucketName).Attrs(ctx)
	if err != nil {
		return nil, fmt.Errorf("Bucket(%q).Attrs: %v", bucketName, err)
	}
	fmt.Fprintf(w, "BucketName: %v\n", attrs.Name)
	fmt.Fprintf(w, "Location: %v\n", attrs.Location)
	fmt.Fprintf(w, "LocationType: %v\n", attrs.LocationType)
	fmt.Fprintf(w, "StorageClass: %v\n", attrs.StorageClass)
	fmt.Fprintf(w, "Turbo replication (RPO): %v\n", attrs.RPO)
	fmt.Fprintf(w, "TimeCreated: %v\n", attrs.Created)
	fmt.Fprintf(w, "Metageneration: %v\n", attrs.MetaGeneration)
	fmt.Fprintf(w, "PredefinedACL: %v\n", attrs.PredefinedACL)
	if attrs.Encryption != nil {
		fmt.Fprintf(w, "DefaultKmsKeyName: %v\n", attrs.Encryption.DefaultKMSKeyName)
	}
	if attrs.Website != nil {
		fmt.Fprintf(w, "IndexPage: %v\n", attrs.Website.MainPageSuffix)
		fmt.Fprintf(w, "NotFoundPage: %v\n", attrs.Website.NotFoundPage)
	}
	fmt.Fprintf(w, "DefaultEventBasedHold: %v\n", attrs.DefaultEventBasedHold)
	if attrs.RetentionPolicy != nil {
		fmt.Fprintf(w, "RetentionEffectiveTime: %v\n", attrs.RetentionPolicy.EffectiveTime)
		fmt.Fprintf(w, "RetentionPeriod: %v\n", attrs.RetentionPolicy.RetentionPeriod)
		fmt.Fprintf(w, "RetentionPolicyIsLocked: %v\n", attrs.RetentionPolicy.IsLocked)
	}
	fmt.Fprintf(w, "RequesterPays: %v\n", attrs.RequesterPays)
	fmt.Fprintf(w, "VersioningEnabled: %v\n", attrs.VersioningEnabled)
	if attrs.Logging != nil {
		fmt.Fprintf(w, "LogBucket: %v\n", attrs.Logging.LogBucket)
		fmt.Fprintf(w, "LogObjectPrefix: %v\n", attrs.Logging.LogObjectPrefix)
	}
	if attrs.CORS != nil {
		fmt.Fprintln(w, "CORS:")
		for _, v := range attrs.CORS {
			fmt.Fprintf(w, "\tMaxAge: %v\n", v.MaxAge)
			fmt.Fprintf(w, "\tMethods: %v\n", v.Methods)
			fmt.Fprintf(w, "\tOrigins: %v\n", v.Origins)
			fmt.Fprintf(w, "\tResponseHeaders: %v\n", v.ResponseHeaders)
		}
	}
	if attrs.Labels != nil {
		fmt.Fprintf(w, "\n\n\nLabels:")
		for key, value := range attrs.Labels {
			fmt.Fprintf(w, "\t%v = %v\n", key, value)
		}
	}
	return attrs, nil
}

Java

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

在 GitHub 上查看 反馈

import com.google.cloud.storage.Bucket;
import com.google.cloud.storage.BucketInfo;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;
import java.util.Map;

public class GetBucketMetadata {
  public static void getBucketMetadata(String projectId, String bucketName) {
    // The ID of your GCP project
    // String projectId = "your-project-id";

    // The ID of your GCS bucket
    // String bucketName = "your-unique-bucket-name";

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

    // Select all fields. Fields can be selected individually e.g. Storage.BucketField.NAME
    Bucket bucket =
        storage.get(bucketName, Storage.BucketGetOption.fields(Storage.BucketField.values()));

    // Print bucket metadata
    System.out.println("BucketName: " + bucket.getName());
    System.out.println("DefaultEventBasedHold: " + bucket.getDefaultEventBasedHold());
    System.out.println("DefaultKmsKeyName: " + bucket.getDefaultKmsKeyName());
    System.out.println("Id: " + bucket.getGeneratedId());
    System.out.println("IndexPage: " + bucket.getIndexPage());
    System.out.println("Location: " + bucket.getLocation());
    System.out.println("LocationType: " + bucket.getLocationType());
    System.out.println("Metageneration: " + bucket.getMetageneration());
    System.out.println("NotFoundPage: " + bucket.getNotFoundPage());
    System.out.println("RetentionEffectiveTime: " + bucket.getRetentionEffectiveTime());
    System.out.println("RetentionPeriod: " + bucket.getRetentionPeriod());
    System.out.println("RetentionPolicyIsLocked: " + bucket.retentionPolicyIsLocked());
    System.out.println("RequesterPays: " + bucket.requesterPays());
    System.out.println("SelfLink: " + bucket.getSelfLink());
    System.out.println("StorageClass: " + bucket.getStorageClass().name());
    System.out.println("TimeCreated: " + bucket.getCreateTime());
    System.out.println("VersioningEnabled: " + bucket.versioningEnabled());
    if (bucket.getLabels() != null) {
      System.out.println("\n\n\nLabels:");
      for (Map.Entry<String, String> label : bucket.getLabels().entrySet()) {
        System.out.println(label.getKey() + "=" + label.getValue());
      }
    }
    if (bucket.getLifecycleRules() != null) {
      System.out.println("\n\n\nLifecycle Rules:");
      for (BucketInfo.LifecycleRule rule : bucket.getLifecycleRules()) {
        System.out.println(rule);
      }
    }
  }
}

Node.js

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

在 GitHub 上查看 反馈

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

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

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

  // Get Bucket Metadata
  const [metadata] = await storage.bucket(bucketName).getMetadata();

  console.log(JSON.stringify(metadata, null, 2));
}

PHP

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

在 GitHub 上查看 反馈

use Google\Cloud\Storage\StorageClient;

/**
 * Get bucket metadata.
 *
 * @param string $bucketName The name of your Cloud Storage bucket.
 *        (e.g. 'my-bucket')
 */
function get_bucket_metadata(string $bucketName): void
{
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);
    $info = $bucket->info();

    printf('Bucket Metadata: %s' . PHP_EOL, print_r($info));
}

Python

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

在 GitHub 上查看 反馈

from google.cloud import storage

def bucket_metadata(bucket_name):
    """Prints out a bucket's metadata."""
    # bucket_name = 'your-bucket-name'

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

    print(f"ID: {bucket.id}")
    print(f"Name: {bucket.name}")
    print(f"Storage Class: {bucket.storage_class}")
    print(f"Location: {bucket.location}")
    print(f"Location Type: {bucket.location_type}")
    print(f"Cors: {bucket.cors}")
    print(f"Default Event Based Hold: {bucket.default_event_based_hold}")
    print(f"Default KMS Key Name: {bucket.default_kms_key_name}")
    print(f"Metageneration: {bucket.metageneration}")
    print(
        f"Public Access Prevention: {bucket.iam_configuration.public_access_prevention}"
    )
    print(f"Retention Effective Time: {bucket.retention_policy_effective_time}")
    print(f"Retention Period: {bucket.retention_period}")
    print(f"Retention Policy Locked: {bucket.retention_policy_locked}")
    print(f"Requester Pays: {bucket.requester_pays}")
    print(f"Self Link: {bucket.self_link}")
    print(f"Time Created: {bucket.time_created}")
    print(f"Versioning Enabled: {bucket.versioning_enabled}")
    print(f"Labels: {bucket.labels}")

Ruby

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

在 GitHub 上查看 反馈

def get_bucket_metadata bucket_name:
  # The ID of your GCS bucket
  # bucket_name = "your-unique-bucket-name"

  require "google/cloud/storage"

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

  puts "ID:                       #{bucket.id}"
  puts "Name:                     #{bucket.name}"
  puts "Storage Class:            #{bucket.storage_class}"
  puts "Location:                 #{bucket.location}"
  puts "Location Type:            #{bucket.location_type}"
  puts "Cors:                     #{bucket.cors}"
  puts "Default Event Based Hold: #{bucket.default_event_based_hold?}"
  puts "Default KMS Key Name:     #{bucket.default_kms_key}"
  puts "Logging Bucket:           #{bucket.logging_bucket}"
  puts "Logging Prefix:           #{bucket.logging_prefix}"
  puts "Metageneration:           #{bucket.metageneration}"
  puts "Retention Effective Time: #{bucket.retention_effective_at}"
  puts "Retention Period:         #{bucket.retention_period}"
  puts "Retention Policy Locked:  #{bucket.retention_policy_locked?}"
  puts "Requester Pays:           #{bucket.requester_pays}"
  puts "Self Link:                #{bucket.api_url}"
  puts "Time Created:             #{bucket.created_at}"
  puts "Versioning Enabled:       #{bucket.versioning?}"
  puts "Index Page:               #{bucket.website_main}"
  puts "Not Found Page:           #{bucket.website_404}"
  puts "Labels:"
  bucket.labels.each do |key, value|
    puts " - #{key} = #{value}"
  end
  puts "Lifecycle Rules:"
  bucket.lifecycle.each do |rule|
    puts "#{rule.action} - #{rule.storage_class} - #{rule.age} - #{rule.matches_storage_class}"
  end
end

Terraform

您可以使用 Terraform 资源查看存储桶的元数据。

在 GitHub 上查看 反馈

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

output "bucket_metadata" {
  value = data.google_storage_bucket.default
}

REST API

JSON API

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

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

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

   其中：

   • OAUTH2_TOKEN 是您在第 1 步中生成的访问令牌的名称。
   • BUCKET_NAME 是相关存储桶的名称，例如 my-bucket。

3. 使用查询参数将搜索结果范围缩小至所需字段：

   curl -X GET \
   -H "Authorization: Bearer OAUTH2_TOKEN" \
   "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME?fields=FIELD1%2CFIELD2"

   其中 FIELD# 是要包含在搜索结果中的存储桶属性。例如，location 和 storageClass。

响应如下例所示：

{
  "location": "US",
  "storageClass": "STANDARD"
}

XML API

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

2. 使用 cURL，通过 GET Bucket 请求调用 XML API：

   curl -X GET \
   -H "Authorization: Bearer OAUTH2_TOKEN" \
   "https://storage.googleapis.com/BUCKET_NAME?QUERY_PARAMETER"

   其中：

   • OAUTH2_TOKEN 是您在第 1 步中生成的访问令牌的名称。
   • BUCKET_NAME 是相关存储桶的名称，例如 my-bucket。
   • QUERY_PARAMETER 是要返回的元数据字段。例如，location（用于获取存储桶的位置）。一次只能对 XML API 使用一个查询参数。

   响应类似如下示例：<LocationConstraint>US</LocationConstraint>。

后续步骤

• 阅读存储桶元数据概览。
• 列出存储桶中的对象。
• 更改存储桶的默认存储类别。
• 添加、移除和查看存储桶上的标签。
• 详细了解如何在 Monitoring 中监控资源。

自行试用

如果您是 Google Cloud 新手，请创建一个帐号来评估 Cloud Storage 在实际场景中的表现。新客户还可获享 $300 赠金，用于运行、测试和部署工作负载。

免费试用 Cloud Storage