O Python 2 não é mais compatível com a comunidade. Recomendamos que você migre aplicativos do Python 2 para o Python 3.

Como migrar para a biblioteca de cliente do Cloud para o Storage

O Cloud Storage permite que o aplicativo exiba objetos de dados grandes, como arquivos de vídeo ou imagem, e permite que os usuários façam upload de arquivos de dados grandes. No ambiente de execução do Python 2, o Google App Engine fornece sua própria biblioteca de cliente para escrever e ler objetos no Cloud Storage. Essa biblioteca do App Engine não está disponível em ambientes de execução mais recentes, incluindo o ambiente de execução do Python 3.

Caso seu aplicativo Python 2 use a biblioteca GoogleAppEngineCloudStorageClient, migre para a biblioteca do Cloud Storage antes de executar o aplicativo no ambiente de execução do Python 3. Você só precisa migrar seu aplicativo para usar uma nova biblioteca de cliente. Todos os objetos de dados e permissões nos buckets do Cloud Storage permanecem inalterados, e é possível acessar seus buckets usando a nova biblioteca de cliente.

Comparação entre as bibliotecas de cliente do App Engine e do Cloud

Semelhanças:

  • A biblioteca de cliente do Cloud é compatível com todos os recursos do Cloud Storage ativados pela biblioteca de cliente do App Engine, como leitura, gravação, remoção e listagem de objetos. A migração deve exigir apenas pequenas alterações no código.

    A biblioteca de cliente do Google Cloud também é compatível com recursos adicionais, como a criação e rotulagem de buckets, além de recuperar versões mais antigas de objetos.

Diferenças:

  • Na biblioteca do App Engine, a função que recupera uma lista de objetos funciona de maneira assíncrona. A biblioteca de cliente do Cloud não fornece uma função assíncrona para listar objetos, embora você possa usar paginação e iterar por meio de um pequeno conjunto de objetos.

  • A biblioteca de cliente do App Engine exige o uso de listas de controle de acesso (ACL) para controlar o acesso a blocos e objetos. No entanto, o Cloud Storage e a biblioteca de cliente do Cloud aceitam dois sistemas para conceder aos usuários permissão para acessar seus buckets e objetos: ACLs e acesso uniforme no nível do bucket. O acesso uniforme no nível do bucket oferece uma experiência de controle de acesso mais simples e consistente em todos os seus recursos do Cloud.

    Todas as ACLs usadas com a biblioteca de cliente do App Engine permanecem em vigor para os buckets existentes após a migração para a biblioteca de cliente do Cloud e você pode continuar usando ACLs, se necessário.

    Se o acesso uniforme no nível do bucket atender às suas necessidades, recomendamos que você use esse sistema mais simples para os novos buckets criados. Embora seja possível converter buckets existentes para usar o acesso uniforme no nível do bucket, isso pode exigir alterações significativas na forma como o aplicativo protege o acesso aos objetos de armazenamento.

Amostras de código:

Antes de começar a migração

Noções básicas sobre as permissões do Cloud Storage

Por padrão, a conta de serviço padrão do app tem privilégios de leitura e gravação nos buckets do projeto e tem direitos totais sobre os objetos criados antes e depois da migração.

Se você usou uma conta de serviço ou de usuário diferente para proteger o acesso aos buckets e objetos do Cloud Storage, continue usando as mesmas contas e técnicas de autenticação antes e depois da migração.

Visão geral do processo de migração

Para migrar seu aplicativo Python para usar a biblioteca de cliente do Cloud para Cloud Storage em vez da biblioteca de cliente do App Engine:

  1. Instale a biblioteca de cliente do Cloud para Cloud Storage.

  2. Atualize seu código para usar a biblioteca de cliente do Cloud.

  3. Teste as atualizações.

  4. Implante o aplicativo no App Engine.

Como instalar a biblioteca de cliente do Cloud para Cloud Storage

