ContainerClient Clase

Referencia

Un cliente para interactuar con un contenedor específico, aunque es posible que ese contenedor aún no exista.

Para las operaciones relacionadas con un blob específico dentro de este contenedor, se puede recuperar un cliente de blobs mediante la get_blob_client función .

Para obtener más configuración opcional, haga clic aquí.

Herencia: azure.storage.blob._shared.base_client.StorageAccountHostsMixin

ContainerClient

azure.storage.blob._encryption.StorageEncryptionMixin

ContainerClient

Constructor

ContainerClient(account_url: str, container_name: str, credential: str | Dict[str, str] | AzureNamedKeyCredential | AzureSasCredential | TokenCredential | None = None, **kwargs: Any)

Parámetros

account_url: str

Requerido

Identificador URI de la cuenta de almacenamiento. Para crear un cliente dado el URI completo al contenedor, use el from_container_url método classmethod.

container_name: str

Requerido

Nombre del contenedor para el blob.

credential

valor predeterminado: None

Credenciales con las que se va a autenticar. Esto es opcional si la dirección URL de la cuenta ya tiene un token de SAS. El valor puede ser una cadena de token de SAS, una instancia de AzureSasCredential o AzureNamedKeyCredential de azure.core.credentials, una clave de acceso compartido de cuenta o una instancia de una clase TokenCredentials de azure.identity. Si el URI del recurso ya contiene un token de SAS, se omitirá en favor de una credencial explícita.

excepto en el caso de AzureSasCredential, donde los tokens de SAS en conflicto generarán un valor ValueError. Si usa una instancia de AzureNamedKeyCredential, "name" debe ser el nombre de la cuenta de almacenamiento y "key" debe ser la clave de la cuenta de almacenamiento.

api_version: str

La versión de la API de storage que se va a usar para las solicitudes. El valor predeterminado es la versión de servicio más reciente que es compatible con el SDK actual. Establecer en una versión anterior puede dar lugar a una compatibilidad de características reducida.

Novedades de la versión 12.2.0.

secondary_hostname: str

El nombre de host del punto de conexión secundario.

max_block_size: int

Tamaño máximo del fragmento para cargar un blob en bloques en fragmentos. El valor predeterminado es 4*1024*1024 o 4 MB.

max_single_put_size: int

Si el tamaño del blob es menor o igual que max_single_put_size, el blob se cargará solo con una solicitud HTTP PUT. Si el tamaño del blob es mayor que max_single_put_size, el blob se cargará en fragmentos. El valor predeterminado es 64*1024*1024 o 64 MB.

min_large_block_upload_threshold: int

Tamaño mínimo del fragmento necesario para usar el algoritmo eficaz de memoria al cargar un blob en bloques. El valor predeterminado es 4*1024*1024+1.

use_byte_buffer: bool

Use un búfer de bytes para cargas de blobs en bloques. El valor predeterminado es False.

max_page_size: int

Tamaño máximo del fragmento para cargar un blob en páginas. El valor predeterminado es 4*1024*1024 o 4 MB.

max_single_get_size: int

El tamaño máximo de un blob que se va a descargar en una sola llamada, el elemento superado se descargará en fragmentos (podría ser paralelo). El valor predeterminado es 32*1024*1024 o 32 MB.

max_chunk_get_size: int

Tamaño máximo de fragmento usado para descargar un blob. El valor predeterminado es 4*1024*1024 o 4 MB.

Métodos

