建立及管理執行個體區隔

預先發布版 — Geo-partitioning

這項功能適用《服務專屬條款》中「一般服務條款」一節的《正式發布前產品條款》。 正式發布前的功能是按照「原樣」提供，支援範圍可能有限。 詳情請參閱推出階段說明。

注意：這項功能適用於 Spanner Enterprise Plus 版本。詳情請參閱 Spanner 版本總覽。

本頁說明如何建立及管理 Spanner 執行個體分割區。

事前準備

如要使用執行個體分區，您必須在空白資料庫中設定 opt_in_dataplacement_preview 資料庫選項：

主控台

1. 前往 Google Cloud 控制台的「Instances」(執行個體) 頁面。

   執行個體

2. 選取要新增執行個體分割區的執行個體。

3. 選取要分割資料的空白資料庫。

4. 在導覽選單中，按一下「Spanner Studio」。

5. 在「Spanner Studio」頁面中，按一下 「New tab」(新增分頁)，或使用空白的編輯器分頁。

6. 輸入下列 ALTER DATABASE DDL 陳述式。

   GoogleSQL

   ALTER DATABASE DATABASE_ID SET OPTIONS (opt_in_dataplacement_preview = true);
   

   將 DATABASE_ID 替換為資料庫的專屬 ID。

   PostgreSQL

   ALTER DATABASE DATABASE_ID SET "spanner.opt_in_dataplacement_preview" = TRUE;
   

   將 DATABASE_ID 替換為資料庫的專屬 ID。

7. 按一下「執行」。

gcloud

如要設定 opt_in_dataplacement_preview 資料庫選項，請使用 gcloud spanner databases ddl update。

GoogleSQL

gcloud spanner databases ddl update DATABASE_ID \
  --instance=INSTANCE_ID \
  --ddl="ALTER DATABASE DATABASE_ID SET OPTIONS (opt_in_dataplacement_preview = true);"

更改下列內容：

• DATABASE_ID：Spanner 資料庫的永久 ID。
• INSTANCE_ID：Spanner 執行個體的永久 ID。

PostgreSQL

gcloud spanner databases ddl update DATABASE_ID \
  --instance=INSTANCE_ID \
  --ddl="ALTER DATABASE DATABASE_ID SET "spanner.opt_in_dataplacement_preview" = TRUE"

更改下列內容：

• DATABASE_ID：Spanner 資料庫的永久 ID。
• INSTANCE_ID：Spanner 執行個體的永久 ID。

建立執行個體分區

控制台

1. 在 Google Cloud 控制台中，開啟「Spanner」頁面。

   前往 Spanner

2. 選取要新增執行個體分割區的執行個體。

3. 在導覽選單中，選取「執行個體分割區」。

4. 按一下「建立執行個體分割區」。

5. 輸入分區 ID，永久識別執行個體分區。執行個體分割區 ID 在Google Cloud 專案中也不得重複。執行個體分割區 ID 設定後即無法變更。

6. 在「選擇設定」部分，選取「區域」或「多區域」。如要比較各區域的規格，請按一下「比較區域設定」。

7. 從下拉式選單中選取設定。

8. 在「Allocate compute capacity」(配置運算容量) 部分的「Unit」(單位) 下方，點選下列其中一個選項：

   • 小型執行個體分區的處理單元。
   • 大型執行個體的「Nodes」(節點)。一個節點等於 1,000 個處理單元。

9. 輸入所選單位的數值。

   執行個體分割區必須至少有一個節點或 1,000 個處理單元。

10. 按一下「建立」，建立執行個體分割區。

gcloud

如要建立執行個體分區，請使用 gcloud beta spanner instance-partitions create。

gcloud beta spanner instance-partitions create INSTANCE_PARTITION_ID \
  --config=INSTANCE_PARTITION_CONFIG \
  --description="INSTANCE_PARTITION_DESCRIPTION" \
  --instance=INSTANCE_ID \
  [--nodes=NODE_COUNT | --processing-units=PROCESSING_UNIT_COUNT]

更改下列內容：

