Cómo usar la biblioteca cliente de Python

En este instructivo se describe cómo usar la biblioteca cliente de las API de Google para Python con el fin de llamar a las API de REST de AI Platform en tus aplicaciones de Python. Los fragmentos de código y los ejemplos en el resto de esta documentación usan esta biblioteca cliente de Python.

En este instructivo crearás un modelo en tu proyecto de Google Cloud Platform. Se trata de una tarea simple que se incluye fácilmente en un pequeño ejemplo.

Objetivos

Este es un instructivo básico diseñado para que te familiarices con esta biblioteca cliente de Python. Cuando hayas terminado, deberías poder hacer lo siguiente:

  • Obtener una representación de Python de los servicios de AI Platform
  • Usar esa representación para crear un modelo en tu proyecto, lo que debería ayudarte a comprender cómo llamar a las otras API de administración de trabajos y modelos

Costos

No se te aplicarán cargos por las operaciones en este instructivo. Consulta la página de precios para obtener más información.

Antes de comenzar

Configura tu proyecto de GCP

  1. Accede a tu Cuenta de Google.

    Si todavía no tienes una cuenta, regístrate para obtener una nueva.

  2. Selecciona o crea un proyecto de GCP.

    Ir a la página Administrar recursos

  3. Asegúrate de tener habilitada la facturación para tu proyecto.

    Aprende a habilitar la facturación

  4. Habilita las AI Platform ("Cloud Machine Learning Engine") y Compute Engine API necesarias.

    Habilita las API

  5. Realiza la instalación y la inicialización del SDK de Cloud.

Configura la autenticación

Para configurar la autenticación, debes crear una clave de cuenta de servicio y establecer una variable de entorno para la ruta de acceso del archivo a la clave de la cuenta de servicio.

  1. Crea una clave de cuenta de servicio para la autenticación:
    1. En GCP Console, ve a la página Crear clave de la cuenta de servicio.

      Ir a la página Crear clave de la cuenta de servicio
    2. Desde la lista desplegable de Cuenta de servicio, selecciona Nueva cuenta de servicio.
    3. En el campo Nombre de cuenta de servicio, ingresa un nombre.
    4. En la lista desplegable Función, selecciona Machine Learning Engine > Administrador de ML Engine y Almacenamiento > Administrador de objeto de almacenamiento.

      Nota: El campo Función autoriza el acceso de tu cuenta de servicio a los recursos. Puedes ver y cambiar este campo luego con GCP Console. Si desarrollas una aplicación de producción, es posible que tengas que especificar permisos más detallados que Machine Learning Engine > Administrador de ML Engine y Almacenamiento > Administrador de objeto de almacenamiento. Puedes obtener más información si consultas el control de acceso de AI Platform.
    5. Haz clic en Crear. Se descargará en tu computadora un archivo JSON que contiene tu clave.
  2. Configura la variable de entorno GOOGLE_APPLICATION_CREDENTIALS en la ruta del archivo JSON que contiene la clave de tu cuenta de servicio. Esta variable solo se aplica a tu sesión actual de shell. Por lo tanto, si abres una sesión nueva, deberás volver a configurar la variable.

Configura un entorno de desarrollo de Python

Elige una de las siguientes opciones para configurar tu entorno de manera local en macOS o en un entorno remoto en Cloud Shell.

Para los usuarios de macOS, te recomendamos configurar tu entorno mediante el uso de la pestaña MACOS siguiente. Cloud Shell, que se muestra en la pestaña CLOUD SHELL, está disponible en macOS, Linux y Windows. Cloud Shell proporciona una forma rápida de probar AI Platform, pero no es adecuado para el trabajo de desarrollo continuo.

macOS

  1. Verifica la instalación de Python
    Confirma si tienes Python instalado y, si es necesario, instálalo.

    python -V
  2. Comprueba la instalación de pip
    pip es el administrador de paquetes de Python, y se incluye con las versiones actuales de Python. Comprueba si ya instalaste pip por medio de la ejecución de pip --version. De lo contrario, consulta cómo instalar pip.

    Puedes actualizar pip con el siguiente comando:

    pip install -U pip

    Consulta la documentación de pip para obtener más detalles.

  3. Instala virtualenv
    virtualenv es una herramienta para crear entornos aislados de Python. Para verificar si ya tienes instalado virtualenv, ejecuta virtualenv --version. De lo contrario, instala virtualenv:

    pip install --user --upgrade virtualenv

    Para crear un entorno de desarrollo aislado en esta guía, crea un nuevo entorno virtual en virtualenv. Por ejemplo, el siguiente comando activa un entorno llamado cmle-env:

    virtualenv cmle-env
    source cmle-env/bin/activate
  4. Para los fines de este instructivo, ejecuta el resto de los comandos dentro de tu entorno virtual.

    Consulta más información sobre el uso de virtualenv. Para salir de virtualenv, ejecuta deactivate.

