Rychlý start: Sestavení aplikace v Go s klientem `gocql` pro správu dat Azure Cosmos DB pro Apache Cassandra

Článek
03/22/2023

PLATÍ PRO: Cassandra

Azure Cosmos DB je vícemodelová databázová služba, která umožňuje rychle vytvářet a dotazovat databáze dokumentů, tabulek, klíč-hodnota a grafů s možnostmi globální distribuce a horizontálního škálování. V tomto rychlém startu začnete vytvořením účtu Azure Cosmos DB for Apache Cassandra. Potom spustíte aplikaci Go, která vytvoří prostor klíčů Cassandra, tabulku a provede několik operací. Tato aplikace v Go používá gocql, což je klient Cassandra pro jazyk Go.

Požadavky

Účet Azure s aktivním předplatným. Vytvořte si ho zdarma. Nebo vyzkoušejte službu Azure Cosmos DB zdarma bez předplatného Azure.
Nainstalujte aplikaci Go do počítače a funkční znalost jazyka Go.
Git.

Vytvoření účtu databáze

Než budete moct vytvořit databázi, musíte vytvořit účet Cassandra ve službě Azure Cosmos DB.

V nabídce Azure Portal nebo na domovské stránce vyberte Vytvořit prostředek.
Na stránce Nový vyhledejte a vyberte Azure Cosmos DB.
Na stránce Azure Cosmos DB vyberte Vytvořit.
Na stránce rozhraní API vyberte Vytvořit v části Cassandra .

Rozhraní API určuje typ účtu, který se má vytvořit. Azure Cosmos DB poskytuje pět rozhraní API: NoSQL pro databáze dokumentů, Gremlin pro databáze grafů, MongoDB pro databáze dokumentů, Azure Table a Cassandra. Pro každé rozhraní API musíte vytvořit samostatný účet.

Vyberte Cassandra, protože v tomto rychlém startu vytváříte tabulku, která funguje s rozhraním API pro Cassandra.

Přečtěte si další informace o rozhraní API pro Cassandra.

Na stránce Vytvořit účet služby Azure Cosmos DB zadejte základní nastavení nového účtu služby Azure Cosmos DB.

Nastavení	Hodnota	Popis
Předplatné	Vaše předplatné	Vyberte předplatné Azure, které chcete pro tento účet služby Azure Cosmos DB použít.
Skupina prostředků	Vytvořit nový Pak zadejte stejný název jako Název účtu.	Vyberte, že chcete vytvořit novou IP adresu. Pak pro svůj účet zadejte nový název skupiny prostředků. Pro zjednodušení použijte stejný název jako název účtu služby Azure Cosmos DB.
Account Name	Zadejte jedinečný název.	Zadejte jedinečný název, který identifikuje váš účet služby Azure Cosmos DB. Identifikátor URI vašeho účtu se cassandra.cosmos.azure.com připojí k jedinečnému názvu účtu. Název účtu může obsahovat pouze malá písmena, číslice a spojovníky (-) a musí být dlouhý 3 až 31 znaků.
Umístění	Oblast nejbližší vašim uživatelům	Vyberte zeměpisné umístění, ve kterém chcete účet služby Azure Cosmos DB hostovat. Použijte umístění, které je nejblíže vašim uživatelům, abyste jim poskytli nejrychlejší přístup k datům.
Režim kapacity	Zřízená propustnost nebo bezserverová	Vyberte Zřízená propustnost a vytvořte účet v režimu zřízené propustnosti . Výběrem možnosti Bezserverový vytvořte účet v bezserverovém režimu.
Uplatnění slevy na úrovni Free služby Azure Cosmos DB	Použít nebo Neaplikovat	Se službou Azure Cosmos DB úrovně Free získáte prvních 1 000 RU/s a 25 GB úložiště zdarma v rámci účtu. Přečtěte si další informace o úrovni Free.
Omezení celkové propustnosti účtu	Vyberte, pokud chcete omezit propustnost účtu.	To je užitečné, pokud chcete omezit celkovou propustnost účtu na určitou hodnotu.

Poznámka