acquire_lease	Solicita una nueva concesión. Si el contenedor no tiene una concesión activa, Blob service crea una concesión sobre el contenedor y devuelve un nuevo identificador de concesión.
close	Este método consiste en cerrar los sockets abiertos por el cliente. No es necesario usarse cuando se usa con un administrador de contextos.
create_container	Crea un nuevo contenedor en la cuenta especificada. Si ya existe un contenedor con el mismo nombre, se produce un error en la operación.
delete_blob	Marca el blob o la instantánea especificados para su eliminación. El blob se elimina posteriormente durante la recolección de elementos no utilizados. Tenga en cuenta que para eliminar un blob, debe eliminar todas sus instantáneas. Puede eliminar ambos al mismo tiempo con la operación delete_blob. Si se habilita una directiva de retención de eliminación para el servicio, esta operación elimina temporalmente el blob o la instantánea y conserva el blob o la instantánea durante el número de días especificado. Después del número especificado de días, los datos del blob se quitan del servicio durante la recolección de elementos no utilizados. Se puede acceder al blob o instantánea eliminado temporalmente mediante list_blobs la especificación de la opción include=["deleted"]. El blob o la instantánea eliminados temporalmente se pueden restaurar mediante <xref:azure.storage.blob.BlobClient.undelete>
delete_blobs	Marca los blobs o instantáneas especificados para su eliminación. Los blobs se eliminan posteriormente durante la recolección de elementos no utilizados. Tenga en cuenta que para eliminar blobs, debe eliminar todas sus instantáneas. Puede eliminar ambos al mismo tiempo con la operación de delete_blobs. Si se habilita una directiva de retención de eliminación para el servicio, esta operación elimina temporalmente los blobs o instantáneas y conserva los blobs o instantáneas durante el número de días especificado. Después del número especificado de días, los datos de los blobs se quitan del servicio durante la recolección de elementos no utilizados. Se puede acceder a los blobs o instantáneas eliminados temporalmente mediante list_blobs la especificación de include=["deleted"] Se pueden restaurar blobs o instantáneas eliminados temporalmente mediante <xref:azure.storage.blob.BlobClient.undelete> El número máximo de blobs que se pueden eliminar en una sola solicitud es 256.
delete_container	Marca el contenedor especificado para su eliminación. El contenedor y los blobs incluidos en él se eliminan posteriormente durante la recolección de elementos no utilizados.
download_blob	Descarga un blob en StorageStreamDownloader. El método readall() debe usarse para leer todo el contenido o readinto() para descargar el blob en una secuencia. El uso de chunks() devuelve un iterador que permite al usuario iterar el contenido en fragmentos.
exists	Devuelve True si existe un contenedor y devuelve False de lo contrario.
find_blobs_by_tags	Devuelve un generador para enumerar los blobs del contenedor especificado cuyas etiquetas coinciden con la expresión de búsqueda especificada. El generador seguirá de forma diferida los tokens de continuación devueltos por el servicio.
from_connection_string	Cree ContainerClient a partir de una cadena de conexión.
from_container_url	Cree ContainerClient desde una dirección URL de contenedor.
get_account_information	Obtiene información relacionada con la cuenta de almacenamiento. La información también se puede recuperar si el usuario tiene una SAS en un contenedor o blob. Las claves del diccionario devuelto incluyen "sku_name" y "account_kind".
get_blob_client	Obtenga un cliente para interactuar con el blob especificado. El blob aún no debe existir.
get_container_access_policy	Obtiene los permisos para el contenedor especificado. Los permisos indican si el acceso a los datos de un contenedor es público.
get_container_properties	Devuelve todos los metadatos definidos por el usuario y las propiedades del sistema para el contenedor especificado. Los datos devueltos no incluyen la lista de blobs del contenedor.
list_blob_names	Devuelve un generador para enumerar los nombres de blobs en el contenedor especificado. El generador seguirá de forma diferida los tokens de continuación devueltos por el servicio. Tenga en cuenta que no se devolverán propiedades ni metadatos adicionales al usar esta API. Además, esta API no tiene una opción para incluir blobs adicionales, como instantáneas, versiones, blobs eliminados temporalmente, etc. Para obtener cualquiera de estos datos, use list_blobs.
list_blobs	Devuelve un generador para enumerar los blobs en el contenedor especificado. El generador seguirá de forma diferida los tokens de continuación devueltos por el servicio.
set_container_access_policy	Establece los permisos para el contenedor especificado o las directivas de acceso almacenadas que se pueden usar con firmas de acceso compartido. Los permisos indican si el acceso a los blobs de un contenedor es público.
set_container_metadata	Establece uno o varios pares nombre-valor definidos por el usuario para el contenedor especificado. Cada llamada a esta operación reemplaza todos los metadatos existentes adjuntados al contenedor. Para quitar todos los metadatos del contenedor, llame a esta operación sin dict de metadatos.
set_premium_page_blob_tier_blobs	Establece los niveles de blob en páginas en todos los blobs. Esta API solo se admite para blobs en páginas en cuentas Premium. El número máximo de blobs que se pueden actualizar en una sola solicitud es 256.
set_standard_blob_tier_blobs	Esta operación establece el nivel en blobs en bloques. El nivel de un blob en bloques determina el tipo de almacenamiento de acceso frecuente, esporádico o de archivo. Esta operación no actualiza la etiqueta ETag del blob. El número máximo de blobs que se pueden actualizar en una sola solicitud es 256.
upload_blob	Crea un nuevo blob a partir de un origen de datos con fragmentación automática.
walk_blobs	Devuelve un generador para enumerar los blobs en el contenedor especificado. El generador seguirá de forma diferida los tokens de continuación devueltos por el servicio. Esta operación enumerará los blobs de acuerdo con una jerarquía, tal y como está delimitado por el carácter delimitador especificado.

acquire_lease

Solicita una nueva concesión. Si el contenedor no tiene una concesión activa, Blob service crea una concesión sobre el contenedor y devuelve un nuevo identificador de concesión.

acquire_lease(lease_duration: int = -1, lease_id: str | None = None, **kwargs) -> BlobLeaseClient

Parámetros

lease_duration: int

Requerido

Especifica la duración de la concesión, en segundos, o bien un valor negativo (-1) para una concesión que no expira nunca. Un concesión no infinita puede durar entre 15 y 60 segundos. No se puede cambiar una duración de concesión mediante renovación o cambio. El valor predeterminado es -1 (concesión infinita).

lease_id: str

Requerido

Identificador de concesión propuesto, con formato de cadena de GUID. Blob service devuelve 400 (solicitud no válida) si el identificador de concesión propuesto no tiene el formato correcto.

if_modified_since: datetime

Un valor DateTime. Azure espera que el valor de fecha pasado sea UTC. Si se incluye la zona horaria, las fechas no UTC se convertirán a UTC. Si se pasa una fecha sin información de zona horaria, se supone que es UTC. Especifique este encabezado para realizar la operación solo si se ha modificado el recurso desde la hora especificada.

if_unmodified_since: datetime

Un valor DateTime. Azure espera que el valor de fecha pasado sea UTC. Si se incluye la zona horaria, las fechas no UTC se convertirán a UTC. Si se pasa una fecha sin información de zona horaria, se supone que es UTC. Especifique este encabezado para realizar la operación solo si no se ha modificado el recurso desde la fecha u hora especificada.

etag: str

Valor ETag o el carácter comodín (*). Se usa para comprobar si el recurso ha cambiado y actuar según la condición especificada por el parámetro match_condition .

match_condition: MatchConditions

Condición de coincidencia que se va a usar en el etag.

timeout: int

Devoluciones

Objeto BlobLeaseClient que se puede ejecutar en un administrador de contexto.

Tipo de valor devuelto

BlobLeaseClient

close

Este método consiste en cerrar los sockets abiertos por el cliente. No es necesario usarse cuando se usa con un administrador de contextos.

close()

create_container

Crea un nuevo contenedor en la cuenta especificada. Si ya existe un contenedor con el mismo nombre, se produce un error en la operación.

create_container(metadata: Dict[str, str] | None = None, public_access: PublicAccess | str | None = None, **kwargs: Any) -> Dict[str, str | datetime]

Parámetros

metadata: dict[str, str]

Requerido

Un dict con pares de name_value que se van a asociar al contenedor como metadatos. Ejemplo:{'Category':'test'}

public_access: PublicAccess

Requerido

Entre los valores posibles se incluyen: "container", "blob".

