Snabbstart: Skapa en Go-app med `gocql` klienten för att hantera Azure Cosmos DB för Apache Cassandra-data

Artikel
04/06/2023

GÄLLER FÖR: Cassandra

Azure Cosmos DB är en databastjänst med flera modeller som gör att du snabbt kan skapa och köra frågor mot dokument-, tabell-, nyckelvärdes- och grafdatabaser med global distribution och vågrät skalning. I den här snabbstarten börjar du med att skapa ett Azure Cosmos DB för Apache Cassandra-konto. Sedan kör du ett Go-program för att skapa ett Cassandra-nyckelutrymme, en tabell och köra några åtgärder. Den här Go-appen använder gocql, som är en Cassandra-klient för språket Go.

Förutsättningar

Ett Azure-konto med en aktiv prenumeration. Skapa en kostnadsfritt. Eller prova Azure Cosmos DB kostnadsfritt utan en Azure-prenumeration.
Gå installerat på datorn och en fungerande kunskap om Go.
Git.

Skapa ett databaskonto

Innan du kan skapa en databas måste du skapa ett Cassandra-konto med Azure Cosmos DB.

Välj Skapa en resurs på Azure Portal-menyn eller på sidan Start.
På sidan Nytt söker du efter och väljer Azure Cosmos DB.
På sidan Azure Cosmos DB väljer du Skapa.
På API-sidan väljer du Skapa under avsnittet Cassandra .

API:et avgör vilken typ av konto som skapas. Azure Cosmos DB innehåller fem API:er: NoSQL för dokumentdatabaser, Gremlin för grafdatabaser, MongoDB för dokumentdatabaser, Azure Table och Cassandra. Du måste skapa ett separat konto för varje API.

Välj Cassandra eftersom du i den här snabbstarten skapar en tabell som fungerar med API:et för Cassandra.

Läs mer om API:et för Cassandra.

På sidan Skapa Azure Cosmos DB-konto anger du de grundläggande inställningarna för det nya Azure Cosmos DB-kontot.

Inställning	Värde	Beskrivning
Prenumeration	Din prenumeration	Välj den Azure-prenumeration som ska användas för det här Azure Cosmos DB-kontot.
Resursgrupp	Skapa ny Ange sedan samma namn som Kontonamn	Välj Skapa ny. Ange sedan ett nytt resursgruppnamn för ditt konto. För enkelhetens skull använder du samma namn som ditt Azure Cosmos DB-kontonamn.
Account Name	Ange ett unikt namn	Ange ett unikt namn som identifierar ditt Azure Cosmos DB-konto. Konto-URI:n läggs cassandra.cosmos.azure.com till ditt unika kontonamn. Kontonamnet får endast innehålla gemener, siffror och bindestreck (-) och måste vara mellan 3 och 31 tecken långt.
Location	Den region som är närmast dina användare	Välj en geografisk plats som värd för ditt Azure Cosmos DB-konto. Använd den plats som är närmast dina användare för att ge dem så snabb åtkomst till data som möjligt.
Kapacitetsläge	Etablerat dataflöde eller serverlöst	Välj Etablerat dataflöde för att skapa ett konto i etablerat dataflödesläge . Välj Serverlös för att skapa ett konto i serverlöst läge.
Tillämpa rabatt på den kostnadsfria nivån för Azure Cosmos DB	Använd eller Använd inte	Med den kostnadsfria Azure Cosmos DB-nivån får du de första 1 000 RU/s och 25 GB lagringsutrymme kostnadsfritt på ett konto. Läs mer om den kostnadsfria nivån.
Begränsa det totala kontodataflödet	Välj för att begränsa dataflödet för kontot	Detta är användbart om du vill begränsa det totala dataflödet för kontot till ett visst värde.

Anteckning

Du kan ha upp till ett Azure Cosmos DB-konto på kostnadsfri nivå per Azure-prenumeration och måste anmäla dig när du skapar kontot. Om du inte ser alternativet att tillämpa rabatten på den kostnadsfria nivån innebär det att ett annat konto i prenumerationen redan har aktiverats med den kostnadsfria nivån.

