Rychlý start: Sestavení aplikace Go pomocí gocql klienta pro správu dat Azure Cosmos DB pro Apache Cassandra

PLATÍ PRO: Cassandra

Azure Cosmos DB je databázová služba s více modely, která umožňuje rychle vytvářet a dotazovat dokumenty, tabulky, klíč-hodnota a grafové databáze s funkcemi globální distribuce a horizontálního škálování. V tomto rychlém startu začnete vytvořením účtu Azure Cosmos DB pro Apache Cassandra. Potom spustíte aplikaci Go, která vytvoří prostor klíčů Cassandra, tabulku a provede několik operací. Tato aplikace Go používá jazyk 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.
• Běžte si nainstalovat do počítače a pracujte na Jazyku Go.
• Git

Vytvoření účtu databáze

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

1. V nabídce webu Azure Portal nebo na domovské stránce vyberte Vytvořit prostředek.

2. Na stránce Nový vyhledejte a vyberte Azure Cosmos DB.

3. Na stránce Azure Cosmos DB vyberte Vytvořit.

4. Na stránce rozhraní API vyberte v části Cassandra možnost Vytvořit.

   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 grafové databáze, 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.

5. 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ření nových Potom zadejte stejný název jako Název účtu.	Vyberte, že chcete vytvořit novou IP adresu. Pak zadejte název nové skupiny prostředků pro váš účet. Pro zjednodušení použijte stejný název jako název účtu služby Azure Cosmos DB.
   Název účtu	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 vašemu jedinečnému názvu účtu. Název účtu může používat jenom malá písmena, číslice a pomlčky (-) a musí mít délku 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 vašim uživatelům nejbližší, abyste jim zajistili nejrychlejší přístup k datům.
   Režim kapacity	Zřízená propustnost nebo bezserverová	Vyberte Zřízenou propustnost a vytvořte účet v režimu zřízené propustnosti. Vyberte Bezserverový účet a vytvořte účet v bezserverovém režimu.
   Uplatnění slevy na úroveň Free služby Azure Cosmos DB	Použít nebo nepoužovat	S úrovní Free služby Azure Cosmos DB získáte prvních 1 000 RU/s a 25 GB úložiště zdarma v účtu. 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 konkrétní hodnotu.

   Poznámka:

   Pro každé předplatné Azure můžete mít maximálně jeden účet Azure Cosmos DB úrovně Free a při vytváření tohoto účtu se musíte přihlásit. Pokud se vám nezobrazuje možnost použít slevu založenou na úrovni Free, znamená to, že v předplatném už je povolený jiný účet s úrovní Free.

   

6. 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 vašeho účtu spárováním oblasti s párovou oblastí. Další oblasti můžete do svého účtu přidat později.
   Zápisy do více oblastí	Zakázat	Funkce zápisu do více oblastí umožňuje využívat zřízenou propustnost pro 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:

   Pokud jako režim kapacity vyberete bezserverový režim, nejsou k dispozici následující možnosti:

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

7. Volitelně můžete nakonfigurovat další podrobnosti na následujících kartách:

   • Sítě – Konfigurace přístupu 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 klíč spravovaný službou nebo klíč spravovaný zákazníkem.
   • Značky – Značky jsou páry názvů a hodnot, které umožňují kategorizovat prostředky a zobrazit konsolidovanou fakturaci použitím stejné značky u více prostředků a skupin prostředků.

8. Vyberte Zkontrolovat a vytvořit.

9. Zkontrolujte nastavení účtu a pak vyberte Vytvořit. Vytvoření účtu trvá několik minut. Počkejte, až se na portálu zobrazí stránka s textem Vaše nasazení je hotové.

   

10. Pokud chcete přejít na stránku účtu Azure Cosmos DB, vyberte Přejít k prostředku.

Klonování ukázkové aplikace

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

1. Otevřete příkazový řádek a vytvořte novou složku s názvem git-samples.

   md "C:\git-samples"
   

2. Otevřete okno terminálu Git, například git bash. cd Pomocí příkazu přejděte do nové složky a nainstalujte ukázkovou aplikaci.

   cd "C:\git-samples"
   

3. 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 nepovinný. Pokud se chcete dozvědět, jak kód vytváří databázové prostředky, můžete zkontrolovat následující fragmenty kódu. Jinak můžete přeskočit k spuštění aplikace.

Funkce GetSession (část) utils\utils.govrátí *gocql.Session hodnotu, která se používá ke spouště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 gocql.NewCluster Azure Cosmos DB se předá funkci, aby získal *gocql.ClusterConfig strukturu, která je nakonfigurovaná tak, aby používala uživatelské jméno, heslo, port a odpovídající verzi protokolu TLS (požadavek na š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í (vyřešených v init 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á ke spouštění různých operací (součást) operations\setup.gove službě Azure Cosmos DB počínaje keyspace a table vytvářením.

Jak název napovídá, DropKeySpaceIfExists funkce zahodí keyspace jenom v případě, ž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 k vytvoření keyspace funkce (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

InsertUserslouží k vytvoření .User Nastaví informace o uživateli (ID, název a město) jako argumenty dotazu pomocí 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 vyhledávání uživatele (model\user.go) pomocí konkrétního ID uživatele a při Scan vazbě atributů uživatele (vrácených Cassandra) k jednotlivým proměnným (userid, name, ), cityje to jen jeden ze způsobů, jak použít výsledek získaný 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 slouží k načtení všech uživatelů. SliceMap slouží jako zkratka k získání všech informací uživatele ve formě řezu map. Každý z nich map si můžete představit jako páry klíč-hodnota, kde název sloupce (například user_id) 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 z informací 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 jsme už zmínili, aplikace přijímá připojení a přihlašovací údaje ve formě proměnných prostředí.

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

   

Zkopírujte hodnoty pro následující atributy (CONTACT POINT, PORTUSERNAME a ) a PRIMARY PASSWORDnastavte je na odpovídající 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 na správnou složku. Příklad:

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

2. V terminálu spusťte následující příkaz a spusťte aplikaci.

go run main.go

3. V okně terminálu se zobrazují oznámení o různých operacích, včetně prostoru klíčů a nastavení tabulky, vytváření uživatelů atd.

4. 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 pro metriky přidružené ke smlouvě SLA (Service Level Agreement) služby Azure Cosmos DB zobrazují hodnotu SLA v porovnání se skutečným výkonem. Tato sada metrik zajišťuje transparentní monitorování smluv SLA.

Kontrola metrik a smluv SLA:

1. V navigační nabídce účtu služby Azure Cosmos DB vyberte Metriky .

2. Vyberte kartu, například Latence, a vpravo vyberte časový rámec. Porovnejte skutečné čáry a čáry SLA v grafech.

   

3. Zkontrolujte metriky na dalších kartách.

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

Až budete s aplikací a účtem služby Azure Cosmos DB hotovi, můžete odstranit vytvořené prostředky Azure, takže se vám nebudou účtovat další poplatky. Odstranění prostředků:

1. Na panelu hledání na webu Azure Portal vyhledejte a vyberte skupiny prostředků.

2. V seznamu vyberte skupinu prostředků, kterou jste vytvořili pro účely tohoto rychlého startu.

   

3. Na stránce Přehled skupiny prostředků vyberte Odstranit skupinu prostředků.

   

4. V dalším okně zadejte název skupiny prostředků, která se má 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 pro Cassandra a spustit aplikaci Go, která vytvoří databázi a kontejner Cassandra. Do účtu služby Azure Cosmos DB teď můžete importovat další data.