container_encryption_scope: dict o ContainerEncryptionScope

Especifica el ámbito de cifrado predeterminado que se va a establecer en el contenedor y usarlo para todas las escrituras futuras.

Novedades de la versión 12.2.0.

timeout: int

Devoluciones

Diccionario de encabezados de respuesta.

Tipo de valor devuelto

Dict[str, Union[str, datetime]]

delete_blob

Marca el blob o la instantánea especificados para su eliminación.

El blob se elimina posteriormente durante la recolección de elementos no utilizados. Tenga en cuenta que para eliminar un blob, debe eliminar todas sus instantáneas. Puede eliminar ambos al mismo tiempo con la operación delete_blob.

Si se habilita una directiva de retención de eliminación para el servicio, esta operación elimina temporalmente el blob o la instantánea y conserva el blob o la instantánea durante el número de días especificado. Después del número especificado de días, los datos del blob se quitan del servicio durante la recolección de elementos no utilizados. Se puede acceder al blob o instantánea eliminado temporalmente mediante list_blobs la especificación de la opción include=["deleted"]. El blob o la instantánea eliminados temporalmente se pueden restaurar mediante <xref:azure.storage.blob.BlobClient.undelete>

delete_blob(blob: str | BlobProperties, delete_snapshots: str | None = None, **kwargs) -> None

Parámetros

blob: str o BlobProperties

Requerido

Blob con el que se va a interactuar. Si se especifica, este valor invalidará un valor de blob especificado en la dirección URL del blob.

delete_snapshots: str

Requerido

Obligatorio si el blob tiene instantáneas asociadas. Estos valores incluyen:

"only": elimina solo las instantáneas de blobs.
"include": elimina el blob junto con todas las instantáneas.

version_id: str

El parámetro version id es un valor DateTime opaco que, cuando está presente, especifica la versión del blob que se va a eliminar.

Novedades de la versión 12.4.0.

Este argumento de palabra clave se introdujo en la versión de API "2019-12-12".

lease: BlobLeaseClient o str

Obligatorio si el blob tiene una concesión activa. El valor puede ser un objeto BlobLeaseClient o el identificador de concesión como una cadena.

if_modified_since: datetime

if_unmodified_since: datetime

Un valor DateTime. Azure espera que el valor de fecha pasado sea UTC. Si se incluye la zona horaria, las fechas no UTC se convertirán a UTC. Si se pasa una fecha sin información de zona horaria, se supone que es UTC. Especifique este encabezado para realizar la operación solo si no se ha modificado el recurso desde la fecha u hora especificada.

etag: str

Valor ETag o el carácter comodín (*). Se usa para comprobar si el recurso ha cambiado y actuar según la condición especificada por el parámetro match_condition .

match_condition: MatchConditions

Condición de coincidencia que se va a usar en el etag.

if_tags_match_condition: str

Especifique una cláusula SQL where en etiquetas de blob para que funcione solo en blob con un valor coincidente. P. ej. "\"tagname\"='my tag'"

Novedades de la versión 12.4.0.

timeout: int

Tipo de valor devuelto

None

delete_blobs

Marca los blobs o instantáneas especificados para su eliminación.

Los blobs se eliminan posteriormente durante la recolección de elementos no utilizados. Tenga en cuenta que para eliminar blobs, debe eliminar todas sus instantáneas. Puede eliminar ambos al mismo tiempo con la operación de delete_blobs.

Si se habilita una directiva de retención de eliminación para el servicio, esta operación elimina temporalmente los blobs o instantáneas y conserva los blobs o instantáneas durante el número de días especificado. Después del número especificado de días, los datos de los blobs se quitan del servicio durante la recolección de elementos no utilizados. Se puede acceder a los blobs o instantáneas eliminados temporalmente mediante list_blobs la especificación de include=["deleted"] Se pueden restaurar blobs o instantáneas eliminados temporalmente mediante <xref:azure.storage.blob.BlobClient.undelete>

El número máximo de blobs que se pueden eliminar en una sola solicitud es 256.

delete_blobs(*blobs: str | Dict[str, Any] | BlobProperties, **kwargs: Any) -> Iterator[HttpResponse]

Parámetros

blobs: str o dict(str, Any) o BlobProperties

Requerido

Blobs que se van a eliminar. Puede ser un único blob o se pueden proporcionar varios valores, donde cada valor es el nombre del blob (str) o BlobProperties.

Nota:

Cuando el tipo de blob es dict, esta es una lista de claves, reglas de valor.

nombre del blob:

key: 'name', value type: str

instantánea que desea eliminar:

key: 'snapshot', value type: str

id. de versión:

key: "version_id", tipo de valor: str

si se van a eliminar instantáneas al eliminar blob:

key: 'delete_snapshots', value: 'include' o 'only'

si el blob modificó o no:

key: "if_modified_since", "if_unmodified_since", tipo de valor: datetime

Etag:

key: 'etag', value type: str

coincide con la etag o no:

key: "match_condition", tipo de valor: MatchConditions

tags match condition (condición de coincidencia de etiquetas):

key: "if_tags_match_condition", tipo de valor: str

Arrendamiento:

key: "lease_id", tipo de valor: Union[str, LeaseClient]

tiempo de espera de la subrecquesta:

key: 'timeout', value type: int

delete_snapshots: str

Obligatorio si un blob tiene instantáneas asociadas. Estos valores incluyen:

"only": elimina solo las instantáneas de blobs.
"include": elimina el blob junto con todas las instantáneas.

if_modified_since: datetime

if_unmodified_since: datetime

Un valor DateTime. Azure espera que el valor de fecha pasado sea UTC. Si se incluye la zona horaria, las fechas no UTC se convertirán a UTC. Si se pasa una fecha sin información de zona horaria, se supone que es UTC. Especifique este encabezado para realizar la operación solo si no se ha modificado el recurso desde la fecha u hora especificada.

if_tags_match_condition: str

