Compartir a través de


BlobServiceClient Clase

Un cliente para interactuar con Blob Service en el nivel de cuenta.

Este cliente proporciona operaciones para recuperar y configurar las propiedades de la cuenta, así como enumerar, crear y eliminar contenedores dentro de la cuenta. En el caso de las operaciones relacionadas con un contenedor o blob específico, los clientes de esas entidades también se pueden recuperar mediante las funciones get_client .

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

Herencia
azure.storage.blob._shared.base_client.StorageAccountHostsMixin
BlobServiceClient
azure.storage.blob._encryption.StorageEncryptionMixin
BlobServiceClient

Constructor

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

Parámetros

account_url
str
Requerido

Dirección URL de la cuenta de Blob Storage. Se descartarán las demás entidades incluidas en la ruta de acceso url (por ejemplo, contenedor o blob). Esta dirección URL se puede autenticar opcionalmente con un token de SAS.

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

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 el contenedor con el mismo nombre ya existe, se generará un resourceExistsError. Este método devuelve un cliente con el que interactuar con el contenedor recién creado.

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. Si no se encuentra el contenedor, se generará un resourceNotFoundError.

find_blobs_by_tags

La operación Filtrar blobs permite a los autores de llamadas enumerar blobs en todos los contenedores cuyas etiquetas coinciden con una expresión de búsqueda determinada. Filtrar blobs busca en todos los contenedores de una cuenta de almacenamiento, pero se puede limitar dentro de la expresión a un único contenedor.

from_connection_string

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

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_client

Obtener un cliente para interactuar con el contenedor especificado.

El contenedor aún no debe existir.

get_service_properties

Obtiene las propiedades de Blob service de una cuenta de almacenamiento, incluido Azure Storage Analytics.

get_service_stats

Recupera las estadísticas relacionadas con la replicación para el servicio Blob.

Solo está disponible cuando la replicación con redundancia geográfica con acceso de lectura está habilitada para la cuenta de almacenamiento.

Con la replicación con redundancia geográfica, Azure Storage mantiene los datos duraderos en dos ubicaciones. En las dos ubicaciones, Azure Storage mantiene constantemente réplicas en estado correcto de los datos. La ubicación en la que lee, crea, actualiza o elimina los datos es la ubicación de la cuenta de almacenamiento principal. La ubicación principal existe en la región que elija en el momento en que cree una cuenta a través del Portal de Administración de Azure clásico de Azure, por ejemplo, Centro-norte de EE. UU. La ubicación en la que se replican los datos es la ubicación secundaria. La ubicación secundaria se determina automáticamente según la ubicación de la principal; está en un segundo centro de datos que se encuentra en la misma región que la ubicación principal. El acceso de solo lectura está disponible en la ubicación secundaria, si la replicación con redundancia geográfica con acceso de lectura está habilitada para la cuenta de almacenamiento.

get_user_delegation_key

Obtenga una clave de delegación de usuarios con el fin de firmar tokens de SAS. Una credencial de token debe estar presente en el objeto de servicio para que esta solicitud se realice correctamente.

list_containers

Devuelve un generador para enumerar los contenedores de la cuenta especificada.

El generador seguirá de forma diferida los tokens de continuación devueltos por el servicio y se detendrá cuando se devuelvan todos los contenedores.

set_service_properties

Establece las propiedades de Blob service de una cuenta de almacenamiento, incluido Azure Storage Analytics.

Si un elemento (por ejemplo, analytics_logging) se deja como None, se conserva la configuración existente en el servicio para esa funcionalidad.

undelete_container

Restaura el contenedor eliminado temporalmente.

La operación solo se realizará correctamente si se usa dentro del número de días especificado establecido en la directiva de retención de eliminación.

Novedad de la versión 12.4.0: esta operación se introdujo en la versión de API "2019-12-12".

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 el contenedor con el mismo nombre ya existe, se generará un resourceExistsError. Este método devuelve un cliente con el que interactuar con el contenedor recién creado.

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

Parámetros

name
str
Requerido

Nombre del contenedor que se va a crear.

metadata
dict(str, str)
Requerido

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

public_access
str o 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

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í.

Tipo de valor devuelto

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. Si no se encuentra el contenedor, se generará un resourceNotFoundError.

