使用双区域存储

概览

本页面介绍如何使用双区域存储。

所需的角色

为了获得创建双区域存储桶所需的权限，请让您的管理员向您授予项目的 Storage Admin (roles/storage.admin) IAM 角色。

此预定义角色包含创建双区域存储桶所需的权限。如需查看所需的确切权限，请展开所需权限部分：

所需权限

• storage.buckets.create
• storage.buckets.enableObjectRetention（仅当为存储桶启用对象保留配置时才需要）
• storage.buckets.list（仅当使用 Google Cloud 控制台创建存储桶时才需要）
• resourcemanager.projects.get（仅当使用 Google Cloud 控制台创建存储桶时才需要）

您也可以使用自定义角色或其他预定义角色来获取这些权限。要查看哪些角色与哪些权限相关联，请参阅适用于 Cloud Storage 的 IAM 角色。

如需了解如何授予项目角色，请参阅管理对项目的访问权限。

创建双区域存储桶

完成以下步骤以创建双区域存储桶：

控制台

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

   进入“存储桶”

2. 点击创建。

3. 在创建存储桶页面上，输入您的存储桶信息。如需转到下一步，请点击继续。

   1. 在指定存储桶的名称部分，输入符合存储桶命名要求的名称。

   2. 在选择数据存储位置部分，选择位置类型旁边的双区域。可选：您可以通过选中添加增强型复制功能复选框，将该功能与增强型复制功能结合使用。

   3. 对于位置，选择要使用的大洲和关联的区域。

   4. 在为数据选择一个默认存储类别部分，为存储桶选择一个存储类别。默认情况下，系统会为上传到存储桶的所有对象分配该默认存储类别。

      注意：右侧窗格中的每月费用估算面板会根据您选择的存储类别和位置以及您预期的数据大小和操作，估算存储桶的每月费用。

   5. 对于选择如何控制对象的访问权限，选择要使用的防止公开访问和访问权限控制选项。

   6. 对于选择如何保护对象数据，选择要使用的保护工具，例如对象版本控制、保留政策和加密方法。

4. 点击创建。

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

命令行

使用带有 --location 和 --placement 标志的 buckets create 命令。

gcloud storage buckets create gs://BUCKET_NAME --location=MULTI-REGION --placement=REGION_1,REGION_2

其中：

• BUCKET_NAME 是您正在创建的存储桶的名称。例如 my-bucket。

• MULTI-REGION 指定与底层区域关联的多区域代码。例如，在选择区域 ASIA-SOUTH1（孟买）和 ASIA-SOUTH2（德里）时，请使用 IN。

• REGION_1 指定存储桶所在区域的地理位置。例如 ASIA-EAST1。

• REGION_2 指定存储桶第二个区域的地理位置。例如 ASIA-SOUTHEAST1。

注意：如果创建 ASIA1、NAM4 或 EUR4 双区域，则不需要 --placement 选项和关联的区域值。

如果请求成功，该命令将返回以下消息：

Creating gs://BUCKET_NAME/...

如需查看使用 gcloud storage 创建存储桶时可用的选项的完整列表，请参阅 buckets create 选项。

客户端库

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& region_a, std::string const& region_b) {
  auto metadata = client.CreateBucket(
      bucket_name,
      gcs::BucketMetadata().set_custom_placement_config(
          gcs::BucketCustomPlacementConfig{{region_a, region_b}}));
  if (!metadata) throw std::move(metadata).status();

  std::cout << "Bucket " << metadata->name() << " created."
            << "\nFull Metadata: " << *metadata << "\n";
}

C#

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

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

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

public class CreateDualRegionBucketSample
{
    public Bucket CreateDualRegionBucket(
        string projectId = "your-project-id",
        string bucketName = "your-unique-bucket-name",
        string location = "your-location",
        string region1 = "your-region1-name",
        string region2 = "your-region2-name")
    {
        var client = StorageClient.Create();

        var bucket = new Bucket
        {
            Name = bucketName,
            Location = location,
            CustomPlacementConfig = new Bucket.CustomPlacementConfigData
            {
                DataLocations = new[] { region1, region2 }
            }
        };

        var storageBucket = client.CreateBucket(projectId, bucket);

        Console.WriteLine($"Created storage bucket {storageBucket.Name}" +
            $" in {storageBucket.Location}" +
            $" with location-type {storageBucket.LocationType} and" +
            $" dataLocations {string.Join(",", storageBucket.CustomPlacementConfig.DataLocations)}.");

        return storageBucket;
    }

}

Go

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

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

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

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

