Szybki start: biblioteka klienta Azure Cosmos DB dla Apache Cassandra w Go

Dotyczy: ✅ Apache Cassanda

Rozpocznij pracę z biblioteką klienta usługi Azure Cosmos DB for Apache Cassandra dla języka Go, aby przechowywać dane bez struktury i zarządzać nimi. Wykonaj kroki opisane w tym przewodniku, aby utworzyć nowe konto, zainstalować bibliotekę klienta języka Go, nawiązać połączenie z kontem, wykonać typowe operacje i wykonać zapytania dotyczące końcowych danych przykładowych.

Dokumentacja referencyjna API | Kod źródłowy biblioteki | Pakiet (Go)

Wymagania wstępne

Subskrypcja platformy Azure
- Jeśli nie masz subskrypcji Azure, przed rozpoczęciem utwórz darmowe konto.

Najnowsza wersja interfejsu wiersza polecenia platformy Azure w usłudze Azure Cloud Shell.
- Jeśli wolisz uruchamiać polecenia referencyjne CLI lokalnie, zaloguj się do Azure CLI przy użyciu polecenia az login.

Go 1.24 lub nowsze

Konfigurowanie

Najpierw skonfiguruj konto i środowisko programistyczne dla tego przewodnika. W tej sekcji przedstawiono proces tworzenia konta, uzyskiwania poświadczeń, a następnie przygotowywania środowiska deweloperskiego.

Tworzenie konta

Zacznij od utworzenia interfejsu API dla konta apache Cassandra. Po utworzeniu konta utwórz przestrzeń kluczy i zasoby tabeli.

"Azure CLI"
Portal Azure

Jeśli nie masz jeszcze docelowej grupy zasobów, użyj az group create polecenia , aby utworzyć nową grupę zasobów w ramach subskrypcji.
```
az group create \
    --name "<resource-group-name>" \
    --location "<location>"
```

Użyj polecenia , az cosmosdb create aby utworzyć nowe konto usługi Azure Cosmos DB dla bazy danych Apache Cassandra z ustawieniami domyślnymi.

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

Utwórz nową przestrzeń kluczy za pomocą az cosmosdb cassandra keyspace create o nazwie cosmicworks.

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

Utwórz nowy obiekt JSON reprezentujący schemat przy użyciu wielolinijkowego polecenia Bash. Następnie użyj az cosmosdb cassandra table create polecenia , aby utworzyć nową tabelę o nazwie 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"

