Administración de propiedades y metadatos de blobs con Python
Además de los datos que contienen, los blobs admiten propiedades del sistema y metadatos definidos por el usuario. En este artículo se muestra cómo administrar propiedades del sistema y metadatos definidos por el usuario con la biblioteca cliente de Azure Storage para Python.
Para obtener información sobre cómo administrar propiedades y metadatos mediante API asincrónicas, consulte Establecer metadatos de blob de forma asincrónica.
Requisitos previos
- Una suscripción a Azure: cree una cuenta gratuita
- Una cuenta de Azure Storage: cree una cuenta de almacenamiento
- Python 3.8 y versiones posteriores
Configurar el entorno
Si no tiene un proyecto existente, en esta sección se muestra cómo configurar uno para que funcione con la biblioteca cliente de Azure Blob Storage para Python. Para más información, vea Introducción a Azure Blob Storage y Python.
Para trabajar con los ejemplos de código de este artículo, siga los pasos siguientes a fin de configurar el proyecto.
Instalar paquetes
Instale los siguientes paquetes mediante pip install
:
pip install azure-storage-blob azure-identity
Adición de instrucciones import
Agregue las instrucciones siguientes import
:
from azure.identity import DefaultAzureCredential
from azure.storage.blob import BlobServiceClient, ContentSettings
Authorization
El mecanismo de autorización debe tener los permisos necesarios para trabajar con propiedades o metadatos del contenedor. Para la autorización con Microsoft Entra ID (recomendada), necesita el rol integrado de RBAC de Azure Lector de datos de Storage Blob o superior para las operaciones get, y el rol Colaborador de datos de blobs de Almacenamiento o superior para las operaciones set. Para obtener más información, consulte la guía de autorización de Establecer propiedades de blobs (API de REST), Obtener propiedades de blobs (API de REST), Establecer metadatos de blobs (API de REST) u Obtener metadatos de blobs (API de REST).
Creación de un objeto de cliente
Para conectar una aplicación a Blob Storage, cree una instancia de BlobServiceClient. En el ejemplo siguiente se muestra cómo crear un objeto de cliente mediante DefaultAzureCredential
para la autorización:
# TODO: Replace <storage-account-name> with your actual storage account name
account_url = "https://<storage-account-name>.blob.core.windows.net"
credential = DefaultAzureCredential()
# Create the BlobServiceClient object
blob_service_client = BlobServiceClient(account_url, credential=credential)
También puede crear objetos de cliente para contenedores o blobs específicos ya sea directamente o desde el objeto BlobServiceClient
. Para obtener más información sobre cómo crear y administrar objetos de cliente, consulte Crear y administrar objetos de cliente que interactúan con los recursos de datos.
Acerca de las propiedades y los metadatos
Propiedades del sistema: en cada recurso de almacenamiento de blobs existen propiedades del sistema. Algunas se pueden leer o establecer, mientras que otras son de solo lectura. En segundo plano, algunas propiedades del sistema corresponden a ciertos encabezados HTTP estándar. La biblioteca cliente de Azure Storage para Python mantiene estas propiedades automáticamente.
Metadatos definidos por el usuario: los metadatos definidos por el usuario se componen de uno o más pares nombre-valor que especifica para un recurso de almacenamiento de blobs. Puede usar metadatos para almacenar valores adicionales con el recurso. Los valores de metadatos se proporcionan para uso personal y no afectan a cómo se comporta el recurso.
Los pares de nombre/valor de metadatos son encabezados HTTP válidos y deben cumplir todas las restricciones que gobiernan los encabezados HTTP. Para obtener más información sobre los requisitos de nomenclatura de metadatos, consulte Nombres de metadatos.
Nota:
Las etiquetas del índice de blobs ofrecen la capacidad de almacenar atributos arbitrarios de clave-valor definidas por el usuario junto con un recurso de Azure Blob Storage. De manera similar a los metadatos, solo las etiquetas del índice de blobs se indexan automáticamente y son objeto de búsquedda mediante el Blob service nativo. Los metadatos no se pueden indexar ni consultar, a menos que se use un servicio independiente, como Azure Search.
Para obtener más información sobre esta característica, vea Administración y búsqueda de datos en Azure Blob Storage con el índice de blobs (versión preliminar).
Establecimiento y recuperación de propiedades
Para establecer propiedades en un blob, use el método siguiente:
Se borran todas las propiedades no establecidas explícitamente. Para conservar las propiedades existentes, primero puede recuperar las propiedades del blob y, a continuación, usarlas para rellenar los encabezados que no se están actualizando.
En el ejemplo de código siguiente se establecen las propiedades del sistema content_type
y content_language
en un blob, a la vez que se conservan las propiedades existentes:
def set_properties(self, blob_service_client: BlobServiceClient, container_name):
blob_client = blob_service_client.get_blob_client(container=container_name, blob="sample-blob.txt")
# Get the existing blob properties
properties = blob_client.get_blob_properties()
# Set the content_type and content_language headers, and populate the remaining headers from the existing properties
blob_headers = ContentSettings(content_type="text/plain",
content_encoding=properties.content_settings.content_encoding,
content_language="en-US",
content_disposition=properties.content_settings.content_disposition,
cache_control=properties.content_settings.cache_control,
content_md5=properties.content_settings.content_md5)
blob_client.set_http_headers(blob_headers)
Para recuperar propiedades en un blob, use el método siguiente:
En el ejemplo de código siguiente se obtienen las propiedades del sistema de un blob y se muestran algunos de los valores:
def get_properties(self, blob_service_client: BlobServiceClient, container_name):
blob_client = blob_service_client.get_blob_client(container=container_name, blob="sample-blob.txt")
properties = blob_client.get_blob_properties()
print(f"Blob type: {properties.blob_type}")
print(f"Blob size: {properties.size}")
print(f"Content type: {properties.content_settings.content_type}")
print(f"Content language: {properties.content_settings.content_language}")
Establecimiento y recuperación de metadatos
Puede especificar metadatos como uno o más pares nombre-valor en un recurso de blob o contenedor. Para establecer los metadatos, envíe un diccionario que contenga pares nombre-valor usando el siguiente método:
El siguiente ejemplo de código establece los metadatos de un blob:
def set_metadata(self, blob_service_client: BlobServiceClient, container_name):
blob_client = blob_service_client.get_blob_client(container=container_name, blob="sample-blob.txt")
# Retrieve existing metadata, if desired
blob_metadata = blob_client.get_blob_properties().metadata
more_blob_metadata = {'docType': 'text', 'docCategory': 'reference'}
blob_metadata.update(more_blob_metadata)
# Set metadata on the blob
blob_client.set_blob_metadata(metadata=blob_metadata)
Para recuperar metadatos, llame al método get_blob_properties en el blob para rellenar la colección de metadatos y, a continuación, lea los valores, como se muestra en el ejemplo siguiente. El método get_blob_properties
recupera propiedades y metadatos de blobs llamando a la operaciones Get Blob Properties y Get Blob Metadata.
En el ejemplo de código siguiente se leen los metadatos de un blob y se imprime cada par clave-valor:
def get_metadata(self, blob_service_client: BlobServiceClient, container_name):
blob_client = blob_service_client.get_blob_client(container=container_name, blob="sample-blob.txt")
# Retrieve existing metadata, if desired
blob_metadata = blob_client.get_blob_properties().metadata
for k, v in blob_metadata.items():
print(k, v)
Establecer metadatos de blob de forma asincrónica
La biblioteca cliente de Azure Blob Storage para Python admite la administración metadatos y propiedades de blob de forma asíncrona. Para obtener más información sobre los requisitos de configuración del proyecto, consulte Programación asincrónica.
Siga estos pasos para establecer metadatos de blob mediante API asincrónicas:
Agregue las siguientes instrucciones import:
import asyncio from azure.identity.aio import DefaultAzureCredential from azure.storage.blob.aio import BlobServiceClient
Agregue código para ejecutar el programa mediante
asyncio.run
. Esta función ejecuta la corrutina pasada,main()
en nuestro ejemplo, y administra el bucle de eventosasyncio
. Las corrutinas se declaran con la sintaxis async/await. En este ejemplo, la corrutinamain()
crea primero el nivel superiorBlobServiceClient
medianteasync with
y, a continuación, llama al método que establece los metadatos del blob. Tenga en cuenta que solo el cliente de nivel superior debe usarasync with
, ya que otros clientes creados a partir de él comparten el mismo grupo de conexiones.async def main(): sample = BlobSamples() # TODO: Replace <storage-account-name> with your actual storage account name account_url = "https://<storage-account-name>.blob.core.windows.net" credential = DefaultAzureCredential() async with BlobServiceClient(account_url, credential=credential) as blob_service_client: await sample.set_metadata(blob_service_client, "sample-container") if __name__ == '__main__': asyncio.run(main())
Agregue código para establecer los metadatos del blob. El código es el mismo que el ejemplo sincrónico, salvo que el método se declara con la palabra clave
async
y la palabra claveawait
se usa al llamar a los métodosget_blob_properties
yset_blob_metadata
.async def set_metadata(self, blob_service_client: BlobServiceClient, container_name): blob_client = blob_service_client.get_blob_client(container=container_name, blob="sample-blob.txt") # Retrieve existing metadata, if desired properties = await blob_client.get_blob_properties() blob_metadata = properties.metadata more_blob_metadata = {'docType': 'text', 'docCategory': 'reference'} blob_metadata.update(more_blob_metadata) # Set metadata on the blob await blob_client.set_blob_metadata(metadata=blob_metadata)
Con esta configuración básica, puede implementar otros ejemplos de este artículo como corrutinas mediante la sintaxis async/await.
Recursos
Para obtener más información sobre cómo administrar las propiedades del sistema y los metadatos definidos por el usuario usando la biblioteca cliente de Azure Blob Storage para Python, consulte los siguientes recursos.
Ejemplos de código
- Ver ejemplo de código sincrónicos o asincrónicos de este artículo (GitHub)
Operaciones de API REST
El SDK de Azure para Python contiene bibliotecas que se crean a partir de la API de REST de Azure, lo que le permite interactuar con las operaciones de API de REST a través de paradigmas conocidos de Python. Los métodos de la biblioteca cliente para administrar las propiedades del sistema y los metadatos definidos por el usuario usan las siguientes operaciones de la API de REST:
- Set Blob Properties (API REST)
- Get Blob Properties (API REST)
- Set Blob Metadata (API REST)
- Get Blob Metadata (API REST)
Recursos de la biblioteca cliente
- Documentación de referencia de la biblioteca cliente
- Código fuente de la biblioteca del cliente
- Paquete (PyPi)
Contenido relacionado
- Este artículo forma parte de la guía para desarrolladores de Blob Storage para Python. Para más información, consulte la lista completa de artículos de la guía para desarrolladores en Compilación de la aplicación de Python.