Den nya kontosidan för Azure Cosmos DB för Apache Cassandra

Konfigurera följande information på fliken Global distribution . Du kan lämna standardvärdena i den här snabbstarten:

Inställningen	Värde	Beskrivning
Geo-redundans	Inaktivera	Aktivera eller inaktivera global distribution på ditt konto genom att koppla ihop din region med en parregion. Du kan lägga till fler regioner i ditt konto senare.
Skrivåtgärder för flera regioner	Inaktivera	Med skrivfunktioner i flera regioner kan du dra nytta av det etablerade dataflödet för dina databaser och containrar över hela världen.
Tillgänglighetszoner	Inaktivera	Tillgänglighetszoner är isolerade platser i en Azure-region. Varje zon utgörs av ett eller flera datacenter som är utrustade med oberoende kraft, kylning och nätverk.

Anteckning

Följande alternativ är inte tillgängliga om du väljer Serverlös som Kapacitetsläge:

Tillämpa rabatt för kostnadsfri nivå
Geo-redundans
Skrivåtgärder för flera regioner

Du kan också konfigurera ytterligare information på följande flikar:
- Nätverk – Konfigurera åtkomst från ett virtuellt nätverk.
- Säkerhetskopieringspolicy – Konfigurera antingen periodisk eller kontinuerlig säkerhetskopieringspolicy.
- Kryptering – Använd antingen tjänsthanterad nyckel eller en kundhanterad nyckel.
- Taggar – Taggar är namn/värde-par som gör att du kan kategorisera resurser och visa konsoliderad fakturering genom att tillämpa samma tagg på flera resurser och resursgrupper.
Välj Granska + skapa.
Granska kontoinställningarna och välj sedan Skapa. Det tar några minuter att skapa kontot. Vänta tills portalsidan visar meddelandet Distributionen är klar.
Välj Gå till resurs för att gå till sidan för Azure Cosmos DB-kontot.

Klona exempelprogrammet

Börja med att klona programmet från GitHub.

Öppna en kommandotolk och skapa en ny mapp med namnet git-samples.
```
md "C:\git-samples"
```
Öppna ett git-terminalfönster, till exempel git bash. cd Använd kommandot för att ändra till den nya mappen och installera exempelappen.
```
cd "C:\git-samples"
```
Klona exempellagringsplatsen med följande kommando. Detta kommando skapar en kopia av exempelappen på din dator.
```
git clone https://github.com/Azure-Samples/azure-cosmos-db-cassandra-go-getting-started.git
```

Granska koden

Det här är valfritt. Om du är intresserad av att lära dig hur koden skapar databasresurserna kan du granska följande kodfragment. Annars kan du gå vidare till Kör programmet

Funktionen GetSession (del av utils\utils.go) returnerar en *gocql.Session som används för att köra klusteråtgärder, till exempel infoga, hitta osv.

func GetSession(cosmosCassandraContactPoint, cosmosCassandraPort, cosmosCassandraUser, cosmosCassandraPassword string) *gocql.Session {
    clusterConfig := gocql.NewCluster(cosmosCassandraContactPoint)
    port, err := strconv.Atoi(cosmosCassandraPort)
    
    clusterConfig.Authenticator = gocql.PasswordAuthenticator{Username: cosmosCassandraUser, Password: cosmosCassandraPassword}
    clusterConfig.Port = port
    clusterConfig.SslOpts = &gocql.SslOptions{Config: &tls.Config{MinVersion: tls.VersionTLS12}}
    clusterConfig.ProtoVersion = 4
    
    session, err := clusterConfig.CreateSession()
    ...
    return session
}

Azure Cosmos DB Cassandra-värden skickas till gocql.NewCluster funktionen för att hämta en *gocql.ClusterConfig struct som sedan konfigureras för att använda användarnamn, lösenord, port och lämplig TLS-version (HTTPS/SSL/TLS-kryptering Säkerhetskrav)

Funktionen GetSession anropas sedan från main funktionen (main.go).