Pro každé předplatné Azure můžete mít až jeden účet služby Azure Cosmos DB úrovně Free a při vytváření účtu musíte vyjádřit výslovný souhlas. Pokud možnost uplatnění slevy na úrovni Free nevidíte, znamená to, že úroveň Free už má povolený jiný účet v předplatném.

Stránka nového účtu pro službu Azure Cosmos DB for Apache Cassandra

Na kartě Globální distribuce nakonfigurujte následující podrobnosti. Pro účely tohoto rychlého startu můžete ponechat výchozí hodnoty:

Nastavení	Hodnota	Popis
Geografická redundance	Zakázat	Povolte nebo zakažte globální distribuci ve svém účtu spárováním oblasti s párovací oblastí. Později můžete ke svému účtu přidat další oblasti.
Zápisy do více oblastí	Zakázat	Funkce zápisu do více oblastí umožňuje využívat zřízenou propustnost pro vaše databáze a kontejnery po celém světě.
Zóny dostupnosti	Zakázat	Zóny dostupnosti jsou izolovaná umístění v rámci oblasti Azure. Každou zónu tvoří jedno nebo několik datacenter vybavených nezávislým napájením, chlazením a sítí.

Poznámka

Následující možnosti nejsou k dispozici, pokud jako režim kapacity vyberete Bezserverový:

Použít slevu založenou na bezplatné úrovni
Geografická redundance
Zápisy do více oblastí

Volitelně můžete nakonfigurovat další podrobnosti na následujících kartách:
- Sítě – Nakonfigurujte přístup z virtuální sítě.
- Zásady zálohování – Nakonfigurujte zásady pravidelného nebo průběžného zálohování.
- Šifrování – Použijte buď klíč spravovaný službou, nebo klíč spravovaný zákazníkem.
- Značky – Značky jsou páry název/hodnota, které umožňují kategorizovat prostředky a zobrazit konsolidovanou fakturaci použitím stejné značky na více prostředků a skupin prostředků.
Vyberte Zkontrolovat a vytvořit.
Zkontrolujte nastavení účtu a pak vyberte Vytvořit. Vytvoření účtu trvá několik minut. Počkejte, až se na stránce portálu zobrazí Vaše nasazení je dokončené.
Výběrem možnosti Přejít k prostředku přejděte na stránku účtu služby Azure Cosmos DB.

Klonování ukázkové aplikace

Začněte klonováním aplikace z GitHubu.

Otevřete příkazový řádek a vytvořte novou složku s názvem git-samples.
```
md "C:\git-samples"
```
Otevřete okno terminálu Git, například git bash. Pomocí příkazu cd přejděte do nové složky a nainstalujte ukázkovou aplikaci.
```
cd "C:\git-samples"
```
Ukázkové úložiště naklonujete spuštěním následujícího příkazu. Tento příkaz vytvoří na vašem počítači kopii ukázkové aplikace.
```
git clone https://github.com/Azure-Samples/azure-cosmos-db-cassandra-go-getting-started.git
```

Kontrola kódu

Tento krok je volitelný. Pokud se chcete dozvědět, jak kód vytváří prostředky databáze, můžete si projít následující fragmenty kódu. V opačném případě můžete přeskočit k části Spuštění aplikace.

Funkce GetSession (část ) utils\utils.govrátí hodnotu *gocql.Session , která se používá k provádění operací clusteru, jako je vložení, hledání atd.

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
}

Hostitel Cassandra služby Azure Cosmos DB se předá gocql.NewCluster funkci, aby získala *gocql.ClusterConfig strukturu, která je nakonfigurovaná tak, aby používala uživatelské jméno, heslo, port a příslušnou verzi protokolu TLS (požadavek na zabezpečení šifrování HTTPS/SSL/TLS).

Funkce GetSession se pak volá z main funkce (main.go).

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

Informace o připojení a přihlašovací údaje se přijímají ve formě proměnných prostředí (řeší se init v metodě ).

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")
    }
}

Pak se používá k provádění různých operací (součást ) se operations\setup.goslužbou Azure Cosmos DB, počínaje keyspace a table vytvořením.

