Partekatu honen bidez:

Inicio rápido: Uso de Azure Cosmos DB for NoSQL con Azure SDK para Go

  • Artikulua
  • Honi aplikatzen zaio:
    ✅ NoSQL

En este inicio rápido, implementará una aplicación básica de Azure Cosmos DB for Table mediante Azure SDK para Go. Azure Cosmos DB for Table es un almacén de datos sin esquema que permite a las aplicaciones almacenar datos de tabla estructurados en la nube. Aprenderá a crear tablas y filas, y a realizar tareas básicas en el recurso de Azure Cosmos DB mediante el SDK de Azure para Go.

Documentación de referencia de la API | Código fuente de la biblioteca | Paquete (Go) | Azure Developer CLI

Requisitos previos

  • CLI de desarrollo de Azure
  • Docker Desktop
  • Go 1.21 o más reciente

Antes de comenzar, si no tiene una cuenta de Azure, cree una gratuita.

Inicialización del proyecto

Use Azure Developer CLI (azd) para crear una cuenta de Azure Cosmos DB for Table e implementar una aplicación de ejemplo contenedorizada. La aplicación de ejemplo usa la biblioteca cliente para administrar, crear, leer y consultar datos de ejemplo.

  1. Abra un terminal en un directorio vacío.

  2. Si aún no está autenticado, autentíquese en Azure Developer CLI mediante azd auth login. Siga los pasos especificados por la herramienta para autenticarse en la CLI mediante sus credenciales de Azure preferidas.

    azd auth login

  3. Ejecute azd init para inicializar el proyecto.

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

  4. Durante la inicialización, configure un nombre de entorno único.

  5. Implemente la cuenta de Azure Cosmos DB mediante azd up. Las plantillas de Bicep también implementan una aplicación web de muestra.

    azd up

  6. Durante el proceso de aprovisionamiento, seleccione la suscripción, la ubicación deseada y el grupo de recursos de destino. Espere a que se complete el proceso de aprovisionamiento. El proceso puede tardar aproximadamente cinco minutos.

  7. Una vez realizado el aprovisionamiento de los recursos de Azure, se incluye una dirección URL a la aplicación web en ejecución en la salida.

    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. Use la dirección URL de la consola para ir a la aplicación web en el explorador. Observe la salida de la aplicación en ejecución.

Captura de pantalla de la aplicación web en ejecución.

Instalación de la biblioteca cliente

La biblioteca cliente está disponible a través de Go, como paquete azcosmos.

  1. Abra un terminal y vaya a la carpeta /src.

    cd ./src

  2. Si aún no está instalado, instale el paquete azcosmos mediante go install.

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

  3. Además, instale el paquete azidentity si aún no está instalado.

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

  4. Abra y revise el archivo src/go.mod para validar que existen las entradas github.com/Azure/azure-sdk-for-go/sdk/data/azcosmos y github.com/Azure/azure-sdk-for-go/sdk/azidentity.

Modelo de objetos

Nombre Descripción
CosmosClient Esta clase es la clase de cliente principal y se usa para administrar bases de datos o metadatos de toda la cuenta.
CosmosDatabase Esta clase representa una base de datos dentro de la cuenta.
CosmosContainer Esta clase se usa principalmente para realizar operaciones de lectura, actualización y eliminación en el contenedor o en los elementos almacenados en el contenedor.
PartitionKey Esta clase representa una clave de partición lógica. Esta clase es necesaria para muchas operaciones y consultas comunes.

Ejemplos de código

El código de ejemplo de la plantilla usa una base de datos denominada cosmicworks y un contenedor denominado products. El contenedor products contiene detalles como el nombre, la categoría, la cantidad, un identificador único y una marca de venta para cada producto. El contenedor usa la propiedad /category como clave de partición lógica.

Autenticar el cliente

En este ejemplo se crea una nueva instancia de CosmosClient mediante azcosmos.NewClient y se autentica mediante una instancia 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
}

Obtención de una base de datos

Use client.NewDatabase para recuperar la base de datos existente denominada cosmicworks.

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

Obtención de un contenedor

Recupere el contenedor existente products mediante database.NewContainer.

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

Crear un elemento

Compile un tipo de Go con todos los miembros que desea serializar en JSON. En este ejemplo, el tipo tiene un identificador único y campos para categoría, nombre, cantidad, precio y venta.

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

Cree un elemento en el contenedor mediante container.UpsertItem. Este método "actualiza" eficazmente el elemento si ya existe.

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
}

Lectura de un elemento

Se puede realizar una operación de lectura de punto mediante el identificador único (id) y los campos de clave de partición. Use container.ReadItem para recuperar de forma eficaz el elemento específico.

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

Elementos de consulta

Realice una consulta en varios elementos de un contenedor mediante container.NewQueryItemsPager. Busque todos los elementos de una categoría especificada mediante esta consulta con parámetros:

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)

Analice los resultados paginados de la consulta realizando un bucle en cada página de resultados mediante pager.NextPage. Use pager.More para determinar si quedan resultados al principio de cada bucle.

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

Limpieza de recursos

Cuando ya no necesite la aplicación o los recursos de ejemplo, quite la implementación correspondiente y todos los recursos.

azd down

Contenido relacionado