BlobServiceClient Classe

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

Esse cliente fornece operações para recuperar e configurar as propriedades da conta, bem como listar, criar e excluir contêineres dentro da conta. Para operações relacionadas a um contêiner ou blob específico, os clientes dessas entidades também podem ser recuperados usando as funções get_client .

Herança

azure.storage.blob._shared.base_client_async.AsyncStorageAccountHostsMixin

BlobServiceClient

azure.storage.blob._blob_service_client.BlobServiceClient

BlobServiceClient

azure.storage.blob._encryption.StorageEncryptionMixin

BlobServiceClient

Construtor

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

Parâmetros

account_url

str

Obrigatório

A URL para a conta de armazenamento de blobs. Todas as outras entidades incluídas no caminho da URL (por exemplo, contêiner ou blob) serão descartadas. Essa URL pode ser autenticada opcionalmente com um token SAS.

credential

valor padrão: None

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

• exceto no caso de AzureSasCredential, em que os tokens SAS conflitantes gerarão um ValueError. Se estiver usando uma instância de AzureNamedKeyCredential, "name" deverá ser o nome da conta de armazenamento e "key" deverá ser a chave da conta de armazenamento.

api_version

str

A versão da API de Armazenamento a ser usada para solicitações. O valor padrão é a versão de serviço mais recente compatível com o SDK atual. A configuração para uma versão mais antiga pode resultar em redução da compatibilidade de recursos.

Novo na versão 12.2.0.

secondary_hostname

str

O nome do host do ponto de extremidade secundário.

max_block_size

int

O tamanho máximo da parte para carregar um blob de blocos em partes. O padrã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 com apenas uma solicitação HTTP PUT. Se o tamanho do blob for maior que max_single_put_size, o blob será carregado em partes. O padrão é 64*1024*1024 ou 64 MB.

min_large_block_upload_threshold

int

O tamanho mínimo da parte necessária para usar o algoritmo com eficiência de memória ao carregar um blob de blocos. O padrão é 4*1024*1024+1.

use_byte_buffer

bool

Use um buffer de bytes para uploads de blob de blocos. Usa False como padrão.

max_page_size

int

O tamanho máximo da parte para carregar um blob de páginas. O padrão é 4*1024*1024 ou 4 MB.

max_single_get_size

int

O tamanho máximo de um blob a ser baixado em uma única chamada, a parte excedida será baixada em partes (pode ser paralela). O padrão é 32*1024*1024 ou 32 MB.

max_chunk_get_size

int

O tamanho máximo da parte usada para baixar um blob. O padrão é 4*1024*1024 ou 4 MB.

Métodos

close	Esse método é para fechar os soquetes abertos pelo cliente. Ele não precisa ser usado ao usar com um gerenciador de contexto.
create_container	Cria um novo contêiner na conta especificada. Se o contêiner com o mesmo nome já existir, um ResourceExistsError será gerado. Esse método retorna um cliente com o qual interagir com o contêiner recém-criado.
delete_container	Marca o contêiner especificado para exclusão. O contêiner e todos os blobs contidos são excluídos posteriormente, durante a coleta de lixo. Se o contêiner não for encontrado, um ResourceNotFoundError será gerado.
find_blobs_by_tags	A operação Filtrar Blobs permite que os chamadores listem blobs em todos os contêineres cujas marcas correspondem a uma determinada expressão de pesquisa. Os blobs de filtro pesquisam em todos os contêineres dentro de uma conta de armazenamento, mas podem ser definidos dentro da expressão para um único contêiner.
from_connection_string	Crie BlobServiceClient a partir de uma cadeia de conexão.
get_account_information	Obtém informações relacionadas à conta de armazenamento. As informações também poderão ser recuperadas se o usuário tiver uma SAS para um contêiner ou blob. As chaves no dicionário retornado incluem 'sku_name' e 'account_kind'.
get_blob_client	Faça com que um cliente interaja com o blob especificado. O blob ainda não precisa existir.
get_container_client	Faça com que um cliente interaja com o contêiner especificado. O contêiner ainda não precisa existir.
get_service_properties	Obtém as propriedades do serviço Blob de uma conta de armazenamento, incluindo Análise de Armazenamento do Azure.
get_service_stats	Recupera as estatísticas relacionadas à replicação do serviço Blob. Ela só estará disponível quando a replicação com redundância geográfica de acesso de leitura estiver habilitada para a conta de armazenamento. Com a replicação georredundante, o Armazenamento do Azure mantém seus dados duráveis em dois locais. Em ambos os locais, o Armazenamento do Azure mantém constantemente várias réplicas íntegras de seus dados. O local onde você lê, cria, atualiza ou exclui dados é o local da conta de armazenamento principal. O local primário existe na região escolhida no momento em que você cria uma conta por meio do portal clássico do Azure Management Azure, por exemplo, Centro-Norte dos EUA. O local no qual seus dados são replicados é o local secundário. O local secundário é determinado automaticamente com base no local principal; ele está em um segundo data center que reside na mesma região que o local principal. O acesso somente leitura está disponível no local secundário se a replicação georredundante de acesso de leitura está habilitada para sua conta de armazenamento.
get_user_delegation_key	Obtenha uma chave de delegação de usuário com a finalidade de assinar tokens SAS. Uma credencial de token deve estar presente no objeto de serviço para que essa solicitação tenha êxito.
list_containers	Retorna um gerador para listar os contêineres na conta especificada. O gerador seguirá lentamente os tokens de continuação retornados pelo serviço e será interrompido quando todos os contêineres forem retornados.
set_service_properties	Define as propriedades do serviço Blob de uma conta de armazenamento, incluindo Análise de Armazenamento do Azure. Se um elemento (por exemplo, analytics_logging) for deixado como Nenhum, as configurações existentes no serviço para essa funcionalidade serão preservadas.
undelete_container	Restaura o contêiner excluído temporariamente. A operação só será bem-sucedida se for usada dentro do número especificado de dias definido na política de retenção de exclusão. Novidades na versão 12.4.0: essa operação foi introduzida na versão de API '2019-12-12'.