• INSTANCE_PARTITION_ID：永久執行個體分割區 ID，在 Google Cloud 專案中是唯一的。執行個體分割區 ID 設定後即無法變更。
• INSTANCE_PARTITION_CONFIG：執行個體分割區設定的永久 ID，可定義執行個體分割區的地理位置，並影響資料儲存位置。
• INSTANCE_PARTITION_DESCRIPTION：要在 Google Cloud 控制台中顯示的執行個體分割區名稱。執行個體分割區名稱在 Google Cloud 專案中不得重複。
• INSTANCE_ID：Spanner 執行個體的永久 ID，這個執行個體分區位於該執行個體中。
• NODE_COUNT：執行個體分區的運算能力，以節點數量表示。一個節點等於 1000 個處理單元。
• PROCESSING_UNIT_COUNT：執行個體的運算資源，以處理單元數量表示。執行個體分割區必須至少有 1000 個處理單元。輸入數量時，請以 1000 為單位 (1000、2000、3000 等)。

舉例來說，如要在 eur3 中建立 5 個節點的執行個體分區 europe-partition，請執行下列指令：

  gcloud beta spanner instance-partitions create europe-partition --config=eur3 \
    --description="europe-partition" --instance=test-instance --nodes=5

用戶端程式庫

C++

如要瞭解如何安裝及使用 Spanner 的用戶端程式庫，請參閱「Spanner 用戶端程式庫」。

void CreateInstancePartition(
    google::cloud::spanner_admin::InstanceAdminClient client,
    std::string const& project_id, std::string const& instance_id,
    std::string const& instance_partition_id) {
  auto project = google::cloud::Project(project_id);
  auto in = google::cloud::spanner::Instance(project_id, instance_id);
  auto config = project.FullName() + "/instanceConfigs/nam3";

  google::spanner::admin::instance::v1::CreateInstancePartitionRequest request;
  request.set_parent(in.FullName());
  request.set_instance_partition_id(instance_partition_id);
  request.mutable_instance_partition()->set_display_name(
      "Test instance partition");
  request.mutable_instance_partition()->set_node_count(1);
  request.mutable_instance_partition()->set_config(config);

  auto instance_partition = client.CreateInstancePartition(request).get();
  if (!instance_partition) throw std::move(instance_partition).status();
  std::cout << "Created instance partition [" << instance_partition_id << "]:\n"
            << instance_partition->DebugString();
}

C#

如要瞭解如何安裝及使用 Spanner 的用戶端程式庫，請參閱「Spanner 用戶端程式庫」。

using Google.Cloud.Spanner.Admin.Instance.V1;
using Google.Cloud.Spanner.Common.V1;
using Google.LongRunning;
using System;

public class CreateInstancePartitionSample
{
    public InstancePartition CreateInstancePartition(string projectId, string instanceId, string instancePartitionId)
    {
        // Create the InstanceAdminClient instance.
        InstanceAdminClient instanceAdminClient = InstanceAdminClient.Create();

        // Initialize request parameters.
        InstancePartition partition = new InstancePartition
        {
            DisplayName = "This is a display name.",
            NodeCount = 1,
            ConfigAsInstanceConfigName = InstanceConfigName.FromProjectInstanceConfig(projectId, "nam3"),
        };
        InstanceName instanceName = InstanceName.FromProjectInstance(projectId, instanceId);

        // Make the CreateInstancePartition request.
        Operation<InstancePartition, CreateInstancePartitionMetadata> response = instanceAdminClient.CreateInstancePartition(instanceName, partition, instancePartitionId);

        Console.WriteLine("Waiting for the operation to finish.");

        // Poll until the returned long-running operation is complete.
        Operation<InstancePartition, CreateInstancePartitionMetadata> completedResponse = response.PollUntilCompleted();

        if (completedResponse.IsFaulted)
        {
            Console.WriteLine($"Error while creating instance partition: {completedResponse.Exception}");
            throw completedResponse.Exception;
        }

        Console.WriteLine($"Instance created successfully.");

        return completedResponse.Result;
    }
}

Go

如要瞭解如何安裝及使用 Spanner 的用戶端程式庫，請參閱「Spanner 用戶端程式庫」。

import (
	"context"
	"fmt"
	"io"

	instance "cloud.google.com/go/spanner/admin/instance/apiv1"
	"cloud.google.com/go/spanner/admin/instance/apiv1/instancepb"
)

