Objetivos
Este tutorial apresenta as seguintes etapas usando a Cloud Spanner API com a REST:
- Criar uma instância e um banco de dados do Cloud Spanner.
- Gravar, ler e executar consultas SQL em dados contidos no banco de dados
- Atualizar o esquema do banco de dados.
- Adicionar um índice secundário ao banco de dados.
- Usar o índice para ler e executar consultas SQL nos dados
- Recuperar dados usando uma transação somente leitura.
Se você quer usar bibliotecas de cliente do Cloud Spanner em vez de usar a REST API, consulte Tutoriais.
Custos
Neste tutorial, usamos o Cloud Spanner, que é um componente faturável do Google Cloud Platform. Para informações sobre o custo de utilização do Cloud Spanner, consulte Preços.
Antes de começar
-
Faça login na sua Conta do Google.
Se você ainda não tiver uma, inscreva-se.
-
Selecione ou crie um projeto do Google Cloud Platform.
-
Verifique se o faturamento foi ativado no projeto do Google Cloud Platform.
Maneiras de fazer chamadas REST
Você pode fazer as chamadas REST do Cloud Spanner usando:
- A funcionalidade Faça um teste! encontrada na Documentação de referência da Cloud Spanner API. Os exemplos apresentados nesta página usam o recurso Faça um teste! .
- as APIs Explorer do Google, que contém a API Cloud Spanner e outras APIs do Google;
- Outras ferramentas ou bibliotecas compatíveis com chamadas HTTP REST.
Convenções usadas nesta página
Nos exemplos são utilizados os exemplos
[PROJECT_ID]
como código do projeto do GCP. Substitua[PROJECT_ID]
pelo código do seu projeto do GCP. Não inclua[
e]
no código do projeto.Os exemplos criam e usam um código de instância de
test-instance
. Substitua o código da instância se você não estiver usandotest-instance
.Os exemplos criam e usam um código de banco de dados de
example-db
. Substitua o código do banco de dados se você não estiver usandoexample-db
.Os exemplos usam
[SESSION]
como parte de um nome de sessão. Substitua por[SESSION]
o valor que você receber quando criar uma sessão. Não inclua[
e]
no nome da sessão.Os exemplos usam um código de transação de
[TRANSACTION_ID]
. Substitua[TRANSACTION_ID]
pelo valor que você receber quando criar uma transação. Não inclua[
e]
no código da transação.A funcionalidade Faça um teste! é compatível com a inclusão interativa de campos de solicitação HTTP individuais. A maioria dos exemplos neste tópico fornece toda a solicitação em vez de descrever como adicionar interativamente campos individuais.
Instâncias
Ao usar o Cloud Spanner pela primeira vez, é necessário criar uma instância que é uma alocação de recursos usados pelos bancos de dados do Cloud Spanner. Quando você cria uma instância, escolhe onde armazenar seus dados e quantos nodes serão usados por eles.
Listar configurações de instância
Ao criar uma instância, você especifica uma configuração de instância que define a colocação geográfica e a replicação de bancos de dados nessa instância. É possível escolher uma configuração regional, para armazenar dados em uma região ou uma configuração de várias regiões, para distribuir dados em várias regiões. Saiba mais em Instâncias.
Use projects.instanceConfigs.list
para determinar quais configurações estão disponíveis para o projeto do GCP.
- Clique em
projects.instanceConfigs.list
. Para o pai, digite:
projects/[PROJECT_ID]
Clique em Executar. As configurações de instância disponíveis são mostradas na resposta. Veja um exemplo de resposta (seu projeto pode ter diferentes configurações de instância):
{ "instanceConfigs": [ { "name": "projects/[PROJECT_ID]/instanceConfigs/regional-asia-south1", "displayName": "asia-south1" }, { "name": "projects/[PROJECT_ID]/instanceConfigs/regional-asia-east1", "displayName": "asia-east1" }, { "name": "projects/[PROJECT_ID]/instanceConfigs/regional-asia-northeast1", "displayName": "asia-northeast1" }, { "name": "projects/[PROJECT_ID]/instanceConfigs/regional-europe-west1", "displayName": "europe-west1" }, { "name": "projects/[PROJECT_ID]/instanceConfigs/regional-us-east4", "displayName": "us-east4" }, { "name": "projects/[PROJECT_ID]/instanceConfigs/regional-us-central1", "displayName": "us-central1" } ] }
Você usa o valor do name
para uma das configurações da instância quando cria sua instância.
Criar uma instância
- Clique em
projects.instances.create
. Para o pai, digite:
projects/[PROJECT_ID]
Clique em Adicionar parâmetros do corpo da solicitação e selecione
instance
.Clique no balão da dica em Instância para ver os campos possíveis. Adicione valores para os seguintes campos:
nodeCount
: digite1
.config
: digite o valor doname
de uma das configurações de instâncias regionais retornadas quando você listar configurações de instância.displayName
: digiteTest Instance
.
Clique no balão da dica depois do colchete de fechamento para Instância e selecione instanceId.
Para
instanceId
, digitetest-instance
.
A página de criação da instância Faça um teste! agora deve aparecer assim:Clique em Executar. Na resposta é retornada uma operação de longa duração que pode ser consultada para verificar o status.
É possível listar suas instâncias usando projects.instances.list
.
Criar um banco de dados
Crie um banco de dados chamado example-db
.
- Clique em
projects.instances.databases.create
. Para o pai, digite:
projects/[PROJECT_ID]/instances/test-instance
Clique em Adicionar parâmetros do corpo da solicitação e selecione
createStatement
.Para
createStatement
, digite:CREATE DATABASE `example-db`
O nome do banco de dados
example-db
, contém um hífen, portanto precisa ser colocado entre aspas simples (`
).Clique em Executar. Na resposta é retornada uma operação de longa duração que pode ser consultada para verificar o status.
É possível listar seus bancos de dados usando projects.instances.databases.list
.
Criar um esquema
Use o Idioma de Definição de Dados (DDL) do Cloud Spanner para criar, alterar ou remover tabelas e criar ou remover índices.
- Clique em
projects.instances.databases.updateDdl
. Para o banco de dados, digite:
projects/[PROJECT_ID]/instances/test-instance/databases/example-db
Para o Corpo de solicitação, use o seguinte:
{ "statements": [ "CREATE TABLE Singers ( SingerId INT64 NOT NULL, FirstName STRING(1024), LastName STRING(1024), SingerInfo BYTES(MAX) ) PRIMARY KEY (SingerId)", "CREATE TABLE Albums ( SingerId INT64 NOT NULL, AlbumId INT64 NOT NULL, AlbumTitle STRING(MAX)) PRIMARY KEY (SingerId, AlbumId), INTERLEAVE IN PARENT Singers ON DELETE CASCADE" ] }
A matriz de
statements
contém as instruções DDL que definem o esquema.Clique em Executar. A resposta retorna uma operação de longa duração que pode ser consultada para verificar o status.
O esquema define duas tabelas, Singers
e Albums
, para um aplicativo básico de música. Essas tabelas são usadas em toda esta página. Caso ainda não tenha feito isso, dê uma olhada no esquema de exemplo.
É possível recuperar o esquema usando projects.instances.databases.getDdl
.
Criar uma sessão
Antes de adicionar, atualizar, excluir ou consultar dados, você precisa criar uma sessão que represente um canal de comunicação com o serviço de banco de dados do Cloud Spanner. Não utilize uma sessão diretamente se estiver usando uma biblioteca de cliente do Cloud Spanner, porque a biblioteca gerencia sessões em seu nome.
- Clique em
projects.instances.databases.sessions.create
. Para o banco de dados, digite:
projects/[PROJECT_ID]/instances/test-instance/databases/example-db
Clique em Executar.
A resposta mostra a sessão que você criou, no formato
projects/[PROJECT_ID]/instances/test-instance/databases/example-db/sessions/[SESSION]
Você usará esta sessão quando ler ou gravar no banco de dados.
As sessões devem ser de longa duração. O serviço de banco de dados do Cloud Spanner pode excluir uma sessão quando ela estiver inativa por mais de uma hora. As tentativas de usar uma sessão excluída resultam em NOT_FOUND
. Se você encontrar esse erro, crie e use uma nova sessão. É possível ver se uma sessão ainda está ativa usando projects.instances.databases.sessions.get
.
Para informações relacionadas, consulte Manter uma sessão ociosa ativa.
O próximo passo é gravar dados no seu banco de dados.
Gravar dados
Os dados são gravados usando o tipo Mutation
. Mutation
é um contêiner para operações de mutação. Em uma Mutation
é representada uma sequência de inserções, atualizações, exclusões e outras ações que podem ser aplicadas atomicamente em diferentes linhas e tabelas em um banco de dados do Cloud Spanner.
- Clique em
projects.instances.databases.sessions.commit
. Para a sessão, digite:
projects/[PROJECT_ID]/instances/test-instance/databases/example-db/sessions/[SESSION]
Você receberá esse valor quando criar uma sessão.
Para o Corpo de solicitação, use o seguinte código:
{ "singleUseTransaction": { "readWrite": {} }, "mutations": [ { "insertOrUpdate": { "table": "Singers", "columns": [ "SingerId", "FirstName", "LastName" ], "values": [ [ "1", "Marc", "Richards" ], [ "2", "Catalina", "Smith" ], [ "3", "Alice", "Trentor" ], [ "4", "Lea", "Martin" ], [ "5", "David", "Lomond" ] ] } }, { "insertOrUpdate": { "table": "Albums", "columns": [ "SingerId", "AlbumId", "AlbumTitle" ], "values": [ [ "1", "1", "Total Junk" ], [ "1", "2", "Go, Go, Go" ], [ "2", "1", "Green" ], [ "2", "2", "Forever Hold Your Peace" ], [ "2", "3", "Terrified" ] ] } } ] }
Clique em Executar. A resposta mostra o carimbo de data/hora da confirmação.
Este exemplo usou insertOrUpdate
. Outras operações para Mutations
são insert
, update
, replace
e delete
.
Para informações sobre como codificar tipos de dados, consulte TypeCode.
Consultar dados usando SQL
- Clique em
projects.instances.databases.sessions.executeSql
. Para a sessão, digite:
projects/[PROJECT_ID]/instances/test-instance/databases/example-db/sessions/[SESSION]
Você receberá esse valor quando criar uma sessão.
Para o Corpo de solicitação, use o seguinte código:
{ "sql": "SELECT SingerId, AlbumId, AlbumTitle FROM Albums" }
Clique em Executar. A resposta exibe os resultados da consulta.
Ler dados usando a API de leitura
- Clique em
projects.instances.databases.sessions.read
. Para a sessão, digite:
projects/[PROJECT_ID]/instances/test-instance/databases/example-db/sessions/[SESSION]
Você receberá esse valor quando criar uma sessão.
Para o Corpo de solicitação, use o seguinte código:
{ "table": "Albums", "columns": [ "SingerId", "AlbumId", "AlbumTitle" ], "keySet": { "all": true } }
Clique em Executar. A resposta exibe os resultados de leitura.
Atualizar o esquema do banco de dados
Suponha que você precise adicionar uma nova coluna chamada MarketingBudget
à tabela Albums
, que exige uma atualização para o esquema de banco de dados. O Cloud Spanner é compatível com atualizações de esquema para um banco de dados enquanto o banco de dados continua a suprir o tráfego. Para fazer atualizações no esquema, não é necessário desconectar o banco de dados nem bloquear tabelas ou colunas inteiras. É possível continuar gravando dados no banco de dados durante a atualização do esquema.
Adicionar uma coluna
- Clique em
projects.instances.databases.updateDdl
. Para o banco de dados, digite:
projects/[PROJECT_ID]/instances/test-instance/databases/example-db
Para o Corpo de solicitação, use o seguinte:
{ "statements": [ "ALTER TABLE Albums ADD COLUMN MarketingBudget INT64" ] }
A matriz de
statements
contém as instruções DDL que definem o esquema.Clique em Executar. Isso pode levar alguns minutos para ser concluído, mesmo após a resposta ter sido retornada pela chamada REST. A resposta retorna uma operação de longa duração que pode ser consultada para verificar o status.
Gravar dados na coluna nova
O código a seguir grava dados na coluna nova. Ele define MarketingBudget
como 100000
para a linha informada por Albums(1, 1)
e 500000
para a linha informada por Albums(2, 2)
.
- Clique em
projects.instances.databases.sessions.commit
. Para a sessão, digite:
projects/[PROJECT_ID]/instances/test-instance/databases/example-db/sessions/[SESSION]
Você receberá esse valor quando criar uma sessão.
Para o Corpo de solicitação, use o seguinte código:
{ "singleUseTransaction": { "readWrite": {} }, "mutations": [ { "update": { "table": "Albums", "columns": [ "SingerId", "AlbumId", "MarketingBudget" ], "values": [ [ "1", "1", "100000" ], [ "2", "2", "500000" ] ] } } ] }
Clique em Executar. A resposta mostra o carimbo de data/hora da confirmação.
Também é possível executar uma consulta SQL ou uma chamada de leitura para coletar os valores que você acabou de gravar.
Veja como executar a consulta:
- Clique em
projects.instances.databases.sessions.executeSql
. Para a sessão, digite:
projects/[PROJECT_ID]/instances/test-instance/databases/example-db/sessions/[SESSION]
Você receberá esse valor quando criar uma sessão.
Para o Corpo de solicitação, use o seguinte código:
{ "sql": "SELECT SingerId, AlbumId, MarketingBudget FROM Albums" }
Clique em Executar. Como parte da resposta, você deve ver duas linhas que contêm os valores atualizados
MarketingBudget
:"rows": [ [ "1", "1", "100000" ], [ "1", "2", null ], [ "2", "1", null ], [ "2", "2", "500000" ], [ "2", "3", null ] ]
Usar um índice secundário
Suponha que você queira buscar todas as linhas de Albums
que têm valores de AlbumTitle
em um determinado intervalo. É possível ler todos os valores da coluna AlbumTitle
usando uma instrução SQL ou uma chamada de leitura e, em seguida, descartar as linhas que não atendam aos critérios. Porém, fazer essa varredura em uma tabela completa é um processo caro, especialmente em tabelas com muitas linhas. Em vez disso, acelere a recuperação de linhas ao pesquisar por colunas de chaves não primárias por meio da criação de um índice secundário na tabela.
Adicionar um índice secundário a uma tabela requer uma atualização de esquema. Como outras atualizações de esquema, o Cloud Spanner é compatível com a adição de um índice enquanto o banco de dados continua a disponibilizar o tráfego. O Cloud Spanner preenche o índice com dados (processo conhecido como "preenchimento") em segundo plano. Pode levar alguns minutos para que os preenchimentos sejam concluídos, mas não é necessário deixar o banco de dados off-line ou evitar a gravação em determinadas tabelas ou colunas durante esse processo. Para mais detalhes, consulte o preenchimento de índices.
Adicionar um índice secundário
É possível adicionar um índice usando updateDdl
.
- Clique em
projects.instances.databases.updateDdl
. Para o banco de dados, digite:
projects/[PROJECT_ID]/instances/test-instance/databases/example-db
Para o Corpo de solicitação, use o seguinte código:
{ "statements": [ "CREATE INDEX AlbumsByAlbumTitle ON Albums(AlbumTitle)" ] }
Clique em Executar. Isso pode levar alguns minutos para ser concluído, mesmo após a resposta ter sido retornada pela chamada REST. Na resposta é retornada uma operação de longa duração que pode ser consultada para verificar o status.
Consultar usando o índice
- Clique em
projects.instances.databases.sessions.executeSql
. Para a sessão, digite:
projects/[PROJECT_ID]/instances/test-instance/databases/example-db/sessions/[SESSION]
Você receberá esse valor quando criar uma sessão.
Para o Corpo de solicitação, use o seguinte código:
{ "sql": "SELECT AlbumId, AlbumTitle, MarketingBudget FROM Albums@{FORCE_INDEX=AlbumsByAlbumTitle} WHERE AlbumTitle >= 'Aardvark' AND AlbumTitle < 'Goo'" }
Clique em Executar. Como parte da resposta, você verá as seguintes linhas:
"rows": [ [ "2", "Go, Go, Go", null ], [ "2", "Forever Hold Your Peace", "500000" ] ]
Fazer uma leitura usando o índice
- Clique em
projects.instances.databases.sessions.read
. Para a sessão, digite:
projects/[PROJECT_ID]/instances/test-instance/databases/example-db/sessions/[SESSION]
Você receberá esse valor quando criar uma sessão.
Para o Corpo de solicitação, use o seguinte código:
{ "table": "Albums", "columns": [ "AlbumId", "AlbumTitle" ], "keySet": { "all": true }, "index": "AlbumsByAlbumTitle" }
Clique em Executar. Como parte da resposta, você deve ver as seguintes linhas:
"rows": [ [ "2", "Forever Hold Your Peace" ], [ "2", "Go, Go, Go" ], [ "1", "Green" ], [ "3", "Terrified" ], [ "1", "Total Junk" ] ]
Adicionar um índice com a cláusula STORING
Talvez você tenha notado que o exemplo de leitura acima não inclui a leitura da coluna MarketingBudget
. Isso ocorre porque a interface de leitura do Cloud Spanner não é compatível com a capacidade de associar um índice a uma tabela de dados para pesquisar valores que não estão armazenados no índice.
Crie uma definição alternativa de AlbumsByAlbumTitle
que armazene uma cópia do MarketingBudget
no índice.
Você pode adicionar um índice STORING usando updateDdl
.
- Clique em
projects.instances.databases.updateDdl
. Para o banco de dados, digite:
projects/[PROJECT_ID]/instances/test-instance/databases/example-db
Para o Corpo de solicitação, use o seguinte código:
{ "statements": [ "CREATE INDEX AlbumsByAlbumTitle2 ON Albums(AlbumTitle) STORING (MarketingBudget)" ] }
Clique em Executar. Isso pode levar alguns minutos para ser concluído, mesmo após a resposta ter sido retornada pela chamada REST. A resposta retorna uma operação de longa duração que pode ser consultada para verificar o status.
Agora você pode executar uma leitura que busque todas as colunas AlbumId
, AlbumTitle
e MarketingBudget
do índice AlbumsByAlbumTitle2
:
- Clique em
projects.instances.databases.sessions.read
. Para a sessão, digite:
projects/[PROJECT_ID]/instances/test-instance/databases/example-db/sessions/[SESSION]
Você receberá esse valor quando criar uma sessão.
Para o Corpo de solicitação, use o seguinte código:
{ "table": "Albums", "columns": [ "AlbumId", "AlbumTitle", "MarketingBudget" ], "keySet": { "all": true }, "index": "AlbumsByAlbumTitle2" }
Clique em Executar. Como parte da resposta, você deve ver as seguintes linhas:
"rows": [ [ "2", "Forever Hold Your Peace", "500000" ], [ "2", "Go, Go, Go", null ], [ "1", "Green", null ], [ "3", "Terrified", null ], [ "1", "Total Junk", "100000" ] ]
Recuperar dados usando transações somente leitura
Suponha que você queira executar mais de uma leitura no mesmo carimbo de data/hora. As transações somente leitura observam um prefixo consistente do histórico de confirmações da transação. Portanto, o aplicativo sempre recebe dados consistentes.
Criar uma transação somente leitura
- Clique em
projects.instances.databases.sessions.beginTransaction
. Para a sessão, digite:
projects/[PROJECT_ID]/instances/test-instance/databases/example-db/sessions/[SESSION]
Para Corpo de solicitação, use o seguinte:
{ "options": { "readOnly": {} } }
Clique em Executar.
A resposta mostra o código da transação que você criou.
Agora é possível usar a transação somente leitura para recuperar dados em um carimbo de data/hora consistente, mesmo que os dados tenham mudado desde a criação da transação somente leitura.
Executar uma consulta usando a transação somente leitura
- Clique em
projects.instances.databases.sessions.executeSql
. Para a sessão, digite:
projects/[PROJECT_ID]/instances/test-instance/databases/example-db/sessions/[SESSION]
Você receberá esse valor quando criar uma sessão.
Para o Corpo de solicitação, use o seguinte código:
{ "sql": "SELECT SingerId, AlbumId, AlbumTitle FROM Albums", "transaction": { "id": "[TRANSACTION_ID]" } }
Clique em Executar. Você deve ver linhas semelhantes às seguintes na resposta:
"rows": [ [ "2", "2", "Forever Hold Your Peace" ], [ "1", "2", "Go, Go, Go" ], [ "2", "1", "Green" ], [ "2", "3", "Terrified" ], [ "1", "1", "Total Junk" ] ]
Fazer leitura usando a transação somente leitura
- Clique em
projects.instances.databases.sessions.read
. Para a sessão, digite:
projects/[PROJECT_ID]/instances/test-instance/databases/example-db/sessions/[SESSION]
Você receberá esse valor quando criar uma sessão.
Para o Corpo de solicitação, use o seguinte código:
{ "table": "Albums", "columns": [ "SingerId", "AlbumId", "AlbumTitle" ], "keySet": { "all": true }, "transaction": { "id": "[TRANSACTION_ID]" } }
Clique em Executar. Você deve ver linhas semelhantes às seguintes na resposta:
"rows": [ [ "1", "1", "Total Junk" ], [ "1", "2", "Go, Go, Go" ], [ "2", "1", "Green" ], [ "2", "2", "Forever Hold Your Peace" ], [ "2", "3", "Terrified" ] ]
O Cloud Spanner também é compatível com transações de leitura e gravação, que executam atomicamente um conjunto de leituras e gravações em um único ponto lógico no tempo. Para mais informações, consulte Transações de leitura e gravação (a funcionalidade Faça um teste! não é adequada para demonstrar uma transação de leitura e gravação).
Limpeza
Para evitar cobranças adicionais na conta do GCP, pelos recursos utilizados neste tutorial, remova o banco de dados e exclua a instância que você criou.
Remover um banco de dados
- Clique em
projects.instances.databases.dropDatabase
. Para o nome, insira:
projects/[PROJECT_ID]/instances/test-instance/databases/example-db
Clique em Executar.
Excluir uma instância
- Clique em
projects.instances.delete
. Para o nome, insira:
projects/[PROJECT_ID]/instances/test-instance
Clique em Executar.
A seguir
- Acesse o Cloud Spanner em uma instância de máquina virtual: crie uma instância de máquina virtual com acesso ao banco de dados do Cloud Spanner.
- Saiba mais sobre os conceitos do Cloud Spanner.