BlobServiceClient Classe

Um cliente para interagir com o Serviço Blob ao nível da conta.

Este cliente fornece operações para obter e configurar as propriedades da conta, bem como listar, criar e eliminar contentores na conta. Para operações relacionadas com um contentor ou blob específico, os clientes dessas entidades também podem ser obtidos com as funções de get_client .

Para obter mais configuração opcional, clique aqui.

Herança

azure.storage.blob._shared.base_client.StorageAccountHostsMixin

BlobServiceClient

azure.storage.blob._encryption.StorageEncryptionMixin

BlobServiceClient

Construtor

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

Parâmetros

account_url

str

Necessário

O URL para a conta de armazenamento de blobs. Quaisquer outras entidades incluídas no caminho do URL (por exemplo, contentor ou blob) serão eliminadas. Opcionalmente, este URL pode ser autenticado com um token de SAS.

credential

valor predefinido: None

As credenciais com as quais se autenticar. Isto é opcional se o URL da conta já tiver um token de SAS. O valor pode ser uma cadeia de token de SAS, uma instância de uma AzureSasCredential ou AzureNamedKeyCredential a partir de azure.core.credentials, uma chave de acesso partilhada de conta ou uma instância de uma classe TokenCredentials a partir de azure.identity. Se o URI do recurso já contiver um token de SAS, este será ignorado a favor de uma credencial explícita

• exceto no caso do AzureSasCredential, em que os tokens SAS em conflito gerarão um ValueError. Se utilizar uma instância do AzureNamedKeyCredential, "name" deve ser o nome da conta de armazenamento e "chave" deve ser a chave da conta de armazenamento.

api_version

str

A versão da API de Armazenamento a utilizar para pedidos. O valor predefinido é a versão de serviço mais recente compatível com o SDK atual. Definir para uma versão mais antiga pode resultar numa compatibilidade de funcionalidades reduzida.

Novidades na versão 12.2.0.

secondary_hostname

str

O nome do anfitrião do ponto final secundário.

max_block_size

int

O tamanho máximo do segmento para carregar um blob de blocos em segmentos. A predefinição é 4*1024*1024 ou 4 MB.

max_single_put_size

int

Se o tamanho do blob for menor ou igual a max_single_put_size, o blob será carregado apenas com um pedido HTTP PUT. Se o tamanho do blob for superior a max_single_put_size, o blob será carregado em segmentos. A predefinição é 64*1024*1024 ou 64 MB.

min_large_block_upload_threshold

int

O tamanho mínimo de segmento necessário para utilizar o algoritmo eficiente em termos de memória ao carregar um blob de blocos. A predefinição é 4*1024*1024+1.

use_byte_buffer

bool

Utilize uma memória intermédia de bytes para carregamentos de blobs de blocos. Predefinições para Falso.

max_page_size

int

O tamanho máximo do segmento para carregar um blob de página. A predefinição é 4*1024*1024 ou 4 MB.

max_single_get_size

int

O tamanho máximo para que um blob seja transferido numa única chamada, a parte excedida será transferida em segmentos (pode ser paralela). A predefinição é 32*1024*1024 ou 32 MB.

max_chunk_get_size

int

O tamanho máximo de segmento utilizado para transferir um blob. A predefinição é 4*1024*1024 ou 4 MB.

Métodos

