Crie e faça a gestão de partições de instâncias

Pré-visualização — Geo-partitioning

Esta funcionalidade está sujeita aos "Termos das Ofertas de Pré-DG" na secção Termos Gerais de Serviço dos Termos Específicos do Serviço. As funcionalidades de pré-DG estão disponíveis "tal como estão" e podem ter apoio técnico limitado. Para mais informações, consulte as descrições das fases de lançamento.

Nota: esta funcionalidade está disponível na edição Spanner Enterprise Plus. Para mais informações, consulte a Vista geral das edições do Spanner.

Esta página descreve como criar e gerir partições de instâncias do Spanner.

Crie uma partição de instância

Consola

1. Na Google Cloud consola, abra a página Spanner.

   Aceda ao Spanner

2. Selecione a instância na qual quer adicionar partições de instâncias.

3. No menu de navegação, selecione Partições de instâncias.

4. Clique em Criar partição de instância.

5. Introduza um ID de partição para identificar permanentemente a partição da instância. O ID da partição da instância também tem de ser exclusivo no seu Google Cloud projeto. Não pode alterar o ID da partição da instância posteriormente.

6. Na secção Escolha uma configuração, selecione Regional ou Multirregional. Em alternativa, se quiser comparar as especificações entre as regiões, clique em Comparar configurações de regiões.

7. Selecione uma configuração no menu pendente.

8. Na secção Atribuir capacidade de computação, em Unidade, clique numa das seguintes opções:

   • Unidades de processamento para partições de instâncias pequenas.
   • Nós para instâncias grandes. Um nó tem 1000 unidades de processamento.

9. Introduza um valor para a unidade selecionada.

   A partição da instância tem de ter, pelo menos, um nó ou 1000 unidades de processamento.

10. Clique em Criar para criar a partição de instância.

gcloud

Para criar uma partição de instância, use 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]

Substitua o seguinte:

• INSTANCE_PARTITION_ID: o identificador da partição da instância permanente que é exclusivo no seu projeto do Google Cloud . Não pode alterar o ID da partição da instância mais tarde.
• INSTANCE_PARTITION_CONFIG: o identificador permanente da configuração da partição da instância, que define a localização geográfica da partição da instância e afeta o local onde os dados são armazenados.
• INSTANCE_PARTITION_DESCRIPTION: o nome a apresentar para a partição de instância na consola Google Cloud . O nome da partição da instância tem de ser exclusivo no seu Google Cloud projeto.
• INSTANCE_ID: o identificador permanente da sua instância do Spanner onde reside esta partição de instância.
• NODE_COUNT: a capacidade de computação da partição da instância, expressa como um número de nós. Um nó equivale a 1000 unidades de processamento.
• PROCESSING_UNIT_COUNT: a capacidade de computação da instância, expressa como um número de unidades de processamento. A partição da instância tem de ter, pelo menos, 1000 unidades de processamento. Introduza quantidades em múltiplos de 1000 (1000, 2000, 3000 e assim sucessivamente).

Por exemplo, para criar uma partição de instância europe-partition em eur3 com 5 nós, execute o seguinte:

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

Bibliotecas cliente

C++

Para saber como instalar e usar a biblioteca cliente do Spanner, consulte o artigo Bibliotecas cliente do 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#

Para saber como instalar e usar a biblioteca cliente do Spanner, consulte o artigo Bibliotecas cliente do 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

Para saber como instalar e usar a biblioteca cliente do Spanner, consulte o artigo Bibliotecas cliente do 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

Para saber como instalar e usar a biblioteca cliente do Spanner, consulte o artigo Bibliotecas cliente do 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

Para saber como instalar e usar a biblioteca cliente do Spanner, consulte o artigo Bibliotecas cliente do 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

Para saber como instalar e usar a biblioteca cliente do Spanner, consulte o artigo Bibliotecas cliente do 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

Para saber como instalar e usar a biblioteca cliente do Spanner, consulte o artigo Bibliotecas cliente do 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))

Descreva uma partição de instância

gcloud

Para descrever uma partição de instância, use gcloud beta spanner instance-partitions describe.

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

Substitua o seguinte:

• INSTANCE_PARTITION_ID: o identificador permanente da partição de instância.
• INSTANCE_ID: o identificador permanente da instância.

