Compila una biblioteca cliente

Introducción

Puedes usar el servicio de descubrimiento de API de Google para crear una variedad de herramientas diferentes para usar con las API de Google. Sin embargo, el objetivo principal del documento de descubrimiento es permitir que Google cree bibliotecas cliente en varios lenguajes de programación. En esta sección, se describe cómo compilar una biblioteca cliente personalizada para las API de Google.

Una biblioteca cliente estable y con funciones completas es una herramienta complicada que puede tardar meses en desarrollarse. Sin embargo, las instrucciones generales para crear una biblioteca cliente simple para las API de Google se pueden dividir en tres pasos simples:

  1. Recupera el documento de descubrimiento y construye la superficie de la API
  2. Cómo redactar una solicitud
  3. Realizar una llamada y obtener la respuesta

Estos pasos se describen con más detalle en las siguientes secciones. También puede consultar el ejemplo de cliente de API simples en la sección de ejemplos para ver cómo se asignan estas instrucciones al código.

Paso 1: Obtén el documento de descubrimiento

Antes de comenzar a implementar una biblioteca cliente, existen algunos requisitos básicos que influyen en cómo procederás en tu ruta de desarrollo. Por ejemplo, el lenguaje de programación que elijas puede ser de tipo o no escrito; si se escribe, puede ser estático o dinámico. Se puede compilar o interpretar. Estos requisitos guiarán tu enfoque para consumir y usar el documento de descubrimiento.

La primera tarea de desarrollo es recuperar el documento de descubrimiento. Su estrategia para saber exactamente cuándo se debe recuperar el documento depende de los requisitos que identificó. Por ejemplo, en un lenguaje de tipo estático, puedes recuperar el documento de descubrimiento al comienzo del proceso y, luego, generar código para controlar la API específica que se describe en el documento de descubrimiento. Para un lenguaje de tipo fuerte, puedes generar código y compilar una biblioteca compilada. En el caso de un lenguaje escrito dinámicamente, puedes construir de manera diferida las estructuras de programación para interactuar con la API en el momento, a medida que se usa la superficie de programación.

Paso 2: Redacta una solicitud

La composición de una solicitud implica dos pasos independientes:

  1. Composición del cuerpo de la solicitud
  2. Crea la URL de la solicitud.

Debes convertir el cuerpo de la solicitud, si lo hubiera, de una representación apropiada para el idioma al formato de conexión correcto. Por ejemplo, en una biblioteca cliente de Java, puede haber una clase para cada tipo de solicitud que permita la manipulación segura de los datos de la solicitud y se pueda serializar en JSON.

La construcción de la URL de solicitud es un proceso un poco más complicado.

La propiedad path de cada método en la API usa la sintaxis de la plantilla de URI v04. Esta propiedad puede contener variables entre llaves. A continuación, se muestra un ejemplo de una propiedad path con variables:

/example/path/var

En la ruta anterior, var es una variable. El valor de esta variable proviene de la sección parameters del documento discovery para ese método. Cada nombre de variable tiene un valor correspondiente en el objeto parameters. En el ejemplo anterior, hay un parámetro llamado var en la sección parameters (y su propiedad location es path, para indicar que es una variable de ruta de acceso).

Cuando realices una solicitud, debes sustituir el valor de var en la URL. Por ejemplo, si el usuario de la biblioteca realiza una elección que establece var en el valor foo, la URL nueva será /example/path/foo.

Además, ten en cuenta que la propiedad path es un URI relativo. Para calcular el URI absoluto, sigue estos pasos:

  1. Obtén la propiedad rootUrl del nivel superior del documento de descubrimiento.
    Por ejemplo, la propiedad rootUrl en el documento de descubrimiento para la API de Google Cloud Service Management es la siguiente:

    https://servicemanagement.googleapis.com/

  2. Obtén la servicePath del nivel superior del documento de descubrimiento.
    Por ejemplo, la propiedad servicePath en el documento de descubrimiento para la API de Google Cloud Service Management está vacía.

  3. Concatenarlos para obtener:

    https://servicemanagement.googleapis.com/

  4. Toma la propiedad path, expándela como una plantilla de URI y combina los resultados de esa expansión con el URI del paso anterior.
    Por ejemplo, en el método de servicio get de la API de Google Cloud Service Management, el valor de la propiedad path es v1/services/{serviceName}. Por lo tanto, el URI completo del método es el siguiente:

    https://servicemanagement.googleapis.com/v1/services/{serviceName}