close	Este método consiste em fechar os sockets abertos pelo cliente. Não é necessário utilizá-lo ao utilizar com um gestor de contexto.
create_container	Cria um novo contentor na conta especificada. Se o contentor com o mesmo nome já existir, será gerado um ResourceExistsError. Este método devolve um cliente com o qual pode interagir com o contentor criado recentemente.
delete_container	Marca o contentor especificado para eliminação. O contentor e quaisquer blobs contidos no mesmo são posteriormente eliminados durante a recolha de lixo. Se o contentor não for encontrado, será gerado um ResourceNotFoundError.
find_blobs_by_tags	A operação Filtrar Blobs permite que os autores da chamada listem blobs em todos os contentores cujas etiquetas correspondam a uma determinada expressão de pesquisa. Os blobs de filtros pesquisam em todos os contentores numa conta de armazenamento, mas podem ser confinados dentro da expressão a um único contentor.
from_connection_string	Crie BlobServiceClient a partir de uma Cadeia de Ligação.
get_account_information	Obtém informações relacionadas com a conta de armazenamento. As informações também podem ser obtidas se o utilizador tiver uma SAS para um contentor ou blob. As chaves no dicionário devolvido incluem "sku_name" e "account_kind".
get_blob_client	Obter um cliente para interagir com o blob especificado. O blob ainda não precisa de existir.
get_container_client	Obter um cliente para interagir com o contentor especificado. O contentor ainda não precisa de existir.
get_service_properties	Obtém as propriedades do serviço Blob de uma conta de armazenamento, incluindo o Azure Análise de Armazenamento.
get_service_stats	Obtém estatísticas relacionadas com a replicação do serviço Blob. Só está disponível quando a replicação georredundante de acesso de leitura está ativada para a conta de armazenamento. Com a replicação georredundante, o Armazenamento do Azure mantém os seus dados duráveis em duas localizações. Em ambas as localizações, o Armazenamento do Azure mantém constantemente várias réplicas em bom estado de funcionamento dos seus dados. A localização onde lê, cria, atualiza ou elimina dados é a localização principal da conta de armazenamento. A localização primária existe na região que escolher no momento em que cria uma conta através do portal clássico do Azure management do Azure, por exemplo, E.U.A. Centro-Norte. A localização para a qual os seus dados são replicados é a localização secundária. A localização secundária é determinada automaticamente com base na localização da primária; é num segundo datacenter que reside na mesma região que a localização primária. O acesso só de leitura está disponível a partir da localização secundária, se a replicação georredundante com acesso de leitura estiver ativada para a sua conta de armazenamento.
get_user_delegation_key	Obtenha uma chave de delegação de utilizador para fins de assinatura de tokens SAS. Tem de estar presente uma credencial de token no objeto de serviço para que este pedido seja bem-sucedido.
list_containers	Devolve um gerador para listar os contentores na conta especificada. O gerador seguirá preguiçosamente os tokens de continuação devolvidos pelo serviço e parará quando todos os contentores tiverem sido devolvidos.
set_service_properties	Define as propriedades do serviço Blob de uma conta de armazenamento, incluindo o Azure Análise de Armazenamento. Se um elemento (por exemplo, analytics_logging) for deixado como Nenhum, as definições existentes no serviço para essa funcionalidade são preservadas.
undelete_container	Restaura o contentor eliminado de forma recuperável. A operação só será efetuada com êxito se for utilizada no número especificado de dias definido na política de retenção de eliminação. Novidade na versão 12.4.0: esta operação foi introduzida na versão de API "2019-12-12".

close

Este método consiste em fechar os sockets abertos pelo cliente. Não é necessário utilizá-lo ao utilizar com um gestor de contexto.

close()

create_container

Cria um novo contentor na conta especificada.

Se o contentor com o mesmo nome já existir, será gerado um ResourceExistsError. Este método devolve um cliente com o qual pode interagir com o contentor criado recentemente.

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

Parâmetros

name

str

Necessário

O nome do contentor a criar.

metadata

dict(str, str)

Necessário

Um ditado com pares nome-valor para associar ao contentor como metadados. Exemplo: {'Category':'test'}

public_access

str ou PublicAccess

Necessário

Os valores possíveis incluem: "contentor", "blob".

container_encryption_scope

dict ou ContainerEncryptionScope

Especifica o âmbito de encriptação predefinido a definir no contentor e a utilização para todas as escritas futuras.

Novidades na versão 12.2.0.

timeout

int

Define o tempo limite do lado do servidor para a operação em segundos. Para obter mais detalhes, veja https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations. Este valor não é monitorizado nem validado no cliente. Para configurar tempos limite de rede do lado do cliente, veja aqui.

Tipo de retorno

ContainerClient

delete_container

Marca o contentor especificado para eliminação.

O contentor e quaisquer blobs contidos no mesmo são posteriormente eliminados durante a recolha de lixo. Se o contentor não for encontrado, será gerado um ResourceNotFoundError.

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

Parâmetros

container

str ou ContainerProperties

Necessário

O contentor a eliminar. Pode ser o nome do contentor ou uma instância de ContainerProperties.

lease

Necessário

