Delen via

Quickstart: Een Go-app bouwen met de client voor het gocql beheren van Azure Cosmos DB voor Apache Cassandra-gegevens

  • Artikel

VAN TOEPASSING OP: Cassandra

Met Azure Cosmos DB, een databaseservice met meerdere modellen, kunt u snel databases met documenten, tabellen, sleutelwaarden en grafieken maken en hier query's op uitvoeren. Deze databases hebben wereldwijde distributie en horizontale schaalmogelijkheden. In deze quickstart begint u met het maken van een Azure Cosmos DB voor Apache Cassandra-account. Vervolgens voert u een Go-toepassing uit om een Cassandra-keyspace en een tabel te maken en een aantal bewerkingen uit te voeren. Deze Go-app maakt gebruik van gocql, een Cassandra-client voor de Go-taal.

Vereisten

Een databaseaccount maken

Voordat u een database kunt maken, moet u een Cassandra-account maken met Azure Cosmos DB.

  1. Selecteer vanuit het menu van Azure Portal of op de startpagina de optie Een resource maken.

  2. Zoek op de pagina Nieuw naar Azure Cosmos DB en selecteer dit.

  3. Selecteer op de pagina Azure Cosmos DB Maken.

  4. Selecteer Maken onder de sectie Cassandra op de pagina API.

    De API bepaalt het type te maken account. Azure Cosmos DB biedt vijf API's: NoSQL voor documentdatabases, Gremlin voor grafiekdatabases, MongoDB voor documentdatabases, Azure Table en Cassandra. U moet voor elke API een afzonderlijk account maken.

    Selecteer Cassandra, omdat u in deze quickstart een tabel maakt die werkt met de API voor Cassandra.

    Meer informatie over de API voor Cassandra.

  5. Voer op de pagina Azure Cosmos DB-account maken de basisinstellingen voor het nieuwe Azure Cosmos DB-account in.

    Instelling Weergegeven als Beschrijving
    Abonnement Uw abonnement Selecteer het Azure-abonnement dat u wilt gebruiken voor dit Azure Cosmos DB-account.
    Resourcegroep Nieuwe

    Voer vervolgens dezelfde naam in als de Accountnaam    		 Selecteer Nieuw maken. Voer daarna een nieuwe resourcegroepnaam in voor het account. Gebruik dezelfde naam als uw Azure Cosmos DB-accountnaam om het uzelf gemakkelijk te maken.
    Accountnaam Voer een unieke naam in Voer een unieke naam in om uw Azure Cosmos DB-account te identificeren. Uw account-URI wordt cassandra.cosmos.azure.com dat aan uw unieke accountnaam wordt toegevoegd.

    De accountnaam moet tussen de 3 en 31 tekens lang zijn en mag alleen kleine letters, cijfers en afbreekstreepjes bevatten.
    Locatie De regio het dichtst bij uw gebruikers Selecteer een geografische locatie waar u het Azure Cosmos DB-account wilt hosten. Gebruik de locatie die zich het dichtst bij uw gebruikers bevindt, zodat ze de snelst mogelijke toegang tot de gegevens hebben.
    Capaciteitsmodus Ingerichte doorvoer of serverloos Selecteer Ingerichte doorvoer om een account te maken in de modus Ingerichte doorvoer. Selecteer Serverloos om een account te maken in de modus serverloos.
    Niveaukorting op gratis laag van Azure Cosmos DB toepassen Toepassen of niet toepassen Met de gratis laag van Azure Cosmos DB ontvangt u de eerste 1000 RU/s en 25 GB aan opslagruimte gratis in een account. Meer informatie over de gratis laag.
    Totale accountdoorvoer beperken Selecteren om de doorvoer van het account te beperken Dit is handig als u de totale doorvoer van het account wilt beperken tot een specifieke waarde.

    Notitie

    U kunt per Azure-abonnement maximaal één gratis laag voor het Azure Cosmos DB-account hebben, en u moet zich aanmelden wanneer u het account maakt. Als u de optie voor het toepassen van de korting voor gratis lagen niet ziet, betekent dit dat er al een ander account in het abonnement is ingeschakeld met een gratis laag.

    De nieuwe accountpagina voor Azure Cosmos DB voor Apache Cassandra

  6. Configureer op het tabblad Globale distributie de volgende details. U kunt de standaardwaarden voor deze quickstart behouden:

    Instelling Weergegeven als Beschrijving
    Georedundantie Uitschakelen Schakel globale distributie voor uw account in of uit door uw regio te koppelen met een koppelingsregio. U kunt later meer regio's aan uw account toevoegen.
    Schrijven voor meerdere regio's Uitschakelen Dankzij de mogelijkheid voor schrijfbewerkingen in meerdere regio's kunt over de hele wereld profiteren van de ingerichte doorvoer voor uw databases en containers.
    Beschikbaarheidszones Uitschakelen Beschikbaarheidszones zijn geïsoleerde locaties binnen een Azure-regio. Elke zone bestaat uit een of meer datacenters met onafhankelijke stroomvoorziening, koeling en netwerken.

    Notitie

    De volgende opties zijn niet beschikbaar als u Serverloos als Capaciteitsmodus selecteert:

    • Korting voor gratis laag toepassen
    • Geografische redundantie
    • Schrijven voor meerdere regio's

  7. U kunt eventueel aanvullende details configureren op de volgende tabbladen:

    • Netwerken : toegang configureren vanuit een virtueel netwerk.
    • Back-upbeleid: configureer periodiek of doorlopend back-upbeleid.
    • Versleuteling : gebruik een door de service beheerde sleutel of een door de klant beheerde sleutel.
    • Tags: tags zijn naam-/waardeparen waarmee u resources kunt categoriseren en geconsolideerde facturering kunt weergeven door dezelfde tag toe te passen op meerdere resources en resourcegroepen.

  8. Selecteer Controleren + maken.

  9. Controleer de accountinstellingen en selecteer vervolgens Maken. Het duurt een paar minuten om het account te maken. Wacht tot de portal-pagina Uw implementatie is voltooid weergeeft.

    Het deelvenster Meldingen in Azure Portal

  10. Selecteer Ga naar resource om naar de Azure Cosmos DB-accountpagina te gaan.

