Szybki start: używanie usługi Azure Cosmos DB dla noSQL z zestawem Azure SDK dla języka Go

Artykuł
11/09/2024
Dotyczy:

✅ NoSQL

W tym przewodniku Szybki start wdrożysz podstawową aplikację usługi Azure Cosmos DB dla tabel przy użyciu zestawu Azure SDK dla języka Go. Usługa Azure Cosmos DB dla tabel to bez schematu magazyn danych, który umożliwia aplikacjom przechowywanie danych ze strukturą tabeli w chmurze. Dowiesz się, jak tworzyć tabele, wiersze i wykonywać podstawowe zadania w ramach zasobu usługi Azure Cosmos DB przy użyciu zestawu Azure SDK dla języka Go.

Dokumentacja interfejsu API — dokumentacja | pakietu kodu | źródłowego biblioteki (Go) | Interfejs wiersza polecenia dla deweloperów platformy Azure

Wymagania wstępne

Azure Developer CLI
Docker Desktop
Go 1.21 lub nowszy

Jeśli nie masz jeszcze konta platformy Azure, przed rozpoczęciem utwórz bezpłatne konto.

Inicjowanie projektu

Użyj interfejsu wiersza polecenia dla deweloperów platformy Azure (azd), aby utworzyć usługę Azure Cosmos DB dla konta tabeli i wdrożyć konteneryzowaną przykładową aplikację. Przykładowa aplikacja używa biblioteki klienta do zarządzania, tworzenia, odczytywania i wykonywania zapytań dotyczących przykładowych danych.

Otwórz terminal w pustym katalogu.
Jeśli jeszcze nie uwierzytelniono, uwierzytelnij się w interfejsie wiersza polecenia dewelopera platformy Azure przy użyciu polecenia azd auth login. Wykonaj kroki określone przez narzędzie, aby uwierzytelnić się w interfejsie wiersza polecenia przy użyciu preferowanych poświadczeń platformy Azure.
```
azd auth login
```

Użyj azd init polecenia , aby zainicjować projekt.

azd init --template cosmos-db-nosql-go-quickstart

Podczas inicjowania skonfiguruj unikatową nazwę środowiska.
Wdróż konto usługi Azure Cosmos DB przy użyciu polecenia azd up. Szablony Bicep wdrażają również przykładową aplikację internetową.
```
azd up
```
Podczas procesu aprowizacji wybierz subskrypcję, żądaną lokalizację i docelową grupę zasobów. Poczekaj na zakończenie procesu aprowizacji. Proces może potrwać około pięciu minut.

Po zakończeniu aprowizacji zasobów platformy Azure adres URL uruchomionej aplikacji internetowej zostanie uwzględniony w danych wyjściowych.

Deploying services (azd deploy)

  (✓) Done: Deploying service web
- Endpoint: <https://[container-app-sub-domain].azurecontainerapps.io>

SUCCESS: Your application was provisioned and deployed to Azure in 5 minutes 0 seconds.

Użyj adresu URL w konsoli, aby przejść do aplikacji internetowej w przeglądarce. Obserwuj dane wyjściowe uruchomionej aplikacji.

Zrzut ekranu przedstawiający uruchomioną aplikację internetową.

Instalowanie biblioteki klienta

Biblioteka klienta jest dostępna za pośrednictwem języka Go jako azcosmos pakietu.

Otwórz terminal i przejdź do /src folderu.
```
cd ./src
```
Jeśli pakiet nie został jeszcze zainstalowany, zainstaluj go azcosmos przy użyciu polecenia go install.
```
go install github.com/Azure/azure-sdk-for-go/sdk/data/azcosmos
```
Ponadto zainstaluj azidentity pakiet, jeśli nie został jeszcze zainstalowany.
```
go install github.com/Azure/azure-sdk-for-go/sdk/azidentity
```
Otwórz i przejrzyj plik src/go.mod , aby sprawdzić, czy github.com/Azure/azure-sdk-for-go/sdk/data/azcosmos oba wpisy i github.com/Azure/azure-sdk-for-go/sdk/azidentity istnieją.

Model obiektów

Nazwa/nazwisko	opis
`CosmosClient`	Ta klasa jest podstawową klasą klienta i służy do zarządzania metadanymi lub bazami danych dla całego konta.
`CosmosDatabase`	Ta klasa reprezentuje bazę danych w ramach konta.
`CosmosContainer`	Ta klasa jest używana głównie do wykonywania operacji odczytu, aktualizacji i usuwania w kontenerze lub elementach przechowywanych w kontenerze.
`PartitionKey`	Ta klasa reprezentuje klucz partycji logicznej. Ta klasa jest wymagana w przypadku wielu typowych operacji i zapytań.

Przykładowy kod w szablonie używa bazy danych o nazwie i kontenera o nazwie cosmicworks products. Kontener products zawiera szczegóły, takie jak nazwa, kategoria, ilość, unikatowy identyfikator i flaga sprzedaży dla każdego produktu. Kontener używa /category właściwości jako klucza partycji logicznej.

Uwierzytelnianie użytkownika

Ten przykład tworzy nowe wystąpienie CosmosClient użycia i azcosmos.NewClient uwierzytelnia się przy użyciu DefaultAzureCredential wystąpienia.

