Rychlý průvodce: Klientská knihovna Azure Cosmos DB for Apache Cassandra pro Go

Platí pro: ✅ Apache Cassanda

Začínáme s klientskou knihovnou Azure Cosmos DB for Apache Cassandra pro Go pro ukládání, správu a dotazování nestrukturovaných dat Postupujte podle kroků v tomto průvodci a vytvořte nový účet, nainstalujte klientskou knihovnu Go, připojte se k účtu, proveďte běžné operace a dotazujte se na konečná ukázková data.

Referenční dokumentace API | Zdrojový kód knihovny | Balíček (Go)

Požadavky

Předplatné Azure
- Pokud nemáte předplatné Azure, vytvořte si bezplatný účet před zahájením.

Nejnovější verze Azure CLI v Azure Cloud Shellu
- Pokud dáváte přednost místnímu spouštění referenčních příkazů rozhraní příkazového řádku, přihlaste se k Azure CLI pomocí az login příkazu.

Go 1.24 nebo novější

Instalace

Nejprve pro tuto příručku nastavte účet a vývojové prostředí. Tato část vás provede procesem vytvoření účtu, získáním jeho přihlašovacích údajů a následnou přípravou vývojového prostředí.

Vytvoření účtu

Začněte vytvořením rozhraní API pro účet Apache Cassandra. Po vytvoření účtu vytvořte klíčový prostor a tabulkové zdroje.

Azure CLI
Azure Portal

Pokud ještě nemáte cílovou skupinu prostředků, použijte az group create příkaz k vytvoření nové skupiny prostředků ve vašem předplatném.
```
az group create \
    --name "<resource-group-name>" \
    --location "<location>"
```

az cosmosdb create Pomocí příkazu vytvořte nový účet Azure Cosmos DB pro Apache Cassandra s výchozím nastavením.

az cosmosdb create \
    --resource-group "<resource-group-name>" \
    --name "<account-name>" \
    --locations "regionName=<location>" \
    --capabilities "EnableCassandra"

Vytvořte nový keyspace pojmenovaný az cosmosdb cassandra keyspace createcosmicworks.

az cosmosdb cassandra keyspace create \
    --resource-group "<resource-group-name>" \
    --account-name "<account-name>" \
    --name "cosmicworks"

Vytvořte nový objekt JSON, který bude reprezentovat schéma pomocí příkazu Bash s více řádky. Potom pomocí az cosmosdb cassandra table create příkazu vytvořte novou tabulku s názvem products.

schemaJson=$(cat <<EOF
{
  "columns": [
    {
      "name": "id",
      "type": "text"
    },
    {
      "name": "name",
      "type": "text"
    },
    {
      "name": "category",
      "type": "text"
    },
    {
      "name": "quantity",
      "type": "int"
    },
    {
      "name": "price",
      "type": "decimal"
    },
    {
      "name": "clearance",
      "type": "boolean"
    }
  ],
  "partitionKeys": [
    {
      "name": "id"
    }
  ]
}
EOF
)

az cosmosdb cassandra table create \
    --resource-group "<resource-group-name>" \
    --account-name "<account-name>" \
    --keyspace-name "cosmicworks" \
    --name "product" \
    --schema "$schemaJson"

