Compartilhar via

Copiar um blob de uma URL de objeto de origem com o Python

  • Artigo

Este artigo mostra como copiar um blob de uma URL de objeto de origem usando a biblioteca de clientes do Armazenamento do Azure para Python. Você pode copiar um blob de uma origem dentro da mesma conta de armazenamento, de uma origem em uma conta de armazenamento diferente ou de qualquer objeto acessível recuperado por meio de uma solicitação HTTP GET em um URL específico.

Os métodos da biblioteca de clientes abordados neste artigo usam as operações de API REST Colocar um Blob do URL e Colocar um Bloco do URL. Esses métodos são os preferidos para cenários de cópia sempre que você desejar transferir dados para uma conta de armazenamento e tiver um URL para o objeto de origem. Para operações de cópia sempre que você desejar um agendamento assíncrono, consulte Copiar um blob com agendamento assíncrono usando Python.

Para saber mais sobre como copiar blobs usando APIs assíncronas, confira Copiar um blob de uma URL de objeto de origem de maneira assíncrona.

Pré-requisitos

Configure seu ambiente

Se você não tiver um projeto existente, esta seção mostrará como configurar um projeto para funcionar com a biblioteca de clientes do Armazenamento de Blobs do Azure para Python. Para obter mais detalhes, confira Introdução ao Armazenamento de Blobs do Azure e ao Python.

Para trabalhar com os exemplos de código neste artigo, siga estas etapas para configurar seu projeto.

Instalar Pacotes

Instale os seguintes pacotes por meio de pip install:

pip install azure-storage-blob azure-identity

Adicionar instruções de importação

Adicione as seguintes declarações de import :

from azure.identity import DefaultAzureCredential
from azure.storage.blob import (
    BlobServiceClient,
    BlobClient,
)

Autorização

O mecanismo de autorização deve ter as permissões necessárias para executar uma operação de cópia. Para autorização com o Microsoft Entra ID (recomendado), você precisa da função interna de Colaborador de Dados de Blob de Armazenamento ou superior do RBAC do Azure. Para saber mais, consulte as diretrizes de autorização para Colocar blob do URL (API REST) ou Colocar bloco do URL (API REST).

Criar um objeto cliente

Para conectar um aplicativo ao Armazenamento de Blobs, crie uma instância do BlobServiceClient. O exemplo a seguir mostra como criar um objeto cliente usando DefaultAzureCredential para autorização:

# TODO: Replace <storage-account-name> with your actual storage account name
account_url = "https://<storage-account-name>.blob.core.windows.net"
credential = DefaultAzureCredential()

# Create the BlobServiceClient object
blob_service_client = BlobServiceClient(account_url, credential=credential)

Você também pode criar objetos cliente para contêineres ou blobs específicos, diretamente ou do objeto BlobServiceClient. Para saber mais sobre como criar e gerenciar objetos clientes, confira Criar e gerenciar objetos clientes que interagem com recursos de dados.

Sobre a cópia de blobs de um URL de objeto de origem

A operação Put Blob From URL cria um novo blob de blocos em que o conteúdo do blob é lido de um URL específico. A operação é executada de forma síncrona.

A origem pode ser qualquer objeto recuperável por meio de uma solicitação HTTP GET padrão no URL específico. Isso inclui blobs de blocos, blobs de acréscimo, blobs de páginas, instantâneos de blob, versões de blob ou qualquer objeto acessível dentro ou fora do Azure.

Quando o objeto de origem é um blob de blocos, todo o conteúdo do blob confirmado é copiado. O conteúdo do blob de destino é idêntico ao conteúdo da origem, mas a lista de blocos confirmados não é preservada e os blocos não confirmados não são copiados.

O blob de destino é sempre um blob de blocos, podendo ser um blob de blocos existente ou um novo blob de blocos criado pela operação. O conteúdo de um blob existente é substituído pelo conteúdo do novo blob.

A operação Put Blob From URL sempre copia o blob de origem inteiro. Não há suporte para a cópia de um intervalo de bytes ou um conjunto de blocos. Para executar atualizações parciais no conteúdo de um blob de blocos usando um URL de origem, use a API Colocar um Bloco do URL junto com Put Block List.

Para saber mais sobre a operação Put Blob From URL, incluindo limitações de tamanho e considerações de cobrança do blob, confira Comentários sobre Colocar um Blob do URL.

Copiar um blob de um URL de objeto de origem

Esta seção fornece uma visão geral dos métodos fornecidos pela biblioteca de clientes do Armazenamento do Azure para Python para executar uma operação de cópia de uma URL de objeto de origem.

Os métodos a seguir encapsulam a operação de API REST Colocar um Blob do URL e criam um novo blob de blocos em que o conteúdo do blob é lido de um URL específico:

Esses métodos são os preferidos para cenários nos quais você desejar transferir dados para uma conta de armazenamento e tiver um URL para o objeto de origem.

