Quickstart: Azure Cosmos DB for NoSQL-bibliotheek voor Go

Artikel
01/10/2024

VAN TOEPASSING OP: NoSQL

Ga aan de slag met de Azure Cosmos DB for NoSQL-clientbibliotheek voor Go om gegevens in uw containers op te vragen en algemene bewerkingen uit te voeren op afzonderlijke items. Volg deze stappen om een minimale oplossing in uw omgeving te implementeren met behulp van de Azure Developer CLI.

API-referentiedocumentatiebibliotheek | broncodepakket | (Go) | Azure Developer CLI

Vereisten

Een Azure-account met een actief abonnement. Gratis een account maken
Een GitHub-account

Een Azure-account met een actief abonnement. Gratis een account maken
Azure Developer CLI
Docker Desktop

Instellen

Implementeer de ontwikkelcontainer van dit project in uw omgeving. Gebruik vervolgens de Azure Developer CLI (azd) om een Azure Cosmos DB for NoSQL-account te maken en een containervoorbeeldtoepassing te implementeren. De voorbeeldtoepassing maakt gebruik van de clientbibliotheek voor het beheren, maken, lezen en opvragen van voorbeeldgegevens.

Belangrijk

GitHub-accounts bevatten gratis rechten voor opslag en kernuren. Zie inbegrepen opslag- en kernuren voor GitHub-accounts voor meer informatie.

Open een terminal in de hoofdmap van het project.
Verifiëren bij de Azure Developer CLI met behulp van azd auth login. Volg de stappen die door het hulpprogramma zijn opgegeven om te verifiëren bij de CLI met behulp van uw favoriete Azure-referenties.
```
azd auth login
```
Gebruik azd init dit om het project te initialiseren.
```
azd init
```
Configureer tijdens de initialisatie een unieke omgevingsnaam.

Tip

De omgevingsnaam wordt ook gebruikt als de naam van de doelresourcegroep. Voor deze quickstart kunt u overwegen .msdocs-cosmos-db
Implementeer het Azure Cosmos DB-account met behulp van azd up. De Bicep-sjablonen implementeren ook een voorbeeldwebtoepassing.
```
azd up
```
Selecteer tijdens het inrichtingsproces uw abonnement en gewenste locatie. Wacht tot het inrichtingsproces is voltooid. Het proces kan ongeveer vijf minuten duren.

Zodra het inrichten van uw Azure-resources is voltooid, wordt er een URL naar de actieve webtoepassing opgenomen in de uitvoer.

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.

Gebruik de URL in de console om naar uw webtoepassing in de browser te navigeren. Bekijk de uitvoer van de actieve app.

De clientbibliotheek installeren

De clientbibliotheek is beschikbaar via Go, als pakket azcosmos .

Open een terminal en navigeer naar de /src map.
```
cd ./src
```
Als dit nog niet is geïnstalleerd, installeert u het azcosmos pakket met behulp van go install.
```
go install github.com/Azure/azure-sdk-for-go/sdk/data/azcosmos
```
Installeer ook het azidentity pakket als dat nog niet is geïnstalleerd.
```
go install github.com/Azure/azure-sdk-for-go/sdk/azidentity
```
Open en controleer het bestand src/go.mod om te controleren of de github.com/Azure/azure-sdk-for-go/sdk/data/azcosmos en github.com/Azure/azure-sdk-for-go/sdk/azidentity beide vermeldingen bestaan.

Objectmodel

Name	Beschrijving
`CosmosClient`	Deze klasse is de primaire clientklasse en wordt gebruikt voor het beheren van metagegevens of databases voor het hele account.
`CosmosDatabase`	Deze klasse vertegenwoordigt een database binnen het account.
`CosmosContainer`	Deze klasse wordt voornamelijk gebruikt om lees-, update- en verwijderbewerkingen uit te voeren op de container of de items die zijn opgeslagen in de container.
`PartitionKey`	Deze klasse vertegenwoordigt een logische partitiesleutel. Deze klasse is vereist voor veel algemene bewerkingen en query's.

