Rövid útmutató: Azure Cosmos DB ügyfélkönyvtár Apache Cassandra-hoz, Go nyelven

A következőre érvényes:: ✅ Apache Cassanda

Kezdjen bele az Apache Cassandra Azure Cosmos DB ügyfélkönyvtárának használatába a Go nyelvhez, hogy strukturálatlan adatokat tároljon, kezeljen és lekérdezzen. Az útmutató lépéseit követve hozzon létre egy új fiókot, telepítsen egy Go-ügyfélkódtárat, csatlakozzon a fiókhoz, hajtsa végre a gyakori műveleteket, és kérje le a végső mintaadatokat.

API-referenciadokumentáció | Kódtár forráskódja | Csomag (Go)

Előfeltételek

Azure-előfizetés
- Ha nincs Azure-előfizetésed, hozz létre egy ingyenes fiókot mielőtt elkezdenéd.

Az Azure CLI legújabb verziója az Azure Cloud Shellben.
- Ha inkább helyi cli-referenciaparancsokat szeretne futtatni, jelentkezzen be az Azure CLI-be a az login parancs használatával.

Go 1.24 vagy újabb

Előkészítés

Először állítsa be az útmutató fiók- és fejlesztési környezetét. Ez a szakasz végigvezeti a fiók létrehozásának, a hitelesítő adatok beszerzésének, majd a fejlesztési környezet előkészítésének folyamatán.

Fiók létrehozása

Először hozzon létre egy API-t apache Cassandra-fiókhoz. A fiók létrehozása után hozza létre a kulcsteret és a táblaerőforrásokat.

Azure CLI
Azure Portál

Ha még nincs célerőforráscsoportja, a az group create paranccsal hozzon létre egy új erőforráscsoportot az előfizetésben.
```
az group create \
    --name "<resource-group-name>" \
    --location "<location>"
```

az cosmosdb create A paranccsal hozzon létre egy új Azure Cosmos DB-fiókot az Apache Cassandra-fiókhoz alapértelmezett beállításokkal.

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

Hozzon létre egy új kulcsteret az cosmosdb cassandra keyspace create használatával, amit cosmicworks nevére elnevezett.

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

Hozzon létre egy új JSON-objektumot, amely egy többsoros Bash-paranccsal ábrázolja a sémát. Ezután a az cosmosdb cassandra table create paranccsal hozzon létre egy új táblát.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"

