Compila una biblioteca cliente

Puedes usar el servicio de descubrimiento de las APIs de Google para crear una variedad de herramientas diferentes y usarlas 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 este documento, se describe cómo compilar una biblioteca cliente personalizada para las APIs de Google.

Una biblioteca cliente estable y con todas las funciones es una herramienta complicada que puede tardar meses en desarrollarse. No obstante, las instrucciones generales que permiten compilar una biblioteca cliente simple para las APIs de Google se pueden dividir en tres pasos sencillos:

Recupera el documento de descubrimiento y construye la superficie de la API
Redacta una solicitud
Realiza una llamada y recupera la respuesta

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

Recupera el documento de descubrimiento

Antes de comenzar a implementar una biblioteca cliente, hay algunos requisitos básicos que afectan la forma en la que procederás por tu ruta de desarrollo. Por ejemplo, el lenguaje de programación que elijas puede ser de tipo o sin tipo; si se escribe, puede ser escrita de forma estática o dinámica. Puede compilarse o interpretarse. 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. Tu estrategia para el momento exacto en que se debe recuperar el documento está determinada según los requisitos que identificaste. Por ejemplo, en un lenguaje de tipo estático, puedes recuperar el documento de descubrimiento al principio del proceso y, luego, generar código para manejar la API específica que se describe en el Documento de descubrimiento. Para un lenguaje de tipado fuerte, puedes generar código y compilar una biblioteca compilada. En el caso de un lenguaje de tipo dinámico, puedes construir de manera diferida las estructuras de programación para interactuar con la API sobre la marcha a medida que se usa la superficie de programación.

Redacta una solicitud

Para redactar una solicitud, se deben realizar dos pasos separados:

Redactar el cuerpo de la solicitud.
Crear la URL de la solicitud.

Debes convertir el cuerpo de la solicitud, si lo hay, de una representación adecuada del lenguaje 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 una manipulación segura de los datos de la solicitud y que se pueda serializar en JSON.

La construcción de la URL de la 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, que están entre llaves. Este es 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 de descubrimiento de 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, con el objetivo de indicar que es una ruta variable).

Cuando realizas 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.

También ten en cuenta que la propiedad path es un URI relativo. Para calcular el URI absoluto, sigue estos pasos:

Si conoces tu ubicación (región) y el documento de descubrimiento tiene la propiedad endpoints, verifica si tu ubicación está presente en la lista endpoints. Si es así, toma el endpointUrl de la lista endpoints cuyo location coincida con el tuyo.
Si no hay ninguna propiedad endpoints en el documento de descubrimiento o tu ubicación no está presente en la lista endpoints o si quieres orientar al extremo global, toma la propiedad rootUrl de nivel superior del documento de descubrimiento.

Por ejemplo, la propiedad rootUrl del documento de descubrimiento de la API de Service Usage es la siguiente:
```
https://serviceusage.googleapis.com/
```
Toma el servicePath del nivel superior del documento de descubrimiento. Por ejemplo, la propiedad servicePath del documento de descubrimiento de la API de Service Usage está vacía.
Concatenalos entre sí para obtener lo siguiente:
```
https://serviceusage.googleapis.com/
```
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 serviceusage.services.enable de la API de Service Usage v1, el valor de la propiedad path es v1/{+name}:enable. Por lo tanto, el URI completo del método es el siguiente:
```
https://serviceusage.googleapis.com/v1/{+name}:enable
```

No necesitas una clave de API para llamar a la API de Service Usage. Sin embargo, si la API a la que llamas requiere una clave de API, puedes agregar esta clave a la cadena de consulta del URI:

REQUEST_URI?key=API_KEY

Haz una llamada y administra la respuesta

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

Ejemplos

En la sección siguiente, se muestra un ejemplo simple de una biblioteca cliente de las APIs.

Cliente de las APIs simples

A continuación, se muestra un ejemplo de una biblioteca cliente muy simple escrita en Python3. El cliente compila una interfaz para interactuar con la API de Service Usage y, luego, usa esa interfaz para habilitar la API de Compute Engine (compute.googleapis.com) en el proyecto my-project

import httplib2
import json
import uritemplate
import urllib

# Step 1: Fetch Discovery document
DISCOVERY_URI = "https://serviceusage.googleapis.com/$discovery/rest?version=v1"
h = httplib2.Http()
resp, content = h.request(DISCOVERY_URI)
discovery = json.loads(content)
location = None # Set this to your location if appropriate
use_global_endpoint = True # Set this to False if you want to target the endpoint for your location

# Step 2.a: Construct base URI
BASE_URL = None
if not use_global_endpoint and location:
  if discovery['endpoints']:
    BASE_URL = next((item['endpointUrl'] for item in discovery['endpoints'] if item['location'] == location), None)
if not BASE_URL:
  BASE_URL = discovery['rootUrl']
BASE_URL += 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 (serviceusage.services.enable(name='projects/my-project/services/compute.googleapis.com'))

Los componentes fundamentales del cliente son los siguientes:

Paso 1: Recupera el documento de descubrimiento. El documento de descubrimiento de la API de Service Usage 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, la plantilla de URI se expande con los parámetros pasados al método y los parámetros con una ubicación de query se colocan en los parámetros de consulta 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 plataforma del cliente. La superficie del cliente se compila de forma descendente recursivamente sobre el documento de descubrimiento 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 forma 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 muestra cómo se usa la superficie de la API compilada. Primero, se compila un objeto de servicio a partir del documento de descubrimiento y, luego, la API de Service Usage se usa para habilitar la API de Compute Engine en el proyecto my-project.