Compartilhar via


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 .

Para obter mais configurações opcionais, 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
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.

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.

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

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.

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

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) -> ItemPaged[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, confira aqui.

Retornos

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

Tipo de retorno

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

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_account_information(**kwargs: Any) -> Dict[str, str]

Retornos

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

Tipo de retorno

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

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

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_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

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_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

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.

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

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) -> ItemPaged[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

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.

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

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

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, consulte aqui.

Retornos

O ContainerClient não selecionado.

Tipo de retorno

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

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