// Example of creating an instance partition with Go.
// projectID is the ID of the project that the new instance partition will be in.
// instanceID is the ID of the instance that the new instance partition will be in.
// instancePartitionID is the ID of the new instance partition to be created.
func createInstancePartition(w io.Writer, projectID, instanceID, instancePartitionID string) error {
	// projectID := "my-project-id"
	// instanceID := "my-instance"
	// instancePartitionID := "my-instance-partition"
	ctx := context.Background()
	instanceAdmin, err := instance.NewInstanceAdminClient(ctx)
	if err != nil {
		return err
	}
	defer instanceAdmin.Close()

	op, err := instanceAdmin.CreateInstancePartition(ctx, &instancepb.CreateInstancePartitionRequest{
		Parent:              fmt.Sprintf("projects/%s/instances/%s", projectID, instanceID),
		InstancePartitionId: instancePartitionID,
		InstancePartition: &instancepb.InstancePartition{
			Config:          fmt.Sprintf("projects/%s/instanceConfigs/%s", projectID, "nam3"),
			DisplayName:     "my-instance-partition",
			ComputeCapacity: &instancepb.InstancePartition_NodeCount{NodeCount: 1},
		},
	})
	if err != nil {
		return fmt.Errorf("could not create instance partition %s: %w", fmt.Sprintf("projects/%s/instances/%s/instancePartitions/%s", projectID, instanceID, instancePartitionID), err)
	}
	// Wait for the instance partition creation to finish.
	i, err := op.Wait(ctx)
	if err != nil {
		return fmt.Errorf("waiting for instance partition creation to finish failed: %w", err)
	}
	// The instance partition may not be ready to serve yet.
	if i.State != instancepb.InstancePartition_READY {
		fmt.Fprintf(w, "instance partition state is not READY yet. Got state %v\n", i.State)
	}
	fmt.Fprintf(w, "Created instance partition [%s]\n", instancePartitionID)
	return nil
}

Java

如要瞭解如何安裝及使用 Spanner 的用戶端程式庫，請參閱「Spanner 用戶端程式庫」。

import com.google.cloud.spanner.Spanner;
import com.google.cloud.spanner.SpannerOptions;
import com.google.cloud.spanner.admin.instance.v1.InstanceAdminClient;
import com.google.spanner.admin.instance.v1.CreateInstancePartitionRequest;
import com.google.spanner.admin.instance.v1.InstanceConfigName;
import com.google.spanner.admin.instance.v1.InstanceName;
import com.google.spanner.admin.instance.v1.InstancePartition;
import java.util.concurrent.ExecutionException;

class CreateInstancePartitionSample {

  static void createInstancePartition() {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "my-project";
    String instanceId = "my-instance";
    String instancePartitionId = "my-instance-partition";
    createInstancePartition(projectId, instanceId, instancePartitionId);
  }

  static void createInstancePartition(
      String projectId, String instanceId, String instancePartitionId) {
    // Set instance partition configuration.
    int nodeCount = 1;
    String displayName = "Descriptive name";

    // Create an InstancePartition object that will be used to create the instance partition.
    InstancePartition instancePartition =
        InstancePartition.newBuilder()
            .setDisplayName(displayName)
            .setNodeCount(nodeCount)
            .setConfig(InstanceConfigName.of(projectId, "nam3").toString())
            .build();

    try (Spanner spanner =
            SpannerOptions.newBuilder().setProjectId(projectId).build().getService();
        InstanceAdminClient instanceAdminClient = spanner.createInstanceAdminClient()) {

      // Wait for the createInstancePartition operation to finish.
      InstancePartition createdInstancePartition =
          instanceAdminClient
              .createInstancePartitionAsync(
                  CreateInstancePartitionRequest.newBuilder()
                      .setParent(InstanceName.of(projectId, instanceId).toString())
                      .setInstancePartitionId(instancePartitionId)
                      .setInstancePartition(instancePartition)
                      .build())
              .get();
      System.out.printf(
          "Instance partition %s was successfully created%n", createdInstancePartition.getName());
    } catch (ExecutionException e) {
      System.out.printf(
          "Error: Creating instance partition %s failed with error message %s%n",
          instancePartition.getName(), e.getMessage());
    } catch (InterruptedException e) {
      System.out.println(
          "Error: Waiting for createInstancePartition operation to finish was interrupted");
    }
  }
}

Node.js