Especifique una cláusula SQL where en etiquetas de blob para que funcione solo en blob con un valor coincidente. P. ej. "\"tagname\"='my tag'"

Novedades de la versión 12.4.0.

raise_on_any_failure: bool

Se trata de un parámetro booleano que tiene como valor predeterminado True. Cuando se establece, se genera una excepción incluso si hay un único error de operación.

timeout: int

Devoluciones

Iterador de respuestas, uno para cada blob en orden.

Tipo de valor devuelto

Iterator[HttpResponse]

delete_container

Marca el contenedor especificado para su eliminación. El contenedor y los blobs incluidos en él se eliminan posteriormente durante la recolección de elementos no utilizados.

delete_container(**kwargs: Any) -> None

Parámetros

lease: BlobLeaseClient o str

Si se especifica, delete_container solo se realiza correctamente si la concesión del contenedor está activa y coincide con este identificador. Obligatorio si el contenedor tiene una concesión activa.

if_modified_since: datetime

if_unmodified_since: datetime

Un valor DateTime. Azure espera que el valor de fecha pasado sea UTC. Si se incluye la zona horaria, las fechas no UTC se convertirán a UTC. Si se pasa una fecha sin información de zona horaria, se supone que es UTC. Especifique este encabezado para realizar la operación solo si no se ha modificado el recurso desde la fecha u hora especificada.

etag: str

Valor ETag o el carácter comodín (*). Se usa para comprobar si el recurso ha cambiado y actuar según la condición especificada por el parámetro match_condition .

match_condition: MatchConditions

Condición de coincidencia que se va a usar en el etag.

timeout: int

Tipo de valor devuelto

None

download_blob

Descarga un blob en StorageStreamDownloader. El método readall() debe usarse para leer todo el contenido o readinto() para descargar el blob en una secuencia. El uso de chunks() devuelve un iterador que permite al usuario iterar el contenido en fragmentos.

download_blob(blob: str | BlobProperties, offset: int = None, length: int = None, *, encoding: str, **kwargs) -> StorageStreamDownloader[str]

Parámetros

blob: str o BlobProperties

Requerido

Blob con el que se va a interactuar. Si se especifica, este valor invalidará un valor de blob especificado en la dirección URL del blob.

offset: int

Requerido

Inicio del intervalo de bytes que se va a usar para descargar una sección del blob. Debe establecerse si se proporciona longitud.

length: int

Requerido

Número de bytes que se van a leer de la secuencia. Esto es opcional, pero debe proporcionarse para obtener un rendimiento óptimo.

version_id: str

El parámetro version id es un valor DateTime opaco que, cuando está presente, especifica la versión del blob que se va a descargar.

Novedades de la versión 12.4.0.

Este argumento de palabra clave se introdujo en la versión de API "2019-12-12".

validate_content: bool

Si es true, calcula un hash MD5 para cada fragmento del blob. El servicio de almacenamiento comprueba el hash del contenido que ha llegado con el hash que se envió. Esto es principalmente útil para detectar bitflips en la conexión si usa http en lugar de https, como https (valor predeterminado), ya se validará. Tenga en cuenta que este hash MD5 no se almacena con el blob. Tenga en cuenta también que, si está habilitado, el algoritmo de carga eficaz para memoria no se usará porque la computación del hash MD5 requiere almacenamiento en búfer de bloques completos y, al hacerlo, se anula el propósito del algoritmo eficiente en memoria.

lease: BlobLeaseClient o str

Obligatorio si el blob tiene una concesión activa. Si se especifica, download_blob solo se realiza correctamente si la concesión del blob está activa y coincide con este identificador. El valor puede ser un objeto BlobLeaseClient o el identificador de concesión como una cadena.

if_modified_since: datetime

if_unmodified_since: datetime

Un valor DateTime. Azure espera que el valor de fecha pasado sea UTC. Si se incluye la zona horaria, las fechas no UTC se convertirán a UTC. Si se pasa una fecha sin información de zona horaria, se supone que es UTC. Especifique este encabezado para realizar la operación solo si no se ha modificado el recurso desde la fecha u hora especificada.

etag: str

Valor ETag o el carácter comodín (*). Se usa para comprobar si el recurso ha cambiado y actuar según la condición especificada por el parámetro match_condition .

match_condition: MatchConditions

Condición de coincidencia que se va a usar en el etag.

if_tags_match_condition: str

Especifique una cláusula SQL where en etiquetas de blob para que funcione solo en blob con un valor coincidente. P. ej. "\"tagname\"='my tag'"

Novedades de la versión 12.4.0.

cpk: CustomerProvidedEncryptionKey

Cifra los datos en el lado del servicio con la clave especificada. El uso de claves proporcionadas por el cliente debe realizarse a través de HTTPS. Como la propia clave de cifrado se proporciona en la solicitud, se debe establecer una conexión segura para transferir la clave.

max_concurrency: int

Número de conexiones paralelas con las que se va a descargar.

encoding: str

Codificación para descodificar los bytes descargados. El valor predeterminado es None, es decir, sin descodificación.

progress_hook: Callable[[int, int], None]

Devolución de llamada para realizar un seguimiento del progreso de una descarga de larga duración. La firma es function(current: int, total: int) donde current es el número de bytes transferidos hasta ahora, y total es el tamaño total de la descarga.

timeout: int

Establece el tiempo de espera del lado servidor para la operación en segundos. Para más información, consulte https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations. Este valor no se realiza un seguimiento ni se valida en el cliente. Para configurar tiempos de espera de red del lado cliente, consulte aquí. Este método puede realizar varias llamadas al servicio y el tiempo de espera se aplicará a cada llamada individualmente. varias llamadas al servicio de Azure y el tiempo de espera se aplicará a cada llamada individualmente.

Devoluciones

Objeto de streaming (StorageStreamDownloader)

Tipo de valor devuelto

StorageStreamDownloader

exists

Devuelve True si existe un contenedor y devuelve False de lo contrario.

exists(**kwargs: Any) -> bool

Parámetros

timeout: int

Devoluciones