func main() {
    session := utils.GetSession(cosmosCassandraContactPoint, cosmosCassandraPort, cosmosCassandraUser, cosmosCassandraPassword)
    defer session.Close()
    ...
}

Anslutningsinformationen och autentiseringsuppgifterna accepteras i form av miljövariabler (matchas i init metoden)

func init() {
    cosmosCassandraContactPoint = os.Getenv("COSMOSDB_CASSANDRA_CONTACT_POINT")
    cosmosCassandraPort = os.Getenv("COSMOSDB_CASSANDRA_PORT")
    cosmosCassandraUser = os.Getenv("COSMOSDB_CASSANDRA_USER")
    cosmosCassandraPassword = os.Getenv("COSMOSDB_CASSANDRA_PASSWORD")

    if cosmosCassandraContactPoint == "" || cosmosCassandraUser == "" || cosmosCassandraPassword == "" {
        log.Fatal("missing mandatory environment variables")
    }
}

Den används sedan för att köra olika åtgärder (del av operations\setup.go) på Azure Cosmos DB från och med keyspace och table skapande.

Som namnet antyder DropKeySpaceIfExists släpper funktionen den keyspace enda om den finns.

const dropKeyspace = "DROP KEYSPACE IF EXISTS %s"

func DropKeySpaceIfExists(keyspace string, session *gocql.Session) {
    err := utils.ExecuteQuery(fmt.Sprintf(dropKeyspace, keyspace), session)
    if err != nil {
        log.Fatal("Failed to drop keyspace", err)
    }
    log.Println("Keyspace dropped")
}

CreateKeySpace -funktionen används för att skapa keyspace (user_profile)

const createKeyspace = "CREATE KEYSPACE %s WITH REPLICATION = { 'class' : 'NetworkTopologyStrategy', 'datacenter1' : 1 }"

func CreateKeySpace(keyspace string, session *gocql.Session) {
    err := utils.ExecuteQuery(fmt.Sprintf(createKeyspace, keyspace), session)
    if err != nil {
        log.Fatal("Failed to create keyspace", err)
    }
    log.Println("Keyspace created")
}

Detta följs av tabellskapande (user) som hanteras av CreateUserTable funktionen

const createTable = "CREATE TABLE %s.%s (user_id int PRIMARY KEY, user_name text, user_bcity text)"

func CreateUserTable(keyspace, table string, session *gocql.Session) {
    err := session.Query(fmt.Sprintf(createTable, keyspace, table)).Exec()
    if err != nil {
        log.Fatal("failed to create table ", err)
    }
    log.Println("Table created")
}

När nyckelutrymmet och tabellen har skapats anropar vi CRUD-åtgärder (del av operations\crud.go).

InsertUser används för att skapa en User. Den anger användarinformationen (ID, namn och ort) som frågeargument med hjälp av Bind

const createQuery = "INSERT INTO %s.%s (user_id, user_name , user_bcity) VALUES (?,?,?)"

func InsertUser(keyspace, table string, session *gocql.Session, user model.User) {
    err := session.Query(fmt.Sprintf(createQuery, keyspace, table)).Bind(user.ID, user.Name, user.City).Exec()
    if err != nil {
        log.Fatal("Failed to create user", err)
    }
    log.Println("User created")
}

FindUser används för att söka efter en användare (model\user.go) med hjälp av ett specifikt användar-ID medan Scan binder användarattributen (som returneras av Cassandra) till enskilda variabler (userid, name, city) – det är bara ett av de sätt på vilka du kan använda resultatet som sökresultat

const selectQuery = "SELECT * FROM %s.%s where user_id = ?"

func FindUser(keyspace, table string, id int, session *gocql.Session) model.User {
    var userid int
    var name, city string
    err := session.Query(fmt.Sprintf(selectQuery, keyspace, table)).Bind(id).Scan(&userid, &name, &city)

    if err != nil {
        if err == gocql.ErrNotFound {
            log.Printf("User with id %v does not exist\n", id)
        } else {
            log.Printf("Failed to find user with id %v - %v\n", id, err)
        }
    }
    return model.User{ID: userid, Name: name, City: city}
}