Se requiere una clave de API para llamar a la API de Google Cloud Service Management. Por lo tanto, después de aplicar una clave de API, el URI completo para obtener la definición del servicio del servicio de descubrimiento de API es el siguiente:

https://servicemanagement.googleapis.com/v1/services/discovery.googleapis.com?key=API_KEY

Paso 3: Realiza una llamada y controla la respuesta

Después de enviar la solicitud, debes deserializar la respuesta en la representación de lenguaje adecuada y asegurarte de controlar las condiciones de error que podrían ocurrir, tanto en el transporte HTTP subyacente como en los mensajes de error generados desde el servicio de la API. El formato de los errores se documenta como parte de la Guía de estilo de JSON de Google.

Examples

Para obtener algunos ejemplos concretos de bibliotecas cliente y herramientas que se implementaron con el servicio de descubrimiento de API de Google, consulta el documento Bibliotecas y ejemplos. Además, la siguiente sección es un ejemplo simple de una biblioteca cliente de API.

Cliente de API simple

A continuación, se muestra un ejemplo de una biblioteca cliente muy simple escrita en Python3 . El cliente crea una interfaz para interactuar con la API de Google Cloud Service Management y, luego, obtiene la definición del servicio del servicio de descubrimiento de API mediante esa interfaz.

Advertencia: El siguiente código es una versión simplificada significativamente de una biblioteca cliente típica. Es una implementación incompleta que se proporciona para demostrar algunos aspectos de la compilación de una biblioteca cliente. No es código listo para la producción.

import httplib2
import json
import uritemplate
import urllib

# Step 1: Fetch Discovery document
DISCOVERY_URI = "https://servicemanagement.googleapis.com/$discovery/rest?version=v1"
h = httplib2.Http()
resp, content = h.request(DISCOVERY_URI)
discovery = json.loads(content)

# Step 2.a: Construct base URI
BASE_URL = discovery['rootUrl'] + discovery['servicePath']

class Collection(object): pass

def createNewMethod(name, method):
  # Step 2.b Compose request
  def newMethod(**kwargs):
    body = kwargs.pop('body', None)
    url = urllib.parse.urljoin(BASE_URL, uritemplate.expand(method['path'], kwargs))
    for pname, pconfig in method.get('parameters', {}).items():
      if pconfig['location'] == 'path' and pname in kwargs:
        del kwargs[pname]
    if kwargs:
      url = url + '?' + urllib.parse.urlencode(kwargs)
    return h.request(url, method=method['httpMethod'], body=body,
                     headers={'content-type': 'application/json'})

  return newMethod

# Step 3.a: Build client surface
def build(discovery, collection):
  for name, resource in discovery.get('resources', {}).items():
    setattr(collection, name, build(resource, Collection()))
  for name, method in discovery.get('methods', {}).items():
    setattr(collection, name, createNewMethod(name, method))
  return collection

# Step 3.b: Use the client
service = build(discovery, Collection())
print (service.services.get(serviceName='discovery.googleapis.com', key='API_KEY'))

Los componentes clave del cliente son los siguientes:

  • Paso 1: Obtén el documento de descubrimiento.
    El documento de descubrimiento para la API de Google Cloud Service Management se recupera y analiza en una estructura de datos. Dado que Python es un lenguaje de escritura dinámica, el documento de descubrimiento se puede recuperar en el entorno de ejecución.
  • Paso 2.a: Crea el URI base.
    Se calcula el URI base.
  • Paso 2.b: Redacta la solicitud.
    Cuando se llama a un método en una colección, se expande la plantilla de URI con los parámetros que se pasan al método y los parámetros con una ubicación de query se colocan en los parámetros de búsqueda de la URL. Por último, se envía una solicitud a la URL compuesta con el método HTTP especificado en el documento de descubrimiento.
  • Paso 3.a: Compila la superficie del cliente
    La superficie del cliente se compila de forma recurrente desciende sobre el documento de análisis analizado. Para cada método de la sección methods, se adjunta un método nuevo al objeto Collection. Debido a que las colecciones se pueden anidar, buscamos resources y compilamos de manera recursiva un objeto Collection para todos sus miembros si se encuentra uno. Cada colección anidada también se adjunta como un atributo al objeto Collection.
  • Paso 3.b: Usa el cliente.
    Esto demuestra cómo se usa la superficie de la API compilada. Primero, se crea un objeto de servicio a partir del documento de descubrimiento y, luego, se define la servicio Service Discovery con la API de Google Cloud Service Management.