Cette page a été traduite par l'API Cloud Translation.
Switch to English

Premiers pas avec Cloud Spanner en C#

Objectifs

Ce tutoriel vous montre comment effectuer les opérations suivantes à l’aide de la bibliothèque cliente Cloud Spanner pour C# :

  • Créer une instance et une base de données Cloud Spanner
  • Écrire ou lire des données dans la base de données, et exécuter des requêtes SQL sur ces données
  • Mettre à jour le schéma de base de données
  • Mettre à jour les données à l'aide d'une transaction en lecture/écriture
  • Ajouter un index secondaire à la base de données
  • Utiliser l'index pour lire et exécuter des requêtes SQL sur des données
  • Récupérer des données à l'aide d'une transaction en lecture seule

Coûts

Ce tutoriel utilise Cloud Spanner, un composant facturable de Google Cloud. Pour en savoir plus sur le coût d'utilisation de Cloud Spanner, consultez la page Tarifs.

Avant de commencer

Pour obtenir les identifiants d'authentification permettant d'utiliser l'API Cloud Spanner, suivez les étapes décrites dans la section dédiée à la configuration qui traite des sujets suivants : création et définition d'un projet Google Cloud par défaut, activation de la facturation ainsi que de l'API Cloud Spanner, et configuration d'OAuth 2.0.

Veillez en particulier à exécuter gcloud auth application-default login pour configurer votre environnement de développement local avec des identifiants d'authentification.

Préparer votre environnement C# local

  1. Définissez la variable d'environnement GOOGLE_PROJECT_ID sur l'ID de votre projet Google Cloud.

    1. Tout d’abord, définissez la variable GOOGLE_PROJECT_ID pour la session PowerShell en cours :

      $env:GOOGLE_PROJECT_ID = "MY_PROJECT_ID"
    2. Ensuite, définissez GOOGLE_PROJECT_ID pour tous les processus créés après cette commande :

      [Environment]::SetEnvironmentVariable("GOOGLE_PROJECT_ID", "MY_PROJECT_ID", "User")
  2. Téléchargez les identifiants.

    1. Accédez à la page Identifiants dans Google Cloud Console.

      Accéder à la page Identifiants

    2. Cliquez sur Créer des identifiants, puis choisissez Clé de compte de service.

    3. Dans "Compte de service", choisissez le Compte de service Compute Engine par défaut et laissez JSON sélectionné comme "Type de clé". Cliquez sur Créer. Votre ordinateur va télécharger un fichier JSON.

  3. Configurez les identifiants. Pour un fichier nommé FILENAME.json dans le répertoire Téléchargements de CURRENT_USER, situé sur le lecteur C, exécutez les commandes suivantes pour que GOOGLE_APPLICATION_CREDENTIALS pointe vers la clé JSON :

    1. Tout d’abord, définissez la variable GOOGLE_APPLICATION_CREDENTIALS pour cette session PowerShell :

      $env:GOOGLE_APPLICATION_CREDENTIALS = "C:\Users\CURRENT_USER\Downloads\FILENAME.json"
    2. Ensuite, définissez GOOGLE_APPLICATION_CREDENTIALS pour tous les processus créés après cette commande :

      [Environment]::SetEnvironmentVariable("GOOGLE_APPLICATION_CREDENTIALS", "C:\Users\CURRENT_USER\Downloads\FILENAME.json", "User")
  4. Clonez le dépôt de l'exemple d'application sur votre machine locale :

    git clone https://github.com/GoogleCloudPlatform/dotnet-docs-samples
    

    Vous pouvez également télécharger l'exemple en tant que fichier zip et l'extraire.

  5. Avec Visual Studio 2017 ou une version ultérieure, ouvrez Spanner.sln, situé dans le répertoire dotnet-docs-samples\spanner\api du dépôt téléchargé, puis compilez l'application.

  6. Accédez au répertoire du dépôt téléchargé contenant l'application compilée. Exemple :

    cd dotnet-docs-samples\spanner\api\Spanner
    

Créer une instance

Lorsque vous utilisez Cloud Spanner pour la première fois, vous devez créer une instance qui alloue les ressources utilisées par les bases de données Cloud Spanner. Lorsque vous créez une instance, vous choisissez une configuration d'instance, qui détermine l'emplacement de stockage de vos données et le nombre de nœuds à utiliser. Ce dernier paramètre définit la quantité de ressources disponibles dans votre instance pour le stockage et la diffusion.

Exécutez la commande suivante pour créer une instance Cloud Spanner dans la région us-central1 avec un nœud :