boolean

Tipo de valor devuelto

bool

find_blobs_by_tags

Devuelve un generador para enumerar los blobs del contenedor especificado cuyas etiquetas coinciden con la expresión de búsqueda especificada. El generador seguirá de forma diferida los tokens de continuación devueltos por el servicio.

find_blobs_by_tags(filter_expression: str, **kwargs: Any | None) -> ItemPaged[FilteredBlob]

Parámetros

filter_expression: str

Requerido

Expresión que se va a buscar blobs cuyas etiquetas coinciden con la condición especificada. P. ej. ""yourtagname"='firsttag' y "yourtagname2"='secondtag'"

results_per_page: int

Resultado máximo por página al paginar.

timeout: int

Devoluciones

Respuesta iterable (paginación automática) de FilteredBlob.

Tipo de valor devuelto

ItemPaged[BlobProperties]

from_connection_string

Cree ContainerClient a partir de una cadena de conexión.

from_connection_string(conn_str: str, container_name: str, credential: str | Dict[str, str] | AzureNamedKeyCredential | AzureSasCredential | TokenCredential | None = None, **kwargs: Any) -> Self

Parámetros

conn_str: str

Requerido

Cadena de conexión a una cuenta de Azure Storage.

container_name: str

Requerido

Nombre del contenedor del blob.

credential

valor predeterminado: None

Credenciales con las que se va a autenticar. Esto es opcional si la dirección URL de la cuenta ya tiene un token de SAS o la cadena de conexión ya tiene valores de clave de acceso compartido. El valor puede ser una cadena de token de SAS, una instancia de AzureSasCredential o AzureNamedKeyCredential de azure.core.credentials, una clave de acceso compartido de cuenta o una instancia de una clase TokenCredentials de azure.identity. Las credenciales proporcionadas aquí tendrán prioridad sobre las de la cadena de conexión. Si usa una instancia de AzureNamedKeyCredential, "name" debe ser el nombre de la cuenta de almacenamiento y "key" debe ser la clave de la cuenta de almacenamiento.

Devoluciones

Un cliente de contenedor.

Tipo de valor devuelto

ContainerClient

from_container_url

Cree ContainerClient desde una dirección URL de contenedor.

from_container_url(container_url: str, credential: str | Dict[str, str] | AzureNamedKeyCredential | AzureSasCredential | TokenCredential | None = None, **kwargs: Any) -> Self

Parámetros

container_url: str

Requerido

Dirección URL completa del punto de conexión al contenedor, incluido el token de SAS si se usa. Puede ser el punto de conexión principal o el punto de conexión secundario en función del location_mode actual.

credential

valor predeterminado: None

Credenciales con las que se va a autenticar. Esto es opcional si la dirección URL de la cuenta ya tiene un token de SAS o la cadena de conexión ya tiene valores de clave de acceso compartido. El valor puede ser una cadena de token de SAS, una instancia de AzureSasCredential o AzureNamedKeyCredential de azure.core.credentials, una clave de acceso compartido de cuenta o una instancia de una clase TokenCredentials de azure.identity. Si el URI del recurso ya contiene un token de SAS, se omitirá en favor de una credencial explícita.

excepto en el caso de AzureSasCredential, donde los tokens de SAS en conflicto generarán un valor ValueError. Si usa una instancia de AzureNamedKeyCredential, "name" debe ser el nombre de la cuenta de almacenamiento y "key" debe ser la clave de la cuenta de almacenamiento.

Devoluciones

Un cliente de contenedor.

Tipo de valor devuelto

ContainerClient

get_account_information

Obtiene información relacionada con la cuenta de almacenamiento.

La información también se puede recuperar si el usuario tiene una SAS en un contenedor o blob. Las claves del diccionario devuelto incluyen "sku_name" y "account_kind".

get_account_information(**kwargs: Any) -> Dict[str, str]

Devoluciones

Un dict de información de cuenta (SKU y tipo de cuenta).

Tipo de valor devuelto

dict(str, str)

get_blob_client

Obtenga un cliente para interactuar con el blob especificado.

El blob aún no debe existir.

get_blob_client(blob: str | BlobProperties, snapshot: str = None, *, version_id: str | None = None) -> BlobClient

Parámetros

blob: str o BlobProperties

Requerido

Blob con el que se va a interactuar.

snapshot: str

valor predeterminado: None

Instantánea de blob opcional en la que se va a operar. Puede ser la cadena de identificador de instantánea o la respuesta devuelta de create_snapshot.

version_id: str

El parámetro version id es un valor DateTime opaco en el que, cuando está presente, especifica la versión del blob en el que operar.

Devoluciones

Un BlobClient.

Tipo de valor devuelto

BlobClient

get_container_access_policy

Obtiene los permisos para el contenedor especificado. Los permisos indican si el acceso a los datos de un contenedor es público.

get_container_access_policy(**kwargs: Any) -> Dict[str, Any]

Parámetros

lease: BlobLeaseClient o str

Si se especifica, get_container_access_policy solo se realiza correctamente si la concesión del contenedor está activa y coincide con este identificador.

timeout: int

Devoluciones

Información de la directiva de acceso en un dict.

Tipo de valor devuelto

dict[str, Any]

get_container_properties

Devuelve todos los metadatos definidos por el usuario y las propiedades del sistema para el contenedor especificado. Los datos devueltos no incluyen la lista de blobs del contenedor.

get_container_properties(**kwargs: Any) -> ContainerProperties

Parámetros

lease: BlobLeaseClient o str

Si se especifica, get_container_properties solo se realiza correctamente si la concesión del contenedor está activa y coincide con este identificador.

timeout: int

Devoluciones

Propiedades del contenedor especificado dentro de un objeto contenedor.

Tipo de valor devuelto

ContainerProperties

list_blob_names

Devuelve un generador para enumerar los nombres de blobs en el contenedor especificado. El generador seguirá de forma diferida los tokens de continuación devueltos por el servicio.

