Rövid útmutató: Go-alkalmazás létrehozása az ügyféllel az `gocql` Apache Cassandra-adatokhoz készült Azure Cosmos DB kezeléséhez

Cikk
04/06/2023

A KÖVETKEZŐKRE VONATKOZIK: Cassandra

Az Azure Cosmos DB egy többmodelles adatbázis-szolgáltatás, amellyel gyorsan hozhat létre és kérdezhet le dokumentum-, tábla-, kulcs-érték- és gráfadatbázisokat globális terjesztési és horizontális skálázási képességekkel. Ebben a rövid útmutatóban egy Azure Cosmos DB for Apache Cassandra-fiókot fog létrehozni. Ezután futtat egy Go-alkalmazást, amely létrehoz egy Cassandra-kulcsteret, táblát, és végrehajt néhány műveletet. Ez a Go alkalmazás gocql-t használ, amely a Go nyelv Cassandra-ügyfele.

Előfeltételek

Egy Azure-fiók, aktív előfizetéssel. Hozzon létre egyet ingyen. Vagy ingyenesen kipróbálhatja az Azure Cosmos DB-t Azure-előfizetés nélkül.
A Go telepítve van a számítógépen, és a Go munkaértelmével.
Git.

Adatbázisfiók létrehozása

Mielőtt létrehozhat egy adatbázist, létre kell hoznia egy Cassandra-fiókot az Azure Cosmos DB-vel.

A Azure Portal menüben vagy a Kezdőlapon válassza az Erőforrás létrehozása lehetőséget.
Az Új lapon keresse meg és válassza az Azure Cosmos DB lehetőséget.
Az Azure Cosmos DB lapon válassza a Létrehozás lehetőséget.
Az API-lapon válassza a Létrehozás lehetőséget a Cassandra szakaszban.

A létrehozni kívánt fiók típusát az API határozza meg. Az Azure Cosmos DB öt API-t biztosít: a NoSQL-t a dokumentum-adatbázisokhoz, a Gremlint a gráfadatbázisokhoz, a MongoDB-t a dokumentum-adatbázisokhoz, az Azure Tableet és a Cassandrát. Minden API-hoz külön fiókot kell létrehoznia.

Válassza a Cassandra lehetőséget, mert ebben a rövid útmutatóban egy olyan táblát hoz létre, amely a Cassandra API-val működik.

További információ a Cassandra API-járól.

Az Azure Cosmos DB-fiók létrehozása lapon adja meg az új Azure Cosmos DB-fiók alapbeállításait.

Beállítás	Érték	Leírás
Előfizetés	Az Ön előfizetése	Válassza ki az Azure Cosmos DB-fiókhoz használni kívánt Azure-előfizetést.
Erőforráscsoport	Új létrehozása Ezután adja meg ugyanazt a nevet, mint a Fióknév	Válassza az Új létrehozása lehetőséget. Ezután adjon meg egy új erőforráscsoport-nevet a fiókjához. Az egyszerűség kedvéért használja ugyanazt a nevet, mint az Azure Cosmos DB-fiók nevét.
Fiók neve	Adjon meg egy egyedi nevet	Adjon meg egy egyedi nevet az Azure Cosmos DB-fiók azonosításához. A fiók URI-ja cassandra.cosmos.azure.com hozzá lesz fűzve az egyedi fiók nevéhez. A fióknév csak kisbetűket, számokat és kötőjeleket (-) használhat, és 3 és 31 karakter közötti hosszúságúnak kell lennie.
Hely	A felhasználókhoz legközelebb eső régió	Válassza ki az Azure Cosmos DB-fiókot üzemeltetéséhez használni kívánt földrajzi helyet. Használja a felhasználókhoz legközelebbi helyet, hogy a lehető leggyorsabb hozzáférést biztosítsa számukra az adatokhoz.
Kapacitásmód	Kiosztott átviteli sebesség vagy kiszolgáló nélküli	A Kiosztott átviteli sebesség lehetőséget választva hozzon létre egy fiókot kiépített átviteli módban. A Kiszolgáló nélküli lehetőséget választva hozzon létre egy fiókot kiszolgáló nélküli módban.
Ingyenes Azure Cosmos DB-kedvezmény alkalmazása	Alkalmazás vagy Nem alkalmazható	Az Ingyenes Azure Cosmos DB-szinttel az első 1000 RU/s- és 25 GB tárterületet kapja ingyenesen egy fiókban. További információ az ingyenes szintről.
Fiók teljes átviteli sebességének korlátozása	Válassza ki a fiók átviteli sebességének korlátozását	Ez akkor hasznos, ha a fiók teljes átviteli sebességét egy adott értékre szeretné korlátozni.

