Rychlý start: Knihovna Azure Cosmos DB for NoSQL pro Go
PLATÍ PRO: NoSQL
Začněte s klientskou knihovnou Azure Cosmos DB for NoSQL for Go, která umožňuje dotazovat data v kontejnerech a provádět běžné operace s jednotlivými položkami. Pomocí následujícího postupu nasaďte do svého prostředí minimální řešení pomocí Azure Developer CLI.
Referenční dokumentace k | rozhraní API – Balíček zdrojového kódu | knihovny (Go) | Azure Developer CLI
Požadavky
- Účet Azure s aktivním předplatným. Vytvoření účtu zdarma
- Účet GitHub
- Účet Azure s aktivním předplatným. Vytvoření účtu zdarma
- Azure Developer CLI
- Docker Desktop
Nastavení
Nasaďte vývojový kontejner tohoto projektu do svého prostředí. Pak pomocí Azure Developer CLI (azd
) vytvořte účet Azure Cosmos DB for NoSQL a nasaďte kontejnerizovanou ukázkovou aplikaci. Ukázková aplikace používá klientskou knihovnu ke správě, vytváření, čtení a dotazování ukázkových dat.
Důležité
Účty GitHubu zahrnují nárok na úložiště a hodiny jádra bez poplatků. Další informace najdete v zahrnutých hodinách úložiště a jader pro účty GitHubu.
Otevřete terminál v kořenovém adresáři projektu.
Ověřte se v Rozhraní příkazového řádku Azure Developer CLI pomocí
azd auth login
rozhraní příkazového řádku . Postupujte podle kroků určených nástrojem k ověření v rozhraní příkazového řádku pomocí vašich upřednostňovaných přihlašovacích údajů Azure.azd auth login
Slouží
azd init
k inicializaci projektu.azd init --template cosmos-db-nosql-go-quickstart
Poznámka:
V tomto rychlém startu se používá úložiště GitHub šablony azure-samples/cosmos-db-nosql-go-quickstart . Azure Developer CLI tento projekt automaticky naklonuje na váš počítač, pokud tam ještě není.
Během inicializace nakonfigurujte jedinečný název prostředí.
Tip
Název prostředí se také použije jako název cílové skupiny prostředků. Pro účely tohoto rychlého startu zvažte použití .
msdocs-cosmos-db
Nasaďte účet služby Azure Cosmos DB pomocí
azd up
. Šablony Bicep také nasazují ukázkovou webovou aplikaci.azd up
Během procesu zřizování vyberte své předplatné a požadované umístění. Počkejte na dokončení procesu zřizování. Proces může trvat přibližně pět minut.
Po dokončení zřizování prostředků Azure se do výstupu zahrne adresa URL spuštěné webové aplikace.
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.
Pomocí adresy URL v konzole přejděte do webové aplikace v prohlížeči. Sledujte výstup spuštěné aplikace.
Instalace klientské knihovny
Klientská knihovna je k dispozici prostřednictvím jazyka azcosmos
Go jako balíček.
Otevřete terminál a přejděte do
/src
složky.cd ./src
Pokud ještě není nainstalovaný, nainstalujte
azcosmos
balíček pomocígo install
.go install github.com/Azure/azure-sdk-for-go/sdk/data/azcosmos
Pokud ještě není nainstalovaný, nainstalujte
azidentity
balíček.go install github.com/Azure/azure-sdk-for-go/sdk/azidentity
Otevřete a zkontrolujte soubor src/go.mod a ověřte, že
github.com/Azure/azure-sdk-for-go/sdk/azidentity
github.com/Azure/azure-sdk-for-go/sdk/data/azcosmos
obě položky existují.
Objektový model
Název | Popis |
---|---|
CosmosClient |
Tato třída je primární klientskou třídou a slouží ke správě metadat nebo databází pro celý účet. |
CosmosDatabase |
Tato třída představuje databázi v rámci účtu. |
CosmosContainer |
Tato třída se primárně používá k provádění operací čtení, aktualizace a odstraňování v kontejneru nebo v položkách uložených v kontejneru. |
PartitionKey |
Tato třída představuje klíč logického oddílu. Tato třída se vyžaduje pro mnoho běžných operací a dotazů. |
Příklady kódu
- Ověření klienta
- Získání databáze
- Získání kontejneru
- Vytvoření položky
- Získání položky
- Dotazování položek
Vzorový kód v šabloně používá databázi pojmenovanou cosmicworks
a kontejner s názvem products
. Kontejner products
obsahuje podrobnosti, jako je název, kategorie, množství, jedinečný identifikátor a příznak prodeje pro každý produkt. Kontejner používá /category
vlastnost jako klíč logického oddílu.
Ověření klienta
Žádosti o aplikace na většinu služeb Azure musí být autorizované. Tento DefaultAzureCredential
typ použijte jako upřednostňovaný způsob implementace bez hesla mezi vašimi aplikacemi a Službou Azure Cosmos DB for NoSQL. DefaultAzureCredential
podporuje více metod ověřování a určuje, která metoda se má použít za běhu.
Důležité
Žádosti o služby Azure můžete také autorizovat pomocí hesel, připojovací řetězec nebo jiných přihlašovacích údajů přímo. Tento přístup by však měl být používán s opatrností. Vývojáři musí být usilovní, aby tyto tajné kódy nikdy nezpřístupnili v nezabezpečeném umístění. Každý, kdo získá přístup k heslu nebo tajnému klíči, se může ověřit v databázové službě. DefaultAzureCredential
nabízí vylepšené výhody správy a zabezpečení oproti klíči účtu, které umožňují ověřování bez hesla bez rizika ukládání klíčů.
Tato ukázka vytvoří novou instanci CosmosClient
použití azcosmos.NewClient
a ověření pomocí DefaultAzureCredential
instance.
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
}
Získání databáze
Slouží client.NewDatabase
k načtení existující databáze s názvem cosmicworks
.
database, err := client.NewDatabase("cosmicworks")
if err != nil {
return err
}
Získání kontejneru
Načtení existujícího products
kontejneru pomocí database.NewContainer
.
container, err := database.NewContainer("products")
if err != nil {
return err
}
Vytvoření položky
Sestavte typ Go se všemi členy, které chcete serializovat do formátu JSON. V tomto příkladu má typ jedinečný identifikátor a pole pro kategorii, název, množství, cenu a prodej.
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"`
}
Vytvoření položky v kontejneru pomocí container.UpsertItem
. Tato metoda "upserts" položku účinně nahradí položku, pokud již existuje.
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
}
Čtení položky
Proveďte operaci čtení bodu pomocí polí jedinečného identifikátoru (id
) i klíče oddílu. Slouží container.ReadItem
k efektivnímu načtení konkrétní položky.
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
}
}
Dotazování položek
Proveďte dotaz na více položek v kontejneru pomocí container.NewQueryItemsPager
. Pomocí tohoto parametrizovaného dotazu vyhledejte všechny položky v zadané kategorii:
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)
Parsujte stránkované výsledky dotazu tak, že projdete každou stránku výsledků pomocí pager.NextPage
. Slouží pager.More
k určení, jestli na začátku každé smyčky zbývá nějaké výsledky.
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)
}
}
Vyčištění prostředků
Pokud už ukázkovou aplikaci nebo prostředky nepotřebujete, odeberte odpovídající nasazení a všechny prostředky.
azd down
V GitHub Codespaces odstraňte spuštěný codespace, abyste maximalizovali nároky na úložiště a jádro.