FindAllUsers används för att hämta alla användare. SliceMap används som en förkortning för att hämta all användarens information i form av en del av maps. Tänk på var och en map som nyckel/värde-par där kolumnnamnet (till exempel user_id) är nyckeln tillsammans med dess respektive värde.

const findAllUsersQuery = "SELECT * FROM %s.%s"

func FindAllUsers(keyspace, table string, session *gocql.Session) []model.User {
    var users []model.User
    results, _ := session.Query(fmt.Sprintf(findAllUsersQuery, keyspace, table)).Iter().SliceMap()

    for _, u := range results {
        users = append(users, mapToUser(u))
    }
    return users
}

Varje map användarinformation konverteras till en User användningsfunktion mapToUser som helt enkelt extraherar värdet från dess respektive kolumn och använder det för att skapa en instans av structen User

func mapToUser(m map[string]interface{}) model.User {
    id, _ := m["user_id"].(int)
    name, _ := m["user_name"].(string)
    city, _ := m["user_bcity"].(string)

    return model.User{ID: id, Name: name, City: city}
}

Kör programmet

Som tidigare nämnts accepterar programmet anslutningar och autentiseringsuppgifter i formatet miljövariabler.

I ditt Azure Cosmos DB-konto i Azure Portal väljer du Anslutningssträng.

Kopiera värdena för följande attribut (CONTACT POINT, PORToch USERNAME ) och PRIMARY PASSWORDange dem till respektive miljövariabler

set COSMOSDB_CASSANDRA_CONTACT_POINT=<value for "CONTACT POINT">
set COSMOSDB_CASSANDRA_PORT=<value for "PORT">
set COSMOSDB_CASSANDRA_USER=<value for "USERNAME">
set COSMOSDB_CASSANDRA_PASSWORD=<value for "PRIMARY PASSWORD">

I terminalfönstret ändrar du till rätt mapp. Exempel:

cd "C:\git-samples\azure-cosmosdb-cassandra-go-getting-started"

Kör följande kommando i terminalen för att starta programmet.

go run main.go

Terminalfönstret visar meddelanden för de olika åtgärderna, inklusive nyckelutrymme och tabellkonfiguration, användarskapande osv.
I Datautforskaren på Azure-portalen kan du fråga, ändra och arbeta med dessa nya data.

Granska serviceavtal i Azure-portalen

Azure Portal övervakar dataflöde, lagring, tillgänglighet, svarstid och konsekvens för ditt Azure Cosmos DB-konto. Diagram för mått som är associerade med ett serviceavtal för Azure Cosmos DB (SLA) visar SLA-värdet jämfört med faktiska prestanda. Den här måttsviten gör övervakningen av serviceavtalen transparent.

Så här granskar du mått och serviceavtal:

Välj Mått i navigeringsmenyn för ditt Azure Cosmos DB-konto.
Välj en flik, till exempel Svarstid, och välj en tidsram till höger. Jämför linjerna Actual och SLA i diagrammen.
Granska måtten på de andra flikarna.

Rensa resurser

När du är klar med din app och ditt Azure Cosmos DB-konto kan du ta bort de Azure-resurser som du skapade så att du inte debiteras mer. Ta bort resurser:

I Azure Portal sökfältet söker du efter och väljer Resursgrupper.
I listan väljer du den resursgrupp som du skapade för den här snabbstarten.
På resursgruppens översiktssida väljer du Ta bort resursgrupp.
I nästa fönster anger du namnet på resursgruppen som ska tas bort och väljer sedan Ta bort.

Nästa steg

I den här snabbstarten har du lärt dig hur du skapar ett Azure Cosmos DB-konto med API för Cassandra och kör en Go-app som skapar en Cassandra-databas och container. Nu kan du importera ytterligare data till ditt Azure Cosmos DB-konto.

Importera Cassandra-data till Azure Cosmos DB

Snabbstart: Skapa en Go-app med gocql klienten för att hantera Azure Cosmos DB för Apache Cassandra-data