Para objetos grandes, você pode optar por trabalhar com blocos individuais. Os métodos a seguir encapsulam a operação de API REST Colocar um Bloco da URL. Esses métodos criam um novo bloco a ser confirmado como parte de um blob sempre que o conteúdo for lido de uma URL de origem:

Copiar um blob de uma origem no Azure

Se você estiver copiando um blob de uma origem no Azure, o acesso ao blob de origem poderá ser autorizado através do Microsoft Entra ID, de uma assinatura de acesso compartilhado (SAS) ou de uma chave de conta.

O exemplo a seguir mostra um cenário para a cópia de um blob de origem no Azure. O método uploadFromUrl pode, opcionalmente, aceitar um parâmetro booliano para indicar se um blob existente deve ser substituído, conforme mostrado no exemplo.

def copy_from_source_in_azure(self, source_blob: BlobClient, destination_blob: BlobClient):
    # Get the source blob URL and create the destination blob
    # set overwrite param to True if you want to overwrite existing blob data
    destination_blob.upload_blob_from_url(source_url=source_blob.url, overwrite=False)

Copiar um blob de uma origem fora do Azure

Você pode executar uma operação de cópia em qualquer objeto de origem que possa ser recuperado por meio da solicitação HTTP GET em um URL específico, incluindo objetos acessíveis fora do Azure. O exemplo a seguir mostra um cenário para copiar um blob de um URL de objeto de origem acessível.

def copy_from_external_source(self, source_url: str, destination_blob: BlobClient):
    # Create the destination blob from the source URL
    # set overwrite param to True if you want to overwrite existing blob data
    destination_blob.upload_blob_from_url(source_url=source_url, overwrite=False)

Copiar um blob de uma URL de objeto de origem de maneira assíncrona

A biblioteca de clientes do Armazenamento de Blobs do Azure para Python dá suporte à cópia assíncrona de um blob de uma URL de origem. Para saber mais sobre os requisitos de instalação do projeto, confira Programação assíncrona.

Siga estas etapas para copiar um blob de uma URL de objeto de origem usando APIs assíncronas:

  1. Adicione as seguintes instruções de importação:

    import asyncio

from azure.identity.aio import DefaultAzureCredential
from azure.storage.blob.aio import BlobServiceClient, BlobClient

  2. Adicione o código para executar o programa usando asyncio.run. Essa função executa a corrotina passada, main() no nosso exemplo, e gerencia o loop de eventos asyncio. As corrotinas são declaradas com a sintaxe async/await. Neste exemplo, a corrotina main() primeiro cria o BlobServiceClient de nível superior usando async with e, em seguida, chama o método que copia um blob de uma URL de origem. Observe que somente o cliente de nível superior precisa usar async with, pois os outros clientes criados a partir dele compartilham o mesmo pool de conexões.

    async def main():
    sample = BlobCopySamples()

    # TODO: Replace <storage-account-name> with your actual storage account name
    account_url = "https://<storage-account-name>.blob.core.windows.net"
    credential = DefaultAzureCredential()

    async with BlobServiceClient(account_url, credential=credential) as blob_service_client:
        # Copy a blob from one container to another in the same storage account
        source = blob_service_client.get_blob_client(container="source-container", blob="sample-blob.txt")
        destination = blob_service_client.get_blob_client(container="destination-container", blob="sample-blob.txt")
        await sample.copy_from_source_in_azure(source_blob=source, destination_blob=destination)

if __name__ == '__main__':
    asyncio.run(main())

  3. Adicione o código para copiar um blob de uma URL de origem. O exemplo de código a seguir é igual ao exemplo síncrono, com a exceção de que o método é declarado com a palavra-chave async e a palavra-chave await é usada ao chamar o método upload_blob_from_url.

    async def copy_from_source_in_azure(self, source_blob: BlobClient, destination_blob: BlobClient):
    # Get the source blob URL and create the destination blob
    # set overwrite param to True if you want to overwrite existing blob data
    await destination_blob.upload_blob_from_url(source_url=source_blob.url, overwrite=False)

Com essa configuração básica em vigor, você pode implementar outros exemplos neste artigo como corrotinas usando sintaxe a async/await.

Recursos

Para saber mais sobre como copiar blobs usando a biblioteca de clientes do Armazenamento de Blobs do Azure para Python, consulte os recursos a seguir.

Exemplos de código

Operações da API REST

O SDK do Azure para Python contém bibliotecas que criam sobre a API REST do Azure, permitindo a interação com as operações de API REST por meio de paradigmas conhecidos do Python. Os métodos de biblioteca de clientes abordados neste artigo usam as seguintes operações de API REST:

Recursos da biblioteca de clientes

Conteúdo relacionado

  • Este artigo faz parte do guia para desenvolvedores do Armazenamento de Blobs para Python. Para saber mais, veja a lista completa de artigos do guia do desenvolvedor em Criar seu aplicativo Python.