close

Esse método é para fechar os soquetes abertos pelo cliente. Ele não precisa ser usado ao usar com um gerenciador de contexto.

async close()

create_container

Cria um novo contêiner na conta especificada.

Se o contêiner com o mesmo nome já existir, um ResourceExistsError será gerado. Esse método retorna um cliente com o qual interagir com o contêiner recém-criado.

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

Parâmetros

name

str

Obrigatório

O nome do contêiner a ser criado.

metadata

dict(str, str)

Obrigatório

Um dict com pares nome-valor a serem associados ao contêiner como metadados. Exemplo: {'Category':'test'}

public_access

str ou PublicAccess

Obrigatório

Os valores possíveis incluem: 'container', 'blob'.

container_encryption_scope

dict ou ContainerEncryptionScope

Especifica o escopo de criptografia padrão a ser definido no contêiner e usado para todas as gravações futuras.

Novo 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 informações, confira https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations. Esse valor não é rastreado ou validado no cliente. Para configurar tempos limite de rede do lado do cliente, consulte aqui.

Tipo de retorno

ContainerClient

delete_container

Marca o contêiner especificado para exclusão.

O contêiner e todos os blobs contidos são excluídos posteriormente, durante a coleta de lixo. Se o contêiner não for encontrado, um ResourceNotFoundError será gerado.

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

Parâmetros

container

str ou ContainerProperties

Obrigatório

O contêiner a ser excluído. Pode ser o nome do contêiner ou uma instância de ContainerProperties.

lease

Obrigatório

Se especificado, delete_container só terá êxito se a concessão do contêiner estiver ativa e corresponder a essa ID. Obrigatório se o contêiner tiver uma concessão ativa.

if_modified_since

datetime

Um valor Datetime. O Azure espera que o valor de data passado seja UTC. Se o fuso horário for incluído, todos os datetimes não UTC serão convertidos em UTC. Se uma data for passada sem informações de fuso horário, será considerado UTC. Especifique esse cabeçalho para executar a operação somente 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 passado seja UTC. Se o fuso horário for incluído, todos os datetimes não UTC serão convertidos em UTC. Se uma data for passada sem informações de fuso horário, será considerado UTC. Especifique esse cabeçalho para executar a operação somente se o recurso não tiver sido modificado desde a data/hora especificada.

etag

str

Um valor de ETag ou o caractere curinga (*). Usado para marcar 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 ser usada na etag.

timeout

int

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

Tipo de retorno

None

find_blobs_by_tags

