Obiettivi
Questo tutorial illustra i passaggi seguenti utilizzando l'API Cloud Spanner con REST:
- Creare un'istanza e un database Spanner.
- Scrivi, leggi ed esegui query SQL sui dati nel database.
- Aggiorna lo schema del database.
- Aggiungi un indice secondario al database.
- Utilizza l'indice per leggere ed eseguire query SQL sui dati.
- Recupera i dati utilizzando una transazione di sola lettura.
Se vuoi utilizzare le librerie client di Spanner anziché il REST API, consulta i tutorial.
Costi
Questo tutorial utilizza Spanner, che è un componente fatturabile del in Google Cloud. Per informazioni sul costo dell'utilizzo di Spanner, consulta la pagina Prezzi.
Prima di iniziare
- Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Google Cloud project.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Google Cloud project.
Metodi per effettuare chiamate REST
Puoi effettuare chiamate REST Spanner utilizzando:
- La funzionalità Prova disponibile nella documentazione di riferimento dell'API Spanner. Gli esempi mostrati in questa pagina utilizzano Prova!.
- Explorer API di Google, che contiene l'API Cloud Spanner e altre API di Google.
- Altri strumenti o framework che supportano le chiamate REST HTTP.
Convenzioni utilizzate in questa pagina
Gli esempi utilizzano
[PROJECT_ID]
come ID progetto Google Cloud. Sostituisci[PROJECT_ID]
con il tuo ID progetto Google Cloud. (Non includi[
e]
nel tuo ID progetto).Gli esempi creano e utilizzano un ID istanza di
test-instance
. Sostituisci ID istanza se non utilizzitest-instance
.Gli esempi consentono di creare e utilizzare un ID database pari a
example-db
. Sostituisci ID database se non utilizziexample-db
.Negli esempi viene utilizzato
[SESSION]
come parte del nome di una sessione. Sostituisci il valore che ricevi quando crei una sessione per[SESSION]
. (Cosa fare non includere[
e]
nel nome della sessione).Gli esempi utilizzano un ID transazione pari a
[TRANSACTION_ID]
. Sostituisci il valore ricevuto quando crei una transazione con[TRANSACTION_ID]
. (Non includi[
e]
nel tuo ID transazione.)La funzionalità Prova! supporta l'aggiunta interattiva di singoli nomi HTTP campi di richiesta. La maggior parte degli esempi in questo argomento fornisce invece l'intera richiesta di descrivere come aggiungere in modo interattivo singoli campi alla richiesta.
Istanze
Quando utilizzi Spanner per la prima volta, devi creare un'istanza, ovvero delle risorse usate dai database Spanner. Quando crei un'istanza, scegli dove archiviare i tuoi dati e quanto capacità di calcolo dell'istanza.
Elenca le configurazioni delle istanze
Quando crei un'istanza, devi specificare una configurazione dell'istanza, che definisce il posizionamento geografico e la replica dei database in esecuzione in un'istanza Compute Engine. Puoi scegliere una configurazione a livello di regione, che archivia i dati in una o una configurazione multiregionale, che distribuisce i dati tra più regioni regioni. Scopri di più in Istanze.
Utilizza projects.instanceConfigs.list
per determinare quali configurazioni
disponibili per il tuo progetto Google Cloud.
- Fai clic su
projects.instanceConfigs.list
. Per genitore, inserisci:
projects/[PROJECT_ID]
Fai clic su Execute (Esegui). Le configurazioni delle istanze disponibili sono mostrate nella risposta. Ecco un esempio di risposta (il tuo progetto potrebbe avere istanze diverse configurazioni):
{ "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" } ] }
Utilizza il valore name
per una delle configurazioni dell'istanza quando crei
la tua istanza.
Crea un'istanza
- Fai clic su
projects.instances.create
. Per genitore, inserisci:
projects/[PROJECT_ID]
Fai clic su Aggiungi parametri del corpo della richiesta e seleziona
instance
.Fai clic sul fumetto del suggerimento per instance per visualizzare i possibili campi. Aggiungi valori per i seguenti campi:
nodeCount
: inserisci1
.config
: inserisci il valorename
di una delle istanze a livello di regione configurazioni restituite quando elenchi l'istanza configurazioni.displayName
: inserisciTest Instance
.
Fai clic sul fumetto del suggerimento che segue la parentesi di chiusura per instance e seleziona instanceId.
Per
instanceId
, inseriscitest-instance
.
La pagina di creazione dell'istanza Prova! ora dovrebbe avere il seguente aspetto:Fai clic su Execute (Esegui). La risposta restituisce una risposta a lunga esecuzione operativa su cui puoi eseguire una query per verificarne .
Puoi elencare le istanze utilizzando
projects.instances.list
Crea un database
Crea un database denominato example-db
.
- Fai clic su
projects.instances.databases.create
. In parent, inserisci:
projects/[PROJECT_ID]/instances/test-instance
Fai clic su Aggiungi parametri del corpo della richiesta e seleziona
createStatement
.Per
createStatement
, inserisci:CREATE DATABASE `example-db`
(Il nome del database,
example-db
, contiene un trattino, quindi deve essere racchiuso tra apici inversi (`
).Fai clic su Execute (Esegui). La risposta restituisce una risposta a lunga esecuzione operativa su cui puoi eseguire una query per verificarne .
Puoi elencare i database utilizzando
projects.instances.databases.list
Crea uno schema
Utilizzare il Data Definition Language di Spanner (DDL) per creare, modificare o eliminare le tabelle e creare o eliminare gli indici.
- Fai clic su
projects.instances.databases.updateDdl
. In database, inserisci:
projects/[PROJECT_ID]/instances/test-instance/databases/example-db
In Corpo della richiesta, utilizza quanto segue:
{ "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" ] }
L'array
statements
contiene le istruzioni DDL che definiscono lo schema.Fai clic su Execute (Esegui). La risposta restituisce una risposta a lunga esecuzione operativa su cui puoi eseguire una query per verificarne .
Lo schema definisce due tabelle, Singers
e Albums
, per una musica di base
un'applicazione. Queste tabelle vengono utilizzate in questa pagina. Se necessario, dai un'occhiata allo schema di esempio
.
Puoi recuperare lo schema utilizzando
projects.instances.databases.getDdl
Creare una sessione
Prima di poter aggiungere, aggiornare, eliminare o eseguire query sui dati, devi creare una sessione, che rappresenta un canale di comunicazione servizio di database Spanner. (Non usi direttamente una sessione se usi una libreria client di Spanner, perché la libreria client gestisce le sessioni per tuo conto.)
- Fai clic su
projects.instances.databases.sessions.create
. Per database, inserisci:
projects/[PROJECT_ID]/instances/test-instance/databases/example-db
Fai clic su Execute (Esegui).
La risposta mostra la sessione che hai creato, nel modulo
projects/[PROJECT_ID]/instances/test-instance/databases/example-db/sessions/[SESSION]
Utilizzerai questa sessione per leggere o scrivere sul database.
Le sessioni sono pensate per durare a lungo. Il servizio di database Spanner può
Eliminare una sessione quando questa è rimasta inattiva per più di un'ora. Tenta di
utilizza un risultato di sessione eliminata in NOT_FOUND
. Se riscontri questo errore, crea
e utilizzare una nuova sessione. Puoi vedere se una sessione è ancora attiva utilizzando
projects.instances.databases.sessions.get
Per informazioni correlate, vedi Mantenere attiva una sessione inattiva.
Il passaggio successivo consiste nello scrivere i dati nel database.
Scrittura di dati
Scrivi i dati utilizzando
Mutation
di testo. Un Mutation
è un container per le operazioni di mutazione. Un Mutation
rappresenta una sequenza di inserimenti, aggiornamenti, eliminazioni e altre azioni che possono
essere applicato a livello atomico a righe e tabelle diverse in un oggetto Spanner
per configurare un database.
- Fai clic su
projects.instances.databases.sessions.commit
. Per sessione, inserisci:
projects/[PROJECT_ID]/instances/test-instance/databases/example-db/sessions/[SESSION]
Riceverai questo valore quando crei una sessione.
In Corpo della richiesta, utilizza quanto segue:
{ "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" ] ] } } ] }
Fai clic su Execute (Esegui). La risposta mostra il timestamp di commit.
In questo esempio sono stati utilizzati insertOrUpdate
. Altre operazioni
per Mutations
sono insert
, update
, replace
e delete
.
Per informazioni su come codificare i tipi di dati, consulta TypeCode.
Esegui query sui dati utilizzando SQL
- Fai clic su
projects.instances.databases.sessions.executeSql
. Per sessione, inserisci:
projects/[PROJECT_ID]/instances/test-instance/databases/example-db/sessions/[SESSION]
Questo valore viene visualizzato quando crei una sessione.
Per Request body (Corpo della richiesta), utilizza quanto segue:
{ "sql": "SELECT SingerId, AlbumId, AlbumTitle FROM Albums" }
Fai clic su Execute (Esegui). La risposta mostra i risultati della query.
Leggere i dati utilizzando l'API Read
- Fai clic su
projects.instances.databases.sessions.read
. In session, inserisci:
projects/[PROJECT_ID]/instances/test-instance/databases/example-db/sessions/[SESSION]
Questo valore viene visualizzato quando crei una sessione.
In Corpo della richiesta, utilizza quanto segue:
{ "table": "Albums", "columns": [ "SingerId", "AlbumId", "AlbumTitle" ], "keySet": { "all": true } }
Fai clic su Execute (Esegui). La risposta mostra i risultati della lettura.
Aggiorna lo schema del database
Supponi di dover aggiungere una nuova colonna denominata MarketingBudget
a Albums
che richiede un aggiornamento dello schema del database. Spanner
supporta gli aggiornamenti dello schema di un database mentre quest'ultimo continua a essere pubblicato
per via del traffico. Gli aggiornamenti dello schema non richiedono la disconnessione del database e lo fanno
non bloccare intere tabelle o colonne; puoi continuare a scrivere dati nel database
durante l'aggiornamento dello schema.
Aggiungi una colonna
- Fai clic su
projects.instances.databases.updateDdl
. Per database, inserisci:
projects/[PROJECT_ID]/instances/test-instance/databases/example-db
In Corpo della richiesta, utilizza quanto segue:
{ "statements": [ "ALTER TABLE Albums ADD COLUMN MarketingBudget INT64" ] }
L'array
statements
contiene le istruzioni DDL che definiscono lo schema.Fai clic su Execute (Esegui). Il completamento dell'operazione potrebbe richiedere alcuni minuti, anche dopo il La chiamata REST restituisce una risposta. La risposta restituisce un'operazione a lunga esecuzione su cui puoi eseguire una query per verificarne lo stato.
Scrivere i dati nella nuova colonna
Il seguente codice scrive i dati nella nuova colonna. Imposta MarketingBudget
su
100000
per la riga con chiave Albums(1, 1)
e in 500000
per la riga con chiave
di Albums(2, 2)
.
- Fai clic su
projects.instances.databases.sessions.commit
. Per sessione, inserisci:
projects/[PROJECT_ID]/instances/test-instance/databases/example-db/sessions/[SESSION]
Questo valore viene visualizzato quando crei una sessione.
In Corpo della richiesta, utilizza quanto segue:
{ "singleUseTransaction": { "readWrite": {} }, "mutations": [ { "update": { "table": "Albums", "columns": [ "SingerId", "AlbumId", "MarketingBudget" ], "values": [ [ "1", "1", "100000" ], [ "2", "2", "500000" ] ] } } ] }
Fai clic su Execute (Esegui). La risposta mostra il timestamp di commit.
Puoi anche eseguire una query SQL o una chiamata di lettura per recuperare i valori che che ha appena scritto.
Ecco come eseguire la query:
- Fai clic su
projects.instances.databases.sessions.executeSql
. Per sessione, inserisci:
projects/[PROJECT_ID]/instances/test-instance/databases/example-db/sessions/[SESSION]
Riceverai questo valore quando crei una sessione.
Per Request body (Corpo della richiesta), utilizza quanto segue:
{ "sql": "SELECT SingerId, AlbumId, MarketingBudget FROM Albums" }
Fai clic su Execute (Esegui). Come parte della risposta dovresti vedere due righe che contengono i valori
MarketingBudget
aggiornati:"rows": [ [ "1", "1", "100000" ], [ "1", "2", null ], [ "2", "1", null ], [ "2", "2", "500000" ], [ "2", "3", null ] ]
Utilizza un indice secondario
Supponiamo di voler recuperare tutte le righe di Albums
con valori AlbumTitle
in un determinato intervallo. Potresti leggere tutti i valori della colonna AlbumTitle
utilizzando
un'istruzione SQL o una chiamata di lettura, quindi ignorare le righe che non soddisfano i
criteri, ma questa scansione completa della tabella è costosa, soprattutto per le tabelle
con molte righe. In alternativa, puoi velocizzare il recupero delle righe quando effettui ricerche in base a colonne di chiavi non principali creando un indice secondario nella tabella.
L'aggiunta di un indice secondario a una tabella esistente richiede un aggiornamento dello schema. Mi piace altri aggiornamenti dello schema, Spanner supporta l'aggiunta di un indice, mentre continua a gestire traffico. Spanner esegue automaticamente il backfill l'indicizzazione con i dati esistenti. Il completamento dei backfill potrebbe richiedere alcuni minuti ma non è necessario mettere offline il database o evitare di scrivere di tabelle o colonne. Per ulteriori dettagli, vedi il backfill dell'indice.
Dopo aver aggiunto un indice secondario, Spanner lo utilizza automaticamente per le query SQL che potrebbero essere eseguite più velocemente con l'indice. Se utilizzi lo strumento devi specificare l'indice che vuoi utilizzare.
Aggiungi un indice secondario
Puoi aggiungere un indice utilizzando updateDdl
.
- Fai clic su
projects.instances.databases.updateDdl
. Per database, inserisci:
projects/[PROJECT_ID]/instances/test-instance/databases/example-db
In Corpo della richiesta, utilizza quanto segue:
{ "statements": [ "CREATE INDEX AlbumsByAlbumTitle ON Albums(AlbumTitle)" ] }
Fai clic su Execute (Esegui). Il completamento dell'operazione potrebbe richiedere alcuni minuti, anche dopo il La chiamata REST restituisce una risposta. La risposta restituisce una risposta a lunga esecuzione operativa su cui puoi eseguire una query per verificarne .
Query utilizzando l'indice
- Fai clic su
projects.instances.databases.sessions.executeSql
. Per sessione, inserisci:
projects/[PROJECT_ID]/instances/test-instance/databases/example-db/sessions/[SESSION]
Questo valore viene visualizzato quando crei una sessione.
In Corpo della richiesta, utilizza quanto segue:
{ "sql": "SELECT AlbumId, AlbumTitle, MarketingBudget FROM Albums WHERE AlbumTitle >= 'Aardvark' AND AlbumTitle < 'Goo'" }
Fai clic su Execute (Esegui). Nella risposta dovresti vedere le seguenti righe:
"rows": [ [ "2", "Go, Go, Go", null ], [ "2", "Forever Hold Your Peace", "500000" ] ]
Lettura utilizzando l'indice
- Fai clic su
projects.instances.databases.sessions.read
. Per sessione, inserisci:
projects/[PROJECT_ID]/instances/test-instance/databases/example-db/sessions/[SESSION]
Questo valore viene visualizzato quando crei una sessione.
In Corpo della richiesta, utilizza quanto segue:
{ "table": "Albums", "columns": [ "AlbumId", "AlbumTitle" ], "keySet": { "all": true }, "index": "AlbumsByAlbumTitle" }
Fai clic su Execute (Esegui). Nell'ambito della risposta dovresti vedere le seguenti righe:
"rows": [ [ "2", "Forever Hold Your Peace" ], [ "2", "Go, Go, Go" ], [ "1", "Green" ], [ "3", "Terrified" ], [ "1", "Total Junk" ] ]
Aggiungere un indice con la clausola STORING
Potresti aver notato che l'esempio riportato sopra non include la lettura del
Colonna MarketingBudget
. Questo perché l'interfaccia di lettura di Spanner
non supporta la possibilità di unire un indice a una tabella di dati per cercare valori
che non sono archiviati nell'indice.
Crea una definizione alternativa di AlbumsByAlbumTitle
che memorizzi una copia di
MarketingBudget
nell'indice.
Puoi aggiungere un indice STORING utilizzando updateDdl
.
- Fai clic su
projects.instances.databases.updateDdl
. Per database, inserisci:
projects/[PROJECT_ID]/instances/test-instance/databases/example-db
In Corpo della richiesta, utilizza quanto segue:
{ "statements": [ "CREATE INDEX AlbumsByAlbumTitle2 ON Albums(AlbumTitle) STORING (MarketingBudget)" ] }
Fai clic su Execute (Esegui). Il completamento dell'operazione potrebbe richiedere alcuni minuti, anche dopo il La chiamata REST restituisce una risposta. La risposta restituisce un'operazione a lunga esecuzione su cui puoi eseguire una query per verificarne lo stato.
Ora puoi eseguire una lettura che recupera tutti i valori AlbumId
, AlbumTitle
e
MarketingBudget
colonne dall'indice AlbumsByAlbumTitle2
:
- Fai clic su
projects.instances.databases.sessions.read
. Per sessione, inserisci:
projects/[PROJECT_ID]/instances/test-instance/databases/example-db/sessions/[SESSION]
Riceverai questo valore quando crei una sessione.
In Corpo della richiesta, utilizza quanto segue:
{ "table": "Albums", "columns": [ "AlbumId", "AlbumTitle", "MarketingBudget" ], "keySet": { "all": true }, "index": "AlbumsByAlbumTitle2" }
Fai clic su Execute (Esegui). Nell'ambito della risposta dovresti vedere le seguenti righe:
"rows": [ [ "2", "Forever Hold Your Peace", "500000" ], [ "2", "Go, Go, Go", null ], [ "1", "Green", null ], [ "3", "Terrified", null ], [ "1", "Total Junk", "100000" ] ]
Recuperare i dati utilizzando le transazioni di sola lettura
Supponiamo di voler eseguire più di una lettura per lo stesso timestamp. Sola lettura transazioni osservano una coerenza della cronologia di commit delle transazioni, in modo che l'applicazione la coerenza dei dati.
Crea una transazione di sola lettura
- Fai clic su
projects.instances.databases.sessions.beginTransaction
. Per sessione, inserisci:
projects/[PROJECT_ID]/instances/test-instance/databases/example-db/sessions/[SESSION]
In Corpo della richiesta, utilizza quanto segue:
{ "options": { "readOnly": {} } }
Fai clic su Execute (Esegui).
La risposta mostra l'ID della transazione che hai creato.
Ora puoi utilizzare la transazione di sola lettura per recuperare i dati in un il timestamp, anche se i dati sono cambiati dalla creazione dell'URL transazione.
Esegui una query utilizzando la transazione di sola lettura
- Fai clic su
projects.instances.databases.sessions.executeSql
. Per sessione, inserisci:
projects/[PROJECT_ID]/instances/test-instance/databases/example-db/sessions/[SESSION]
Questo valore viene visualizzato quando crei una sessione.
Per Request body (Corpo della richiesta), utilizza quanto segue:
{ "sql": "SELECT SingerId, AlbumId, AlbumTitle FROM Albums", "transaction": { "id": "[TRANSACTION_ID]" } }
Fai clic su Execute (Esegui). Nella risposta dovresti vedere righe simili alle seguenti:
"rows": [ [ "2", "2", "Forever Hold Your Peace" ], [ "1", "2", "Go, Go, Go" ], [ "2", "1", "Green" ], [ "2", "3", "Terrified" ], [ "1", "1", "Total Junk" ] ]
Lettura tramite transazione di sola lettura
- Fai clic su
projects.instances.databases.sessions.read
. Per sessione, inserisci:
projects/[PROJECT_ID]/instances/test-instance/databases/example-db/sessions/[SESSION]
Questo valore viene visualizzato quando crei una sessione.
In Corpo della richiesta, utilizza quanto segue:
{ "table": "Albums", "columns": [ "SingerId", "AlbumId", "AlbumTitle" ], "keySet": { "all": true }, "transaction": { "id": "[TRANSACTION_ID]" } }
Fai clic su Execute (Esegui). Nella risposta dovresti vedere righe simili alle seguenti:
"rows": [ [ "1", "1", "Total Junk" ], [ "1", "2", "Go, Go, Go" ], [ "2", "1", "Green" ], [ "2", "2", "Forever Hold Your Peace" ], [ "2", "3", "Terrified" ] ]
Spanner supporta anche le transazioni di lettura/scrittura, che eseguono un set di legge e scrive atomicamente in un singolo punto logico nel tempo. Per ulteriori informazioni le informazioni, vedi Transazioni di lettura/scrittura. (La La funzionalità Prova! non è adatta per dimostrare una lettura/scrittura transaction.)
Esegui la pulizia
Per evitare che al tuo account Google Cloud vengano addebitati costi aggiuntivi per usate in questo tutorial, elimina il database ed elimina l'istanza che hai creato.
Trascina un database
- Fai clic su
projects.instances.databases.dropDatabase
. Per nome, inserisci:
projects/[PROJECT_ID]/instances/test-instance/databases/example-db
Fai clic su Execute (Esegui).
Elimina un'istanza
- Fai clic su
projects.instances.delete
. Per nome, inserisci:
projects/[PROJECT_ID]/instances/test-instance
Fai clic su Execute (Esegui).
Passaggi successivi
- Accedi a Spanner in un'istanza di macchina virtuale: crea un'istanza di macchina virtuale con accesso al tuo database Spanner.
- Scopri di più sui concetti di Spanner.