Compartir a través de


Introducción a Azure Cosmos DB for NoSQL con Python

SE APLICA A: NoSQL

En este artículo se describe cómo conectarse a Azure Cosmos DB for NoSQL mediante el SDK de Python. Una vez conectado, puede realizar operaciones en bases de datos, contenedores y elementos.

Paquete (PyPi) | Ejemplos | Referencia de la API | Código fuente de la biblioteca | Hacer comentarios

Prerequisites

Configurar su proyecto

Cree un entorno en el que pueda se ejecutar código de Python.

Con un entorno virtual, se pueden instalar paquetes de Python en un entorno aislado sin afectar al resto del sistema.

Instale el SDK de Python de Azure Cosmos DB for NoSQL en el entorno virtual.

pip install azure-cosmos

Crear la aplicación de Python

En su entorno, cree un archivo app.py y agréguele el siguiente código:

import json
import os
import sys
import uuid

from azure.core.exceptions import AzureError
from azure.cosmos import CosmosClient, PartitionKey

El código anterior importa los módulos que usaremos en el resto del artículo.

Conexión de Azure Cosmos DB for NoSQL

Para conectarse a la API de NoSQL de Azure Cosmos DB, cree una instancia de la clase CosmosClient. Esta clase es el punto inicial para realizar todas las operaciones en bases de datos.

Para conectarse a la API para la cuenta NoSQL mediante Microsoft Entra, use una entidad de seguridad. El tipo exacto de entidad de seguridad dependerá de dónde hospede el código de la aplicación. La tabla siguiente sirve como guía de referencia rápida.

Dónde se ejecuta la aplicación Entidad de seguridad
Máquina local (desarrollo y pruebas) Identidad de usuario o entidad de servicio
Azure Identidad administrada
Servidores o clientes fuera de Azure Entidad de servicio

Importación de Azure.Identity

El paquete azure-identity contiene la funcionalidad de autenticación principal que se comparte entre todas las bibliotecas del SDK de Azure.

Importe el paquete azure-identity a su entorno.

pip install azure-identity

Creación de CosmosClient con la implementación de credenciales predeterminada

Si está probando en una máquina local o la aplicación se va a ejecutar en servicios de Azure con compatibilidad directa con identidades administradas, obtenga un token de OAuth mediante la creación de una instancia de DefaultAzureCredential.

En el archivo app.py:

  • Obtenga el punto de conexión para conectarse a su cuenta y establecerlo como la variable de entorno COSMOS_ENDPOINT.

  • Importe la clase DefaultAzureCredential y cree una instancia de ella.

  • Cree una instancia de la clase CosmosClient con el PUNTO DE CONEXIÓN y la credencial como parámetros.

from azure.identity import DefaultAzureCredential

ENDPOINT = os.environ["COSMOS_ENDPOINT"]

credential = DefaultAzureCredential()

client = CosmosClient(ENDPOINT, credential)

Importante

Para obtener más información sobre cómo agregar el rol correcto para que DefaultAzureCredential funcione, consulte Configuración del control de acceso basado en roles con Microsoft Entra ID para la cuenta de Azure Cosmos DB. En concreto, consulte la sección sobre cómo crear roles y asignarlos a un identificador de entidad de seguridad.

Compilación de la aplicación

A medida que compile la aplicación, el código interactuará principalmente con cuatro tipos de recursos:

  • La cuenta de la API de NoSQL, que es el espacio de nombres único de nivel superior para los datos de Azure Cosmos DB.

  • Bases de datos, que organizan los contenedores de la cuenta.

  • Contenedores, que contienen un conjunto de elementos individuales en la base de datos.

  • Elementos, que representan un documento JSON en el contenedor.

En el siguiente diagrama se muestra la relación entre estos recursos.

Diagrama de la jerarquía de Azure Cosmos DB, que incluye cuentas, bases de datos, contenedores y elementos.

Diagrama jerárquico que muestra una cuenta de Azure Cosmos DB en la parte superior. La cuenta tiene dos nodos de base de datos secundarios. Uno de los nodos de la base de datos incluye dos nodos de contenedor secundarios. El otro nodo de la base de datos incluye un único nodo de contenedor secundario. Ese nodo de contenedor único tiene tres nodos de elementos secundarios.

Cada tipo de recurso se representa mediante una o varias clases de Python asociadas. Esta es una lista de las clases más comunes de programación sincrónica (hay clases parecidas de programación asincrónica en el espacio de nombres azure.cosmos.aio).

Clase Descripción
CosmosClient Esta clase proporciona una representación lógica del cliente para el servicio Azure Cosmos DB. El objeto de cliente se usa para configurar y ejecutar solicitudes en el servicio.
DatabaseProxy Referencia a una base de datos que podría existir o no en el servicio. No conviene crear instancias de esta clase directamente. En su lugar, debe usar el método get_database_client de CosmosClient.
ContainerProxy Interfaz para interactuar con un contenedor específico de Cosmos DB. No conviene crear instancias de esta clase directamente. En su lugar, use el método get_container_client de DatabaseProxy para obtener un contenedor existente o el método create_container para crear un contenedor.

En las siguientes guías se muestra cómo usar cada una de estas clases para compilar la aplicación.

Guía Descripción
Creación de una base de datos Creación de bases de datos
Creación de contenedor Creación de contenedores
Ejemplos de elementos Lectura puntual de un elemento específico

Consulte también

Pasos siguientes