Snabbstart: Azure Cosmos DB för NoSQL-biblioteket för Go

Artikel
10/18/2024

GÄLLER FÖR: NoSQL

Kom igång med Azure Cosmos DB for NoSQL-klientbiblioteket för Go för att köra frågor mot data i containrarna och utföra vanliga åtgärder på enskilda objekt. Följ de här stegen för att distribuera en minimal lösning till din miljö med hjälp av Azure Developer CLI.

API-referensdokumentation Bibliotek källkodspaket | (Go) | Azure Developer CLI |

Förutsättningar

Ett Azure-konto med en aktiv prenumeration. Skapa ett konto utan kostnad.
GitHub-konto

Ett Azure-konto med en aktiv prenumeration. Skapa ett konto utan kostnad.
Azure Developer CLI
Docker Desktop

Konfigurera

Distribuera projektets utvecklingscontainer till din miljö. Använd sedan Azure Developer CLI (azd) för att skapa ett Azure Cosmos DB för NoSQL-konto och distribuera ett containerbaserat exempelprogram. Exempelprogrammet använder klientbiblioteket för att hantera, skapa, läsa och fråga efter exempeldata.

Viktigt!

GitHub-konton innehåller en berättigande till lagring och kärntimmar utan kostnad. Mer information finns i inkluderade lagrings- och kärntimmar för GitHub-konton.

Öppna en terminal i projektets rotkatalog.
Autentisera till Azure Developer CLI med .azd auth login Följ stegen som anges av verktyget för att autentisera till CLI med dina önskade Azure-autentiseringsuppgifter.
```
azd auth login
```
Använd azd init för att initiera projektet.
```
azd init --template cosmos-db-nosql-dotnet-quickstart
```
Kommentar

Den här snabbstarten använder GitHub-lagringsplatsen azure-samples/cosmos-db-nosql-dotnet-quickstart . Azure Developer CLI klonar automatiskt det här projektet till datorn om det inte redan finns där.
Under initieringen konfigurerar du ett unikt miljönamn.

Dricks

Miljönamnet används också som målresursgruppnamn. För den här snabbstarten bör du överväga att använda msdocs-cosmos-db.
Distribuera Azure Cosmos DB-kontot med .azd up Bicep-mallarna distribuerar också ett exempelwebbprogram.
```
azd up
```
Under etableringsprocessen väljer du din prenumeration och önskad plats. Vänta tills etableringsprocessen har slutförts. Processen kan ta ungefär fem minuter.

När etableringen av dina Azure-resurser är klar inkluderas en URL till det webbprogram som körs i utdata.

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.

Använd URL:en i konsolen för att navigera till webbprogrammet i webbläsaren. Observera utdata från appen som körs.

Installera klientbiblioteket

Klientbiblioteket är tillgängligt via Go som azcosmos paket.

Öppna en terminal och navigera till /src mappen.
```
cd ./src
```
Om det inte redan är installerat installerar du azcosmos paketet med .go install
```
go install github.com/Azure/azure-sdk-for-go/sdk/data/azcosmos
```
Installera även paketet om det azidentity inte redan är installerat.
```
go install github.com/Azure/azure-sdk-for-go/sdk/azidentity
```
Öppna och granska filen src/go.mod för att verifiera att båda posterna github.com/Azure/azure-sdk-for-go/sdk/data/azcosmos och github.com/Azure/azure-sdk-for-go/sdk/azidentity finns.

Objektmodell

Name	beskrivning
`CosmosClient`	Den här klassen är den primära klientklassen och används för att hantera kontoomfattande metadata eller databaser.
`CosmosDatabase`	Den här klassen representerar en databas i kontot.
`CosmosContainer`	Den här klassen används främst för att utföra läs-, uppdaterings- och borttagningsåtgärder på antingen containern eller objekten som lagras i containern.
`PartitionKey`	Den här klassen representerar en logisk partitionsnyckel. Den här klassen krävs för många vanliga åtgärder och frågor.

Exempelkoden i mallen använder en databas med namnet cosmicworks och containern med namnet products. Containern products innehåller information som namn, kategori, kvantitet, en unik identifierare och en försäljningsflagga för varje produkt. Containern använder egenskapen /category som en logisk partitionsnyckel.

Autentisera klienten

Programbegäranden till de flesta Azure-tjänster måste auktoriseras. Använd typen DefaultAzureCredential som det bästa sättet att implementera en lösenordslös anslutning mellan dina program och Azure Cosmos DB för NoSQL. DefaultAzureCredential stöder flera autentiseringsmetoder och avgör vilken metod som ska användas vid körning.

Viktigt!

Du kan också auktorisera begäranden till Azure-tjänster med hjälp av lösenord, anslutningssträng eller andra autentiseringsuppgifter direkt. Den här metoden bör dock användas med försiktighet. Utvecklare måste vara noggranna för att aldrig exponera dessa hemligheter på en osäker plats. Alla som får åtkomst till lösenordet eller den hemliga nyckeln kan autentisera till databastjänsten. DefaultAzureCredential ger bättre hanterings- och säkerhetsfördelar jämfört med kontonyckeln för att tillåta lösenordslös autentisering utan risk för lagring av nycklar.

Det här exemplet skapar en ny instans av användning azcosmos.NewClient och autentiserar med hjälp av CosmosClient en DefaultAzureCredential instans.

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
}

Hämta en databas

Använd client.NewDatabase för att hämta den befintliga databasen med namnet cosmicworks.

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

Hämta en container

Hämta den befintliga products containern med .database.NewContainer

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

Skapa ett objekt

Skapa en Go-typ med alla medlemmar som du vill serialisera till JSON. I det här exemplet har typen en unik identifierare och fält för kategori, namn, kvantitet, pris och försäljning.

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

Skapa ett objekt i containern med .container.UpsertItem Den här metoden "upserts" objektet ersätter objektet effektivt om det redan finns.

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
}

Läsa ett objekt

Utför en punktläsningsåtgärd med hjälp av både de unika identifierarna (id) och partitionsnyckelfälten. Använd container.ReadItem för att effektivt hämta det specifika objektet.

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

Frågeobjekt

Utför en fråga över flera objekt i en container med hjälp av container.NewQueryItemsPager. Hitta alla objekt i en angiven kategori med den här parameteriserade frågan:

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)

Parsa de sidnumrerade resultaten av frågan genom att loopa igenom varje sida med resultat med hjälp pager.NextPageav . Använd pager.More för att avgöra om det finns några resultat kvar i början av varje loop.

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

Rensa resurser

När du inte längre behöver exempelprogrammet eller resurserna tar du bort motsvarande distribution och alla resurser.

azd down

I GitHub Codespaces tar du bort det kodområde som körs för att maximera dina lagrings- och kärnrättigheter.

Dela via

Snabbstart: Azure Cosmos DB för NoSQL-biblioteket för Go

Förutsättningar

Konfigurera

Installera klientbiblioteket

Objektmodell

Kodexempel

Autentisera klienten

Hämta en databas

Hämta en container

Skapa ett objekt

Läsa ett objekt

Frågeobjekt

Rensa resurser

Feedback

Ytterligare resurser

Dela via

Snabbstart: Azure Cosmos DB för NoSQL-biblioteket för Go

Förutsättningar

Konfigurera

Installera klientbiblioteket

Objektmodell

Kodexempel

Autentisera klienten

Hämta en databas

Hämta en container

Skapa ett objekt

Läsa ett objekt

Frågeobjekt

Rensa resurser

Relaterat innehåll

Feedback

Ytterligare resurser