gcloud spanner instances create test-instance --config=regional-us-central1 `
    --description="Test Instance" --nodes=1

Cette commande crée une instance présentant les caractéristiques suivantes :

  • ID d'instance : test-instance
  • Nom à afficher : Test Instance
  • Configuration d'instance : regional-us-central1 (Les configurations régionales stockent les données dans une région, tandis que les configurations multirégionales les distribuent dans plusieurs régions. Pour en savoir plus, consultez la page Instances).
  • Nombre de nœuds : 1 (node_count correspond à la quantité de ressources de stockage et de diffusion disponibles pour les bases de données de l'instance. Pour en savoir plus, consultez la section Nombre de nœuds).

Vous devriez obtenir le résultat suivant :

Creating instance...done.

Consulter des exemples de fichiers

Le dépôt de fichiers d'exemple contient un exemple illustrant l'utilisation de Cloud Spanner avec C#.

Examinez le fichier spanner/api/Spanner/Program.cs, qui montre comment créer une base de données et modifier un schéma de base de données. Les données utilisent l'exemple de schéma présenté sur la page Schéma et modèle de données.

Créer une base de données

Créez une base de données nommée example-db dans l'instance test-instance en exécutant la commande suivante dans la ligne de commande.

dotnet run createSampleDatabase $env:GOOGLE_PROJECT_ID test-instance example-db

Vous devriez obtenir le résultat suivant :

Created sample database example-db on instance test-instance

Vous venez de créer une base de données Cloud Spanner. Voici le code qui a permis la création de cette base de données.

// Initialize request connection string for database creation.
string connectionString =
    $"Data Source=projects/{projectId}/instances/{instanceId}";
// Make the request.
using (var connection = new SpannerConnection(connectionString))
{
    string createStatement = $"CREATE DATABASE `{databaseId}`";
    var cmd = connection.CreateDdlCommand(createStatement);
    await cmd.ExecuteNonQueryAsync();
}
// Update connection string with Database ID for table creation.
connectionString = connectionString + $"/databases/{databaseId}";
using (var connection = new SpannerConnection(connectionString))
{
    // Define create table statement for table #1.
    string createTableStatement =
   @"CREATE TABLE Singers (
         SingerId INT64 NOT NULL,
         FirstName    STRING(1024),
         LastName STRING(1024),
         ComposerInfo   BYTES(MAX)
     ) PRIMARY KEY (SingerId)";
    // Make the request.
    var cmd = connection.CreateDdlCommand(createTableStatement);
    await cmd.ExecuteNonQueryAsync();
    // Define create table statement for table #2.
    createTableStatement =
    @"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";
    // Make the request.
    cmd = connection.CreateDdlCommand(createTableStatement);
    await cmd.ExecuteNonQueryAsync();
}

Le code définit également deux tables destinées à une application musicale de base : Singers et Albums. Ces tables sont utilisées tout au long de cette page. Consultez l'exemple de schéma si ce n'est pas déjà fait.

L'étape suivante consiste à écrire des données dans la base de données.

Créer un client de base de données

Pour pouvoir effectuer des opérations de lecture ou d'écriture, vous devez créer un objet Spanner​Connection :


using Google.Cloud.Spanner.Data;
using System;
using System.Threading.Tasks;

namespace GoogleCloudSamples.Spanner
{
    public class QuickStart
    {
        static async Task MainAsync()
        {
            string projectId = "YOUR-PROJECT-ID";
            string instanceId = "my-instance";
            string databaseId = "my-database";
            string connectionString =
                $"Data Source=projects/{projectId}/instances/{instanceId}/"
                + $"databases/{databaseId}";
            // Create connection to Cloud Spanner.
            using (var connection = new SpannerConnection(connectionString))
            {
                // Execute a simple SQL statement.
                var cmd = connection.CreateSelectCommand(
                    @"SELECT ""Hello World"" as test");
                using (var reader = await cmd.ExecuteReaderAsync())
                {
                    while (await reader.ReadAsync())
                    {
                        Console.WriteLine(
                            reader.GetFieldValue<string>("test"));
                    }
                }
            }
        }
        public static void Main(string[] args)
        {
            MainAsync().Wait();
        }
    }
}

Un objet Spanner​Connection s'apparente à une connexion à une base de données. Toutes vos interactions avec Cloud Spanner doivent s'effectuer par le biais de cet objet Spanner​Connection.

Pour en savoir plus, consultez la documentation de référence sur Spanner​Connection.

Écrire des données avec le langage LMD

Vous pouvez insérer des données à l'aide du langage de manipulation de données (LMD) dans une transaction en lecture/écriture.

L'exécution d'une instruction LMD s'effectue via la méthode ExecuteNonQueryAsync().

public static async Task WriteUsingDmlCoreAsync(
    string projectId,
    string instanceId,
    string databaseId)
{
    string connectionString =
        $"Data Source=projects/{projectId}/instances/{instanceId}"
        + $"/databases/{databaseId}";

    // Create connection to Cloud Spanner.
    using (var connection =
        new SpannerConnection(connectionString))
    {
        await connection.OpenAsync();

        SpannerCommand cmd = connection.CreateDmlCommand(
            "INSERT Singers (SingerId, FirstName, LastName) VALUES "
               + "(12, 'Melissa', 'Garcia'), "
               + "(13, 'Russell', 'Morales'), "
               + "(14, 'Jacqueline', 'Long'), "
               + "(15, 'Dylan', 'Shaw')");
        int rowCount = await cmd.ExecuteNonQueryAsync();
        Console.WriteLine($"{rowCount} row(s) inserted...");
    }
}

Exécutez l'exemple en utilisant l'argument writeUsingDml.

dotnet run writeUsingDml $env:GOOGLE_PROJECT_ID test-instance example-db

Vous devriez voir les éléments suivants :

4 row(s) inserted...

Écrire des données avec des mutations

Vous pouvez également insérer des données à l'aide de mutations.

Vous pouvez insérer des données à l'aide de la méthode connection.CreateInsertCommand(), qui crée une commande SpannerCommand pour insérer des lignes dans une table. La méthode SpannerCommand.ExecuteNonQueryAsync() ajoute des lignes à la table.

Le code suivant décrit comment insérer des données :

public class Singer
{
    public int SingerId { get; set; }
    public string FirstName { get; set; }
    public string LastName { get; set; }
}

public class Album
{
    public int SingerId { get; set; }
    public int AlbumId { get; set; }
    public string AlbumTitle { get; set; }
}
public static async Task InsertSampleDataAsync(
    string projectId, string instanceId, string databaseId)
{
    const int firstSingerId = 1;
    const int secondSingerId = 2;
    string connectionString =
    $"Data Source=projects/{projectId}/instances/{instanceId}"
    + $"/databases/{databaseId}";
    List<Singer> singers = new List<Singer>
    {
        new Singer { SingerId = firstSingerId, FirstName = "Marc",
            LastName = "Richards" },
        new Singer { SingerId = secondSingerId, FirstName = "Catalina",
            LastName = "Smith" },
        new Singer { SingerId = 3, FirstName = "Alice",
            LastName = "Trentor" },
        new Singer { SingerId = 4, FirstName = "Lea",
            LastName = "Martin" },
        new Singer { SingerId = 5, FirstName = "David",
            LastName = "Lomond" },
    };
    List<Album> albums = new List<Album>
    {
        new Album { SingerId = firstSingerId, AlbumId = 1,
            AlbumTitle = "Total Junk" },
        new Album { SingerId = firstSingerId, AlbumId = 2,
            AlbumTitle = "Go, Go, Go" },
        new Album { SingerId = secondSingerId, AlbumId = 1,
            AlbumTitle = "Green" },
        new Album { SingerId = secondSingerId, AlbumId = 2,
            AlbumTitle = "Forever Hold your Peace" },
        new Album { SingerId = secondSingerId, AlbumId = 3,
            AlbumTitle = "Terrified" },
    };
    // Create connection to Cloud Spanner.
    using (var connection = new SpannerConnection(connectionString))
    {
        await connection.OpenAsync();

        // Insert rows into the Singers table.
        var cmd = connection.CreateInsertCommand("Singers",
            new SpannerParameterCollection
            {
                { "SingerId", SpannerDbType.Int64 },
                { "FirstName", SpannerDbType.String },
                { "LastName", SpannerDbType.String }
            });
        await Task.WhenAll(singers.Select(singer =>
        {
            cmd.Parameters["SingerId"].Value = singer.SingerId;
            cmd.Parameters["FirstName"].Value = singer.FirstName;
            cmd.Parameters["LastName"].Value = singer.LastName;
            return cmd.ExecuteNonQueryAsync();
        }));

        // Insert rows into the Albums table.
        cmd = connection.CreateInsertCommand("Albums",
            new SpannerParameterCollection
            {
                { "SingerId", SpannerDbType.Int64 },
                { "AlbumId", SpannerDbType.Int64 },
                { "AlbumTitle", SpannerDbType.String }
            });
        await Task.WhenAll(albums.Select(album =>
        {
            cmd.Parameters["SingerId"].Value = album.SingerId;
            cmd.Parameters["AlbumId"].Value = album.AlbumId;
            cmd.Parameters["AlbumTitle"].Value = album.AlbumTitle;
            return cmd.ExecuteNonQueryAsync();
        }));
        Console.WriteLine("Inserted data.");
    }
}

Exécutez l'exemple en utilisant l'argument insertSampleData.

dotnet run insertSampleData $env:GOOGLE_PROJECT_ID test-instance example-db

Vous devriez voir les éléments suivants :

Inserted data.

Interroger des données à l'aide de SQL

Cloud Spanner accepte une interface SQL native pour la lecture des données. Vous pouvez accéder à cette interface via la ligne de commande à l'aide de l'outil de ligne de commande gcloud ou de manière automatisée à l'aide de la bibliothèque cliente Cloud Spanner pour C#.

Avec l'outil de ligne de commande

Exécutez l'instruction SQL suivante pour lire les valeurs de toutes les colonnes de la table Albums :

gcloud spanner databases execute-sql example-db --instance=test-instance `
    --sql='SELECT SingerId, AlbumId, AlbumTitle FROM Albums'