Tenga en cuenta que no se devolverán propiedades ni metadatos adicionales al usar esta API. Además, esta API no tiene una opción para incluir blobs adicionales, como instantáneas, versiones, blobs eliminados temporalmente, etc. Para obtener cualquiera de estos datos, use list_blobs.

list_blob_names(**kwargs: Any) -> ItemPaged[str]

Parámetros

name_starts_with: str

Filtra los resultados para devolver solo los blobs cuyos nombres empiezan por el prefijo especificado.

timeout: int

Devoluciones

Respuesta iterable (paginación automática) de nombres de blobs como cadenas.

Tipo de valor devuelto

ItemPaged[str]

list_blobs

Devuelve un generador para enumerar los blobs en el contenedor especificado. El generador seguirá de forma diferida los tokens de continuación devueltos por el servicio.

list_blobs(name_starts_with: str | None = None, include: str | List[str] | None = None, **kwargs: Any) -> ItemPaged[BlobProperties]

Parámetros

name_starts_with: str

Requerido

Filtra los resultados para devolver solo los blobs cuyos nombres empiezan por el prefijo especificado.

include: list[str] o str

Requerido

Especifica uno o varios conjuntos de datos adicionales que se van a incluir en la respuesta. Las opciones incluyen: 'snapshots', 'metadata', 'uncommittedblobs', 'copy', 'deleted', 'deletedwithversions', 'tags', 'versions', 'immutabilitypolicy', 'legalhold'.

timeout: int

Devoluciones

Respuesta iterable (paginación automática) de BlobProperties.

Tipo de valor devuelto

ItemPaged[BlobProperties]

set_container_access_policy

Establece los permisos para el contenedor especificado o las directivas de acceso almacenadas que se pueden usar con firmas de acceso compartido. Los permisos indican si el acceso a los blobs de un contenedor es público.

set_container_access_policy(signed_identifiers: Dict[str, AccessPolicy], public_access: str | PublicAccess | None = None, **kwargs) -> Dict[str, str | datetime]

Parámetros

signed_identifiers: dict[str, AccessPolicy]

Requerido

Diccionario de directivas de acceso que se van a asociar al contenedor. El diccionario puede contener hasta 5 elementos. Un diccionario vacío borrará las directivas de acceso establecidas en el servicio.

public_access: PublicAccess

Requerido

Entre los valores posibles se incluyen: "container", "blob".

lease: BlobLeaseClient o str

Obligatorio si el contenedor tiene una concesión activa. El valor puede ser un objeto BlobLeaseClient o el identificador de concesión como una cadena.

if_modified_since: datetime

Valor datetime. Azure espera que el valor de fecha pasado sea UTC. Si se incluye la zona horaria, las fechas y horas no UTC se convertirán a UTC. Si se pasa una fecha sin información de zona horaria, se supone que es UTC. Especifique este encabezado para realizar la operación solo si el recurso se ha modificado desde la fecha y hora especificadas.

if_unmodified_since: datetime

Valor datetime. Azure espera que el valor de fecha pasado sea UTC. Si se incluye la zona horaria, las fechas y horas no UTC se convertirán a UTC. Si se pasa una fecha sin información de zona horaria, se supone que es UTC. Especifique este encabezado para realizar la operación solo si no se ha modificado el recurso desde la fecha u hora especificada.

timeout: int

Devoluciones

Dict de propiedad actualizada por contenedor (Etag y última modificación).

Tipo de valor devuelto

dict[str, str,

datetime]

set_container_metadata

Establece uno o varios pares nombre-valor definidos por el usuario para el contenedor especificado. Cada llamada a esta operación reemplaza todos los metadatos existentes adjuntados al contenedor. Para quitar todos los metadatos del contenedor, llame a esta operación sin dict de metadatos.

set_container_metadata(metadata: Dict[str, str] | None = None, **kwargs) -> Dict[str, str | datetime]

Parámetros

metadata: dict[str, str]

Requerido

Un dict que contiene pares nombre-valor que se van a asociar al contenedor como metadatos. Ejemplo: {'category':'test'}

lease: BlobLeaseClient o str

Si se especifica, set_container_metadata solo se realiza correctamente si la concesión del contenedor está activa y coincide con este identificador.

if_modified_since: datetime

Un valor DateTime. Azure espera que el valor de fecha pasado sea UTC. Si se incluye la zona horaria, las fechas y horas no UTC se convertirán a UTC. Si se pasa una fecha sin información de zona horaria, se supone que es UTC. Especifique este encabezado para realizar la operación solo si se ha modificado el recurso desde la hora especificada.

if_unmodified_since: datetime

Un valor DateTime. Azure espera que el valor de fecha pasado sea UTC. Si se incluye la zona horaria, las fechas y horas no UTC se convertirán a UTC. Si se pasa una fecha sin información de zona horaria, se supone que es UTC. Especifique este encabezado para realizar la operación solo si no se ha modificado el recurso desde la fecha u hora especificada.

etag: str

Valor ETag o el carácter comodín (*). Se usa para comprobar si el recurso ha cambiado y actuar según la condición especificada por el parámetro match_condition .

timeout: int

Devoluciones

Dict de propiedad actualizada por contenedor (Etag y última modificación).

Tipo de valor devuelto

dict[str, str,

datetime]

set_premium_page_blob_tier_blobs

Establece los niveles de blob en páginas en todos los blobs. Esta API solo se admite para blobs en páginas en cuentas Premium.

El número máximo de blobs que se pueden actualizar en una sola solicitud es 256.

set_premium_page_blob_tier_blobs(premium_page_blob_tier: str | PremiumPageBlobTier | None, *blobs: str | Dict[str, Any] | BlobProperties, **kwargs: Any) -> Iterator[HttpResponse]

Parámetros

premium_page_blob_tier: PremiumPageBlobTier

Requerido

Valor de nivel de blob en páginas en el que se va a establecer el blob. El nivel se correlaciona con el tamaño del blob y el número de IOPS permitidas. Esto solo se aplica a los blobs en páginas en cuentas de Premium Storage.

