Démarrage rapide : utiliser Azure Cosmos DB pour NoSQL avec Azure SDK pour Go
Dans ce guide de démarrage rapide, vous déployez une application Azure Cosmos DB for Table de base en utilisant le kit Azure SDK pour Go. Azure Cosmos DB for Table est un magasin de données sans schéma qui permet aux applications de stocker des données de table structurées dans le cloud. Vous apprenez à créer des tables, des lignes et à effectuer des tâches de base au sein de votre ressource Azure Cosmos DB à l’aide du SDK Azure pour Go.
Documentation de référence de l’API | Code source de la bibliothèque | Package (Go) | Azure Developer CLI
- Azure Developer CLI
- Docker Desktop
Go
version 1.21 ou plus récente
Si vous ne disposez pas d’un compte Azure, créez-en un gratuitement avant de commencer.
Utilisez l’interface Azure Developer CLI (azd
) pour créer un compte Azure Cosmos DB for Table et déployer un exemple d’application conteneurisé. L’exemple d’application utilise la bibliothèque de client pour gérer, créer, lire et interroger des exemples de données.
Ouvrez un terminal dans un répertoire vide.
Si vous n’êtes pas encore authentifié, authentifiez-vous auprès d’Azure Developer CLI à l’aide de
azd auth login
. Suivez les étapes spécifiées par l’outil pour vous authentifier auprès de l’interface CLI à l’aide de vos informations d’identification Azure préférées.azd auth login
Utilisez
azd init
pour initialiser le projet.azd init --template cosmos-db-nosql-go-quickstart
Lors de l’initialisation, configurez un nom d’environnement unique.
Déployez le compte Azure Cosmos DB en utilisant
azd up
. Les modèles Bicep déploient également un exemple d’application web.azd up
Pendant le processus d’approvisionnement, sélectionnez votre abonnement, l’emplacement souhaité et le groupe de ressources cible. Attendez la fin du processus de provisionnement. Le processus peut prendre environ cinq minutes.
Une fois le provisionnement de vos ressources Azure effectué, une URL vers l’application web en cours d’exécution est incluse dans la sortie.
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.
Utilisez l’URL dans la console pour accéder à votre application web dans le navigateur. Observez la sortie de l’application en cours d’exécution.
La bibliothèque cliente est disponible via Go, en tant que package azcosmos
.
Ouvrez un terminal et accédez au dossier
/src
.cd ./src
S’il n’est pas déjà installé, installez le package
azcosmos
à l’aide dego install
.go install github.com/Azure/azure-sdk-for-go/sdk/data/azcosmos
Installez également le package
azidentity
s’il n’est pas déjà installé.go install github.com/Azure/azure-sdk-for-go/sdk/azidentity
Ouvrez et examinez le fichier src/go.mod pour vérifier que les entrées
github.com/Azure/azure-sdk-for-go/sdk/data/azcosmos
etgithub.com/Azure/azure-sdk-for-go/sdk/azidentity
existent.
Nom | Description |
---|---|
CosmosClient |
Il s’agit de la classe cliente principale utilisée pour gérer les métadonnées ou les bases de données à l’échelle du compte. |
CosmosDatabase |
Cette classe représente une base de données dans le compte. |
CosmosContainer |
Cette classe est principalement utilisée pour effectuer des opérations de lecture, de mise à jour et de suppression sur le conteneur ou les éléments stockés dans le conteneur. |
PartitionKey |
Cette classe représente une clé de partition logique. Cette classe est nécessaire pour de nombreuses opérations et requêtes courantes. |
- Authentifier le client
- Obtenir une base de données
- Obtenir un conteneur
- Créer un élément
- Obtenir un élément
- Éléments de requête
L’exemple de code du modèle utilise une base de données nommée cosmicworks
et un conteneur nommé products
. Le conteneur products
contient des détails tels que le nom, la catégorie, la quantité, un identificateur unique et un indicateur de vente pour chaque produit. Le conteneur utilise la propriété /category
en tant que clé de partition logique.
Cet exemple crée une instance de CosmosClient
à l’aide de azcosmos.NewClient
et s’authentifie à l’aide d’une instance de 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
}
Utilisez client.NewDatabase
pour récupérer la base de données existante nommée cosmicworks
.
database, err := client.NewDatabase("cosmicworks")
if err != nil {
return err
}
Récupérez le conteneur products
existant à l’aide de database.NewContainer
.
container, err := database.NewContainer("products")
if err != nil {
return err
}
Générez un type Go avec tous les membres que vous souhaitez sérialiser dans JSON. Dans cet exemple, le type a un identificateur unique et des champs pour la catégorie, le nom, la quantité, le prix et la vente.
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"`
}
Créez un élément dans le conteneur à l’aide de container.UpsertItem
. Cette méthode fait un « upsert » de l’élément en le remplaçant de manière effective s’il existe déjà.
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
}
Effectuez une opération de lecture de point à l’aide des champs d’identificateur unique (id
) et de clé de partition. Utilisez container.ReadItem
pour récupérer efficacement l’élément spécifique.
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
}
}
Effectuez une requête sur plusieurs éléments d’un conteneur à l’aide de container.NewQueryItemsPager
. Recherchez tous les éléments d’une catégorie spécifiée à l’aide de cette requête paramétrable :
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)
Analysez les résultats paginés de la requête en boucle dans chaque page de résultats à l’aide de pager.NextPage
. Utilisez pager.More
pour déterminer s’il existe des résultats laissés au début de chaque boucle.
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)
}
}
Lorsque vous n’avez plus besoin de l’exemple d’application ou de ressources, supprimez le déploiement correspondant et toutes les ressources.
azd down