Se especificado, delete_container só é bem-sucedido se a concessão do contentor estiver ativa e corresponder a este ID. Necessário se o contentor tiver uma concessão ativa.

if_modified_since

datetime

Um valor DateTime. O Azure espera que o valor de data transmitido seja UTC. Se o fuso horário estiver incluído, quaisquer datetimes não UTC serão convertidos em UTC. Se uma data for transmitida sem informações de fuso horário, assume-se que é UTC. Especifique este cabeçalho para executar a operação apenas se o recurso tiver sido modificado desde a hora especificada.

if_unmodified_since

datetime

Um valor DateTime. O Azure espera que o valor de data transmitido seja UTC. Se o fuso horário estiver incluído, quaisquer datetimes não UTC serão convertidos em UTC. Se uma data for transmitida sem informações de fuso horário, assume-se que é UTC. Especifique este cabeçalho para executar a operação apenas se o recurso não tiver sido modificado desde a data/hora especificada.

etag

str

Um valor ETag ou o caráter universal (*). Utilizado para verificar se o recurso foi alterado e agir de acordo com a condição especificada pelo parâmetro match_condition .

match_condition

MatchConditions

A condição de correspondência a utilizar no etag.

timeout

int

Define o tempo limite do lado do servidor para a operação em segundos. Para obter mais detalhes, veja https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations. Este valor não é monitorizado nem validado no cliente. Para configurar tempos limite de rede do lado do cliente, veja aqui.

Tipo de retorno

None

find_blobs_by_tags

A operação Filtrar Blobs permite que os autores da chamada listem blobs em todos os contentores cujas etiquetas correspondam a uma determinada expressão de pesquisa. Os blobs de filtros pesquisam em todos os contentores numa conta de armazenamento, mas podem ser confinados dentro da expressão a um único contentor.

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

Parâmetros

filter_expression

str

Necessário

A expressão para localizar blobs cujas etiquetas correspondem à condição especificada. Por exemplo, ""yourtagname"='firsttag' e "yourtagname2"='secondtag'" Para especificar um contentor, por exemplo. "@container='containerName' e "Name"='C'"

results_per_page

int

O resultado máximo por página ao paginar.

timeout

int

Define o tempo limite do lado do servidor para a operação em segundos. Para obter mais detalhes, veja https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations. Este valor não é monitorizado nem validado no cliente. Para configurar tempos limite de rede do lado do cliente, veja aqui.

Devoluções

Uma resposta iterável (paginação automática) de BlobProperties.

Tipo de retorno

ItemPaged[FilteredBlob]

from_connection_string

Crie BlobServiceClient a partir de uma Cadeia de Ligação.

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

Parâmetros

conn_str

str

Necessário

Uma cadeia de ligação a uma conta de Armazenamento do Azure.

credential

valor predefinido: None

As credenciais com as quais se autenticar. Isto é opcional se o URL da conta já tiver um token de SAS ou se a cadeia de ligação já tiver valores de chave de acesso partilhados. O valor pode ser uma cadeia de token de SAS, uma instância de um AzureSasCredential ou AzureNamedKeyCredential a partir de azure.core.credentials, uma chave de acesso partilhada de conta ou uma instância de uma classe TokenCredentials a partir de azure.identity. As credenciais aqui fornecidas terão precedência sobre as credenciais na cadeia de ligação. Se utilizar uma instância do AzureNamedKeyCredential, "name" deve ser o nome da conta de armazenamento e "chave" deve ser a chave da conta de armazenamento.

Devoluções

Um cliente do serviço Blob.

Tipo de retorno

BlobServiceClient

get_account_information

Obtém informações relacionadas com a conta de armazenamento.

As informações também podem ser obtidas se o utilizador tiver uma SAS para um contentor ou blob. As chaves no dicionário devolvido incluem "sku_name" e "account_kind".

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

Devoluções

Um ditado das informações da conta (SKU e tipo de conta).

Tipo de retorno

dict(str, str)

get_blob_client

Obter um cliente para interagir com o blob especificado.

O blob ainda não precisa de 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 ou ContainerProperties

Necessário

O contentor no qual o blob se encontra. Pode ser o nome do contentor ou uma instância de ContainerProperties.

blob

str ou BlobProperties

Necessário

O blob com o qual interagir. Pode ser o nome do blob ou uma instância de BlobProperties.