A operação Filtrar Blobs permite que os chamadores listem blobs em todos os contêineres cujas marcas correspondem a uma determinada expressão de pesquisa. Os blobs de filtro pesquisam em todos os contêineres dentro de uma conta de armazenamento, mas podem ser definidos dentro da expressão para um único contêiner.

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

Parâmetros

filter_expression

str

Obrigatório

A expressão para localizar blobs cujas marcas correspondem à condição especificada. ex. ""yourtagname"='firsttag' e "yourtagname2"='secondtag'" Para especificar um contêiner, 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 informações, confira https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations. Esse valor não é rastreado ou validado no cliente. Para configurar tempos limite de rede do lado do cliente, consulte aqui.

Retornos

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

Tipo de retorno

AsyncItemPaged[FilteredBlob]

from_connection_string

Crie BlobServiceClient a partir de uma cadeia de conexã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

Obrigatório

Uma cadeia de conexão com uma conta de Armazenamento do Azure.

credential

valor padrão: None

As credenciais com as quais autenticar. Isso é opcional se a URL da conta já tiver um token SAS ou a cadeia de conexão já tiver valores de chave de acesso compartilhado. O valor pode ser uma cadeia de caracteres de token SAS, uma instância de um AzureSasCredential ou AzureNamedKeyCredential de azure.core.credentials, uma chave de acesso compartilhado de conta ou uma instância de uma classe TokenCredentials do azure.identity. As credenciais fornecidas aqui terão precedência sobre aquelas na cadeia de conexão. Se estiver usando uma instância do AzureNamedKeyCredential, "name" deverá ser o nome da conta de armazenamento e "key" deverá ser a chave da conta de armazenamento.

Retornos

Um cliente do serviço Blob.

Tipo de retorno

BlobServiceClient

get_account_information

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

As informações também poderão ser recuperadas se o usuário tiver uma SAS para um contêiner ou blob. As chaves no dicionário retornado incluem 'sku_name' e 'account_kind'.

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

Retornos

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

Tipo de retorno

dict(str, str)

get_blob_client

Faça com que um cliente interaja com o blob especificado.

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

Obrigatório

O contêiner no qual o blob está. Esse pode ser o nome do contêiner ou uma instância de ContainerProperties.

blob

str ou BlobProperties

Obrigatório

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

snapshot

str ou dict(str, Any)

valor padrão: None

O blob opcional instantâneo no qual operar. Essa pode ser a ID do instantâneo ou uma saída de dicionário retornada por create_snapshot.

version_id

str

O parâmetro id de versão é um valor datetime opaco que, quando presente, especifica a versão do blob no qual operar.

Retornos

Um BlobClient.

Tipo de retorno

BlobClient

get_container_client

Faça com que um cliente interaja com o contêiner especificado.

O contêiner ainda não precisa existir.

get_container_client(container: ContainerProperties | str) -> ContainerClient

Parâmetros

container

str ou ContainerProperties

Obrigatório

O contêiner. Esse pode ser o nome do contêiner ou uma instância de ContainerProperties.

Retornos

Um ContainerClient.

Tipo de retorno

ContainerClient

get_service_properties

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

async 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 informações, confira https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations. Esse valor não é rastreado ou validado no cliente. Para configurar tempos limite de rede do lado do cliente, confira aqui.

Retornos

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

Tipo de retorno

Dict[str, Any]

get_service_stats

Recupera as estatísticas relacionadas à replicação do serviço Blob.

Ela só estará disponível quando a replicação com redundância geográfica de acesso de leitura estiver habilitada para a conta de armazenamento.

Com a replicação georredundante, o Armazenamento do Azure mantém seus dados duráveis em dois locais. Em ambos os locais, o Armazenamento do Azure mantém constantemente várias réplicas íntegras de seus dados. O local onde você lê, cria, atualiza ou exclui dados é o local da conta de armazenamento principal. O local primário existe na região escolhida no momento em que você cria uma conta por meio do portal clássico do Azure Management Azure, por exemplo, Centro-Norte dos EUA. O local no qual seus dados são replicados é o local secundário. O local secundário é determinado automaticamente com base no local principal; ele está em um segundo data center que reside na mesma região que o local principal. O acesso somente leitura está disponível no local secundário se a replicação georredundante de acesso de leitura está habilitada para sua conta de armazenamento.

async 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 informações, confira https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations. Esse valor não é rastreado ou validado no cliente. Para configurar tempos limite de rede do lado do cliente, confira aqui.