Por exemplo, para descrever a partição de instância europe-partition, execute o seguinte:

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

Apresentar partições de instâncias

Consola

1. Na Google Cloud consola, abra a página Spanner.

   Aceda ao Spanner

2. Selecione uma instância na lista.

3. No menu de navegação, selecione Partições de instâncias.

   É apresentada uma lista de partições de instâncias associadas a essa instância.

gcloud

Para listar as partições da instância, use gcloud beta spanner instance-partitions list.

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

A CLI gcloud imprime uma lista das partições de instância do Spanner, juntamente com o ID, o nome a apresentar, a configuração e a capacidade de computação de cada partição de instância.

Edite uma partição de instância

A secção seguinte explica como alterar a capacidade de computação da partição da instância. Não pode alterar o ID, o nome nem a configuração da partição da instância.

Altere a capacidade de computação

Tem de aprovisionar capacidade de computação suficiente para manter a utilização da CPU e a utilização de armazenamento abaixo dos máximos recomendados. Para mais informações, consulte as quotas e os limites do Spanner.

Se quiser aumentar a capacidade de computação de uma partição de instância, o seu Google Cloud projeto tem de ter quota suficiente para adicionar a capacidade de computação. O tempo necessário para concluir o pedido de aumento depende do tamanho do pedido. Na maioria dos casos, os pedidos são concluídos em poucos minutos. Em casos raros, o aumento da escala pode demorar até uma hora a ser concluído.

Consola

1. Na Google Cloud consola, abra a página Spanner.

   Aceda ao Spanner

2. Selecione uma instância na lista.

3. No menu de navegação, selecione Partições de instâncias.

4. Na lista de partições de instâncias, na coluna Ações, clique em Mais ações e selecione Editar.

5. Altere a capacidade de computação escolhendo uma unidade de medida (unidades de processamento ou nós) e, em seguida, introduzindo uma quantidade. Quando usar unidades de processamento, introduza quantidades em múltiplos de 1000 (1000, 2000, 3000 e assim sucessivamente). Cada nó é igual a 1000 unidades de processamento.

   A partição da instância tem de ter, pelo menos, um nó (1000 unidades de processamento).

6. Clique em Guardar.

   Se vir uma caixa de diálogo a indicar que tem uma quota insuficiente para adicionar capacidade de computação , siga as instruções para pedir uma quota mais elevada.

gcloud

Para alterar a capacidade de computação da partição da instância, use gcloud beta spanner instance-partitions update. Quando usar este comando, especifique a capacidade de computação como um número de nós ou unidades de processamento.

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

Substitua o seguinte:

• INSTANCE_PARTITION_ID: o identificador permanente da partição de instância.
• INSTANCE_ID: o identificador permanente da instância.
• NODE_COUNT: a nova capacidade de computação da partição da instância, expressa como um número de nós. Um nó equivale a 1000 unidades de processamento.
• PROCESSING_UNIT_COUNT: a nova capacidade de computação da partição da instância, expressa como um número de unidades de processamento. A partição da instância tem de ter, pelo menos, 1000 unidades de processamento. Introduza quantidades em múltiplos de 1000 (1000, 2000, 3000 e assim sucessivamente).

Sinalizadores opcionais:

• --async: Use esta flag se quiser que o seu pedido seja devolvido imediatamente, sem aguardar a conclusão da operação em curso.

Pode verificar o estado da sua solicitação executando o comando gcloud spanner operations describe.

Elimine uma partição de instância

Não pode eliminar uma partição de instância enquanto estiver associada a posicionamentos ou dados. Primeiro, tem de mover todos os dados que se encontram na partição da instância ou eliminar as tabelas de posicionamento que usam a partição da instância antes de poder eliminar a partição da instância.

Consola

1. Na Google Cloud consola, abra a página Spanner.

   Aceda ao Spanner

2. Selecione uma instância na lista.

3. No menu de navegação, selecione Partições de instâncias.

4. Na lista de partições de instâncias, na coluna Ações, clique em Mais ações e selecione Eliminar.

5. Siga as instruções para confirmar que quer eliminar a partição da instância.

6. Clique em Eliminar.

gcloud

Use o comando gcloud beta spanner instance-partitions delete.

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

O que se segue?

• Saiba como criar e gerir a tabela de posicionamentos e as chaves.