Szybki start: biblioteka Azure Cosmos DB for NoSQL dla języka Go
DOTYCZY: NoSQL
Rozpocznij pracę z biblioteką klienta usługi Azure Cosmos DB for NoSQL dla języka Go, aby wykonywać zapytania o dane w kontenerach i wykonywać typowe operacje na poszczególnych elementach. Wykonaj następujące kroki, aby wdrożyć minimalne rozwiązanie w środowisku przy użyciu interfejsu wiersza polecenia dla deweloperów platformy Azure.
Dokumentacja interfejsu API — dokumentacja | pakietu kodu | źródłowego biblioteki (Go) | Interfejs wiersza polecenia dla deweloperów platformy Azure
Wymagania wstępne
- Konto platformy Azure z aktywną subskrypcją. Utwórz konto bezpłatnie.
- Konto usługi GitHub
- Konto platformy Azure z aktywną subskrypcją. Utwórz konto bezpłatnie.
- Interfejs wiersza polecenia dla deweloperów platformy Azure
- Docker Desktop
Konfigurowanie
Wdróż kontener projektowy w swoim środowisku. Następnie użyj interfejsu wiersza polecenia dla deweloperów platformy Azure (azd
), aby utworzyć konto usługi Azure Cosmos DB for NoSQL 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.
Ważne
Konta usługi GitHub obejmują uprawnienia do magazynowania i godzin podstawowych bez ponoszenia kosztów. Aby uzyskać więcej informacji, zobacz uwzględnione godziny magazynowania i rdzeni dla kont usługi GitHub.
Otwórz terminal w katalogu głównym projektu.
Uwierzytelnianie w interfejsie wiersza polecenia dla deweloperów 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
Podczas inicjowania skonfiguruj unikatową nazwę środowiska.
Napiwek
Nazwa środowiska będzie również używana jako nazwa docelowej grupy zasobów. W tym przewodniku Szybki start rozważ użycie polecenia
msdocs-cosmos-db
.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ę i żądaną lokalizację. 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.
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 poleceniago 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 igithub.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łady kodu
- Uwierzytelnianie użytkownika
- Pobieranie bazy danych
- Pobieranie kontenera
- Tworzenie elementu
- Pobieranie elementu
- Elementy kwerend
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
Żądania aplikacji do większości usług platformy Azure muszą być autoryzowane. DefaultAzureCredential
Użyj typu jako preferowanego sposobu implementacji połączenia bez hasła między aplikacjami i usługą Azure Cosmos DB for NoSQL. DefaultAzureCredential
obsługuje wiele metod uwierzytelniania i określa, która metoda powinna być używana w czasie wykonywania.
Ważne
Możesz również autoryzować żądania do usług platformy Azure przy użyciu haseł, parametry połączenia lub innych poświadczeń bezpośrednio. Należy jednak zachować ostrożność przy użyciu tego podejścia. Deweloperzy muszą być sumienni, aby nigdy nie ujawniać tych wpisów tajnych w niezabezpieczonej lokalizacji. Każdy, kto uzyskuje dostęp do hasła lub klucza tajnego, może uwierzytelnić się w usłudze bazy danych. DefaultAzureCredential
oferuje ulepszone korzyści związane z zarządzaniem i zabezpieczeniami za pośrednictwem klucza konta, aby umożliwić uwierzytelnianie bez hasła bez ryzyka przechowywania kluczy.
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(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: "70b63682-b93a-4c77-aad2-65501347265f",
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 := "70b63682-b93a-4c77-aad2-65501347265f"
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.
context := context.TODO()
items := []Item{}
requestCharge := float32(0)
for pager.More() {
response, err := pager.NextPage(context)
if err != nil {
return err
}
requestCharge += response.RequestCharge
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
W usłudze GitHub Codespaces usuń działającą przestrzeń kodu, aby zmaksymalizować uprawnienia magazynu i rdzenia.
Powiązana zawartość
- Przewodnik Szybki start dla platformy .NET
- Przewodnik Szybki start dotyczący języka JavaScript/Node.js
- Przewodnik Szybki start dla języka Java
- Przewodnik Szybki start dla języka Python