Jelentkezzen be az Azure Portalra (https://portal.azure.com).
Írja be az Azure Cosmos DB-t a globális keresősávba.
A Szolgáltatások területen válassza az Azure Cosmos DB-t.
Az Azure Cosmos DB panelen válassza a Létrehozás, majd az Apache Cassandra-hoz készült Azure Cosmos DB lehetőséget a Egyebek lapon.
Válassza a fióktípushoz tartozó Kérelemegység (RU) adatbázisfiókot .

Az Alapszintű beállítások panelen konfigurálja a következő beállításokat, majd válassza a Véleményezés + létrehozás lehetőséget:

	Érték
Terhelés típusa	Tanulás
Előfizetés	Az Azure-előfizetés kiválasztása
Erőforráscsoport	Új erőforráscsoport létrehozása vagy meglévő erőforráscsoport kiválasztása
Fiók neve	Globálisan egyedi név megadása
Rendelkezésre állási zónák	letiltása
Helyszín	Válasszon egy támogatott Azure-régiót az előfizetéséhez

Jótanács

A meg nem határozott beállításokat az alapértelmezett értékekre hagyhatja. Konfigurálhatja azt is, hogy a fiók teljes átviteli sebessége másodpercenként 1000 kérelemegységre (RU/s) legyen korlátozva, vagy engedélyezze az ingyenes szintet a költségek minimalizálása érdekében.

A Véleményezés + létrehozás panelen várja meg, amíg a fiók érvényesítése sikeresen befejeződik, majd válassza a Létrehozás lehetőséget.
A portál automatikusan az Üzembe helyezés panelre navigál. Várjon, amíg az üzembe helyezés befejeződik.
Az üzembe helyezés befejezése után válassza az Erőforrás megnyitása lehetőséget az Apache Cassandra-fiókhoz tartozó új API-hoz való navigáláshoz.
Az erőforrásmenüben válassza az Adatkezelő lehetőséget.
Az Adatkezelőben válassza az + Új tábla lehetőséget.

A Táblázat hozzáadása párbeszédpanelen konfigurálja a következő beállításokat, majd válassza az OK gombot:

	Érték
Keyspace	Új létrehozása
Kulcstér neve	`cosmicworks`
táblanév	`product`
Táblaséma	`(id text, name text, category text, quantity int, price decimal, clearance boolean, PRIMARY KEY (id))`

Jótanács

A meg nem határozott beállításokat az alapértelmezett értékekre hagyhatja.

Hitelesítő adatok lekérése

Most szerezze be az ügyfélkódtár jelszavát, amellyel kapcsolatot hozhat létre a nemrég létrehozott fiókkal.

Azure CLI
Azure Portál

A fiók kapcsolattartási pontjának és felhasználónevének lekérésére használható az cosmosdb show .

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

Jegyezze le az contactPoint és username tulajdonságok értékét az előző parancsok kimenetéből. Ezeknek a tulajdonságoknak az értékei: a kapcsolattartási pont és a felhasználónév, amelyeket a könyvtárral való fiók-csatlakozáshoz használ az útmutató következő részeiben.

A fiók az cosmosdb keys list lekéréséhez használható.

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

Jegyezze fel a primaryMasterKey tulajdonság értékét az előző parancsok kimenetéből. Ennek a tulajdonságnak az értéke az jelszó, amit az útmutató későbbi részében használni fogsz a könyvtár segítségével a fiókhoz való csatlakozáshoz.

Fejlesztési környezet előkészítése

Ezután konfigurálja a fejlesztési környezetet egy új projekttel és az ügyfélkódtárral. Ez a lépés az utolsó szükséges előfeltétel, mielőtt továbblépne az útmutató többi részére.

Kezdje egy üres mappában.
Hozzon létre egy új Go-modult.
```
go mod init quickstart
```
Importálja a csomagot a github.com/apache/cassandra-gocql-driver/v2 Go-ból.
```
go get github.com/apache/cassandra-gocql-driver/v2
```
Hozza létre a main.go fájlt.
Adja hozzá a Go-alkalmazás sablonját.
```
package main

func main() {    
}
```
Fontos

Az útmutató további lépései feltételezi, hogy a kódot a main függvényen belül adja hozzá.

Objektummodell

	Leírás
`Cluster`	Egy specifikus klaszterkapcsolatot képvisel.
`Session`	Adott csoportkapcsolattal rendelkező entitások

Ügyfél hitelesítése

Első lépésként hitelesíti az ügyfelet az útmutatóban korábban összegyűjtött hitelesítő adatokkal.

Nyissa meg a main.go fájlt az integrált fejlesztési környezetben (IDE).
A függvényen main belül importálja a következő csomagokat a github.com/apache/cassandra-gocql-driver/v2 csomaggal együtt:
- context
- crypto/tls
```
import (
    "context"
    "crypto/tls"
    "github.com/apache/cassandra-gocql-driver/v2"
)
```
Sztringváltozók létrehozása az útmutatóban korábban gyűjtött hitelesítő adatokhoz. Nevezze el a változókat username, passwordés contactPoint.
```
username := "<username>"
password := "<password>"
contactPoint := "<contact-point>"
```
Konfiguráljon egy ilyen típusú példányt PasswordAuthenticator az előző lépésekben megadott hitelesítő adatokkal. Tárolja az eredményt egy névvel ellátott authenticationváltozóban.
```
authentication := gocql.PasswordAuthenticator{
    Username: username,
    Password: password,
}
```
Konfiguráljon egy SslOptions példányt a Transport Layer Security (TLS) protokoll legalább 1.2-es verziójával, a contactPoint változót célkiszolgálónév-ként megadva. Tárolja az eredményt egy névvel ellátott sslOptionsváltozóban.
```
sslOptions := &gocql.SslOptions{
    Config: &tls.Config{
        MinVersion: tls.VersionTLS12,
        ServerName: contactPoint,
    },
}
```
Hozzon létre egy új klaszterspecifikációt a NewCluster és a contactPoint változó használatával.
```
cluster := gocql.NewCluster(contactPoint)
```
Konfigurálja a fürtspecifikációs objektumot az előző lépésekben létrehozott hitelesítő- és konfigurációs változók használatával.
```
cluster.SslOpts = sslOptions
cluster.Authenticator = authentication
```
Konfigurálja a klaszter specifikációs objektum fennmaradó részét ezekkel a statikus értékekkel.
```
cluster.Keyspace = "cosmicworks"
cluster.Port = 10350
cluster.ProtoVersion = 4    
```
Hozzon létre egy új munkamenetet, amely a fürthöz csatlakozik a használatával CreateSession.
```
session, _ := cluster.CreateSession()
```
Konfigurálja a munkamenetet úgy, hogy a Close függvény visszatérése után meghívja a main függvényt.
```
defer session.Close()
```
Hozzon létre egy új Background környezeti objektumot, és tárolja a ctx változóban.
```
ctx := context.Background()
```

Figyelmeztetés

Ebben az útmutatóban le van tiltva a teljes átviteli rétegbiztonság (TLS) ellenőrzése a hitelesítés egyszerűsítése érdekében. Éles telepítéseknél teljesen engedélyezze az érvényesítést.

Adatok frissítése vagy beszúrása

Következő lépésként új adatokat kell beszúrni egy táblába. Az Upserting biztosítja az adatok megfelelő létrehozását vagy cseréjét attól függően, hogy ugyanazok az adatok már léteznek-e a táblában.

Adjon meg egy új, az útmutatóban korábban létrehozott táblának megfelelő mezőkkel ellátott Product új típust.
```
type Product struct {
    id        string
    name      string
    category  string
    quantity  int
    clearance bool
}
```
Jótanács

A Go alkalmazásban létrehozhatja ezt a típust egy másik fájlban, vagy létrehozhatja a meglévő fájl végén.

Hozzon létre egy új típusú Productobjektumot. Tárolja az objektumot egy névvel ellátott productváltozóban.

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

Hozzon létre egy új sztringváltozót insertQuery a Cassandra Query Language (CQL) lekérdezéssel egy új sor beszúrásához.

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

A lekérdezés futtatásához használja az Query és ExecContext a függvényeket. Adja meg a product változó különböző tulajdonságait lekérdezési paraméterekként.
```
_ = session.Query(
    insertQuery,
    product.id, 
    product.name, 
    product.category, 
    product.quantity, 
    product.clearance,
).ExecContext(ctx)
```

Adatok beolvasása

Ezután olvassa be azokat az adatokat, amelyeket korábban a táblázatba illesztett be.

Hozzon létre egy új karakterlánc változót readQuery, amely CQL-lekérdezést tartalmaz, és megegyezik az azonos id mezővel rendelkező elemekkel.

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

Hozzon létre egy sztringváltozót id ugyanazzal az értékkel, mint a jelen útmutatóban korábban létrehozott termék.
```
id := "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb" 
```
Hozzon létre egy másik változót, matchedProduct amely a művelet eredményét tárolja.
```
var matchedProduct Product
```

QueryA , , ConsistencyIterContextés Scan függvények együttes használatával megkeresheti a lekérdezésnek megfelelő egyetlen elemet, és hozzárendelheti annak tulajdonságait a matchedProduct változóhoz.

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

Adatok lekérdezése

Végül egy lekérdezéssel megkeresheti a táblában egy adott szűrőnek megfelelő összes adatot.

Hozzon létre sztringváltozókat findQuery a CQL-lekérdezéssel és category a szükséges paraméterrel.

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

category := "gear-surf-surfboards"

Query, Consistency, IterContext és Scanner függvények együttes használatával hozzon létre egy szkennert, amely több elemen tud iterálni, amelyek megfelelnek a lekérdezésnek.
```
queriedProducts := session.Query(
    findQuery, 
    &category,
).Consistency(gocql.All).IterContext(ctx).Scanner()
```

A Next és Scan függvények használatával áttekintheti a lekérdezés eredményein, és az egyes eredmények tulajdonságait hozzárendelheti a belső queriedProduct változóhoz.

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

A kód futtatása

Futtassa az újonnan létrehozott alkalmazást egy terminál használatával az alkalmazáskönyvtárban.

go run .

Erőforrások tisztítása