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.

Exemplos de código:

Operações básicas de armazenamento usando as APIs do App Engine
Operações básicas de armazenamento usando a biblioteca de cliente do Cloud para Cloud Storage

Antes de começar a migração

Se você ainda não tiver feito isso, configure o ambiente de desenvolvimento do Python para usar uma versão do Python compatível com o Google Cloud e instale ferramentas de teste para criar Python isolado.

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

Por padrão, a conta de serviço padrão criada automaticamente 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:

Instale a biblioteca de cliente do Cloud para Cloud Storage.
Atualize seu código para usar a biblioteca de cliente do Cloud.
Teste as atualizações.
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:

Atualize o arquivo app.yaml:
1. Se você usa as bibliotecas de cliente do Cloud, adicione as versões mais recentes das bibliotecas grpcio e setuptools.
2. Adicione a biblioteca ssl, já que isso é exigido pelo Cloud Storage.
A seguir, um exemplo de arquivo app.yaml:
```
runtime: python27
threadsafe: yes
api_version: 1

libraries:
- name: grpcio
  version: 1.0.0
- name: setuptools
  version: 36.6.0
- name: ssl
  version: latest
```
Algumas bibliotecas de cliente não precisam da biblioteca SSL. Se você não incluir a biblioteca SSL para uma biblioteca de cliente que precisa dela, verá um erro SSL no Análise de registros quando o aplicativo receber uma solicitação.
Atualize o arquivo requirements.txt adicionando as bibliotecas de cliente do Cloud para o Cloud Storage à lista de dependências:
```
google-cloud-storage==1.24.1
```
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.

Em seguida, execute pip install -t lib -r requirements.txt para atualizar a lista de bibliotecas disponíveis para seu app.
Para apps do Python 2, se o app estiver usando bibliotecas integradas ou copiadas, você precisa especificar esses caminhos no arquivo 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. Exemplo:
```
import os
path = os.path.join(os.path.dirname(os.path.realpath(__file__)), 'lib')
```

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_from_string` Veja um exemplo 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 um exemplo de código.
Ler a partir do armazenamento	`blob.download_to_file` `blob.download_to_filename` `blob.download_as_string` Veja um exemplo de código.
Excluir um objeto	`blob.delete` Veja um exemplo de código.
Copiar um objeto	`bucket.copy_blob` Veja um exemplo de código.
Ler metadados de um objeto	`blob.propertyname` e `blob.metadata` Veja um exemplo 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á:

Teste o aplicativo no App Engine.
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.