Vous devez obtenir le résultat suivant :

SingerId AlbumId AlbumTitle
1        1       Total Junk
1        2       Go, Go, Go
2        1       Green
2        2       Forever Hold Your Peace
2        3       Terrified

Avec la bibliothèque cliente Cloud Spanner pour C#

Vous pouvez non seulement exécuter une instruction SQL en ligne de commande, mais également appliquer la même instruction SQL de manière automatisée à l'aide de la bibliothèque cliente Cloud Spanner pour C#.

Utilisez la méthode ExecuteReaderAsync() pour exécuter la requête SQL.

string connectionString =
$"Data Source=projects/{projectId}/instances/"
+ $"{instanceId}/databases/{databaseId}";
// Create connection to Cloud Spanner.
using (var connection = new SpannerConnection(connectionString))
{
    var cmd = connection.CreateSelectCommand(
        "SELECT SingerId, AlbumId, AlbumTitle FROM Albums");
    using (var reader = await cmd.ExecuteReaderAsync())
    {
        while (await reader.ReadAsync())
        {
            Console.WriteLine("SingerId : "
                + reader.GetFieldValue<string>("SingerId")
                + " AlbumId : "
                + reader.GetFieldValue<string>("AlbumId")
                + " AlbumTitle : "
                + reader.GetFieldValue<string>("AlbumTitle"));
        }
    }
}

Le code ci-dessous permet d'exécuter la requête et d'accéder aux données.

dotnet run querySampleData $env:GOOGLE_PROJECT_ID test-instance example-db

Vous devriez obtenir le résultat suivant :