Megjegyzés

Azure-előfizetésenként legfeljebb egy ingyenes szintű Azure Cosmos DB-fiókkal rendelkezhet, és a fiók létrehozásakor be kell jelentkeznie. Ha nem látja az ingyenes szint kedvezményének alkalmazását, az azt jelenti, hogy az előfizetés egy másik fiókja már engedélyezve van az ingyenes szinttel.

Az Apache Cassandra-hoz készült Azure Cosmos DB új fiókoldala

A Globális terjesztés lapon konfigurálja az alábbi adatokat. Az alapértelmezett értékeket a következő rövid útmutató céljára hagyhatja:

Beállítás	Érték	Leírás
Georedundancia	Letiltás	Engedélyezze vagy tiltsa le a globális terjesztést a fiókjában a régió párosításával egy párrégióval. Később további régiókat is felvehet a fiókjába.
Többrégiós írók	Letiltás	A többrégiós írási képesség lehetővé teszi, hogy kihasználja a kiosztott átviteli sebességet az adatbázisok és tárolók számára világszerte.
Rendelkezésre állási zónák	Letiltás	Availability Zones egy Azure-régióban elkülönített helyek. Minden rendelkezésreállási zóna egy vagy több, független áramforrással, hűtéssel és hálózatkezelési megoldással ellátott adatközpontból áll.

Megjegyzés

A következő beállítások nem érhetők el, ha a Kiszolgáló nélküli lehetőséget választja Kapacitás módként:

Az ingyenes szint árengedményének alkalmazása
Georedundancia
Többrégiós írók

A további részleteket a következő lapon is konfigurálhatja:
- Hálózatkezelés – Virtuális hálózatról való hozzáférés konfigurálása.
- Biztonsági mentési szabályzat – Konfigurálja az időszakos vagy folyamatos biztonsági mentési szabályzatot.
- Titkosítás – Használjon szolgáltatás által felügyelt kulcsot vagy ügyfél által felügyelt kulcsot.
- Címkék – A címkék név-érték párok, amelyek lehetővé teszik az erőforrások kategorizálását és a konszolidált számlázás megtekintését azáltal, hogy ugyanazt a címkét több erőforrásra és erőforráscsoportra alkalmazza.
Válassza az Áttekintés + létrehozás lehetőséget.
Tekintse át a fiókbeállításokat, majd válassza a Létrehozás lehetőséget. A fiók létrehozása néhány percet vesz igénybe. Várja meg, amíg a portállapon megjelenik az Üzembe helyezés befejeződött.
Válassza az Erőforrás megnyitása lehetőséget az Azure Cosmos DB-fiók lapjának megtekintéséhez.

A mintaalkalmazás klónozása

Először klónozd az alkalmazást a GitHubról.

Nyisson meg egy parancssort, és hozzon létre egy nevű új mappát git-samples.
```
md "C:\git-samples"
```
Nyisson meg egy git-terminálablakot, például a git basht. cd A paranccsal válthat az új mappára, és telepítheti a mintaalkalmazást.
```
cd "C:\git-samples"
```
Futtassa a következő parancsot a mintatárház klónozásához. Ez a parancs másolatot hoz létre a mintaalkalmazásról az Ön számítógépén.
```
git clone https://github.com/Azure-Samples/azure-cosmos-db-cassandra-go-getting-started.git
```

A kód áttekintése

Ez a lépés nem kötelező. Ha szeretné megtudni, hogyan hozza létre a kód az adatbázis-erőforrásokat, tekintse át az alábbi kódrészleteket. Ellenkező esetben továbbléphet az alkalmazás futtatására

A GetSession függvény (része utils\utils.go) egy olyan függvényt *gocql.Session ad vissza, amelyet fürtműveletek végrehajtására használnak, például beszúrásra, keresésre stb.

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
}

Az Azure Cosmos DB Cassandra-gazdagépet a rendszer átadja a függvénynek, *gocql.ClusterConfig hogy megkapja a felhasználónevet, a jelszót, a portot és a megfelelő TLS-verzió használatára konfigurált struktúrát (HTTPS/SSL/TLS titkosítási biztonsági követelmény)gocql.NewCluster

A GetSession függvény ezután a main függvényből (main.go) lesz meghívva.

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

A kapcsolati adatok és a hitelesítő adatok környezeti változók formájában lesznek elfogadva (a init metódusban feloldva)

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

Ezután különböző műveletek végrehajtására szolgál (a részeoperations\setup.go) az Azure Cosmos DB-n, kezdve a létrehozással és table a létrehozássalkeyspace.

