Schnellstart: Azure Cosmos DB for NoSQL-Bibliothek für Go

Führen Sie die ersten Schritte mit der Azure Cosmos DB for NoSQL-Clientbibliothek für Go durch, um Daten in Ihren Containern abzufragen und allgemeine Vorgänge für einzelne Elemente auszuführen. Führen Sie die folgenden Schritte aus, um eine minimale Lösung für Ihre Umgebung mithilfe der Azure Developer CLI bereitzustellen.

API-Referenzdokumentation | Quellcode der Bibliothek | Paket (Go) | Azure Developer CLI

Voraussetzungen

Einrichten

Stellen Sie den Entwicklungscontainer dieses Projekts in Ihrer Umgebung bereit. Verwenden Sie dann Azure Developer CLI (azd), um ein Azure Cosmos DB for NoSQL-Konto zu erstellen und eine containerisierte Beispielanwendung bereitzustellen. Die Beispielanwendung verwendet die Clientbibliothek zum Verwalten, Erstellen, Lesen und Abfragen von Beispieldaten.

1. Öffnen Sie ein Terminal im Stammverzeichnis des Projekts.

2. Authentifizieren Sie sich mithilfe von azd auth login bei Azure Developer CLI. Führen Sie die vom Tool angegebenen Schritte aus, um sich mit Ihren bevorzugten Azure-Anmeldeinformationen bei der CLI zu authentifizieren.

   azd auth login
   

3. Verwenden Sie azd init, um das Projekt zu initialisieren.

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

   Hinweis

   Diese Schnellstartanleitung verwendet das GitHub-Vorlagenrepository azure-samples/cosmos-db-nosql-dotnet-quickstart. Die Azure Developer CLI klont dieses Projekt automatisch auf Ihrem Computer, wenn es noch nicht vorhanden ist.

4. Konfigurieren Sie während der Initialisierung einen eindeutigen Umgebungsnamen.

   Tipp

   Der Umgebungsname wird auch als Name der Zielressourcengruppe verwendet. Ziehen Sie für diese Schnellstartanleitung die Verwendung von msdocs-cosmos-db in Betracht.

5. Stellen Sie das Azure Cosmos DB-Konto mit azd up bereit. Die Bicep-Vorlagen stellen auch eine Beispielwebanwendung bereit.

   azd up
   

6. Wählen Sie während des Bereitstellungsprozesses Ihr Abonnement und den gewünschten Standort aus. Warten Sie auf den Abschluss des Bereitstellungsvorgangs. Dieser Prozess kann ca. fünf Minuten dauern.

7. Sobald die Bereitstellung Ihrer Azure-Ressourcen abgeschlossen ist, enthält die Ausgabe eine URL zur ausgeführten Webanwendung.

   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. Verwenden Sie die URL in der Konsole, um im Browser zu Ihrer Webanwendung zu navigieren. Sehen Sie sich die Ausgabe der ausgeführten App an.

   

Installieren der Clientbibliothek

Die Clientbibliothek ist über Go als azcosmos-Paket verfügbar.

1. Öffnen Sie ein Terminal, und navigieren Sie zu dem /src-Ordner.

   cd ./src
   

2. Installieren Sie das azcosmos-Paket mithilfe von go install, falls es noch nicht installiert ist.

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

3. Installieren Sie außerdem das azidentity-Paket, wenn es noch nicht installiert ist.

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

4. Öffnen und überprüfen Sie die Datei src/go.mod, um zu bestätigen, dass die Einträge github.com/Azure/azure-sdk-for-go/sdk/data/azcosmos und github.com/Azure/azure-sdk-for-go/sdk/azidentity vorhanden sind.

Objektmodell

Codebeispiele

• Authentifizieren des Clients
• Datenbank abrufen
• Container abrufen
• Erstellen eines Elements
• Abrufen eines Elements
• Abfrageelemente

Der Beispielcode in der Vorlage verwendet eine Datenbank mit dem Namen cosmicworks und einen Container mit dem Namen products. Der products-Container enthält Details wie Name, Kategorie, Menge, eindeutiger Bezeichner und ein Verkaufsflag für jedes Produkt. Der Container verwendet die /category-Eigenschaft als logischen Partitionsschlüssel.

Authentifizieren des Clients

Anwendungsanforderungen an die meisten Azure-Dienste müssen autorisiert werden. Verwenden Sie den DefaultAzureCredential-Typ als bevorzugte Methode, um eine kennwortlose Verbindung zwischen Ihren Anwendungen und Azure Cosmos DB for NoSQL zu implementieren. DefaultAzureCredential unterstützt mehrere Authentifizierungsmethoden und bestimmt, welche Methode zur Laufzeit verwendet werden soll.

In diesem Beispiel wird eine neue Instanz von CosmosClient mithilfe von azcosmos.NewClient erstellt und mithilfe einer DefaultAzureCredential-Instanz authentifiziert.

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
}

Datenbank abrufen

Verwenden Sie client.NewDatabase, um die vorhandene Datenbank mit dem Namen cosmicworks abzurufen.

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

Container abrufen

Rufen Sie den vorhandenen products-Container mithilfe von database.NewContainer ab.

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

Erstellen eines Elements

Erstellen Sie einen Go-Eintragstyp mit allen Membern, die Sie in JSON serialisieren möchten. In diesem Beispiel weist der Typ einen eindeutigen Bezeichner und Felder für Kategorie, Name, Menge, Preis und Verkauf auf.

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

Erstellen Sie mithilfe von container.UpsertItem ein Element im Container. Mit dieser Methode wird ein Upsertvorgang für das Element ausgeführt, wodurch es effektiv ersetzt wird (sofern schon vorhanden).

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
}

Lesen eines Elements

Führen Sie einen Punktlesevorgang aus, indem Sie sowohl die eindeutigen Bezeichner (id) als auch die Partitionsschlüsselfelder verwenden. Verwenden Sie container.ReadItem, um das jeweilige Element effizient abzurufen.

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

Abfrageelemente

Führen Sie mithilfe von container.NewQueryItemsPager eine Abfrage für mehrere Elemente in einem Container durch. Suchen Sie alle Elemente in einer angegebenen Kategorie mithilfe dieser parametrisierten Abfrage:

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)

Parsen Sie die paginierten Ergebnisse der Abfrage, indem Sie jede Ergebnisseite mit pager.NextPage in einer Schleife durchlaufen. Verwenden Sie pager.More, um zu ermitteln, ob zu Beginn jeder Schleife Ergebnisse vorhanden sind.

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

Bereinigen von Ressourcen

azd down

Zugehöriger Inhalt

• Schnellstartanleitung für .NET
• Schnellstart für Node.js
• Schnellstartanleitung für Java
• Schnellstartanleitung für Python