Muestra de App Engine y Google Cloud Storage

ID de región

REGION_ID es un código abreviado que Google asigna en función de la región que seleccionas cuando creas la app. El código no corresponde a un país ni a una provincia, aunque algunos ID de región puedan parecer similares a los códigos de país y provincia que se suelen usar. En el caso de las apps creadas después de febrero de 2020, REGION_ID.r se incluye en las URL de App Engine. En el caso de las apps existentes creadas antes de esta fecha, el ID de región es opcional en la URL. Obtén más información acerca de los ID de región.

Aprende cómo habilitar el acceso de Cloud Storage a tu app de Python en App Engine y cómo crear, escribir, leer y enumerar archivos en el bucket de Cloud Storage.

En el instructivo, suponemos que estás familiarizado con Python y que ya configuraste tu entorno de desarrollo.

Cuando se ejecuta esta muestra, se ejecuta una secuencia de comandos y se escribe el resultado en el navegador. La secuencia de comandos muestra las siguientes funciones de la biblioteca cliente de Cloud Storage:

  • Crear un archivo y escribirlo en un bucket
  • Leer el archivo y obtener los metadatos
  • Crear varios archivos y, luego, enumerarlos desde el bucket
  • Enumerar los archivos que se acaban de agregar al bucket
  • Leer ese mismo conjunto de archivos
  • Borrar ese conjunto de archivos

Objetivos

  • Describir el proyecto de Python para ver el diseño y los archivos requeridos
  • Entender el código para conectarse a Cloud Storage
  • Entender el código para crear, escribir, leer, enumerar y borrar archivos
  • Entender el código para los reintentos
  • Compilar y probar la app en tu servidor de desarrollo local
  • Implementar la app para la producción en Google App Engine

Costos

App Engine tiene un nivel de uso gratuito. Si el uso total de App Engine es menor que los límites especificados en la cuota gratuita de App Engine, no se aplican cargos por este instructivo.

Antes de comenzar

Antes de ejecutar esta muestra, necesitas un ID del proyecto, la herramienta de línea de comandos de gcloud y un bucket de Cloud Storage:

  1. Crea un proyecto nuevo de la consola de Google Cloud o recupera el ID del proyecto existente desde la consola de Google Cloud:

    Ir a la página Proyectos

  2. Instala y, luego, inicializa la CLI de Google Cloud:

    Descarga el SDK

  3. Activa el bucket predeterminado de Cloud Storage.

Clona el proyecto del instructivo

Para clonar el proyecto, sigue estos pasos:

  1. Clona la biblioteca cliente y la app de muestra (demostración) en tu máquina local.

    git clone https://github.com/GoogleCloudPlatform/python-docs-samples

    Como alternativa, puedes descargar la muestra como un archivo ZIP y extraerla.

  2. Navega al directorio correspondiente en el proyecto clonado o descargado:

    cd python-docs-samples/appengine/standard/storage/appengine-client

Instala dependencias

La herramienta virtualenv te permite crear un entorno de Python limpio en tu sistema. Para el desarrollo de App Engine, esto ayuda a garantizar que el código que pruebes de forma local sea similar al entorno en el que se implementará el código. Para obtener más información, consulta Usa bibliotecas de terceros.

Para instalar virtualenv y las dependencias de muestra, sigue estos pasos:

macOS/Linux

  1. Si no tienes virtualenv, instálalo en todo el sistema mediante pip.
    sudo pip install virtualenv
  2. Crea un entorno aislado de Python: 
    virtualenv env
source env/bin/activate
  3. Si no estás en el directorio que contiene el código de muestra, navega al directorio que contiene el código de muestra hello_world. Luego, instala las dependencias: 
    cd YOUR_SAMPLE_CODE_DIR
pip install -t lib -r requirements.txt

Windows

Si tienes Google Cloud CLI instalado, también deberías tener instalado Python 2.7, por lo general, en C:\python27_x64\ (para sistemas de 64 bits). Usa PowerShell para ejecutar tus paquetes de Python.

  1. Ubica la instalación de PowerShell.
  2. Haz clic derecho en el acceso directo a PowerShell y, luego, inícialo como administrador.
  3. Intenta ejecutar el comando python. Si no se encuentra, agrega la carpeta de Python a la PATH de tu entorno. 
    $env:Path += ";C:\python27_x64\"
  4. Si no tienes virtualenv, instálalo en todo el sistema mediante pip:
    python -m pip install virtualenv
  5. Crea un entorno de Python aislado. 
    python -m virtualenv env