delete_container(container: ContainerProperties | str, lease: BlobLeaseClient | str | None = None, **kwargs) -> None

Parámetros

container
str o ContainerProperties
Requerido

Contenedor que se va a eliminar. Puede ser el nombre del contenedor o una instancia de ContainerProperties.

lease
Requerido

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

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

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í.

Tipo de valor devuelto

find_blobs_by_tags

La operación Filtrar blobs permite a los autores de llamadas enumerar blobs en todos los contenedores cuyas etiquetas coinciden con una expresión de búsqueda determinada. Filtrar blobs busca en todos los contenedores de una cuenta de almacenamiento, pero se puede limitar dentro de la expresión a un único contenedor.

find_blobs_by_tags(filter_expression: str, **kwargs: Any) -> 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'" Para especificar un contenedor, por ejemplo. "@container='containerName' y "Name"='C'"

results_per_page
int

Resultado máximo por página al paginar.

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 los tiempos de espera de red del lado cliente, consulte aquí.

Devoluciones

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

Tipo de valor devuelto

from_connection_string

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

from_connection_string(conn_str: 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.

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 Blob service.

Tipo de valor devuelto

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

Una diferencia de la información de la cuenta (SKU y tipo de cuenta).

Tipo de valor devuelto

get_blob_client

Obtenga un cliente para interactuar con el blob especificado.

El blob aún no debe existir.

get_blob_client(container: ContainerProperties | str, blob: BlobProperties | str, snapshot: Dict[str, Any] | str | None = None, *, version_id: str | None = None) -> BlobClient

Parámetros

container
str o ContainerProperties
Requerido

Contenedor en el que se encuentra el blob. Puede ser el nombre del contenedor o una instancia de ContainerProperties.

blob
str o BlobProperties
Requerido

Blob con el que se va a interactuar. Puede ser el nombre del blob o una instancia de BlobProperties.

snapshot
str o dict(str, Any)
valor predeterminado: None

Instantánea de blob opcional en la que se va a operar. Puede ser el identificador de la instantánea o una salida de diccionario devuelta por 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

get_container_client

Obtener un cliente para interactuar con el contenedor especificado.

El contenedor aún no debe existir.

get_container_client(container: ContainerProperties | str) -> ContainerClient

Parámetros

container
str o ContainerProperties
Requerido

Contenedor. Puede ser el nombre del contenedor o una instancia de ContainerProperties.

Devoluciones

A ContainerClient.

Tipo de valor devuelto

get_service_properties

Obtiene las propiedades de Blob service de una cuenta de almacenamiento, incluido Azure Storage Analytics.

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

Parámetros

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í.

Devoluciones

Objeto que contiene propiedades de Blob Service, como el registro de análisis, métricas de hora y minuto, reglas de cors, etc.

Tipo de valor devuelto

get_service_stats

Recupera las estadísticas relacionadas con la replicación para el servicio Blob.

Solo está disponible cuando la replicación con redundancia geográfica con acceso de lectura está habilitada para la cuenta de almacenamiento.

Con la replicación con redundancia geográfica, Azure Storage mantiene los datos duraderos en dos ubicaciones. En las dos ubicaciones, Azure Storage mantiene constantemente réplicas en estado correcto de los datos. La ubicación en la que lee, crea, actualiza o elimina los datos es la ubicación de la cuenta de almacenamiento principal. La ubicación principal existe en la región que elija en el momento en que cree una cuenta a través del Portal de Administración de Azure clásico de Azure, por ejemplo, Centro-norte de EE. UU. La ubicación en la que se replican los datos es la ubicación secundaria. La ubicación secundaria se determina automáticamente según la ubicación de la principal; está en un segundo centro de datos que se encuentra en la misma región que la ubicación principal. El acceso de solo lectura está disponible en la ubicación secundaria, si la replicación con redundancia geográfica con acceso de lectura está habilitada para la cuenta de almacenamiento.

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

Parámetros

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í.

Devoluciones

Las estadísticas del servicio BLOB.

Tipo de valor devuelto

get_user_delegation_key

Obtenga una clave de delegación de usuarios con el fin de firmar tokens de SAS. Una credencial de token debe estar presente en el objeto de servicio para que esta solicitud se realice correctamente.

get_user_delegation_key(key_start_time: datetime, key_expiry_time: datetime, **kwargs: Any) -> UserDelegationKey

Parámetros

key_start_time
datetime
Requerido

Un valor DateTime. Indica cuándo la clave es válida.

key_expiry_time
datetime
Requerido

Un valor DateTime. Indica cuándo la clave deja de ser válida.

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í.

Devoluciones

Clave de delegación de usuarios.

Tipo de valor devuelto

list_containers

Devuelve un generador para enumerar los contenedores de la cuenta especificada.

El generador seguirá de forma diferida los tokens de continuación devueltos por el servicio y se detendrá cuando se devuelvan todos los contenedores.

list_containers(name_starts_with: str | None = None, include_metadata: bool | None = False, **kwargs) -> ItemPaged[ContainerProperties]

Parámetros

name_starts_with
str
Requerido

Filtra los resultados para devolver solo los contenedores cuyos nombres comienzan por el prefijo especificado.

include_metadata
bool
Requerido

Especifica que los metadatos de contenedor que se van a devolver en la respuesta. El valor predeterminado es False.

include_deleted
bool

Especifica que los contenedores eliminados se devolverán en la respuesta. Esto es para la cuenta habilitada para la restauración de contenedores. El valor predeterminado es False. .. versionadded:: 12.4.0

include_system
bool

Marca que especifica que se deben incluir los contenedores del sistema. .. versionadded:: 12.10.0

results_per_page
int

Número máximo de nombres de contenedor que se van a recuperar por llamada API. Si la solicitud no especifica que el servidor devuelva hasta 5000 elementos.

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í.

Devoluciones

Iterable (paginación automática) de ContainerProperties.

Tipo de valor devuelto

set_service_properties

Establece las propiedades de Blob service de una cuenta de almacenamiento, incluido Azure Storage Analytics.

Si un elemento (por ejemplo, analytics_logging) se deja como None, se conserva la configuración existente en el servicio para esa funcionalidad.

set_service_properties(analytics_logging: BlobAnalyticsLogging | None = None, hour_metrics: Metrics | None = None, minute_metrics: Metrics | None = None, cors: List[CorsRule] | None = None, target_version: str | None = None, delete_retention_policy: RetentionPolicy | None = None, static_website: StaticWebsite | None = None, **kwargs) -> None

Parámetros

analytics_logging
BlobAnalyticsLogging
Requerido

Agrupa los valores de Logging de análisis de Azure.

hour_metrics
Metrics
Requerido

La configuración de métricas de hora proporciona un resumen de las estadísticas de solicitud agrupadas por API en agregados por hora para blobs.

minute_metrics
Metrics
Requerido

La configuración de métricas por minuto proporciona estadísticas de solicitud para cada minuto para los blobs.

cors
list[CorsRule]
Requerido

Puede incluir hasta cinco elementos CorsRule en la lista. Si se especifica una lista vacía, se eliminarán todas las reglas de CORS y CORS se deshabilitará para el servicio.

target_version
str
Requerido

Indica la versión predeterminada que se va a usar para las solicitudes si no se especifica la versión de una solicitud entrante.

delete_retention_policy
RetentionPolicy
Requerido

La directiva de retención de eliminación especifica si se deben conservar los blobs eliminados. También especifica el número de días y versiones del blob que se van a conservar.

static_website
StaticWebsite
Requerido

Especifica si la característica de sitio web estático está habilitada y, si es así, indica el documento de índice y el documento de error 404 que se va a usar.

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í.

Tipo de valor devuelto

undelete_container

Restaura el contenedor eliminado temporalmente.

La operación solo se realizará correctamente si se usa dentro del número de días especificado establecido en la directiva de retención de eliminación.

Novedad de la versión 12.4.0: esta operación se introdujo en la versión de API "2019-12-12".

undelete_container(deleted_container_name: str, deleted_container_version: str, **kwargs: Any) -> ContainerClient

Parámetros

deleted_container_name
str
Requerido

Especifica el nombre del contenedor eliminado que se va a restaurar.

deleted_container_version
str
Requerido

Especifica la versión del contenedor eliminado que se va a restaurar.

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í.

Devoluciones

ContainerClient no eliminado.

Tipo de valor devuelto

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

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