Jak název napovídá, funkce zahodí pouze v keyspace případě, DropKeySpaceIfExists že existuje.

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 slouží k vytvoření 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")
}

Následuje vytvoření tabulky (user), která se postará o CreateUserTable funkci.

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")
}

Po vytvoření prostoru klíčů a tabulky vyvoláme operace CRUD (součást ).operations\crud.go

InsertUserse používá k vytvoření .User Pomocí příkazu nastaví informace o uživateli (ID, jméno a město) jako argumenty dotazu. 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 slouží k hledání uživatele (model\user.go) pomocí konkrétního ID uživatele, zatímco Scan váže atributy uživatele (vrácené Cassandrou) na jednotlivé proměnné (userid, name, ), cityje to jen jeden ze způsobů, jak můžete použít získaný výsledek jako výsledek vyhledávacího dotazu.

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 se používá k načtení všech uživatelů. SliceMap slouží jako zkratka k získání všech informací o uživateli ve formě výseče maps. Každý z nich map si můžete představit jako páry klíč-hodnota, user_idkde název sloupce (například ) je klíč spolu s příslušnou hodnotou.

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
}

Každá map informace o uživateli se převede na User funkci using mapToUser , která jednoduše extrahuje hodnotu z příslušného User sloupce a použije ji k vytvoření instance struktury.

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}
}

Spuštění aplikace

Jak už jsme zmínili, aplikace přijímá připojení a přihlašovací údaje ve formě proměnných prostředí.

V účtu služby Azure Cosmos DB v Azure Portal vyberte Připojovací řetězec.

Zkopírujte hodnoty následujících atributů (CONTACT POINT, PORTUSERNAME a PRIMARY PASSWORD) a nastavte je na příslušné proměnné prostředí.

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">

V okně terminálu přejděte do správné složky. Například:

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

Spuštěním následujícího příkazu v terminálu spusťte aplikaci.

go run main.go

V okně terminálu se zobrazí oznámení o různých operacích, včetně nastavení prostoru klíčů a tabulky, vytvoření uživatele atd.
Na portálu Azure Portal otevřete Data Explorer, abyste se mohli na tato nová data dotazovat, měnit je a pracovat s nimi.

Ověření smluv SLA na webu Azure Portal

Azure Portal monitoruje propustnost, úložiště, dostupnost, latenci a konzistenci účtu služby Azure Cosmos DB. Grafy metrik přidružených ke smlouvě o úrovni služeb (SLA) služby Azure Cosmos DB zobrazují hodnotu SLA v porovnání se skutečným výkonem. Díky této sadě metrik je monitorování smluv SLA transparentní.

Kontrola metrik a smluv SLA:

V navigační nabídce účtu služby Azure Cosmos DB vyberte Metriky .
Vyberte kartu, například Latence, a vpravo vyberte časový rámec. Porovnejte čáry Skutečné hodnoty a SLA v grafech.
Zkontrolujte metriky na ostatních kartách.

Vyčištění prostředků

Až aplikaci a účet služby Azure Cosmos DB dokončíte, můžete vytvořené prostředky Azure odstranit, aby se vám neúčtovaly další poplatky. Odstranění prostředků:

Na panelu Azure Portal hledání vyhledejte a vyberte Skupiny prostředků.
V seznamu vyberte skupinu prostředků, kterou jste vytvořili pro účely tohoto rychlého startu.
Na stránce Přehled skupiny prostředků vyberte Odstranit skupinu prostředků.
V dalším okně zadejte název skupiny prostředků, kterou chcete odstranit, a pak vyberte Odstranit.

Další kroky

V tomto rychlém startu jste zjistili, jak vytvořit účet služby Azure Cosmos DB s rozhraním API for Cassandra a spustit aplikaci v Go, která vytvoří databázi a kontejner Cassandra. Teď můžete do svého účtu služby Azure Cosmos DB importovat další data.

Import dat Cassandra do služby Azure Cosmos DB

Rychlý start: Sestavení aplikace v Go s klientem gocql pro správu dat Azure Cosmos DB pro Apache Cassandra