. env\Scripts\activate
  6. Navegue al directorio del proyecto e instale las dependencias. Si no estás en el directorio que contiene el código de muestra, navega al directorio que contiene el código de muestra hello_world. Luego, instala las dependencias: 
    cd YOUR_SAMPLE_CODE_DIR
python -m pip install -t lib -r requirements.txt

El código de muestra que clonaste o descargaste ya contiene un archivo appengine_config.py, que se necesita para indicarle a App Engine que use la carpeta lib a fin de cargar las dependencias de forma local y cuando se implementen.

Ejecuta de manera local

Para ejecutar la muestra de forma local, haz lo siguiente:

  1. En el subdirectorio del proyecto python-docs-samples/appengine/standard/storage/appengine-client, ejecuta la app en el servidor de desarrollo local:

    python3 CLOUD_SDK_ROOT/bin/dev_appserver.py .

  2. Espera el mensaje de operación correcta, que debería verse de la siguiente manera:

    INFO     2016-04-12 21:33:35,446 api_server.py:205] Starting API server at: http://localhost:36884
INFO     2016-04-12 21:33:35,449 dispatcher.py:197] Starting module "default" running at: http://localhost:8080
INFO     2016-04-12 21:33:35,449 admin_server.py:116] Starting admin server at: http://localhost:8000

  3. Visita esta URL en el navegador:

    http://localhost:8080/

    La aplicación se ejecutará cuando se carga la página y mostrará el resultado al navegador para indicar lo que se ejecutó. El resultado se verá así:

    Hello_Storage

  4. Presiona Control+C para detener el servidor de desarrollo.

Explicación de app.yaml

El archivo app.yaml especifica los detalles de configuración de la aplicación:

appengine/standard/storage/appengine-client/app.yaml 
runtime: python27
api_version: 1
threadsafe: yes

env_variables:

handlers:
- url: /blobstore.*
  script: blobstore.app

- url: /.*
  script: main.app

Para obtener más información sobre las opciones de configuración disponibles en este archivo, consulta la referencia de app.yaml.

Explicación de las importaciones

El archivo main.py contiene las importaciones típicas que se usan para acceder a Cloud Storage a través de la biblioteca cliente:

appengine/standard/storage/appengine-client/main.py 
import os

import cloudstorage
from google.appengine.api import app_identity

import webapp2

Necesitas el módulo os y la API de app_identity para obtener el nombre del bucket predeterminado en el entorno de ejecución. Necesitarás este nombre del bucket para todas las operaciones de acceso de Cloud Storage.

La muestra también usa el framework web webapp2.

Especifica el bucket de Cloud Storage

Antes de realizar cualquier operación en Cloud Storage, debes proporcionar el nombre del bucket. La forma más fácil de hacer esto es con el bucket predeterminado para tu proyecto, el que puedes obtener de la siguiente manera:

appengine/standard/storage/appengine-client/main.py 
def get(self):
    bucket_name = os.environ.get(
        'BUCKET_NAME', app_identity.get_default_gcs_bucket_name())

    self.response.headers['Content-Type'] = 'text/plain'
    self.response.write(
        'Demo GCS Application running from Version: {}\n'.format(
            os.environ['CURRENT_VERSION_ID']))
    self.response.write('Using bucket name: {}\n\n'.format(bucket_name))

Escribe un archivo en Cloud Storage

En el siguiente ejemplo, se muestra como escribir en el bucket:

appengine/standard/storage/appengine-client/main.py 
def create_file(self, filename):
    """Create a file."""

    self.response.write('Creating file {}\n'.format(filename))

    # The retry_params specified in the open call will override the default
    # retry params for this particular file handle.
    write_retry_params = cloudstorage.RetryParams(backoff_factor=1.1)
    with cloudstorage.open(
        filename, 'w', content_type='text/plain', options={
            'x-goog-meta-foo': 'foo', 'x-goog-meta-bar': 'bar'},
            retry_params=write_retry_params) as cloudstorage_file:
                cloudstorage_file.write('abcde\n')
                cloudstorage_file.write('f'*1024*4 + '\n')
    self.tmp_filenames_to_clean_up.append(filename)

Ten en cuenta que en la llamada para open (abrir) el archivo en el que deseas escribir, el ejemplo especifica determinados encabezados de Cloud Storage que escriben metadatos personalizados del archivo. Estos metadatos se pueden recuperar mediante cloudstorage.stat. Puedes encontrar la lista de encabezados compatibles en la referencia de cloudstorage.open.

