Primeiros passos com o Cloud Spanner usando a REST

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 GCP.

Observação: se você não pretende manter os recursos criados neste tutorial, crie um novo projeto em vez de selecionar um existente. Depois de terminar, é possível excluir o projeto, removendo todos os recursos associados ao projeto e ao tutorial.

Acessar a página Gerenciar recursos
Verifique se o faturamento foi ativado para o projeto.

Saiba como ativar o faturamento

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 usando test-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 usando example-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:
1. nodeCount: digite 1.
2. config: digite o valor do name de uma das configurações de instâncias regionais retornadas quando você listar configurações de instância.
3. displayName: digite Test Instance.
Clique no balão da dica depois do colchete de fechamento para Instância e selecione instanceId.
Para instanceId, digite test-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.

Objetivos

Custos

Antes de começar

Maneiras de fazer chamadas REST

Convenções usadas nesta página

Instâncias

Listar configurações de instância

Criar uma instância

Criar um banco de dados

Criar um esquema

Criar uma sessão

Gravar dados

Consultar dados usando SQL

Ler dados usando a API de leitura

Atualizar o esquema do banco de dados

Adicionar uma coluna

Gravar dados na coluna nova

Usar um índice secundário

Adicionar um índice secundário

Consultar usando o índice

Fazer uma leitura usando o índice

Adicionar um índice com a cláusula STORING

Recuperar dados usando transações somente leitura

Criar uma transação somente leitura

Executar uma consulta usando a transação somente leitura

Fazer leitura usando a transação somente leitura

Limpeza

Remover um banco de dados

Excluir uma instância

A seguir

Enviar comentários sobre…