snapshot

str ou dict(str, Any)

valor predefinido: None

O instantâneo de blob opcional no qual pretende operar. Pode ser o ID do instantâneo ou um resultado do dicionário devolvido por create_snapshot.

version_id

str

O parâmetro ID da versão é um valor dateTime opaco que, quando presente, especifica a versão do blob a operar.

Devoluções

Um BlobClient.

Tipo de retorno

BlobClient

get_container_client

Obter um cliente para interagir com o contentor especificado.

O contentor ainda não precisa de existir.

get_container_client(container: ContainerProperties | str) -> ContainerClient

Parâmetros

container

str ou ContainerProperties

Necessário

O contentor. Pode ser o nome do contentor ou uma instância de ContainerProperties.

Devoluções

Um ContainerClient.

Tipo de retorno

ContainerClient

get_service_properties

Obtém as propriedades do serviço Blob de uma conta de armazenamento, incluindo o Azure Análise de Armazenamento.

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

Parâmetros

timeout

int

Define o tempo limite do lado do servidor para a operação em segundos. Para obter mais detalhes, veja https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations. Este valor não é controlado ou validado no cliente. Para configurar tempos limite de rede do lado do cliente, veja aqui.

Devoluções

Um objeto que contém propriedades do serviço de blobs, como registo de análise, métricas de hora/minuto, regras cors, etc.

Tipo de retorno

Dict[str, Any]

get_service_stats

Obtém estatísticas relacionadas com a replicação do serviço Blob.

Só está disponível quando a replicação georredundante de acesso de leitura está ativada para a conta de armazenamento.

Com a replicação georredundante, o Armazenamento do Azure mantém os seus dados duráveis em duas localizações. Em ambas as localizações, o Armazenamento do Azure mantém constantemente várias réplicas em bom estado de funcionamento dos seus dados. A localização onde lê, cria, atualiza ou elimina dados é a localização principal da conta de armazenamento. A localização primária existe na região que escolher no momento em que cria uma conta através do portal clássico do Azure management do Azure, por exemplo, E.U.A. Centro-Norte. A localização para a qual os seus dados são replicados é a localização secundária. A localização secundária é determinada automaticamente com base na localização da primária; é num segundo datacenter que reside na mesma região que a localização primária. O acesso só de leitura está disponível a partir da localização secundária, se a replicação georredundante com acesso de leitura estiver ativada para a sua conta de armazenamento.

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

Parâmetros

timeout

int

Define o tempo limite do lado do servidor para a operação em segundos. Para obter mais detalhes, veja https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations. Este valor não é controlado ou validado no cliente. Para configurar tempos limite de rede do lado do cliente, veja aqui.

Devoluções

As estatísticas do serviço blob.

Tipo de retorno

Dict[str, Any]

get_user_delegation_key

Obtenha uma chave de delegação de utilizador para fins de assinatura de tokens SAS. Tem de estar presente uma credencial de token no objeto de serviço para que este pedido seja bem-sucedido.

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

Parâmetros

key_start_time

datetime

Necessário

Um valor DateTime. Indica quando a chave se torna válida.

key_expiry_time

datetime

Necessário

Um valor DateTime. Indica quando a chave deixa de ser válida.

timeout

int

Define o tempo limite do lado do servidor para a operação em segundos. Para obter mais detalhes, veja https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations. Este valor não é controlado ou validado no cliente. Para configurar tempos limite de rede do lado do cliente, veja aqui.

Devoluções

A chave de delegação do utilizador.

Tipo de retorno

UserDelegationKey

list_containers

Devolve um gerador para listar os contentores na conta especificada.

O gerador seguirá preguiçosamente os tokens de continuação devolvidos pelo serviço e parará quando todos os contentores tiverem sido devolvidos.

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

Parâmetros

name_starts_with

str

Necessário

Filtra os resultados para devolver apenas os contentores cujos nomes começam com o prefixo especificado.

include_metadata

bool

Necessário

Especifica os metadados de contentor a devolver na resposta. O valor predefinido é Falso.

include_deleted

bool

Especifica que os contentores eliminados serão devolvidos na resposta. Isto destina-se à conta com restauro de contentor ativado. O valor predefinido é Falso. .. versionadded:: 12.4.0