Cloud Shell

  1. Abre Google Cloud Platform Console.

    Google Cloud Platform Console

  2. Haz clic en el botón Activar Cloud Shell en la parte superior de la ventana de la consola.

    Activa Google Cloud Shell

    Se abrirá una sesión de Cloud Shell dentro de un nuevo marco en la parte inferior de la consola que mostrará un mensaje de línea de comandos. La sesión de shell puede tardar unos segundos en inicializar.

    Sesión de Cloud Shell

    Tu sesión de Cloud Shell está lista para usarse.

  3. Configura la herramienta de línea de comandos de gcloud para usar tu proyecto seleccionado.

    gcloud config set project [selected-project-id]

    en el que [selected-project-id] es el ID de tu proyecto. (Omite los corchetes).

Instala la biblioteca cliente de las API de Google para Python

Instala la biblioteca cliente de las API de Google para Python.

Este es un instructivo básico diseñado para que te familiarices con esta biblioteca cliente de Python. Cuando hayas terminado, deberías poder hacer lo siguiente:

  • Obtener una representación de Python de los servicios de AI Platform
  • Usar esa representación para crear un modelo en tu proyecto, lo que debería ayudarte a comprender cómo llamar a las otras API de administración de trabajos y modelos
No se te aplicarán cargos por las operaciones en este instructivo. Consulta la página de precios para obtener más información.

Cómo importar los módulos obligatorios

Cuando desees usar la biblioteca cliente de las API de Google para Python con el fin de llamar a las API de REST de AI Platform en tu código, debes importar su paquete y el paquete OAuth2. Para este instructivo (y en la mayoría de los usos estándar de AI Platform), solo necesitas importar algunos módulos específicos:

Consulta la documentación de esos paquetes para obtener información sobre los otros módulos disponibles.

Crea un archivo nuevo de Python con tu editor favorito y agrega estas líneas:

from oauth2client.client import GoogleCredentials
from googleapiclient import discovery
from googleapiclient import errors

Cómo compilar una representación de Python de la API

Obtén tu representación de Python de la API de REST. El método al que llamas es build porque la biblioteca cliente de la API usa la detección de servicios para configurar dinámicamente las conexiones a los servicios tal y como existen cuando realizas la llamada. Llama a tu objeto que encapsula los servicios ml:

ml = discovery.build('ml','v1')

Cómo configurar tus parámetros y el cuerpo de la solicitud

Para realizar una llamada a un servicio, debes crear los parámetros y el cuerpo de la solicitud que se pasarán a la API de REST. Pasa los parámetros como parámetros regulares de Python al método que representa la llamada. El cuerpo es un recurso JSON tal y como lo usarías si llamaras directamente a la API con una solicitud HTTP.

Consulta la API de REST para crear un modelo en una nueva pestaña del navegador, projects.models.create:

  • Observa la ruta de acceso al parámetro parent, que es la parte del URI de la solicitud que identifica el proyecto. Si estuvieras haciendo la solicitud HTTP POST directamente, usarías el siguiente URI:

    https://ml.googleapis.com/v1/projects/your_project_ID/models
    

    Cuando se usa la biblioteca cliente de la API, la parte variable del URI se representa como un parámetro de tipo string para la llamada a la API. Lo configurarás en 'projects/<var>your_project_ID</var>'. Almacena tu proyecto en una variable para hacer que las llamadas a la API sean más limpias:

    project_id = 'projects/{}'.format('your_project_ID')
    
  • El cuerpo de la solicitud es un recurso JSON que representa la información del modelo. Puedes ver en la definición de recurso del modelo que tiene dos valores para la entrada: nombre y descripción (opcional). Puedes pasar un diccionario de Python en lugar de JSON y la biblioteca cliente de la API realizará la conversión necesaria.

    Crea tu diccionario de Python:

    request_dict = {'name': 'your-model-name',
                   'description': 'This is a machine learning model entry.'}
    