Nota:

Si desea establecer un nivel diferente en distintos blobs, establezca este parámetro posicional en Ninguno.

A continuación, se tomará el nivel de blob en cada BlobProperties.

blobs: str o dict(str, Any) o BlobProperties

Requerido

Blobs con los que se va a interactuar. Puede ser un único blob o se pueden proporcionar varios valores, donde cada valor es el nombre del blob (str) o BlobProperties.

Nota:

Cuando el tipo de blob es dict, esta es una lista de claves, reglas de valor.

nombre del blob:

key: 'name', value type: str

Nivel de blob premium:

key: "blob_tier", tipo de valor: PremiumPageBlobTier

Arrendamiento:

key: "lease_id", tipo de valor: Union[str, LeaseClient]

tiempo de espera de la subrequest:

key: "timeout", tipo de valor: int

timeout: int

raise_on_any_failure: bool

Se trata de un parámetro booleano que tiene como valor predeterminado True. Cuando se establece, se genera una excepción incluso si se produce un único error de operación.

Devoluciones

Iterador de respuestas, uno para cada blob en orden

Tipo de valor devuelto

<xref:iterator>[HttpResponse]

set_standard_blob_tier_blobs

Esta operación establece el nivel en blobs en bloques.

El nivel de un blob en bloques determina el tipo de almacenamiento de acceso frecuente, esporádico o de archivo. Esta operación no actualiza la etiqueta ETag del blob.

El número máximo de blobs que se pueden actualizar en una sola solicitud es 256.

set_standard_blob_tier_blobs(standard_blob_tier: str | StandardBlobTier | None, *blobs: str | Dict[str, Any] | BlobProperties, **kwargs: Any) -> Iterator[HttpResponse]

Parámetros

standard_blob_tier: str o StandardBlobTier

Requerido

Indica el nivel que se va a establecer en todos los blobs. Entre las opciones se incluyen "Frecuente", "Esporádico", "Archivo". El nivel de acceso frecuente está optimizado para almacenar datos a los que se accede con frecuencia. El nivel de almacenamiento esporádico está optimizado para almacenar datos a los que se accede con poca frecuencia y se almacena durante al menos un mes. El nivel de archivo está optimizado para almacenar datos a los que rara vez se accede y se almacena durante al menos seis meses con requisitos de latencia flexibles.

Nota:

Si desea establecer un nivel diferente en distintos blobs, establezca este parámetro posicional en Ninguno.

A continuación, se tomará el nivel de blob en cada BlobProperties.

blobs: str o dict(str, Any) o BlobProperties

Requerido

Blobs con los que se va a interactuar. Puede ser un único blob o se pueden proporcionar varios valores, donde cada valor es el nombre del blob (str) o BlobProperties.

Nota:

Cuando el tipo de blob es dict, esta es una lista de claves, reglas de valor.

nombre del blob:

key: 'name', value type: str

nivel de blob estándar:

key: "blob_tier", tipo de valor: StandardBlobTier

prioridad de rehidratación:

key: "rehydrate_priority", tipo de valor: RehydratePriority

Arrendamiento:

key: "lease_id", tipo de valor: Union[str, LeaseClient]

Instantánea:

key: "snapshot", value type: str

id. de versión:

key: "version_id", tipo de valor: str

tags match condition(Condición de coincidencia de etiquetas):

key: "if_tags_match_condition", tipo de valor: str

tiempo de espera de la subrequest:

key: "timeout", tipo de valor: int

rehydrate_priority: RehydratePriority

Indica la prioridad con la que rehidratar un blob archivado.

if_tags_match_condition: str

Especifique una cláusula SQL where en las etiquetas de blob para operar solo en el blob con un valor coincidente. P. ej. "\"tagname\"='my tag'"

Novedad de la versión 12.4.0.

timeout: int

raise_on_any_failure: bool

Se trata de un parámetro booleano que tiene como valor predeterminado True. Cuando se establece, se genera una excepción incluso si se produce un único error de operación.

Devoluciones

Iterador de respuestas, uno para cada blob en orden

Tipo de valor devuelto

Iterator[HttpResponse]

upload_blob

Crea un nuevo blob a partir de un origen de datos con fragmentación automática.

upload_blob(name: str | BlobProperties, data: bytes | str | Iterable | IO, blob_type: str | BlobType = BlobType.BLOCKBLOB, length: int | None = None, metadata: Dict[str, str] | None = None, **kwargs) -> BlobClient

Parámetros

name: str o BlobProperties

Requerido

Blob con el que se va a interactuar. Si se especifica, este valor invalidará un valor de blob especificado en la dirección URL del blob.

data

Requerido

Datos del blob que se van a cargar.

blob_type: BlobType

Requerido

Tipo de blob. Puede ser BlockBlob, PageBlob o AppendBlob. El valor predeterminado es BlockBlob.

length: int

Requerido

Número de bytes que se van a leer de la secuencia. Esto es opcional, pero debe proporcionarse para obtener un rendimiento óptimo.

metadata: dict(str, str)

Requerido

Pares nombre-valor asociados al blob como metadatos.

overwrite: bool

Si el blob que se va a cargar debe sobrescribir los datos actuales. Si es True, upload_blob sobrescribirá los datos existentes. Si se establece en False, se producirá un error en la operación con ResourceExistsError. La excepción a lo anterior es con los tipos de blobs append: si se establece en False y los datos ya existen, no se generará un error y los datos se anexarán al blob existente. Si se establece overwrite=True, se eliminará el blob en anexos existente y se creará uno nuevo. El valor predeterminado es False.

content_settings: ContentSettings

Objeto ContentSettings usado para establecer propiedades de blob. Se usa para establecer el tipo de contenido, la codificación, el idioma, la disposición, md5 y el control de caché.

validate_content: bool