// createBucketDualRegion creates a new dual-region bucket in the project in the
// provided location and regions.
// See https://cloud.google.com/storage/docs/locations#location-dr for more information.
func createBucketDualRegion(w io.Writer, projectID, bucketName string) error {
	// projectID := "my-project-id"
	// bucketName := "bucket-name"
	location := "US"
	region1 := "US-EAST1"
	region2 := "US-WEST1"

	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*30)
	defer cancel()

	storageDualRegion := &storage.BucketAttrs{
		Location: location,
		CustomPlacementConfig: &storage.CustomPlacementConfig{
			DataLocations: []string{region1, region2},
		},
	}
	bucket := client.Bucket(bucketName)
	if err := bucket.Create(ctx, projectID, storageDualRegion); err != nil {
		return fmt.Errorf("Bucket(%q).Create: %w", bucketName, err)
	}

	attrs, err := bucket.Attrs(ctx)
	if err != nil {
		return fmt.Errorf("Bucket(%q).Attrs: %w", bucketName, err)
	}
	fmt.Fprintf(w, "Created bucket %v", bucketName)
	fmt.Fprintf(w, " - location: %v", attrs.Location)
	fmt.Fprintf(w, " - locationType: %v", attrs.LocationType)
	fmt.Fprintf(w, " - customPlacementConfig.dataLocations: %v", attrs.CustomPlacementConfig.DataLocations)
	return nil
}

Java

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

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

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

public class CreateBucketDualRegion {

  public static void createBucketDualRegion(
      String projectId,
      String bucketName,
      String location,
      String firstRegion,
      String secondRegion) {
    // The ID of your GCP project.
    // String projectId = "your-project-id";

    // The ID to give your GCS bucket.
    // String bucketName = "your-unique-bucket-name";

    // The location your dual regions will be located in.
    // String location = "US";

    // One of the regions the dual region bucket is to be created in.
    // String firstRegion = "US-EAST1";

    // The second region the dual region bucket is to be created in.
    // String secondRegion = "US-WEST1";

    // See this documentation for other valid locations and regions:
    // https://cloud.google.com/storage/docs/locations

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

    CustomPlacementConfig config =
        CustomPlacementConfig.newBuilder()
            .setDataLocations(Arrays.asList(firstRegion, secondRegion))
            .build();

    BucketInfo bucketInfo =
        BucketInfo.newBuilder(bucketName)
            .setLocation(location)
            .setCustomPlacementConfig(config)
            .build();

    Bucket bucket = storage.create(bucketInfo);

    System.out.println(
        "Created bucket "
            + bucket.getName()
            + " in location "
            + bucket.getLocation()
            + " with location type "
            + bucket.getLocationType()
            + " with Custom Placement Config "
            + bucket.getCustomPlacementConfig().toString());
  }
}

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 bucket's pair of regions. Case-insensitive.
// See this documentation for other valid locations:
// https://cloud.google.com/storage/docs/locations
// const location = 'US';
// const region1 = 'US-EAST1';
// const region2 = 'US-WEST1';

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

// Creates a client
// The bucket in the sample below will be created in the project associated with this client.
// For more information, please see https://cloud.google.com/docs/authentication/production or https://googleapis.dev/nodejs/storage/latest/Storage.html
const storage = new Storage();

async function createDualRegionBucket() {
  // For regions supporting dual-regions see: https://cloud.google.com/storage/docs/locations
  const [bucket] = await storage.createBucket(bucketName, {
    location,
    customPlacementConfig: {
      dataLocations: [region1, region2],
    },
  });

  console.log(`Created '${bucket.name}'`);
  console.log(`- location: '${bucket.metadata.location}'`);
  console.log(`- locationType: '${bucket.metadata.locationType}'`);
  console.log(
    `- customPlacementConfig: '${JSON.stringify(
      bucket.metadata.customPlacementConfig
    )}'`
  );
}

createDualRegionBucket().catch(console.error);

PHP

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

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

use Google\Cloud\Storage\StorageClient;

/**
 * Create a new bucket with a custom default storage class and location.
 *
 * @param string $bucketName The name of your Cloud Storage bucket.
 *        (e.g. 'my-bucket')
 * @param string $location Location for the bucket's regions. Case-insensitive.
 *        (e.g. 'US')
 * @param string $region1 First region for the bucket's regions. Case-insensitive.
 *        (e.g. 'US-EAST1')
 * @param string $region2 Second region for the bucket's regions. Case-insensitive.
 *        (e.g. 'US-WEST1')
 */
function create_bucket_dual_region(string $bucketName, string $location, string $region1, string $region2): void
{
    $storage = new StorageClient();
    $bucket = $storage->createBucket($bucketName, [
        'location' => $location,
        'customPlacementConfig' => [
            'dataLocations' => [$region1, $region2],
        ],
    ]);

    $info = $bucket->info();

    printf("Created '%s':", $bucket->name());
    printf("- location: '%s'", $info['location']);
    printf("- locationType: '%s'", $info['locationType']);
    printf("- customPlacementConfig: '%s'" . PHP_EOL, print_r($info['customPlacementConfig'], true));
}

Python

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

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

from google.cloud import storage


def create_bucket_dual_region(bucket_name, location, region_1, region_2):
    """Creates a Dual-Region Bucket with provided location and regions.."""
    # The ID of your GCS bucket
    # bucket_name = "your-bucket-name"

    # The bucket's pair of regions. Case-insensitive.
    # See this documentation for other valid locations:
    # https://cloud.google.com/storage/docs/locations
    # region_1 = "US-EAST1"
    # region_2 = "US-WEST1"
    # location = "US"

    storage_client = storage.Client()
    bucket = storage_client.create_bucket(bucket_name, location=location, data_locations=[region_1, region_2])

    print(f"Created bucket {bucket_name}")
    print(f" - location: {bucket.location}")
    print(f" - location_type: {bucket.location_type}")
    print(f" - customPlacementConfig data_locations: {bucket.data_locations}")

