Python 2 ya no es compatible con la comunidad. Te recomendamos que migres las apps de Python 2 a Python 3.

Muestra de App Engine y Google Cloud Storage

ID de la región

REGION_ID es un código abreviado que Google asigna en función de la región que seleccionas cuando creas tu app. El código no corresponde a un país o provincia, aunque algunos ID de región puedan parecer similares a los códigos de país y provincia de uso común. Incluir REGION_ID.r en las URL de App Engine es opcional para las apps existentes, y pronto será obligatorio para todas las apps nuevas. A fin de garantizar una transición sin problemas, estamos actualizando App Engine con lentitud para usar los ID de región. Si aún no actualizamos tu proyecto de Google Cloud, no verás un ID de región para la app. Dado que el ID es opcional para las apps existentes, no necesitas actualizar las URL ni realizar otros cambios una vez que el ID de región esté disponible para las apps existentes. Obtén más información acerca de los ID de región.

Aprende cómo habilitar el acceso en Cloud Storage a tu aplicación Python en App Engine y a crear, escribir, leer y mostrar archivos en el depósito de Cloud Storage.

En el instructivo, se supone que estás familiarizado con Python y que 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 características de la biblioteca cliente de Cloud Storage:

  • Crear un archivo y escribir el archivo al depósito.
  • Leer el archivo y obtener sus metadatos.
  • Crear varios archivos y, luego, mostrarlos desde el depósito.
  • Mostrar los archivos recientemente agregados al depósito.
  • Leer ese mismo conjunto de archivos
  • Borrar ese conjunto de archivos.

Objetivos

  • Recorrer el proyecto en Pyhton para ver el diseño obligatorio y los archivos
  • Entender el código para conectarse a Cloud Storage
  • Entender el código para crear, escribir, leer, mostrar y eliminar archivos
  • Entender el código para 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 depósito de Cloud Storage:

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

    Ir a la página Proyectos

    Sugerencia: Recupera una lista de tus ID de proyectos existentes con la herramienta de línea de comandos de gcloud.

  2. Instala y, luego, inicializa el SDK de Google Cloud:

    Descargar el SDK

  3. Activa el depósito de Cloud Storage predeterminado.

Clona el proyecto del instructivo

Para clonar el proyecto, haz lo siguiente:

  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
    

    De manera opcional, 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 la 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 en un directorio externo al proyecto y actívalo:
    virtualenv env
    source env/bin/activate
  3. Navega al directorio del proyecto y, luego, instala las dependencias:
    cd YOUR_PROJECT
    pip install -t lib -r requirements.txt

Windows

Si tienes el SDK de Cloud 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 aislado de Python en un directorio externo al proyecto y actívalo:
    python -m virtualenv env
    env\Scripts\activate
  6. Navega al directorio del proyecto y, luego, instala las dependencias:
    cd YOUR_PROJECT
    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, necesario para indicarle a App Engine que use la carpeta lib para cargar las dependencias de forma local y cuando se implementen.

Ejecución 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]:

    dev_appserver.py .
    
  2. Espera el mensaje de éxito, 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 tu 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ó. La salida obtenida 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:

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 utilizadas para acceder a Cloud Storage a través de la biblioteca cliente:

import os

import cloudstorage
from google.appengine.api import app_identity

import webapp2

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

La muestra también usa el framework web webapp2.

Cómo especificar el depósito de Cloud Storage

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

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

Cómo escribir un archivo en Cloud Storage

En el siguiente ejemplo, se muestra como escribir en el depósito:

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 open para abrir el archivo que deseas escribir, la ejemplo especifica ciertos 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 de Cloud Storage predeterminada de lectura pública se aplicará al objeto cuando se escriba en el depósito.

Por último, observa la llamada para close 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 adjuntar el archivo. Si necesitas modificar un archivo, deberás abrirlo de nuevo en modo de escritura, lo cual reemplaza el archivo, no lo adjunta.

Cómo leer un archivo desde Cloud Storage

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

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())

El ejemplo ilustra 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. El valor predeterminado para open es el modo de solo lectura.

Cómo enumerar el contenido del depósito

El código de muestra representa cómo desplazarse por un depósito con una gran cantidad de archivos mediante los parámetros marker y max_keys para desplazarse por una lista de contenidos del depósito:

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 quieres mostrar el archivo con su jerarquía de directorios más reconocible, establece el parámetro delimiter en el delimitador de directorio que deseas utilizar.

Borra archivos

La muestra de código muestra las eliminaciones de archivos, en este caso, la eliminación de todos los archivos agregados durante la ejecución de la aplicación. No lo harías en tu código, ya que esta es solo una función de limpieza de esta muestra:

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 aplicación 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 de Cloud Console alternativo al proyecto que inicializaste como predeterminado en la herramienta 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]

    Sugerencia: Si especificas un ID de versión de una aplicación que se subió antes, tu implementación reemplazará la versión existente en App Engine. Esto no siempre es conveniente, en especial, si la versión de App Engine entrega tráfico. Para evitar interrumpir el tráfico a tu aplicación, puedes implementarla con un ID de versión distinto y, luego, mover el tráfico a esa versión. Para obtener más información sobre cómo mover el tráfico, consulta divide el tráfico.

  2. Una vez completado 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, al igual que cuando la ejecutaste de forma local. Sin embargo, ahora la app escribirá y leerá desde tu depósito de Cloud Storage.

Para obtener más información acerca de cómo implementar tu aplicación desde la línea de comandos, consulta la página sobre cómo implementar una aplicación de Python 2.

Qué sigue