Si es true, calcula un hash MD5 para cada fragmento del blob. El servicio de almacenamiento comprueba el hash del contenido que ha llegado con el hash que se envió. Esto es principalmente útil para detectar bitflips en la conexión si se usa http en lugar de https, como https (el valor predeterminado), ya se validará. Tenga en cuenta que este hash MD5 no se almacena con el blob. Tenga en cuenta también que si está habilitado, no se usará el algoritmo de carga eficaz para memoria, ya que calcular el hash MD5 requiere almacenar en búfer bloques completos y, al hacerlo, se anula el propósito del algoritmo eficiente en memoria.

lease: BlobLeaseClient o str

Obligatorio si el contenedor tiene una concesión activa. El valor puede ser un objeto BlobLeaseClient o el identificador de concesión como una cadena.

if_modified_since: datetime

if_unmodified_since: datetime

Un valor DateTime. Azure espera que el valor de fecha pasado sea UTC. Si se incluye la zona horaria, las fechas y horas no UTC se convertirán a UTC. Si se pasa una fecha sin información de zona horaria, se supone que es UTC. Especifique este encabezado para realizar la operación solo si no se ha modificado el recurso desde la fecha u hora especificada.

etag: str

Valor ETag o el carácter comodín (*). Se usa para comprobar si el recurso ha cambiado y actuar según la condición especificada por el parámetro match_condition .

match_condition: MatchConditions

Condición de coincidencia que se va a usar en la etiqueta electrónica.

if_tags_match_condition: str

Especifique una cláusula SQL where en las etiquetas de blob para operar solo en el blob con un valor coincidente. P. ej. "\"tagname\"='my tag'"

Novedad de la versión 12.4.0.

timeout: int

Establece el tiempo de espera del lado servidor para la operación en segundos. Para más información, consulte https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations. Este valor no se realiza ni se valida en el cliente. Para configurar los tiempos de espera de red del lado cliente, consulte aquí. Este método puede realizar varias llamadas al servicio y el tiempo de espera se aplicará a cada llamada individualmente.

premium_page_blob_tier: PremiumPageBlobTier

standard_blob_tier: StandardBlobTier

Valor de nivel de blob estándar en el que se va a establecer el blob. Para esta versión de la biblioteca, esto solo se aplica a blobs en bloques en cuentas de almacenamiento estándar.

maxsize_condition: int

Encabezado condicional opcional. Longitud máxima en bytes permitida para el blob en anexos. Si la operación Append Block haría que el blob supere ese límite o si el tamaño del blob ya es mayor que el valor especificado en este encabezado, la solicitud producirá un error MaxBlobSizeConditionNotMet (código de estado HTTP 412 - Error de condición previa).

max_concurrency: int

Número máximo de conexiones paralelas que se usarán cuando el tamaño del blob supere los 64 MB.

cpk: CustomerProvidedEncryptionKey

encryption_scope: str

Ámbito de cifrado predefinido que se usa para cifrar los datos en el servicio. Se puede crear un ámbito de cifrado mediante la API de administración y hacer referencia aquí por su nombre. Si se ha definido un ámbito de cifrado predeterminado en el contenedor, este valor lo invalidará si el ámbito de nivel de contenedor está configurado para permitir invalidaciones. De lo contrario, se generará un error.

Novedad de la versión 12.2.0.

encoding: str

El valor predeterminado es UTF-8.

progress_hook: Callable[[int, Optional[int]], None]

Devolución de llamada para realizar un seguimiento del progreso de una carga de larga duración. La firma es function(current: int, total: Optional[int]), donde current es el número de bytes transferidos hasta ahora, y total es el tamaño del blob o None si se desconoce el tamaño.

Devoluciones

BlobClient para interactuar con el blob recién cargado.

Tipo de valor devuelto

BlobClient

walk_blobs

Devuelve un generador para enumerar los blobs en el contenedor especificado. El generador seguirá de forma diferida los tokens de continuación devueltos por el servicio. Esta operación enumerará los blobs de acuerdo con una jerarquía, tal y como está delimitado por el carácter delimitador especificado.

walk_blobs(name_starts_with: str | None = None, include: str | List[str] | None = None, delimiter: str = '/', **kwargs: Any | None) -> ItemPaged[BlobProperties]

Parámetros

name_starts_with: str

Requerido

Filtra los resultados para devolver solo los blobs cuyos nombres empiezan por el prefijo especificado.

include: list[str] o str

Requerido

delimiter: str

Requerido

Cuando la solicitud incluye este parámetro, la operación devuelve un elemento BlobPrefix en el cuerpo de la respuesta que actúa como marcador de posición para todos los blobs cuyos nombres comienzan con la misma subcadena hasta la apariencia del carácter delimitador. El delimitador puede ser un carácter o una cadena.

timeout: int

Devoluciones

Respuesta iterable (paginación automática) de BlobProperties.

Tipo de valor devuelto

ItemPaged[BlobProperties]

Atributos

api_version

La versión de la API de storage que se usa para las solicitudes.

location_mode

Modo de ubicación que el cliente está usando actualmente.

De forma predeterminada, será "principal". Entre las opciones se incluyen "primary" y "secondary".

primary_endpoint

Dirección URL completa del punto de conexión principal.

primary_hostname

Nombre de host del punto de conexión principal.

secondary_endpoint

Dirección URL completa del punto de conexión secundario si está configurada.

Si no está disponible, se generará un valor ValueError. Para especificar explícitamente un nombre de host secundario, use el argumento opcional secondary_hostname palabra clave en la creación de instancias.

Excepciones

ValueError

secondary_hostname

El nombre de host del punto de conexión secundario.

Si no está disponible, será Ninguno. Para especificar explícitamente un nombre de host secundario, use el argumento opcional secondary_hostname palabra clave en la creación de instancias.

url

Dirección URL completa del punto de conexión a esta entidad, incluido el token de SAS si se usa.

Puede ser el punto de conexión principal o el punto de conexión secundario en función del actual location_mode. :returns: la dirección URL completa del punto de conexión a esta entidad, incluido el token de SAS si se usa. :rtype: str