De voorbeeldcode in de sjabloon maakt gebruik van een database met de naam cosmicworks en container.products De products container bevat details zoals naam, categorie, hoeveelheid, een unieke id en een verkoopvlag voor elk product. De container gebruikt de /category eigenschap als een logische partitiesleutel.

De client verifiëren

Toepassingsaanvragen voor de meeste Azure-services moeten worden geautoriseerd. Gebruik het DefaultAzureCredential type als voorkeursmethode om een wachtwoordloze verbinding tussen uw toepassingen en Azure Cosmos DB for NoSQL te implementeren. DefaultAzureCredential ondersteunt meerdere verificatiemethoden en bepaalt welke methode tijdens runtime moet worden gebruikt.

Belangrijk

U kunt aanvragen voor Azure-services ook rechtstreeks autoriseren met behulp van wachtwoorden, verbindingsreeks s of andere referenties. Deze aanpak moet echter met voorzichtigheid worden gebruikt. Ontwikkelaars moeten ijverig zijn om deze geheimen nooit zichtbaar te maken op een onbeveiligde locatie. Iedereen die toegang krijgt tot het wachtwoord of de geheime sleutel, kan zich verifiëren bij de databaseservice. DefaultAzureCredential biedt verbeterde beheer- en beveiligingsvoordelen ten opzichte van de accountsleutel om verificatie zonder wachtwoord mogelijk te maken zonder het risico dat sleutels worden opgeslagen.

In dit voorbeeld wordt een nieuw exemplaar gemaakt van het gebruik azcosmos.NewClient en de verificatie met behulp van CosmosClient een DefaultAzureCredential exemplaar.

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
}

Een database ophalen

Gebruik client.NewDatabase deze om de bestaande database met de naam cosmicworksop te halen.

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

Een container ophalen

Haal de bestaande products container op met behulp van database.NewContainer.

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

Een item maken

Bouw een Go-type met alle leden die u in JSON wilt serialiseren. In dit voorbeeld heeft het type een unieke id en velden voor categorie, naam, hoeveelheid, prijs en verkoop.

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"`
}

Maak een item in de container met behulp van container.UpsertItem. Met deze methode wordt het item effectief vervangen als het al bestaat.

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
}

Een item lezen

Voer een puntleesbewerking uit met behulp van zowel de unieke id (id) als de partitiesleutelvelden. Gebruik container.ReadItem dit om het specifieke item efficiënt op te halen.

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
    }

Query-items

Voer een query uit op meerdere items in een container met behulp van container.NewQueryItemsPager. Zoek alle items in een opgegeven categorie met behulp van deze geparameteriseerde query:

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)

Parseer de gepagineerde resultaten van de query door elke pagina met resultaten te doorlopen met behulp pager.NextPagevan . Gebruik pager.More dit om te bepalen of er resultaten achterblijven aan het begin van elke lus.

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)
    }
}

Resources opschonen

Wanneer u de voorbeeldtoepassing of resources niet meer nodig hebt, verwijdert u de bijbehorende implementatie en alle resources.

azd down

Verwijder in GitHub Codespaces de actieve codespace om uw opslag- en kernrechten te maximaliseren.

Volgende stap

Go-pakket

Delen via

Quickstart: Azure Cosmos DB for NoSQL-bibliotheek voor Go

Vereisten

Instellen

De clientbibliotheek installeren

Objectmodel

Codevoorbeelden

De client verifiëren

Een database ophalen

Een container ophalen

Een item maken

Een item lezen

Query-items

Resources opschonen

Volgende stap

Feedback

Feedback

Aanvullende resources

Delen via

Quickstart: Azure Cosmos DB for NoSQL-bibliotheek voor Go

Vereisten

Instellen

De clientbibliotheek installeren

Objectmodel

Codevoorbeelden

De client verifiëren

Een database ophalen

Een container ophalen

Een item maken

Een item lezen

Query-items

Resources opschonen

Gerelateerde inhoud

Volgende stap

Feedback

Feedback

Aanvullende resources