credential, err := azidentity.NewDefaultAzureCredential(nil)
if err != nil {
    return err
}

clientOptions := azcosmos.ClientOptions{
    EnableContentResponseOnWrite: true,
}

client, err := azcosmos.NewClient("<azure-cosmos-db-nosql-account-endpoint>", credential, &clientOptions)
if err != nil {
    return err
}

Pobieranie bazy danych

Użyj client.NewDatabase polecenia , aby pobrać istniejącą bazę danych o nazwie cosmicworks.

database, err := client.NewDatabase("cosmicworks")
if err != nil {
    return err
}

Pobieranie kontenera

Pobierz istniejący products kontener przy użyciu polecenia database.NewContainer.

container, err := database.NewContainer("products")
if err != nil {
    return err
}

Tworzenie elementu

Skompiluj typ języka Go ze wszystkimi elementami członkowskimi, które chcesz serializować w formacie JSON. W tym przykładzie typ ma unikatowy identyfikator i pola dla kategorii, nazwy, ilości, ceny i sprzedaży.

type Item struct {
  Id        string  `json:"id"`
  Category  string  `json:"category"`
  Name      string  `json:"name"`
  Quantity  int     `json:"quantity"`
  Price     float32 `json:"price"`
  Clearance bool    `json:"clearance"`
}

Utwórz element w kontenerze przy użyciu polecenia container.UpsertItem. Ta metoda "upserts" element skutecznie zastępuje element, jeśli już istnieje.

item := Item {
    Id:        "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
    Category:  "gear-surf-surfboards",
    Name:      "Yamba Surfboard",
    Quantity:  12,
    Price:     850.00,
    Clearance: false,
}

partitionKey := azcosmos.NewPartitionKeyString("gear-surf-surfboards")

context := context.TODO()

bytes, err := json.Marshal(item)
if err != nil {
    return err
}

response, err := container.UpsertItem(context, partitionKey, bytes, nil)
if err != nil {
    return err
}

Odczytywanie elementu

Wykonaj operację odczytu punktu przy użyciu pól unikatowego identyfikatora (id) i klucza partycji. Służy container.ReadItem do wydajnego pobierania określonego elementu.

partitionKey := azcosmos.NewPartitionKeyString("gear-surf-surfboards")

context := context.TODO()

itemId := "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"

response, err := container.ReadItem(context, partitionKey, itemId, nil)
if err != nil {
    return err
}

if response.RawResponse.StatusCode == 200 {
    read_item := Item{}
    err := json.Unmarshal(response.Value, &read_item)
    if err != nil {
        return err
    }
}

Elementy kwerend

Wykonaj zapytanie dotyczące wielu elementów w kontenerze przy użyciu polecenia container.NewQueryItemsPager. Znajdź wszystkie elementy w określonej kategorii przy użyciu tego sparametryzowanego zapytania:

SELECT * FROM products p WHERE p.category = @category

partitionKey := azcosmos.NewPartitionKeyString("gear-surf-surfboards")

query := "SELECT * FROM products p WHERE p.category = @category"

queryOptions := azcosmos.QueryOptions{
    QueryParameters: []azcosmos.QueryParameter{
        {Name: "@category", Value: "gear-surf-surfboards"},
    },
}

pager := container.NewQueryItemsPager(query, partitionKey, &queryOptions)

Przeanalizuj wyniki zapytania podzielonego na strony, wykonując pętlę na każdej stronie wyników przy użyciu polecenia pager.NextPage. Użyj pager.More polecenia , aby określić, czy istnieją jakiekolwiek wyniki pozostawione na początku każdej pętli.

items := []Item{}

for pager.More() {
    response, err := pager.NextPage(context.TODO())
    if err != nil {
        return err
    }

    for _, bytes := range response.Items {
        item := Item{}
        err := json.Unmarshal(bytes, &item)
        if err != nil {
            return err
        }
        items = append(items, item)
    }
}

Czyszczenie zasobów

Jeśli nie potrzebujesz już przykładowej aplikacji lub zasobów, usuń odpowiednie wdrożenie i wszystkie zasoby.

azd down

Udostępnij za pośrednictwem

Szybki start: używanie usługi Azure Cosmos DB dla noSQL z zestawem Azure SDK dla języka Go

Wymagania wstępne

Inicjowanie projektu

Instalowanie biblioteki klienta

Model obiektów

Przykłady kodu

Uwierzytelnianie użytkownika

Pobieranie bazy danych

Pobieranie kontenera

Tworzenie elementu

Odczytywanie elementu

Elementy kwerend

Czyszczenie zasobów

Opinia

Dodatkowe zasoby

Udostępnij za pośrednictwem

Szybki start: używanie usługi Azure Cosmos DB dla noSQL z zestawem Azure SDK dla języka Go

Wymagania wstępne

Inicjowanie projektu

Instalowanie biblioteki klienta

Model obiektów

Przykłady kodu

Uwierzytelnianie użytkownika

Pobieranie bazy danych

Pobieranie kontenera

Tworzenie elementu

Odczytywanie elementu

Elementy kwerend

Czyszczenie zasobów

Powiązana zawartość

Opinia

Dodatkowe zasoby