SingerId: 1 AlbumId: 1 AlbumTitle: Total Junk
SingerId: 1 AlbumId: 2 AlbumTitle: Go, Go, Go
SingerId: 2 AlbumId: 1 AlbumTitle: Green
SingerId: 2 AlbumId: 2 AlbumTitle: Forever Hold your Peace
SingerId: 2 AlbumId: 3 AlbumTitle: Terrified

Requête utilisant un paramètre SQL

Vous pouvez inclure des valeurs personnalisées dans les instructions SQL à l'aide des types SQL compatibles.

Voici un exemple d'utilisation de @lastName en tant que paramètre dans la clause WHERE pour interroger des enregistrements contenant une valeur spécifique pour LastName.

string connectionString =
$"Data Source=projects/{projectId}/instances/{instanceId}"
+ $"/databases/{databaseId}";
// Create connection to Cloud Spanner.
using (var connection = new SpannerConnection(connectionString))
{
    var cmd = connection.CreateSelectCommand(
        "SELECT SingerId, FirstName, LastName FROM Singers "
        + $"WHERE LastName = @lastName",
        new SpannerParameterCollection {
            {"lastName", SpannerDbType.String}});
    cmd.Parameters["lastName"].Value = "Garcia";
    using (var reader = await cmd.ExecuteReaderAsync())
    {
        while (await reader.ReadAsync())
        {
            Console.WriteLine("SingerId : "
            + reader.GetFieldValue<string>("SingerId")
            + " FirstName : "
            + reader.GetFieldValue<string>("FirstName")
            + " LastName : "
            + reader.GetFieldValue<string>("LastName"));
        }
    }
}

Le code ci-dessous permet d'exécuter la requête avec un paramètre et d'accéder aux données :

dotnet run queryWithParameter $env:GOOGLE_PROJECT_ID test-instance example-db

Vous devriez obtenir le résultat suivant :

SingerId : 12 FirstName : Melissa LastName : Garcia

Mettre à jour le schéma de base de données

Supposons que vous deviez ajouter la colonne MarketingBudget à la table Albums. L'ajout d'une colonne à une table existante nécessite une mise à jour du schéma de base de données. Cloud Spanner permet de mettre à jour le schéma d'une base de données pendant que celle-ci continue de diffuser du trafic. Les mises à jour du schéma ne nécessitent pas la mise hors connexion de la base de données et ne verrouillent pas des tables ou des colonnes entières. Vous pouvez continuer à écrire des données dans la base de données pendant ces mises à jour. Pour en savoir plus sur les mises à jour de schéma acceptées et sur les performances liées aux modifications de schéma, consultez la page Mises à jour de schéma.

Ajouter une colonne

Vous pouvez ajouter une colonne à l'aide de l'outil de ligne de commande gcloud, ou bien de manière automatisée, à l'aide de la bibliothèque cliente Cloud Spanner pour C#.

Avec l'outil de ligne de commande

Pour ajouter la colonne à la table, utilisez la commande ALTER TABLE suivante :