De voorbeeldtoepassing klonen

Begin met klonen van de toepassing vanuit GitHub.

  1. Open een opdrachtprompt en maak een nieuwe map met de naam git-samples.

    md "C:\git-samples"

  2. Open een venster in een git-terminal zoals git bash. Gebruik de opdracht cd om dit in de nieuwe map te veranderen en installeren van de voorbeeld-app.

    cd "C:\git-samples"

  3. Voer de volgende opdracht uit om de voorbeeldopslagplaats te klonen. Deze opdracht maakt een kopie van de voorbeeld-app op uw computer.

    git clone https://github.com/Azure-Samples/azure-cosmos-db-cassandra-go-getting-started.git

De code bekijken

Deze stap is optioneel. Als u wilt weten hoe de databaseresources met de code worden gemaakt, kunt u de volgende codefragmenten bekijken. Anders slaat u dit over en gaat u naar De toepassing uitvoeren

De functie GetSession (onderdeel van utils\utils.go) retourneert een *gocql.Session die wordt gebruikt voor het uitvoeren van clusterbewerkingen, zoals invoegen, zoeken, enzovoort.

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
}

De Azure Cosmos DB Cassandra-host wordt doorgegeven aan de gocql.NewCluster functie om een *gocql.ClusterConfig struct op te halen die vervolgens is geconfigureerd voor het gebruik van de gebruikersnaam, het wachtwoord, de poort en de juiste TLS-versie (HTTPS/SSL/TLS-versleutelingsbeveiligingsvereiste)

De functie GetSession wordt vervolgens aangeroepen vanuit de functie main (main.go).

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

De verbindingsgegevens en referenties worden geaccepteerd in de vorm van omgevingsvariabelen (opgelost in de methode init)

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

Deze wordt vervolgens gebruikt voor het uitvoeren van verschillende bewerkingen (onderdeel van operations\setup.go) op Azure Cosmos DB die beginnen met keyspace en het maken van table.

Zoals de naam wordt voorgesteld, wordt de keyspace alleen door de functie DropKeySpaceIfExists neergezet als deze bestaat.

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

De functie CreateKeySpace wordt gebruikt voor het maken van de 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")
}

Dit wordt gevolgd door het maken van tabellen (user), waarbij functie CreateUserTable wordt gebruikt

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

Zodra de keyspace en tabel zijn gemaakt, worden er CRUD-bewerkingen aanroepen (onderdeel van operations\crud.go).