Přihlaste se k webu Azure Portal (https://portal.azure.com).
Do globálního panelu hledání zadejte Azure Cosmos DB .
V rámci služeb vyberte Azure Cosmos DB.
V podokně Azure Cosmos DB vyberte Vytvořit a potom Azure Cosmos DB for Apache Cassandra na kartě Ostatní.
Jako typ účtu vyberte účet databáze jednotky žádosti (RU ).

V podokně Základy nakonfigurujte následující možnosti a pak vyberte Zkontrolovat a vytvořit:

	Hodnota
Typ úlohy	Vzdělávání
Předplatné	Výběr předplatného Azure
Skupina prostředků	Vytvoření nové skupiny prostředků nebo výběr existující skupiny prostředků
Název účtu	Zadejte globálně jedinečný název.
Zóny dostupnosti	Zakázat
Umístění	Vyberte podporovanou oblast Azure pro vaše předplatné.

Návod

U výchozích hodnot můžete ponechat všechny nezadané možnosti. Můžete také nakonfigurovat účet tak, aby omezil celkovou propustnost účtu na 1 000 jednotek žádostí za sekundu (RU/s), nebo povolit úroveň Free, aby se minimalizovaly náklady.

V podokně Zkontrolovat a vytvořit počkejte na úspěšné ověření účtu a pak vyberte Vytvořit.
Portál automaticky přejde do podokna Nasazení . Počkejte, až se nasazení dokončí.
Po dokončení nasazení vyberte Přejít k prostředku a přejděte do nového rozhraní API pro účet Apache Cassandra.
V nabídce prostředků vyberte možnost Průzkumník dat .
V Průzkumníku dat vyberte + Nová tabulka.

V dialogovém okně Přidat tabulku nakonfigurujte následující možnosti a pak vyberte OK:

	Hodnota
Keyspace	Create new
Název prostoru klíčů	`cosmicworks`
Název tabulky	`product`
Schéma tabulky	`(id text, name text, category text, quantity int, price decimal, clearance boolean, PRIMARY KEY (id))`

Návod

U výchozích hodnot můžete ponechat všechny nezadané možnosti.

Získání přihlašovacích údajů

Teď získejte heslo pro klientskou knihovnu, které se má použít k vytvoření připojení k nedávno vytvořenému účtu.

Azure CLI
Azure Portal

Slouží az cosmosdb show k získání kontaktního bodu a uživatelského jména pro účet.

az cosmosdb show \
    --resource-group "<resource-group-name>" \
    --name "<account-name>" \
    --query "{username:name,contactPoint:documentEndpoint}"

Poznamenejte si hodnotu contactPoint a username vlastnosti z výstupu předchozích příkazů. Hodnoty těchto vlastností jsou kontaktní bod a uživatelské jméno , které použijete později v tomto průvodci pro připojení k účtu s knihovnou.

Slouží az cosmosdb keys list k získání klíčů pro účet.

az cosmosdb keys list \
    --resource-group "<resource-group-name>" \
    --name "<account-name>" \
    --type "keys"

Poznamenejte si hodnotu primaryMasterKey vlastnosti z výstupu předchozích příkazů. Hodnota této vlastnosti je heslo , které použijete později v tomto průvodci pro připojení k účtu s knihovnou.

Příprava vývojového prostředí

Potom nakonfigurujte vývojové prostředí s novým projektem a klientskou knihovnou. Tento krok je posledním požadovaným předpokladem před přechodem na zbytek této příručky.

Začněte v prázdném adresáři.
Vytvořte nový modul Go.
```
go mod init quickstart
```
Importujte github.com/apache/cassandra-gocql-driver/v2 balíček z Go.
```
go get github.com/apache/cassandra-gocql-driver/v2
```
Vytvořte soubor main.go .
Přidejte základní šablonu aplikace Go.
```
package main

func main() {    
}
```
Důležité

Zbývající kroky v této příručce předpokládají, že do funkce přidáváte svůj kód main .

Objektový model

	Popis
`Cluster`	Představuje konkrétní připojení ke clusteru.
`Session`	Entity, které mají konkrétní připojení ke clusteru

Příklady kódu

Ověření klienta
Provést operaci Upsert (aktualizace nebo vložení) na data
Čtení dat
Dotazování dat

Ověření klienta

Začněte ověřením klienta pomocí přihlašovacích údajů shromážděných dříve v této příručce.

Otevřete soubor main.go v integrovaném vývojovém prostředí (IDE).
V rámci main funkce naimportujte spolu s balíčkem github.com/apache/cassandra-gocql-driver/v2 následující balíčky:
- context
- crypto/tls
```
import (
    "context"
    "crypto/tls"
    "github.com/apache/cassandra-gocql-driver/v2"
)
```
Vytvořte řetězcové proměnné pro přihlašovací údaje shromážděné dříve v této příručce. Pojmenujte proměnné username, passworda contactPoint.
```
username := "<username>"
password := "<password>"
contactPoint := "<contact-point>"
```
Nakonfigurujte instanci typu PasswordAuthenticator s přihlašovacími údaji zadanými v předchozích krocích. Uložte výsledek do proměnné s názvem authentication.
```
authentication := gocql.PasswordAuthenticator{
    Username: username,
    Password: password,
}
```
Nakonfigurujte instanci SslOptions s minimální verzí protokolu TLS (Transport Layer Security) 1.2 a proměnnou contactPoint jako název cílového serveru. Uložte výsledek do proměnné s názvem sslOptions.
```
sslOptions := &gocql.SslOptions{
    Config: &tls.Config{
        MinVersion: tls.VersionTLS12,
        ServerName: contactPoint,
    },
}
```
Vytvořte novou specifikaci clusteru pomocí NewCluster a proměnné contactPoint.
```
cluster := gocql.NewCluster(contactPoint)
```
Nakonfigurujte objekt specifikace clusteru pomocí přihlašovacích údajů a konfiguračních proměnných vytvořených v předchozích krocích.
```
cluster.SslOpts = sslOptions
cluster.Authenticator = authentication
```

Nakonfigurujte zbytek objektu specifikace clusteru s těmito statickými hodnotami.

cluster.Keyspace = "cosmicworks"
cluster.Port = 10350
cluster.ProtoVersion = 4

Vytvořte novou relaci, která se připojí ke clusteru pomocí CreateSession.
```
session, _ := cluster.CreateSession()
```
Nakonfigurujte relace tak, aby vyvolala funkci Close po návratu z funkce main.
```
defer session.Close()
```
Vytvořte nový Background kontextový objekt a uložte ho ctx do proměnné.
```
ctx := context.Background()
```

Výstraha

Úplné ověření protokolu TLS (Transport Layer Security) je v tomto průvodci zakázané, aby se zjednodušilo ověřování. Pro produkční nasazení plně povolte ověřování.

Vložit nebo aktualizovat data

V dalším kroku přepište nová data do tabulky. Přenesení zajistí, že se data vytvoří nebo nahradí odpovídajícím způsobem v závislosti na tom, jestli stejná data již v tabulce existují.

Definujte nový typ s názvem Product s poli odpovídajícími tabulce vytvořené dříve v této příručce.
```
type Product struct {
    id        string
    name      string
    category  string
    quantity  int
    clearance bool
}
```
Návod

V go můžete tento typ vytvořit v jiném souboru nebo ho vytvořit na konci existujícího souboru.

Vytvořte nový objekt typu Product. Uložte objekt do proměnné s názvem product.

product := Product {
    id:        "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
    name:      "Yamba Surfboard",
    category:  "gear-surf-surfboards",
    quantity:  12,
    clearance: false,
}

Vytvořte novou řetězcovou proměnnou s názvem insertQuery dotazu Cassandra Query Language (CQL) pro vložení nového řádku.

insertQuery := `
    INSERT INTO
        product (id, name, category, quantity, clearance)
    VALUES
        (?, ?, ?, ?, ?)
`

Použijte funkce Query a ExecContext ke spuštění dotazu. Předejte různé vlastnosti product proměnné jako parametry dotazu.

_ = session.Query(
    insertQuery,
    product.id, 
    product.name, 
    product.category, 
    product.quantity, 
    product.clearance,
).ExecContext(ctx)

Čtení dat

Potom načtěte data, která byla dříve převedena do tabulky.

Vytvořte novou řetězcovou proměnnou pojmenovanou readQuery s dotazem CQL, který odpovídá položkám se stejným polem id.

readQuery := `
    SELECT
        id,
        name,
        category,
        quantity,
        clearance
    FROM
        product
    WHERE id = ?
    LIMIT 1
`

Vytvořte řetězcovou proměnnou s názvem id se stejnou hodnotou jako produkt vytvořený dříve v této příručce.
```
id := "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb" 
```
Vytvořte další proměnnou s názvem matchedProduct pro uložení výsledku této operace.
```
var matchedProduct Product
```

Pomocí funkcí Query, Consistency, IterContext a Scan společně najděte jednu položku, která odpovídá dotazu, a nastavte její vlastnosti proměnné matchedProduct.

session.Query(
    readQuery,
    &id,
).Consistency(gocql.One).IterContext(ctx).Scan(
    &matchedProduct.id,
    &matchedProduct.name,
    &matchedProduct.category,
    &matchedProduct.quantity,
    &matchedProduct.clearance,
)

Dotaz k datům

Nakonec pomocí dotazu najděte všechna data, která odpovídají určitému filtru v tabulce.

Vytvořte řetězcové proměnné pojmenované findQuery a category pomocí dotazu CQL a požadovaného parametru.

findQuery := `
    SELECT
        id,
        name,
        category,
        quantity,
        clearance
    FROM
        product
    WHERE
        category = ?
    ALLOW FILTERING
`

category := "gear-surf-surfboards"

Pomocí funkcí Query, Consistency, IterContext a Scanner společně vytvořte skener, který může iterovat přes více položek, které odpovídají dotazu.
```
queriedProducts := session.Query(
    findQuery, 
    &category,
).Consistency(gocql.All).IterContext(ctx).Scanner()
```

Použijte funkce Next a Scan k iteraci přes výsledky dotazu a přiřaďte vlastnosti každého výsledku vnitřní proměnné queriedProduct.

for queriedProducts.Next() {
    var queriedProduct Product
    queriedProducts.Scan(
        &queriedProduct.id,
        &queriedProduct.name,
        &queriedProduct.category,
        &queriedProduct.quantity,
        &queriedProduct.clearance,
    )
    // Do something here with each result
}

Spuštění kódu

Spusťte nově vytvořenou aplikaci pomocí terminálu v adresáři vaší aplikace.

go run .

Vyčistěte zdroje