También, ten en cuenta que no se configuró el encabezado x-goog-acl. Esto significa que la LCA predeterminada de Cloud Storage de lectura pública se aplicará al objeto cuando se escriba en el bucket.

Por último, observa la llamada para close (cerrar) el archivo después de terminar la escritura. Si no lo haces, el archivo no se escribirá en Cloud Storage. Ten en cuenta que después de llamar a close, no puedes agregar el archivo. Si necesitas modificar un archivo, tienes que abrirlo de nuevo en modo de escritura, lo cual reemplaza el archivo, no lo agrega.

Lee un archivo desde Cloud Storage

En el siguiente ejemplo, se muestra cómo leer un archivo del bucket:

appengine/standard/storage/appengine-client/main.py 
def read_file(self, filename):
    self.response.write(
        'Abbreviated file content (first line and last 1K):\n')

    with cloudstorage.open(filename) as cloudstorage_file:
        self.response.write(cloudstorage_file.readline())
        cloudstorage_file.seek(-1024, os.SEEK_END)
        self.response.write(cloudstorage_file.read())

En la muestra, se indica cómo mostrar las líneas seleccionadas del archivo que se lee, en este caso, la línea de apertura y las últimas 1,000 líneas, mediante seek.

Ten en cuenta que no se especifica ningún modo en el código anterior cuando el archivo está abierto como lectura. La opción predeterminada para open es el modo de solo lectura.

Enumera el contenido del bucket

En el código de muestra, se indica cómo desplazarse por un bucket con una gran cantidad de archivos. A fin de desplazarse por una lista de contenidos del bucket, usa los parámetros marker y max_keys:

appengine/standard/storage/appengine-client/main.py 
def list_bucket(self, bucket):
    """Create several files and paginate through them."""

    self.response.write('Listbucket result:\n')

    # Production apps should set page_size to a practical value.
    page_size = 1
    stats = cloudstorage.listbucket(bucket + '/foo', max_keys=page_size)
    while True:
        count = 0
        for stat in stats:
            count += 1
            self.response.write(repr(stat))
            self.response.write('\n')

        if count != page_size or count == 0:
            break
        stats = cloudstorage.listbucket(
            bucket + '/foo', max_keys=page_size, marker=stat.filename)

Ten en cuenta que el nombre completo del archivo se muestra como una string sin delimitadores de directorio. Si deseas mostrar el archivo con su jerarquía de directorios más reconocible, establece el parámetro delimiter en el delimitador del directorio que deseas usar.

Borra archivos

En la muestra de código, se muestran los archivos que se borraron, en este caso, la eliminación de todos los archivos agregados durante la ejecución de la aplicación. No debes hacerlo en tu código, ya que esta es solo una función de limpieza de esta muestra:

appengine/standard/storage/appengine-client/main.py 
def delete_files(self):
    self.response.write('Deleting files...\n')
    for filename in self.tmp_filenames_to_clean_up:
        self.response.write('Deleting file {}\n'.format(filename))
        try:
            cloudstorage.delete(filename)
        except cloudstorage.NotFoundError:
            pass

Implementa la muestra

Para implementar y ejecutar la muestra en App Engine, sigue estos pasos:

  1. Para subir la app de muestra, ejecuta el siguiente comando desde el directorio python-docs-samples/appengine/standard/storage/appengine-client donde se encuentra el archivo app.yaml:

    gcloud app deploy

    Marcas opcionales:

    • Incluye la marca --project para especificar un ID del proyecto alternativo de la consola de Google Cloud al que inicializaste como predeterminado en la CLI de gcloud. Ejemplo: --project [YOUR_PROJECT_ID]
    • Incluye el marcador -v para especificar un ID de versión; de lo contrario, se generará uno automáticamente. Ejemplo: -v [YOUR_VERSION_ID]

  2. Cuando se complete el proceso de implementación, puedes ver la aplicación en https://PROJECT_ID.REGION_ID.r.appspot.com si ejecutas el siguiente comando:

    gcloud app browse

    La app de demo se ejecuta cuando cargas la página, de igual forma que cuando la ejecutaste de forma local. Sin embargo, ahora la app escribirá y leerá desde el bucket de Cloud Storage.

Para obtener más información acerca de cómo implementar la app desde la línea de comandos, consulta Implementa una app de Python 2.

¿Qué sigue?