Retornos

As estatísticas do serviço blob.

Tipo de retorno

Dict[str, Any]

get_user_delegation_key

Obtenha uma chave de delegação de usuário com a finalidade de assinar tokens SAS. Uma credencial de token deve estar presente no objeto de serviço para que essa solicitação tenha êxito.

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

Parâmetros

key_start_time

datetime

Obrigatório

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

key_expiry_time

datetime

Obrigató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 informações, confira https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations. Esse valor não é rastreado ou validado no cliente. Para configurar tempos limite de rede do lado do cliente, confira aqui.

Retornos

A chave de delegação do usuário.

Tipo de retorno

UserDelegationKey

list_containers

Retorna um gerador para listar os contêineres na conta especificada.

O gerador seguirá lentamente os tokens de continuação retornados pelo serviço e será interrompido quando todos os contêineres forem retornados.

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

Parâmetros

name_starts_with

str

Obrigatório

Filtra os resultados para retornar somente contêineres cujos nomes começam com o prefixo especificado.

include_metadata

bool

Obrigatório

Especifica que os metadados de contêiner a serem retornados na resposta. O valor padrão é Falso.

include_deleted

bool

Especifica que contêineres excluídos a serem retornados na resposta. Isso é para a conta habilitada para restauração de contêiner. O valor padrão é Falso. .. versionadded:: 12.4.0

include_system

bool

Sinalizador especificando que os contêineres do sistema devem ser incluídos. .. versionadded:: 12.10.0

results_per_page

int

O número máximo de nomes de contêiner a serem recuperados por chamada à API. Se a solicitação não especificar, o servidor retornará até 5.000 itens.

timeout

int

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

Retornos

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

Tipo de retorno

AsyncItemPaged[ContainerProperties]

set_service_properties

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

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

async 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

Obrigatório

Agrupa as configurações de Log da Análise do Azure.

hour_metrics

Metrics

Obrigatório

As configurações de métricas de hora fornecem um resumo das estatísticas de solicitação agrupadas pela API em agregações por hora para blobs.

minute_metrics

Metrics

Obrigatório

As configurações de métricas de minuto fornecem estatísticas de solicitação para cada minuto para blobs.

cors

list[CorsRule]

Obrigatório

Você pode incluir até cinco elementos CorsRule na lista. Se uma lista vazia for especificada, todas as regras CORS serão excluídas e o CORS será desabilitado para o serviço.

target_version

str

Obrigatório

Indica a versão padrão a ser usada para solicitações se a versão de uma solicitação de entrada não for especificada.

delete_retention_policy

RetentionPolicy

Obrigatório

A política de retenção de exclusão especifica se os blobs excluídos devem ser retidos. Ele também especifica o número de dias e versões do blob a serem mantidos.

static_website

StaticWebsite

Obrigatório

Especifica se o recurso de site estático está habilitado e, se sim, indica o documento de índice e o documento de erro 404 a ser usado.

timeout

int

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

Tipo de retorno

None

undelete_container

Restaura o contêiner excluído temporariamente.

A operação só será bem-sucedida se for usada dentro do número especificado de dias definido na política de retenção de exclusão.

Novidades na versão 12.4.0: essa operação foi introduzida na versão de API '2019-12-12'.

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

Parâmetros

deleted_container_name

str

Obrigatório

Especifica o nome do contêiner excluído a ser restaurado.

deleted_container_version

str

Obrigatório

Especifica a versão do contêiner excluído a ser restaurado.

timeout

int

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

Retornos

O ContainerClient de exclusão reversível recuperado.

Tipo de retorno

ContainerClient

Atributos

api_version

A versão da API de Armazenamento usada para solicitações.

location_mode

O modo de localização que o cliente está usando no momento.

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

primary_endpoint

A URL completa do ponto de extremidade primário.

primary_hostname

O nome do host do ponto de extremidade primário.

secondary_endpoint

A URL completa do ponto de extremidade secundário, se configurada.

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

Exceções

ValueError

secondary_hostname

O nome do host do ponto de extremidade secundário.

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

url

A URL completa do ponto de extremidade para essa entidade, incluindo o token SAS, se usado.

Isso pode ser o ponto de extremidade primário ou o ponto de extremidade secundário, dependendo do atual location_mode. :returns: a URL completa do ponto de extremidade para essa entidade, incluindo o token SAS, se usado. :rtype: str