Zaloguj się do witryny Azure Portal (https://portal.azure.com).
Wprowadź wartość Azure Cosmos DB na pasku wyszukiwania globalnego.
W obszarze Usługi wybierz pozycję Azure Cosmos DB.
W okienku Azure Cosmos DB wybierz pozycję Utwórz, a następnie pozycję Azure Cosmos DB for Apache Cassandra na karcie Inne .
Wybierz Request unit (RU) database account dla typu konta.

W okienku Podstawowe skonfiguruj następujące opcje, a następnie wybierz pozycję Przejrzyj i utwórz:

	Wartość
Typ obciążenia	Szkolenie
Subskrypcja	Wybierz subskrypcję platformy Azure
Grupa zasobów	Utwórz nową grupę zasobów lub wybierz istniejącą grupę zasobów
Nazwa konta	Podaj globalnie unikatową nazwę
Strefy dostępności	Wyłącz
Lokalizacja	Wybieranie obsługiwanego regionu platformy Azure dla subskrypcji

Wskazówka

Możesz pozostawić wszystkie nieokreślone opcje do ich wartości domyślnych. Możesz również skonfigurować konto, aby ograniczyć łączną przepływność konta do 1000 jednostek żądań na sekundę (RU/s) lub włączyć warstwę Bezpłatna, aby zminimalizować koszty.

W okienku Przeglądanie i tworzenie poczekaj na pomyślne zakończenie walidacji konta, a następnie wybierz pozycję Utwórz.
Portal automatycznie przechodzi do okienka Wdrażanie. Poczekaj na zakończenie wdrożenia.
Po zakończeniu wdrażania wybierz pozycję Przejdź do zasobu, aby uzyskać dostęp do nowego interfejsu API dla konta Apache Cassandra.
W menu zasobów wybierz opcję Eksplorator danych .
W Eksploratorze danych wybierz pozycję + Nowa tabela.

W oknie dialogowym Dodawanie tabeli skonfiguruj następujące opcje, a następnie wybierz przycisk OK:

	Wartość
Keyspace	Utwórz nową
Nazwa przestrzeni kluczy	`cosmicworks`
Nazwa tabeli	`product`
Schemat tabeli	`(id text, name text, category text, quantity int, price decimal, clearance boolean, PRIMARY KEY (id))`

Wskazówka

Możesz pozostawić wszystkie nieokreślone opcje do ich wartości domyślnych.

Pobieranie poświadczeń

Teraz pobierz hasło biblioteki klienta do utworzenia połączenia z niedawno utworzonym kontem.

"Azure CLI"
Portal Azure

Użyj az cosmosdb show polecenia , aby uzyskać punkt kontaktu i nazwę użytkownika dla konta.

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

Zapisz wartości właściwości contactPoint i username z danych wyjściowych poprzednich poleceń. Wartości tych właściwości to punkt kontaktowy i nazwa użytkownika używana w dalszej części tego przewodnika w celu nawiązania połączenia z kontem z biblioteką.

Użyj az cosmosdb keys list polecenia, aby pobrać klucze dla konta.

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

Zanotuj wartość właściwości primaryMasterKey z danych wyjściowych wcześniejszych poleceń. Wartość tej właściwości to hasło , którego użyjesz w dalszej części tego przewodnika, aby nawiązać połączenie z kontem z biblioteką.

Przygotowywanie środowiska projektowego

Następnie skonfiguruj środowisko deweloperskie przy użyciu nowego projektu i biblioteki klienta. Ten krok jest ostatnim wymaganiem wstępnym przed przejściem do pozostałej części tego przewodnika.

Rozpocznij w pustym katalogu.
Utwórz nowy moduł języka Go.
```
go mod init quickstart
```
Zaimportuj github.com/apache/cassandra-gocql-driver/v2 pakiet z Go.
```
go get github.com/apache/cassandra-gocql-driver/v2
```
Utwórz plik main.go .
Dodaj szablon aplikacji Go.
```
package main

func main() {    
}
```
Ważne

W pozostałych krokach tego przewodnika założono, że dodajesz swój kod w funkcji main.

Model obiektów

	Opis
`Cluster`	Reprezentuje określone połączenie z klastrem
`Session`	Jednostki, które przechowują określone połączenie z klastrem

Uwierzytelnianie klienta

Zacznij od uwierzytelnienia klienta przy użyciu poświadczeń zebranych wcześniej w tym przewodniku.

Otwórz plik main.go w zintegrowanym środowisku projektowym (IDE).
W funkcji main zaimportuj następujące pakiety wraz z pakietem github.com/apache/cassandra-gocql-driver/v2:
- context
- crypto/tls
```
import (
    "context"
    "crypto/tls"
    "github.com/apache/cassandra-gocql-driver/v2"
)
```
Utwórz zmienne tekstowe dla poświadczeń zebranych wcześniej w tym przewodniku. Nazwij zmienne username, passwordi contactPoint.
```
username := "<username>"
password := "<password>"
contactPoint := "<contact-point>"
```
Skonfiguruj wystąpienie typu PasswordAuthenticator używając poświadczeń określonych w poprzednich krokach. Zapisz wynik w zmiennej o nazwie authentication.
```
authentication := gocql.PasswordAuthenticator{
    Username: username,
    Password: password,
}
```
Skonfiguruj wystąpienie SslOptions z minimalną wersją protokołu Transport Layer Security (TLS) 1.2 i contactPoint zmienną jako nazwę serwera docelowego. Zapisz wynik w zmiennej o nazwie sslOptions.
```
sslOptions := &gocql.SslOptions{
    Config: &tls.Config{
        MinVersion: tls.VersionTLS12,
        ServerName: contactPoint,
    },
}
```
Utwórz nową specyfikację klastra przy użyciu NewCluster i zmiennej contactPoint.
```
cluster := gocql.NewCluster(contactPoint)
```
Skonfiguruj obiekt specyfikacji klastra przy użyciu zmiennych poświadczeń i konfiguracji utworzonych w poprzednich krokach.
```
cluster.SslOpts = sslOptions
cluster.Authenticator = authentication
```
Skonfiguruj pozostałą część obiektu specyfikacji klastra przy użyciu tych wartości statycznych.
```
cluster.Keyspace = "cosmicworks"
cluster.Port = 10350
cluster.ProtoVersion = 4    
```
Utwórz nową sesję, która łączy się z klastrem przy użyciu polecenia CreateSession.
```
session, _ := cluster.CreateSession()
```
Skonfiguruj sesję, aby wywołać funkcję Close po tym, jak funkcja main zakończy działanie.
```
defer session.Close()
```
Utwórz nowy Background obiekt kontekstu i zapisz go w zmiennej ctx .
```
ctx := context.Background()
```

Ostrzeżenie

Pełna weryfikacja zabezpieczeń warstwy transportu (TLS) jest wyłączona w tym przewodniku, aby uprościć uwierzytelnianie. W przypadku wdrożeń produkcyjnych w pełni włącz walidację.

Aktualizuj lub dodaj dane

Następnie dodaj nowe dane do tabeli. Upserting gwarantuje, że dane są tworzone lub zastępowane odpowiednio w zależności od tego, czy te same dane już istnieją w tabeli.

Zdefiniuj nowy typ o nazwie Product z polami odpowiadającymi tabeli utworzonej wcześniej w tym przewodniku.
```
type Product struct {
    id        string
    name      string
    category  string
    quantity  int
    clearance bool
}
```
Wskazówka

W języku Go możesz utworzyć ten typ w innym pliku lub utworzyć go na końcu istniejącego pliku.

Utwórz nowy obiekt typu Product. Zapisz obiekt w zmiennej o nazwie product.

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

Utwórz nową zmienną ciągu o nazwie insertQuery z zapytaniem Języka zapytań Cassandra (CQL) w celu wstawienia nowego wiersza.

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

Użyj funkcji Query i ExecContext, aby uruchomić zapytanie. Przekaż różne właściwości zmiennej product jako parametry zapytania.

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

Odczyt danych

Następnie odczytaj dane, które zostały wcześniej dodane lub zmodyfikowane w tabeli.

Utwórz nową zmienną ciągu o nazwie readQuery z zapytaniem CQL, które pasuje do elementów z tym samym id polem.

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

Utwórz zmienną ciągu o nazwie id o tej samej wartości co produkt utworzony wcześniej w tym przewodniku.
```
id := "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb" 
```
Utwórz inną zmienną o nazwie matchedProduct , aby zapisać wynik tej operacji.
```
var matchedProduct Product
```

Użyj funkcji Query, Consistency, IterContext i Scan razem, aby znaleźć pojedynczy element zgodny z zapytaniem i przypisać jego właściwości do zmiennej matchedProduct.

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

Wykonywanie zapytań o dane

Na koniec użyj zapytania, aby znaleźć wszystkie dane zgodne z określonym filtrem w tabeli.

Utwórz zmienne ciągu o nazwie findQuery i category za pomocą zapytania CQL i wymaganego parametru.

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

category := "gear-surf-surfboards"

Użyj funkcji Query, Consistency, IterContext i Scanner razem, aby utworzyć skaner, który potrafi iterować przez wiele elementów, które pasują do zapytania.
```
queriedProducts := session.Query(
    findQuery, 
    &category,
).Consistency(gocql.All).IterContext(ctx).Scanner()
```

Użyj funkcji Next i Scan, aby iterować po wynikach zapytania i przypisywać właściwości każdego wyniku do zmiennej wewnętrznej 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
}

Uruchamianie kodu

Uruchom nowo utworzoną aplikację przy użyciu terminalu w katalogu aplikacji.

go run .

Uprzątnij zasoby