Condividi tramite

Guida introduttiva: Usare Azure Cosmos DB per NoSQL con Azure SDK per Go

  • Articolo
  • Si applica a:
    ✅ NoSQL

In questa guida introduttiva si distribuisce un'applicazione Azure Cosmos DB per tabelle di base usando Azure SDK for Go. Azure Cosmos DB per tabella è un archivio dati senza schema che consente alle applicazioni di archiviare dati strutturati della tabella nel cloud. Si apprenderà come creare tabelle, righe ed eseguire attività di base all'interno della risorsa di Azure Cosmos DB usando Azure SDK for Go.

Documentazione di riferimento dell'API | Codice sorgente della libreria | Pacchetto (Get) | Azure Developer CLI

Prerequisiti

  • Azure Developer CLI
  • Docker Desktop
  • Go 1.21 o versione successiva

Se non si ha un account Azure, creare un account gratuito prima di iniziare.

Inizializzare il progetto

Usare l'interfaccia della riga di comando per sviluppatori di Azure (azd) per creare un account Azure Cosmos DB per tabelle e distribuire un'applicazione di esempio in contenitori. L'applicazione di esempio usa la libreria client per gestire, creare, leggere ed eseguire query sui dati di esempio.

  1. Aprire un terminale in una directory vuota.

  2. Se non si è già autenticati, eseguire l'autenticazione all'interfaccia della riga di comando per sviluppatori di Azure usando azd auth login. Seguire i passaggi specificati dallo strumento per eseguire l'autenticazione all'interfaccia della riga di comando usando le credenziali di Azure preferite.

    azd auth login

  3. Usare azd init per inizializzare il progetto.

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

  4. Durante l'inizializzazione, configurare un nome di ambiente univoco.

  5. Distribuire l'account Azure Cosmos DB usando azd up. I modelli Bicep distribuiscono anche un'applicazione Web di esempio.

    azd up

  6. Durante il processo di provisioning selezionare la sottoscrizione, la località desiderata e il gruppo di risorse di destinazione. Attendere il completamento del processo di provisioning. Per il processo sono necessari circa 5 minuti.

  7. Al termine del provisioning delle risorse di Azure, nell'output viene incluso un URL dell'applicazione Web in esecuzione.

    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.

  8. Usare l'URL nella console per passare all'applicazione Web nel browser. Osservare l'output dell'app in esecuzione.

Screenshot dell'applicazione Web in esecuzione.

Installare la libreria client

La libreria client è disponibile tramite Go, come pacchetto azcosmos.

  1. Aprire un terminale e passare alla cartella /src.

    cd ./src

  2. Se non è già installato, installare il pacchetto azcosmos usando go install.

    go install github.com/Azure/azure-sdk-for-go/sdk/data/azcosmos

  3. Installare anche il pacchetto azidentity se non lo è già.

    go install github.com/Azure/azure-sdk-for-go/sdk/azidentity

  4. Aprire ed esaminare il file src/go.mod per verificare che esistano entrambe le voci github.com/Azure/azure-sdk-for-go/sdk/data/azcosmos e github.com/Azure/azure-sdk-for-go/sdk/azidentity.

Modello a oggetti

Nome Descrizione
CosmosClient Questa classe è la classe client primaria e viene usata per gestire i metadati o i database a livello di account.
CosmosDatabase Questa classe rappresenta un database all'interno dell'account.
CosmosContainer Questa classe viene usata principalmente per eseguire operazioni di lettura, aggiornamento ed eliminazione sul contenitore o sugli elementi archiviati all'interno del contenitore.
PartitionKey Questa classe rappresenta una chiave di partizione logica. Questa classe è necessaria per molte operazioni e query comuni.

Esempi di codice

Il codice di esempio nel modello usa un database denominato cosmicworks e un contenitore denominato products. Il contenitore products contiene dettagli quali nome, categoria, quantità, identificatore univoco e flag di vendita per ogni prodotto. Il contenitore usa la proprietà /category come chiave di partizione logica.

Autenticare il client

Questo esempio crea una nuova istanza di CosmosClient usando azcosmos.NewClient ed esegue l'autenticazione usando un'istanza di DefaultAzureCredential.

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
}

Ottenere un database

Usare client.NewDatabase per recuperare il database esistente denominato cosmicworks.

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

Ottenere un contenitore

Recuperare il contenitore products esistente usando database.NewContainer.

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

Creare un elemento

Creare un tipo di Go con tutti i membri da serializzare in JSON. In questo esempio il tipo ha un identificatore univoco e i campi per categoria, nome, quantità, prezzo e vendita.

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

Creare un elemento nel contenitore usando container.UpsertItem. Questo metodo esegue l'upsert dell'elemento, in pratica sostituendolo, se esiste già.

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
}

Leggere un elemento

Eseguire un'operazione di lettura dei punti usando sia l'identificatore univoco (id) che i campi chiave di partizione. Usare container.ReadItem per recuperare in modo efficiente l'elemento specifico.

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

Eseguire query sugli elementi

Eseguire una query su più elementi in un contenitore usando container.NewQueryItemsPager. Trovare tutti gli elementi all'interno di una categoria specificata usando questa query con parametri:

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)

Analizzare i risultati impaginati della query eseguendo un ciclo in ogni pagina di risultati usando pager.NextPage. Usare pager.More per determinare se all'inizio di ogni ciclo sono rimasti risultati.

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

Pulire le risorse

Quando l'applicazione o le risorse di esempio non sono più necessarie, rimuovere la distribuzione corrispondente e tutte le risorse.

azd down

Contenuto correlato