Para disponibilizar a biblioteca de cliente do Cloud para Cloud Storage em seu aplicativo quando ele for executado no App Engine:

  1. Crie um arquivo requirements.txt na mesma pasta do app.yaml e adicione as seguintes linhas:

     google-cloud-storage==1.24.1
     googleapis_common_protos
    

    Recomendamos que você use a versão 1.24.1 da biblioteca de cliente do Cloud Storage porque ela é compatível com aplicativos Python 2.7.

    É necessário googleapis_common_protos para os aplicativos Python 2 acessarem os serviços do Google Cloud.

  2. No arquivo app.yaml do app, especifique as bibliotecas RPC e SSL do Google na seção libraries:

    libraries:
    - name: grpcio
      version: 1.0.0
    - name: ssl
      version: latest
    
  3. Crie um diretório para armazenar bibliotecas de terceiros, como lib/. Em seguida, use pip install para instalar as bibliotecas no diretório. Por exemplo:

      pip install -t lib -r requirements.txt
      

  4. Crie um arquivo appengine_config.py na mesma pasta que seu arquivo app.yaml. Adicione a instrução a seguir ao seu arquivo appengine_config.py:

    # appengine_config.py
    import pkg_resources
    from google.appengine.ext import vendor
    
    # Set path to your libraries folder.
    path = 'lib'
    # Add libraries installed in the path folder.
    vendor.add(path)
    # Add libraries to pkg_resources working set to find the distribution.
    pkg_resources.working_set.add_entry(path)
    

    O arquivo appengine_config.py no exemplo anterior pressupõe que a pasta lib está localizada no diretório de trabalho atual. Se não for possível garantir que lib estará sempre no diretório de trabalho atual, especifique o caminho completo para a pasta lib. Por exemplo:

    import os
    path = os.path.join(os.path.dirname(os.path.realpath(__file__)), 'lib')
    

Para desenvolvimento local, recomendamos que você instale dependências em um ambiente virtual, como o virtualenv para Python 2.

Como atualizar seu código para usar a biblioteca de cliente do Cloud

Como criar um cliente do Cloud Storage

Para usar a biblioteca de cliente do Cloud para Cloud Storage, crie um objeto Client. O cliente contém credenciais e outros dados necessários para se conectar ao Cloud Storage. Por exemplo:

from google.cloud import storage

client = storage.Client()

No cenário de autorização padrão descrito anteriormente, o cliente do Cloud Storage contém credenciais da conta de serviço padrão do App Engine, que está autorizada a interagir com os buckets e objetos do seu projeto. Se você não estiver trabalhando nesse cenário padrão, consulte Application Default Credentials (ADC) para informações sobre como fornecer credenciais.

Como usar os métodos da biblioteca de cliente do Cloud

A tabela a seguir resume os métodos da biblioteca de cliente do Cloud a serem usados ao implementar recursos específicos do Cloud Storage.

Recurso do Cloud Storage Métodos de cliente do Cloud
Listar objetos em um bucket Client.list_blobs

Veja um exemplo de código simples e um exemplo de modo de diretório de emulação.

Para percorrer a lista de objetos, use a propriedade pages do objeto iterador que Client.list_blobs retorna.

Gravar no armazenamento blob.upload_from_file
blob.upload_from_filename
blob.upload_as_string

Veja uma amostra de código.

Especificar ACLs Para aplicar uma ACL predefinida, use o predefined_acl parâmetro quando você criar um bucket ou criar um objeto.

Para um controle mais minucioso, use bucket.acl.reload() ou blob.acl.reload() para recuperar as ACLs definidas atualmente. Em seguida, use os métodos ACL para adicionar ou remover ACLs. Veja uma amostra de código.

Ler a partir do armazenamento blob.download_to_file
blob.download_to_filename
blob.download_as_string

Veja uma amostra de código.

Excluir um objeto blob.delete

Veja uma amostra de código.

Copiar um objeto bucket.copy_blob

Veja uma amostra de código.

Ler metadados de um objeto blob.propertyname
e
blob.metadata

Veja uma amostra de código.

Como testar suas atualizações

É possível testar as atualizações do aplicativo em um ambiente local, mas todas as solicitações do Cloud Storage precisam ser enviadas pela Internet para um bucket real do Cloud Storage. Nem o App Engine nem o Cloud Storage fornecem um emulador do Cloud Storage.

Para obter mais informações sobre como testar aplicativos do Python 2, consulte Como usar o servidor de desenvolvimento local.

Para mais informações sobre como testar aplicativos Python 3, consulte Como testar e implantar seu aplicativo.

Implantar o app

Quando estiver pronto para implantar o aplicativo, você deverá:

  1. Teste o aplicativo no App Engine.

  2. Se o aplicativo for executado sem erros, use a divisão de tráfego para aumentar gradualmente o tráfego de seu aplicativo atualizado. Monitore de perto o aplicativo em busca de problemas antes de direcionar mais tráfego para o aplicativo atualizado.