InsertUser wordt gebruikt om een User te maken. De gebruikersgegevens (ID, naam en plaats) worden ingesteld als de query-argumenten met 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 wordt gebruikt om te zoeken naar een gebruiker (model\user.go) met behulp van een specifieke gebruikers-id terwijl Scan de gebruikers kenmerken (geretourneerd door Cassandra) koppelt aan afzonderlijke variabelen (userid, name, city). Dit is slechts een van de manieren waarop u het resultaat van de zoekquery kunt gebruiken

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 wordt gebruikt om alle gebruikers op te halen. SliceMap wordt gebruikt als een steno om alle gegevens van de gebruiker op te halen in de vorm van een segment van maps. U kunt elk map beschouwen als sleutelwaardeparen waarbij de kolomnaam (bijvoorbeeld user_id) de sleutel is en de bijbehorende waarde.

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
}

Elk map van gebruikersgegevens wordt geconverteerd naar een User met behulp van functie mapToUser waarmee de waarde van de desbetreffende kolom wordt geëxtraheerd en wordt gebruikt om een instantie van de struct User te maken

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

De toepassing uitvoeren

Zoals eerder vermeld, accepteert de toepassing connectiviteit en referenties in de vorm van de omgevingsvariabelen.

  1. Selecteer in uw Azure Cosmos DB-account in de Azure-portal de optie Verbindingsreeks.

    Details uit de pagina Verbindingsreeks bekijken en kopiëren via Azure Portal

Kopieer de waarden voor de volgende kenmerken (CONTACT POINT, PORT, USERNAME en PRIMARY PASSWORD) en stel deze in op de respectieve omgevingsvariabelen

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

Ga in het venster Terminal naar de juiste map. Voorbeeld:

cd "C:\git-samples\azure-cosmosdb-cassandra-go-getting-started"
  1. Voer in het terminal de volgende opdracht uit om de toepassing te starten.
go run main.go

  1. In het venster terminal worden meldingen weergegeven voor de verschillende bewerkingen, zoals het instellen van de instellingen van de keyspace en tabel, maken van gebruikers, enz.

  2. Open Data Explorer in de Azure-portal om deze nieuwe gegevens te bekijken, te wijzigen, een query erop uit te voeren of er iets anders mee te doen.

    De gegevens bekijken in Data Explorer - Azure Cosmos DB

SLA’s bekijken in Azure Portal

Azure Portal bewaakt de doorvoer van uw Azure Cosmos DB-account, opslag, beschikbaarheid, latentie en consistentie. Grafieken voor metrische gegevens die zijn gekoppeld aan een Azure Cosmos DB Service Level Agreement (SLA) tonen de SLA-waarde in vergelijking met de werkelijke prestaties. Deze suite van metrische gegevens zorgt voor een transparante bewaking van uw SLA's.

Metrische gegevens en SLA's weergeven:

  1. Selecteer Metrische gegevens in het navigatiemenu van uw Azure Cosmos DB-account.

  2. Selecteer een tabblad, bijvoorbeeld Latentie, en selecteer aan de rechterkant een tijdsbestek. Vergelijk de lijnen Werkelijk en SLA in de grafieken met elkaar.

    Azure Cosmos DB-pakket met metrische gegevens

  3. Bekijk de metrische gegevens op de andere tabbladen.

Resources opschonen

Wanneer u uw app en Azure Cosmos DB-account niet meer nodig hebt, kunt u de Azure-resources die u hebt gemaakt, verwijderen zodat er geen kosten meer voor in rekening worden gebracht. Om de resources te verwijderen:

  1. Zoek en selecteer Resourcegroepen in de zoekbalk op Azure Portal.

  2. Selecteer de resourcegroep die u eerder voor deze quickstart hebt gemaakt uit de lijst.

    Resourcegroep selecteren die moet worden verwijderd

  3. Selecteer Resourcegroep verwijderen op de pagina Overzicht van de resourcegroep.

    De resourcegroep verwijderen

  4. Selecteer in het volgende venster de naam van de resourcegroep die u wilt verwijderen en selecteer vervolgens Verwijderen.

Volgende stappen

In deze quickstart hebt u geleerd hoe u een Azure Cosmos DB-account maakt met API voor Cassandra en een Go-app uitvoert waarmee een Cassandra-database en -container wordt gemaakt. Nu kunt u aanvullende gegevens in uw Azure Cosmos DB-account importeren.

Cassandra-gegevens importeren in Azure Cosmos DB