Cómo crear tu solicitud

Hacer llamadas a las API con la biblioteca cliente de Python es un proceso de dos pasos: primero debes crear una solicitud y luego realizar la llamada mediante esa solicitud.

Cómo crear la solicitud

Usa los objetos cliente compilados que creaste antes (si seguiste exactamente el fragmento de código, se llama ml) como la raíz de la jerarquía de la API y especifica la API que deseas usar. Cada colección en la ruta de acceso a la API se comporta como una función que muestra una lista de las colecciones y los métodos que contiene. Por ejemplo, la raíz de todas las API de AI Platform es projects, por lo que tu llamada comienza con ml.projects().

Usa este código para formar tu solicitud:

request = ml.projects().models().create(parent=project_id, body=request_dict)

Envía la solicitud

La solicitud que construiste en el último paso expone un método execute que llamas para enviar la solicitud al servicio:

response = request.execute()

Es común que los desarrolladores combinen este paso con el último:

response = ml.projects().models().create(parent=project_id,
                                         body=request_dict).execute()

Controla errores simples

Muchos aspectos pueden salir mal cuando haces llamadas a la API a través de Internet. Conviene controlar los errores comunes. La forma más sencilla de abordar los errores es poner tu solicitud en un bloque de try y detectar posibles errores. La mayoría de los errores que probablemente recibas del servicio son errores HTTP, que se encapsulan en la clase HttpError. Para detectar estos errores, usa el módulo de errors del paquete googleapiclient.

Une tu llamada a request.execute() en un bloque try. También pon una declaración de print en el bloque, de modo que intentes imprimir la respuesta solo si la llamada se realiza correctamente:

try:
    response = request.execute()
    print(response)

Agrega un bloque de captura para controlar los errores HTTP. Puedes usar HttpError._get_reason() para obtener los campos de texto de la razón de la respuesta:

except errors.HttpError, err:
    # Something went wrong, print out some information.
    print('There was an error creating the model. Check the details:')
    print(err._get_reason())

Por supuesto, una simple declaración impresa podría no ser el enfoque correcto para tu aplicación.

Revisión general

Aquí está el ejemplo completo:

from googleapiclient import discovery
from googleapiclient import errors

# Store your full project ID in a variable in the format the API needs.
project_id = 'projects/{}'.format('your_project_ID')

# Build a representation of the Cloud ML API.
ml = discovery.build('ml', 'v1')

# Create a dictionary with the fields from the request body.
request_dict = {'name': 'your_model_name',
               'description': 'your_model_description'}

# Create a request to call projects.models.create.
request = ml.projects().models().create(
              parent=project_id, body=request_dict)

# Make the call.
try:
    response = request.execute()
    print(response)
except errors.HttpError, err:
    # Something went wrong, print out some information.
    print('There was an error creating the model. Check the details:')
    print(err._get_reason())

Cómo generalizar a otros métodos

Puedes usar el procedimiento que aprendiste aquí para realizar cualquiera de las otras llamadas a la API de REST. Algunas de las API requieren recursos JSON mucho más complicados que la creación de un modelo, pero los principios son los mismos:

  1. Importa googleapiclient.discovery y googleapiclient.errors.

  2. Usa el módulo de descubrimiento para compilar una representación de Python de la API.

  3. Usa la representación de la API como una serie de objetos anidados para obtener la API que deseas y crear una solicitud. Por ejemplo,

    request = ml.projects().models().versions().delete(
        name='projects/myproject/models/mymodel/versions/myversion')
    
  4. Llama a request.execute() para enviar la solicitud y controla las excepciones de manera adecuada en tu aplicación.

  5. Cuando hay un cuerpo de respuesta, puedes tratarlo como un diccionario de Python para acceder a los objetos JSON especificados en la referencia de la API. Ten en cuenta que muchos de los objetos en las respuestas tienen campos que están presentes solo en algunas circunstancias. Siempre debes comprobar para evitar errores clave:

    response = request.execute()
    
    some_value = response.get('some_key') or 'default_value'
    

Pasos siguientes

¿Te sirvió esta página? Envíanos tu opinión:

Enviar comentarios sobre…

Cloud ML Engine para TensorFlow