Ahogy a neve is sugallja, a DropKeySpaceIfExists függvény az egyetlent elveti keyspace , ha létezik.

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 függvény használatával hozza létre a 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")
}

Ezt követi a táblalétrehozás (user), amely gondoskodik a függvényről CreateUserTable

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

A kulcstér és a tábla létrehozása után meghívjuk a CRUD-műveleteket (a része operations\crud.go).

InsertUser a használatával hoz létre egy User. A felhasználói adatokat (azonosítót, nevet és várost) a lekérdezés argumentumaként állítja be a 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")
}

FindUseregy adott felhasználói azonosítót használó felhasználó (model\user.go) keresésére szolgál, miközben Scan a (Cassandra által visszaadott) felhasználói attribútumokat az egyes változókhoz (userid, , namecity) köti. Ez csak az egyik módszer, amellyel a keresési lekérdezés eredményeként kapott eredményt használhatja

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 az összes felhasználó lekérésére szolgál. SliceMap rövidítésként használja a felhasználó összes információjának lekéréséhez s szelet mapformájában. Tekintsünk mindegyikre map kulcs-érték párként, user_idahol az oszlop neve (például ) a kulcs és a hozzá tartozó érték.

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
}

A rendszer minden map felhasználói információt egy User olyan használati mapToUser függvénysé konvertál, amely egyszerűen kinyeri az értéket a megfelelő oszlopból, és a szerkezet egy példányának létrehozására használja.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}
}

Az alkalmazás futtatása

Ahogy korábban említettük, az alkalmazás a környezeti változók formájában fogadja el a kapcsolatot és a hitelesítő adatokat.

A Azure Portal lévő Azure Cosmos DB-fiókjában válassza a Kapcsolati sztring lehetőséget.

Másolja ki a következő attribútumok (CONTACT POINT, , USERNAME és PRIMARY PASSWORD) értékeit, PORTés állítsa őket a megfelelő környezeti változókra

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

A terminálablakban váltson a megfelelő mappára. Például:

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

A terminálban futtassa a következő parancsot az alkalmazás elindításához.

go run main.go

A terminálablak értesítéseket jelenít meg a különböző műveletekről, beleértve a kulcsteret és a táblabeállítást, a felhasználók létrehozását stb.
Ha megnyitja az Adatkezelőt az Azure Portalon, lekérdezheti és módosíthatja és használhatja az új adatokat.

Tekintse át az SLA-kat az Azure Portalon

A Azure Portal figyeli az Azure Cosmos DB-fiók átviteli sebességét, tárhelyét, rendelkezésre állását, késését és konzisztenciáját. Az Azure Cosmos DB szolgáltatásiszint-szerződéshez (SLA) társított metrikák diagramjai az SLA értékét jelenítik meg a tényleges teljesítményhez képest. Ez a metrikákból álló csomag átláthatóvá teszi az SLA-k monitorozását.

Metrikák és SLA-k áttekintése:

Az Azure Cosmos DB-fiók navigációs menüjében válassza a Metrikák lehetőséget.
Válasszon ki egy lapot, például a Késés lapot, és válasszon ki egy időkeretet a jobb oldalon. Hasonlítsa össze a diagramok Tényleges és SLA sorait.
Tekintse át a metrikákat a többi lapon.

Az erőforrások eltávolítása

Ha végzett az alkalmazással és az Azure Cosmos DB-fiókkal, törölheti a létrehozott Azure-erőforrásokat, így nem kell további díjakat fizetnie. Az erőforrások törlése:

A Azure Portal Keresősávon keresse meg és válassza ki az Erőforráscsoportok elemet.
A listában válassza ki a rövid útmutatóhoz létrehozott erőforráscsoportot.
Az erőforráscsoport Áttekintés lapján válassza az Erőforráscsoport törlése lehetőséget.
A következő ablakban adja meg a törölni kívánt erőforráscsoport nevét, majd válassza a Törlés lehetőséget.

Következő lépések

Ebben a rövid útmutatóban megtanulta, hogyan hozhat létre Azure Cosmos DB-fiókot a Cassandra API-val, és hogyan futtathat egy Go-alkalmazást, amely létrehoz egy Cassandra-adatbázist és -tárolót. Mostantól további adatokat importálhat az Azure Cosmos DB-fiókjába.

Cassandra-adatok importálása az Azure Cosmos DB-be

Rövid útmutató: Go-alkalmazás létrehozása az ügyféllel az gocql Apache Cassandra-adatokhoz készült Azure Cosmos DB kezeléséhez