gcloud spanner databases ddl update example-db --instance=test-instance `
    --ddl='ALTER TABLE Albums ADD COLUMN MarketingBudget INT64'

Vous devriez obtenir le résultat suivant :

Schema updating...done.

Avec la bibliothèque cliente Cloud Spanner pour C#

Pour modifier le schéma, utilisez CreateDdlCommand() :

// Initialize request argument(s).
string connectionString =
    $"Data Source=projects/{projectId}/instances/"
    + $"{instanceId}/databases/{databaseId}";
string alterStatement =
    "ALTER TABLE Albums ADD COLUMN MarketingBudget INT64";
// Make the request.
using (var connection = new SpannerConnection(connectionString))
{
    var updateCmd = connection.CreateDdlCommand(alterStatement);
    await updateCmd.ExecuteNonQueryAsync();
}
Console.WriteLine("Added the MarketingBudget column.");

Exécutez l'exemple à l'aide de la commande addColumn.

dotnet run addColumn $env:GOOGLE_PROJECT_ID test-instance example-db

Vous devriez obtenir le résultat suivant :

Added the MarketingBudget column.

Écrire des données dans la nouvelle colonne

Le code ci-dessous permet d'écrire des données dans la nouvelle colonne. Il définit MarketingBudget sur 100000 pour la ligne correspondant à la clé Albums(1, 1) et sur 500000 pour la ligne correspondant à la clé Albums(2, 2).

string connectionString =
$"Data Source=projects/{projectId}/instances/{instanceId}"
+ $"/databases/{databaseId}";
// Create connection to Cloud Spanner.
using (var connection = new SpannerConnection(connectionString))
{
    var cmd = connection.CreateUpdateCommand("Albums",
        new SpannerParameterCollection {
            {"SingerId", SpannerDbType.Int64},
            {"AlbumId", SpannerDbType.Int64},
            {"MarketingBudget", SpannerDbType.Int64},
        });
    var cmdLookup =
        connection.CreateSelectCommand("SELECT * FROM Albums");
    using (var reader = await cmdLookup.ExecuteReaderAsync())
    {
        while (await reader.ReadAsync())
        {
            if (reader.GetFieldValue<int>("SingerId") == 1
                && reader.GetFieldValue<int>("AlbumId") == 1)
            {
                cmd.Parameters["SingerId"].Value =
                    reader.GetFieldValue<int>("SingerId");
                cmd.Parameters["AlbumId"].Value =
                    reader.GetFieldValue<int>("AlbumId");
                cmd.Parameters["MarketingBudget"].Value = 100000;
                await cmd.ExecuteNonQueryAsync();
            }
            if (reader.GetInt64(0) == 2 && reader.GetInt64(1) == 2)
            {
                cmd.Parameters["SingerId"].Value =
                    reader.GetFieldValue<int>("SingerId");
                cmd.Parameters["AlbumId"].Value =
                    reader.GetFieldValue<int>("AlbumId");
                cmd.Parameters["MarketingBudget"].Value = 500000;
                await cmd.ExecuteNonQueryAsync();
            }
        }
    }
}
Console.WriteLine("Updated data.");

Exécutez l'exemple à l'aide de la commande writeDataToNewColumn.

dotnet run writeDataToNewColumn $env:GOOGLE_PROJECT_ID test-instance example-db

Vous devriez obtenir le résultat suivant :

Updated data.

Vous pouvez également exécuter une requête SQL pour récupérer les valeurs que vous venez d'écrire.

Le code permettant d'exécuter la requête est présenté ci-dessous.

string connectionString =
$"Data Source=projects/{projectId}/instances/{instanceId}"
+ $"/databases/{databaseId}";
// Create connection to Cloud Spanner.
using (var connection = new SpannerConnection(connectionString))
{
    var cmd =
        connection.CreateSelectCommand("SELECT * FROM Albums");
    using (var reader = await cmd.ExecuteReaderAsync())
    {
        while (await reader.ReadAsync())
        {
            string budget = string.Empty;
            if (reader["MarketingBudget"] != DBNull.Value)
            {
                budget = reader.GetFieldValue<string>("MarketingBudget");
            }
            Console.WriteLine("SingerId : "
            + reader.GetFieldValue<string>("SingerId")
            + " AlbumId : "
            + reader.GetFieldValue<string>("AlbumId")
            + $" MarketingBudget : {budget}");
        }
    }
}

Pour mettre en œuvre cette requête, exécutez l'exemple en utilisant l'argument queryNewColumn.

dotnet run queryNewColumn $env:GOOGLE_PROJECT_ID test-instance example-db

Vous devriez obtenir le résultat suivant :

SingerId : 1 AlbumId : 1 MarketingBudget : 100000
SingerId : 1 AlbumId : 2 MarketingBudget :
SingerId : 2 AlbumId : 1 MarketingBudget :
SingerId : 2 AlbumId : 2 MarketingBudget : 500000
SingerId : 2 AlbumId : 3 MarketingBudget :

Mettre à jour des données

Vous pouvez mettre à jour des données à l'aide du langage LMD dans une transaction en lecture/écriture.

L'exécution d'une instruction LMD s'effectue via la méthode ExecuteNonQueryAsync().

public static async Task WriteWithTransactionUsingDmlCoreAsync(
    string projectId,
    string instanceId,
    string databaseId)
{
    // This sample transfers 200,000 from the MarketingBudget
    // field of the second Album to the first Album. Make sure to run
    // the addColumn and writeDataToNewColumn samples first,
    // in that order.
    string connectionString =
        $"Data Source=projects/{projectId}/instances/{instanceId}"
        + $"/databases/{databaseId}";

    decimal transferAmount = 200000;
    decimal secondBudget = 0;
    decimal firstBudget = 0;

    // Create connection to Cloud Spanner.
    using (var connection =
        new SpannerConnection(connectionString))
    {
        await connection.OpenAsync();

        // Create a readwrite transaction that we'll assign
        // to each SpannerCommand.
        using (var transaction =
                await connection.BeginTransactionAsync())
        {
            // Create statement to select the second album's data.
            var cmdLookup = connection.CreateSelectCommand(
             "SELECT * FROM Albums WHERE SingerId = 2 AND AlbumId = 2");
            cmdLookup.Transaction = transaction;
            // Excecute the select query.
            using (var reader = await cmdLookup.ExecuteReaderAsync())
            {
                while (await reader.ReadAsync())
                {
                    // Read the second album's budget.
                    secondBudget =
                       reader.GetFieldValue<decimal>("MarketingBudget");
                    // Confirm second Album's budget is sufficient and
                    // if not raise an exception. Raising an exception
                    // will automatically roll back the transaction.
                    if (secondBudget < transferAmount)
                    {
                        throw new Exception("The first album's "
                                + $"budget {secondBudget} "
                                + "is less than the "
                                + "amount to transfer.");
                    }
                }
            }
            // Read the first album's budget.
            cmdLookup = connection.CreateSelectCommand(
             "SELECT * FROM Albums WHERE SingerId = 1 and AlbumId = 1");
            cmdLookup.Transaction = transaction;
            using (var reader = await cmdLookup.ExecuteReaderAsync())
            {
                while (await reader.ReadAsync())
                {
                    firstBudget =
                      reader.GetFieldValue<decimal>("MarketingBudget");
                }
            }

            // Update second album to remove the transfer amount.
            secondBudget -= transferAmount;
            SpannerCommand cmd = connection.CreateDmlCommand(
                "UPDATE Albums SET MarketingBudget = @MarketingBudget "
                + "WHERE SingerId = 2 and AlbumId = 2");
            cmd.Parameters.Add("MarketingBudget", SpannerDbType.Int64, secondBudget);
            cmd.Transaction = transaction;
            await cmd.ExecuteNonQueryAsync();
            // Update first album to add the transfer amount.
            firstBudget += transferAmount;
            cmd = connection.CreateDmlCommand(
                "UPDATE Albums SET MarketingBudget = @MarketingBudget "
                + "WHERE SingerId = 1 and AlbumId = 1");
            cmd.Parameters.Add("MarketingBudget", SpannerDbType.Int64, firstBudget);
            cmd.Transaction = transaction;
            await cmd.ExecuteNonQueryAsync();

            await transaction.CommitAsync();
        }
        Console.WriteLine("Transaction complete.");
    }
}

Exécutez l'exemple en utilisant l'argument writeWithTransactionUsingDml.

dotnet run writeWithTransactionUsingDml $env:GOOGLE_PROJECT_ID test-instance example-db

Vous devriez obtenir le résultat suivant :

Transaction complete.

Effectuer de nouvelles tentatives de transactions en lecture/écriture

Cloud Spanner effectue de nouvelles tentatives pour chaque appel réseau et résiste aux pannes du réseau. Toutefois, un blocage peut survenir en cas de fortes contraintes, entraînant la génération, par une transaction Cloud Spanner, d'une SpannerException "Aborted". Pour gérer cette exception, vous devez appliquer une approche de type "nouvelle tentative", comme indiqué ci-dessous, pour réessayer d'exécuter la transaction dans son intégralité.

Premièrement, définissez une méthode à appeler lors de la nouvelle tentative d'exécution de la transaction. L'exemple suivant définit une méthode nommée RetryRobot.

public class RetryRobot
{
    public TimeSpan FirstRetryDelay { get; set; } = TimeSpan.FromSeconds(1000);
    public float DelayMultiplier { get; set; } = 2;
    public int MaxTryCount { get; set; } = 7;
    public Func<Exception, bool> ShouldRetry { get; set; }

    /// <summary>
    /// Retry action when assertion fails.
    /// </summary>
    /// <param name="func"></param>
    public T Eventually<T>(Func<T> func)
    {
        TimeSpan delay = FirstRetryDelay;
        for (int i = 0; ; ++i)
        {
            try
            {
                return func();
            }
            catch (Exception e)
            when (ShouldCatch(e) && i < MaxTryCount)
            {
                Thread.Sleep(delay);
                delay *= (int)DelayMultiplier;
            }
        }
    }

    private bool ShouldCatch(Exception e)
    {
        return ShouldRetry != null && ShouldRetry(e);
    }
}

Ensuite, créez une instance de la méthode RetryRobot, appelée retryRobot, en spécifiant IsTransientSpannerFault() en tant que condition d'erreur devant faire l'objet d'une nouvelle tentative. Puis exécutez l'ensemble de la transaction en utilisant retryRobot.Eventually.

Voici le code pour effectuer une nouvelle tentative :

var retryRobot = new RetryRobot
{
    MaxTryCount = 3,
    DelayMultiplier = 2,
    ShouldRetry = (e) => e.IsTransientSpannerFault()
};

await retryRobot.Eventually(() =>
    ReadWriteWithTransactionAsync(
        projectId, instanceId, databaseId));

Utiliser un index secondaire

Supposons que vous vouliez récupérer toutes les lignes de la table Albums dont les valeurs AlbumTitle sont comprises dans une certaine plage. Vous pouvez lire toutes les valeurs de la colonne AlbumTitle à l'aide d'une instruction SQL ou d'un appel de lecture, puis supprimer les lignes qui ne correspondent pas aux critères. Toutefois, cette analyse complète de la table est coûteuse, en particulier si celle-ci comporte beaucoup de lignes. Vous pouvez accélérer la récupération des lignes lors des recherches effectuées en fonction des colonnes de clé non primaire en créant un index secondaire pour la table.

L'ajout d'un index secondaire à une table existante nécessite une mise à jour du schéma. Comme pour les autres mises à jour de schéma, le service Cloud Spanner permet d'ajouter l'index alors que la base de données continue de diffuser du trafic. Cloud Spanner remplit automatiquement l'index à l'aide de vos données existantes. Les remplissages peuvent prendre quelques minutes. Toutefois, ce processus ne requiert pas la mise hors connexion de la base de données et ne vous empêche pas d'écrire dans la table indexée. Pour en savoir plus, consultez la section relative au remplissage des index.

Une fois l'index secondaire ajouté, Cloud Spanner l'utilise automatiquement pour les requêtes SQL susceptibles de s'exécuter plus rapidement avec l'index. Si vous utilisez l'interface de lecture, vous devez spécifier l'index que vous souhaitez utiliser.

Ajouter un index secondaire

Vous pouvez ajouter un index à l'aide de l'outil de ligne de commande gcloud, ou bien de manière automatisée, à l'aide de la bibliothèque cliente Cloud Spanner pour C#.

Avec l'outil de ligne de commande

Exécutez la commande CREATE INDEX suivante pour ajouter un index à la base de données :

gcloud spanner databases ddl update example-db --instance=test-instance `
    --ddl='CREATE INDEX AlbumsByAlbumTitle ON Albums(AlbumTitle)'