如要瞭解如何安裝及使用 Spanner 的用戶端程式庫，請參閱「Spanner 用戶端程式庫」。

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

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// const projectId = 'my-project-id';
// const instanceId = 'my-instance';
// const instancePartitionId = 'my-instance-partition';

// Creates a client
const spanner = new Spanner({
  projectId: projectId,
});

// Get the instance admin client
const instanceAdminClient = spanner.getInstanceAdminClient();

// Creates a new instance partition
try {
  console.log(
    `Creating instance partition ${instanceAdminClient.instancePartitionPath(
      projectId,
      instanceId,
      instancePartitionId,
    )}.`,
  );
  const [operation] = await instanceAdminClient.createInstancePartition({
    instancePartitionId: instancePartitionId,
    parent: instanceAdminClient.instancePath(projectId, instanceId),
    instancePartition: {
      config: instanceAdminClient.instanceConfigPath(projectId, 'nam3'),
      nodeCount: 1,
      displayName: 'Test instance partition',
    },
  });

  console.log(
    `Waiting for operation on ${instancePartitionId} to complete...`,
  );
  await operation.promise();

  console.log(`Created instance partition ${instancePartitionId}.`);
} catch (err) {
  console.error('ERROR:', err);
}

PHP

如要瞭解如何安裝及使用 Spanner 的用戶端程式庫，請參閱「Spanner 用戶端程式庫」。

use Google\Cloud\Spanner\Admin\Instance\V1\Client\InstanceAdminClient;
use Google\Cloud\Spanner\Admin\Instance\V1\CreateInstancePartitionRequest;
use Google\Cloud\Spanner\Admin\Instance\V1\InstancePartition;

/**
 * Creates an instance partition.
 * Example:
 * ```
 * create_instance_partition($projectId, $instanceId, $instancePartitionId);
 * ```
 *
 * @param string $projectId The Google Cloud project ID.
 * @param string $instanceId The Spanner instance ID.
 * @param string $instancePartitionId The instance partition ID.
 */
function create_instance_partition(string $projectId, string $instanceId, string $instancePartitionId): void
{
    $instanceAdminClient = new InstanceAdminClient();

    $instanceName = $instanceAdminClient->instanceName($projectId, $instanceId);
    $instancePartitionName = $instanceAdminClient->instancePartitionName($projectId, $instanceId, $instancePartitionId);
    $configName = $instanceAdminClient->instanceConfigName($projectId, 'nam3');

    $instancePartition = (new InstancePartition())
        ->setConfig($configName)
        ->setDisplayName('Test instance partition.')
        ->setNodeCount(1);

    $operation = $instanceAdminClient->createInstancePartition(
        (new CreateInstancePartitionRequest())
        ->setParent($instanceName)
        ->setInstancePartitionId($instancePartitionId)
        ->setInstancePartition($instancePartition)
    );

    print('Waiting for operation to complete...' . PHP_EOL);
    $operation->pollUntilComplete();

    printf('Created instance partition %s' . PHP_EOL, $instancePartitionId);
}

Python

如要瞭解如何安裝及使用 Spanner 的用戶端程式庫，請參閱「Spanner 用戶端程式庫」。

def create_instance_partition(instance_id, instance_partition_id):
    """Creates an instance partition."""
    from google.cloud.spanner_admin_instance_v1.types import spanner_instance_admin

    spanner_client = spanner.Client()
    instance_admin_api = spanner_client.instance_admin_api

    config_name = "{}/instanceConfigs/nam3".format(spanner_client.project_name)

    operation = spanner_client.instance_admin_api.create_instance_partition(
        parent=instance_admin_api.instance_path(spanner_client.project, instance_id),
        instance_partition_id=instance_partition_id,
        instance_partition=spanner_instance_admin.InstancePartition(
            config=config_name,
            display_name="Test instance partition",
            node_count=1,
        ),
    )

    print("Waiting for operation to complete...")
    operation.result(OPERATION_TIMEOUT_SECONDS)

    print("Created instance partition {}".format(instance_partition_id))

說明執行個體分區

gcloud

如要說明執行個體分區，請使用 gcloud beta spanner instance-partitions describe。

gcloud beta spanner instance-partitions describe PARTITION_ID \
  --instance=INSTANCE_ID

更改下列內容：