Ruby

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

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

# The ID of your GCS bucket
# bucket_name = "your-bucket-name"

# The bucket's pair of regions. Case-insensitive.
# See this documentation for other valid locations:
# https://cloud.google.com/storage/docs/locations
# region_1 = "US-EAST1"
# region_2 = "US-WEST1"

require "google/cloud/storage"

storage = Google::Cloud::Storage.new
bucket  = storage.create_bucket bucket_name,
                                custom_placement_config: { data_locations: [region_1, region_2] }

puts "Bucket #{bucket.name} created:"
puts "- location: #{bucket.location}"
puts "- location_type: #{bucket.location_type}"
puts "- custom_placement_config:"
puts "  - data_locations: #{bucket.data_locations}"

REST API

JSON API

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

2. 创建一个包含存储桶设置的 JSON 文件，其中必须包括 name 和 location。如需查看完整的设置列表，请参阅 Buckets:Insert 文档。以下是一些常用的设置，包括：

   {
     "name": "BUCKET_NAME",
     "location": "MULTI-REGION",
     "customPlacementConfig": {
       "dataLocations": ["REGION_1", "REGION_2"]
       },
     "storageClass": "STORAGE_CLASS"
   }

   其中：

   • BUCKET_NAME 是您要为自己的存储桶指定的名称（须遵循命名要求），例如 my-bucket。
   • MULTI-REGION 指定与底层区域关联的多区域代码。例如，在选择区域 ASIA-SOUTH1（孟买）和 ASIA-SOUTH2（德里）时，请使用 IN。
   • REGION_1 和 REGION_2 是您要存储自己存储桶的对象数据的区域。例如 ASIA-EAST1 和 ASIA-SOUTHEAST1。
   • STORAGE_CLASS 是您存储桶的存储类别，例如 STANDARD。
   注意：如果创建 ASIA1、NAM4 或 EUR4 双区域，则不需要 customPlacementConfig 字段和关联的 dataLocations 值。

3. 使用 cURL 调用 JSON API：

   curl -X POST --data-binary @JSON_FILE_NAME \
    -H "Authorization: Bearer OAUTH2_TOKEN" \
    -H "Content-Type: application/json" \
    "https://storage.googleapis.com/storage/v1/b?project=PROJECT_ID"

   其中：

   • JSON_FILE_NAME 是您在第 2 步中创建的 JSON 文件的名称。
   • OAUTH2_TOKEN 是您在第 1 步中生成的访问令牌。
   • PROJECT_ID 是将与您的存储桶相关联的项目的 ID，例如 my-project。

XML API

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

2. 创建一个包含以下信息的 XML 文件：

     <CreateBucketConfiguration>
        <LocationConstraint>MULTI-REGION</LocationConstraint>
           <CustomPlacementConfig>
              <DataLocations>
                 <DataLocation>REGION_1</DataLocation>
                 <DataLocation>REGION_2</DataLocation>
              </DataLocations>
           </CustomPlacementConfig>
        <StorageClass>STORAGE_CLASS</StorageClass>
     </CreateBucketConfiguration>
    

   其中：

   • MULTI-REGION 指定与底层区域关联的多区域代码。例如，在选择区域 ASIA-SOUTH1（孟买）和 ASIA-SOUTH2（德里）时，请使用 IN。
   • REGION_1 和 REGION_2 是您要存储自己存储桶的对象数据的区域。例如 ASIA-EAST1 和 ASIA-SOUTHEAST1。

   • STORAGE_CLASS 是您的存储桶的默认存储类别，例如 STANDARD。

     注意：如果创建 ASIA1、NAM4 或 EUR4 双区域，则不需要 customPlacementConfig 字段和关联的 dataLocations 值。

3. 使用 cURL 调用 XML API：

     curl -X PUT --data-binary @XML_FILE_NAME \
     -H "Authorization: Bearer OAUTH2_TOKEN" \
     -H "x-goog-project-id: PROJECT_ID" \
     "https://storage.googleapis.com/BUCKET_NAME"
   

   其中：

   • XML_FILE_NAME 是您在第 2 步中创建的 XML 文件的名称。
   • OAUTH2_TOKEN 是您在第 1 步中生成的访问令牌。
   • PROJECT_ID 是将与您的存储桶相关联的项目的 ID，例如 my-project。
   • BUCKET_NAME 是您要为自己的存储桶指定的名称（须遵循存储桶命名要求），例如 my-bucket。

   如果请求包含不受支持的区域，则系统会返回错误消息。如果请求成功，则系统不会返回响应。

后续步骤

• 详细了解增强型复制。
• 检索存储桶元数据，包括双区域存储桶使用的区域配对。
• 详细了解增强型复制价格或查看价格示例。