Vous devriez obtenir le résultat suivant :

Schema updating...done.

Avec la bibliothèque cliente Cloud Spanner pour C#

Utilisez CreateDdlCommand() pour ajouter un index :

// Initialize request argument(s).
string connectionString =
    $"Data Source=projects/{projectId}/instances/"
    + $"{instanceId}/databases/{databaseId}";
string createStatement =
    "CREATE INDEX AlbumsByAlbumTitle ON Albums(AlbumTitle)";
// Make the request.
using (var connection = new SpannerConnection(connectionString))
{
    var createCmd = connection.CreateDdlCommand(createStatement);
    await createCmd.ExecuteNonQueryAsync();
}
Console.WriteLine("Added the AlbumsByAlbumTitle index.");

Exécutez l'exemple à l'aide de la commande addIndex.

  dotnet run addIndex $env:GOOGLE_PROJECT_ID test-instance example-db

L'ajout d'un index peut prendre quelques minutes. Une fois l'index ajouté, vous devriez obtenir le résultat suivant :

  Added the AlbumsByAlbumTitle index.

Ajouter un index avec une clause STORING

Vous avez peut-être remarqué que l'exemple ci-dessus n'incluait pas la lecture de la colonne MarketingBudget. En effet, l'interface de lecture de Cloud Spanner ne permet pas de joindre un index à une table de données pour rechercher des valeurs qui ne sont pas stockées dans l'index.