include_system

bool

Sinalizador que especifica que os contentores do sistema devem ser incluídos. .. versionadded:: 12.10.0

results_per_page

int

O número máximo de nomes de contentor a obter por chamada à API. Se o pedido não especificar, o servidor devolverá até 5000 itens.

timeout

int

Define o tempo limite do lado do servidor para a operação em segundos. Para obter mais detalhes, veja https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations. Este valor não é controlado ou validado no cliente. Para configurar tempos limite de rede do lado do cliente, veja aqui.

Devoluções

Um iterável (paginação automática) de ContainerProperties.

Tipo de retorno

ItemPaged[ContainerProperties]

set_service_properties

Define as propriedades do serviço Blob de uma conta de armazenamento, incluindo o Azure Análise de Armazenamento.

Se um elemento (por exemplo, analytics_logging) for deixado como Nenhum, as definições existentes no serviço para essa funcionalidade são preservadas.

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

Necessário

Agrupa as definições do Registo do Azure Analytics.

hour_metrics

Metrics

Necessário

As definições de métricas de hora fornecem um resumo das estatísticas de pedidos agrupadas pela API em agregados por hora para blobs.

minute_metrics

Metrics

Necessário

As definições de métricas de minuto fornecem estatísticas de pedidos para cada minuto para blobs.

cors

list[CorsRule]

Necessário

Pode incluir até cinco elementos CorsRule na lista. Se for especificada uma lista vazia, todas as regras CORS serão eliminadas e o CORS será desativado para o serviço.

target_version

str

Necessário

Indica a versão predefinida a utilizar para pedidos se a versão de um pedido recebido não for especificada.

delete_retention_policy

RetentionPolicy

Necessário

A política de retenção eliminar especifica se pretende reter blobs eliminados. Também especifica o número de dias e versões do blob a manter.

static_website

StaticWebsite

Necessário

Especifica se a funcionalidade de site estático está ativada e, se sim, indica o documento de índice e o documento de erro 404 a utilizar.

timeout

int

Define o tempo limite do lado do servidor para a operação em segundos. Para obter mais detalhes, veja https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations. Este valor não é controlado ou validado no cliente. Para configurar tempos limite de rede do lado do cliente, veja aqui.

Tipo de retorno

None

undelete_container

Restaura o contentor eliminado de forma recuperável.

A operação só será efetuada com êxito se for utilizada no número especificado de dias definido na política de retenção de eliminação.

Novidade na versão 12.4.0: esta operação foi introduzida na versão de API "2019-12-12".

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

Parâmetros

deleted_container_name

str

Necessário

Especifica o nome do contentor eliminado a restaurar.

deleted_container_version

str

Necessário

Especifica a versão do contentor eliminado a restaurar.

timeout

int

Define o tempo limite do lado do servidor para a operação em segundos. Para obter mais detalhes, veja https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations. Este valor não é controlado ou validado no cliente. Para configurar tempos limite de rede do lado do cliente, veja aqui.

Devoluções

O ContainerClient não desativado.

Tipo de retorno

ContainerClient

Atributos

api_version

A versão da API de Armazenamento utilizada para pedidos.

location_mode

O modo de localização que o cliente está a utilizar atualmente.

Por predefinição, será "primário". As opções incluem "principal" e "secundário".

primary_endpoint

O URL do ponto final primário completo.

primary_hostname

O nome do anfitrião do ponto final primário.

secondary_endpoint

O URL completo do ponto final secundário, se configurado.

Se não estiver disponível, será gerado um ValueError. Para especificar explicitamente um nome de anfitrião secundário, utilize o argumento opcional secondary_hostname palavra-chave na instanciação.

Exceções

ValueError

secondary_hostname

O nome do anfitrião do ponto final secundário.

Se não estiver disponível, este será Nenhum. Para especificar explicitamente um nome de anfitrião secundário, utilize o argumento opcional secondary_hostname palavra-chave na instanciação.

url

O URL de ponto final completo para esta entidade, incluindo o token de SAS, se utilizado.

Este pode ser o ponto final principal ou o ponto final secundário, dependendo do atual location_mode. :returns: o URL de ponto final completo para esta entidade, incluindo o token SAS, se utilizado. :rtype: str