• INSTANCE_PARTITION_ID：執行個體分區的永久 ID。
• INSTANCE_ID：執行個體的永久 ID。

舉例來說，如要說明執行個體分區 europe-partition，請執行下列指令：

  gcloud beta spanner instance-partitions describe europe-partition
    --instance=test-instance

列出執行個體分區

控制台

1. 在 Google Cloud 控制台中，開啟「Spanner」頁面。

   前往 Spanner

2. 從清單中選取執行個體。

3. 在導覽選單中，選取「執行個體分割區」。

   系統會顯示與該執行個體相關聯的執行個體分割區清單。

gcloud

如要列出執行個體分割區，請使用 gcloud beta spanner instance-partitions list。

gcloud beta spanner instance-partitions list --instance=INSTANCE_ID

gcloud CLI 會顯示 Spanner 執行個體分區清單，以及每個執行個體分區的 ID、顯示名稱、設定和運算容量。

編輯執行個體分區

下節說明如何變更執行個體分區的運算容量。您無法變更執行個體分割區 ID、名稱或設定。

變更運算能力

您必須佈建足夠的運算資源，讓 CPU 使用率和儲存空間使用率低於建議最大值。詳情請參閱 Spanner 的配額與限制。

如要增加執行個體分區的運算資源，您的Google Cloud 專案必須有足夠的配額，才能增加運算資源。增加要求完成所需的時間取決於要求的大小。在大多數情況下，要求會在幾分鐘內完成。在極少數情況下，擴充作業最多可能需要一小時才能完成。

控制台

1. 在 Google Cloud 控制台中，開啟「Spanner」頁面。

   前往 Spanner

2. 從清單中選取執行個體。

3. 在導覽選單中，選取「執行個體分割區」。

4. 在執行個體分割區清單的「動作」欄下方，按一下「更多動作」，然後選取「編輯」。

5. 選擇測量單位 (處理單元或節點)，然後輸入數量，即可變更運算資源。使用處理單元時，請輸入 1,000 的倍數 (1,000、2,000、3,000 等)。每個節點等於 1000 個處理單元。

   執行個體分割區必須至少有一個節點 (1,000 個處理單元)。

6. 按一下 [儲存]。

   如果出現對話方塊，指出您的配額不足，無法新增運算容量，請按照操作說明申請更多配額。

gcloud

如要變更執行個體分區的運算能力，請使用 gcloud beta spanner instance-partitions update。使用這項指令時，請以節點或處理單元數量指定運算資源。

gcloud beta spanner instance-partitions update INSTANCE_PARTITION_ID \
  --instance=INSTANCE_ID \
  [--nodes=NODE_COUNT | --processing-units=PROCESSING_UNIT_COUNT]
  [--async]

更改下列內容：

• INSTANCE_PARTITION_ID：執行個體分區的永久 ID。
• INSTANCE_ID：執行個體的永久 ID。
• NODE_COUNT：執行個體分區的新運算能力，以節點數量表示。一個節點等於 1000 個處理單元。
• PROCESSING_UNIT_COUNT：執行個體分區的新運算能力，以處理單元數量表示。執行個體分割區必須至少有 1000 個處理單元。請輸入 1000 的倍數 (1000、2000、3000 等)。

選用標記：

• --async：如要讓要求立即傳回，不必等待進行中的作業完成，請使用這個旗標。

您可以執行 gcloud spanner operations describe，查看要求狀態。

刪除執行個體分區

執行個體分區與任何放置位置或資料相關聯時，您無法刪除該分區。如要刪除執行個體分區，請務必先移動執行個體分區中的所有資料，或刪除使用執行個體分區的刊登位置資料表。

控制台

1. 在 Google Cloud 控制台中，開啟「Spanner」頁面。

   前往 Spanner

2. 從清單中選取執行個體。

3. 在導覽選單中，選取「執行個體分割區」。

4. 在執行個體分割區清單中，按一下「動作」欄下方的「更多動作」，然後選取「刪除」。

5. 請按照操作說明來確認您要刪除的執行個體分割區。

6. 點選「刪除」。

gcloud

使用 gcloud beta spanner instance-partitions delete 指令。

gcloud beta spanner instance-partitions delete INSTANCE_PARTITION_ID
  --instance=INSTANCE_ID

後續步驟

• 瞭解如何建立及管理刊登位置表格和鍵。