Créez une autre définition de l'index AlbumsByAlbumTitle qui stocke dans l'index une copie de MarketingBudget.

Avec l'outil de ligne de commande

gcloud spanner databases ddl update example-db --instance=test-instance `
    --ddl='CREATE INDEX AlbumsByAlbumTitle2 ON Albums(AlbumTitle) STORING (MarketingBudget)'

L'ajout d'un index peut prendre quelques minutes. Une fois l'index ajouté, vous devriez obtenir le résultat suivant :

Schema updating...done.

Avec la bibliothèque cliente Cloud Spanner pour C#

Pour ajouter un index avec une clause STORING, utilisez la méthode CreateDdlCommand() :

// Initialize request argument(s).
string connectionString =
    $"Data Source=projects/{projectId}/instances/"
    + $"{instanceId}/databases/{databaseId}";
string createStatement =
    "CREATE INDEX AlbumsByAlbumTitle2 ON Albums(AlbumTitle) "
    + "STORING (MarketingBudget)";
// Make the request.
using (var connection = new SpannerConnection(connectionString))
{
    var createCmd = connection.CreateDdlCommand(createStatement);
    await createCmd.ExecuteNonQueryAsync();
}
Console.WriteLine("Added the AlbumsByAlbumTitle2 index.");

Exécutez l'exemple à l'aide de la commande addStoringIndex.

dotnet run addStoringIndex $env:GOOGLE_PROJECT_ID test-instance example-db

Vous devriez obtenir le résultat suivant :

Added the AlbumsByAlbumTitle2 index.

Vous pouvez maintenant exécuter une opération de lecture permettant de récupérer toutes les colonnes AlbumId, AlbumTitle et MarketingBudget à partir de l'index AlbumsByAlbumTitle2 :

Lisez des données à l'aide de l'index de stockage que vous avez créé en exécutant une requête qui spécifie explicitement ce nouvel index :

string connectionString =
$"Data Source=projects/{projectId}/instances/{instanceId}"
+ $"/databases/{databaseId}";
// Create connection to Cloud Spanner.
using (var connection = new SpannerConnection(connectionString))
{
    var cmd = connection.CreateSelectCommand(
        "SELECT AlbumId, AlbumTitle, MarketingBudget FROM Albums@ "
        + "{FORCE_INDEX=AlbumsByAlbumTitle2} "
        + $"WHERE AlbumTitle >= @startTitle "
        + $"AND AlbumTitle < @endTitle",
        new SpannerParameterCollection {
            {"startTitle", SpannerDbType.String},
            {"endTitle", SpannerDbType.String} });
    cmd.Parameters["startTitle"].Value = startTitle;
    cmd.Parameters["endTitle"].Value = endTitle;
    using (var reader = await cmd.ExecuteReaderAsync())
    {
        while (await reader.ReadAsync())
        {
            Console.WriteLine("AlbumId : "
            + reader.GetFieldValue<string>("AlbumId")
            + " AlbumTitle : "
            + reader.GetFieldValue<string>("AlbumTitle")
            + " MarketingBudget : "
            + reader.GetFieldValue<string>("MarketingBudget"));
        }
    }
}

Exécutez l'exemple à l'aide de la commande queryDataWithStoringIndex.

dotnet run queryDataWithStoringIndex $env:GOOGLE_PROJECT_ID test-instance example-db

Un résultat semblable à celui-ci s'affiche :

AlbumId : 2 AlbumTitle : Forever Hold your Peace MarketingBudget : 300000
AlbumId : 2 AlbumTitle : Go, Go, Go MarketingBudget : 300000

Récupérer des données à l'aide de transactions en lecture seule

Supposons que vous souhaitiez exécuter plusieurs opérations de lecture avec le même horodatage. Les transactions en lecture seule tiennent compte d'un préfixe cohérent de l'historique de commit des transactions, de sorte que votre application obtienne toujours des données cohérentes. Utilisez le champ d'application TransactionScope() du framework .NET avec OpenAsReadOnlyAsync() pour exécuter des transactions en lecture seule.

L'exemple ci-dessous montre comment exécuter une requête et effectuer une lecture dans la même transaction en lecture seule.

.NET Standard 2.0

string connectionString =
$"Data Source=projects/{projectId}/instances/{instanceId}"
+ $"/databases/{databaseId}";
// Gets a transaction object that captures the database state
// at a specific point in time.
using (TransactionScope scope = new TransactionScope(
    TransactionScopeAsyncFlowOption.Enabled))
{
    // Create connection to Cloud Spanner.
    using (var connection = new SpannerConnection(connectionString))
    {
        // Open the connection, making the implicitly created
        // transaction read only when it connects to the outer
        // transaction scope.
        await connection.OpenAsReadOnlyAsync()
            .ConfigureAwait(false);
        var cmd = connection.CreateSelectCommand(
            "SELECT SingerId, AlbumId, AlbumTitle FROM Albums");
        // Read #1.
        using (var reader = await cmd.ExecuteReaderAsync())
        {
            while (await reader.ReadAsync())
            {
                Console.WriteLine("SingerId : "
                    + reader.GetFieldValue<string>("SingerId")
                    + " AlbumId : "
                    + reader.GetFieldValue<string>("AlbumId")
                    + " AlbumTitle : "
                    + reader.GetFieldValue<string>("AlbumTitle"));
            }
        }
        // Read #2. Even if changes occur in-between the reads,
        // the transaction ensures that Read #1 and Read #2
        // return the same data.
        using (var reader = await cmd.ExecuteReaderAsync())
        {
            while (await reader.ReadAsync())
            {
                Console.WriteLine("SingerId : "
                    + reader.GetFieldValue<string>("SingerId")
                    + " AlbumId : "
                    + reader.GetFieldValue<string>("AlbumId")
                    + " AlbumTitle : "
                    + reader.GetFieldValue<string>("AlbumTitle"));
            }
        }
    }
    scope.Complete();
    Console.WriteLine("Transaction complete.");
}

.NET Standard 1.5

string connectionString =
    $"Data Source=projects/{projectId}/instances/{instanceId}"
    + $"/databases/{databaseId}";

// Create connection to Cloud Spanner.
using (var connection = new SpannerConnection(connectionString))
{
    await connection.OpenAsync();

    // Open a new read only transaction.
    using (var transaction =
        await connection.BeginReadOnlyTransactionAsync())
    {
        var cmd = connection.CreateSelectCommand(
            "SELECT SingerId, AlbumId, AlbumTitle FROM Albums");
        cmd.Transaction = transaction;

        // Read #1.
        using (var reader = await cmd.ExecuteReaderAsync())
        {
            while (await reader.ReadAsync())
            {
                Console.WriteLine("SingerId : "
                    + reader.GetFieldValue<string>("SingerId")
                    + " AlbumId : "
                    + reader.GetFieldValue<string>("AlbumId")
                    + " AlbumTitle : "
                    + reader.GetFieldValue<string>("AlbumTitle"));
            }
        }
        // Read #2. Even if changes occur in-between the reads,
        // the transaction ensures that Read #1 and Read #2
        // return the same data.
        using (var reader = await cmd.ExecuteReaderAsync())
        {
            while (await reader.ReadAsync())
            {
                Console.WriteLine("SingerId : "
                    + reader.GetFieldValue<string>("SingerId")
                    + " AlbumId : "
                    + reader.GetFieldValue<string>("AlbumId")
                    + " AlbumTitle : "
                    + reader.GetFieldValue<string>("AlbumTitle"));
            }
        }
    }
}
Console.WriteLine("Transaction complete.");

Exécutez l'exemple à l'aide de la commande queryDataWithTransaction.

dotnet run queryDataWithTransaction $env:GOOGLE_PROJECT_ID test-instance example-db

Un résultat semblable à celui-ci s'affiche :

SingerId : 2 AlbumId : 2 AlbumTitle : Forever Hold your Peace
SingerId : 1 AlbumId : 2 AlbumTitle : Go, Go, Go
SingerId : 2 AlbumId : 1 AlbumTitle : Green
SingerId : 2 AlbumId : 3 AlbumTitle : Terrified
SingerId : 1 AlbumId : 1 AlbumTitle : Total Junk
SingerId : 2 AlbumId : 2 AlbumTitle : Forever Hold your Peace
SingerId : 1 AlbumId : 2 AlbumTitle : Go, Go, Go
SingerId : 2 AlbumId : 1 AlbumTitle : Green
SingerId : 2 AlbumId : 3 AlbumTitle : Terrified
SingerId : 1 AlbumId : 1 AlbumTitle : Total Junk

Nettoyage

Pour éviter que des ressources supplémentaires soient facturées sur votre compte Cloud Billing, supprimez la base de données et supprimez l'instance que vous avez créée.

Supprimer la base de données

Si vous supprimez une instance, toutes les bases de données qu'elle contient sont automatiquement supprimées. Cette étape montre comment supprimer une base de données sans supprimer l'instance. Des frais continueront à vous être facturés pour cette dernière.

Avec l'outil de ligne de commande

gcloud spanner databases delete example-db --instance=test-instance

Utiliser Cloud Console

  1. Accédez à la page Instances Cloud Spanner dans Google Cloud Console.

    Accéder à la page Instances

  2. Cliquez sur l'instance.

  3. Cliquez sur la base de données que vous souhaitez supprimer.

  4. Sur la page Détails de la base de données, cliquez sur Supprimer.

  5. Confirmez que vous souhaitez supprimer la base de données, puis cliquez sur Supprimer.

Supprimer l'instance

La suppression d'une instance supprime automatiquement toutes les bases de données créées dans cette instance.

Avec l'outil de ligne de commande

gcloud spanner instances delete test-instance

Utiliser Cloud Console

  1. Accédez à la page Instances Cloud Spanner dans Google Cloud Console.

    Accéder à la page Instances

  2. Cliquez sur votre instance.

  3. Cliquez sur Supprimer.

  4. Confirmez que vous souhaitez supprimer l'instance, puis cliquez sur Supprimer.

Étapes suivantes

  • Accédez à Cloud Spanner dans une instance de machine virtuelle : créez une instance de machine virtuelle ayant accès à votre base de données Cloud Spanner.
  • Obtenez davantage d'informations concernant les identifiants d'autorisation et d'authentification sur la page Premiers pas avec l'authentification.
  • Découvrez les concepts liés à Cloud Spanner.