Agregar una API como un proveedor de tipos

En esta página, se describe cómo agregar una API a Deployment Manager como proveedor de tipos. Para obtener más información sobre los tipos y los proveedores de tipos, lee la documentación Descripción general de tipos.

Un proveedor de tipos expone todos los recursos de una API de terceros a Deployment Manager como tipos base que puedes usar en las configuraciones. Una API de RESTful que admita operaciones de creación, lectura, actualización y eliminación (CRUD) debe entregar directamente estos tipos.

Puedes agregar cualquier API como proveedor de tipos, siempre que la API tenga una especificación de OpenAPI, (anteriormente Swagger©) o un documento de Google Descubre. Agrega proveedores de tipos para usar las API que Google no proporciona de forma automática.

En este documento no se describe cómo hacer funcionar tu propio servicio de API. Se da por supuesto que ya existe una API que deseas agregar o que ya has creado una API en ejecución a la que se puede acceder desde un extremo público. Por ejemplo, podrías implementar una API de ejemplo con Google Cloud Endpoints; para ello, sigue la Guía de inicio rápido de Cloud Endpoints.

Antes de comenzar

Componentes de un proveedor de tipos

Un proveedor de tipos consta de los siguientes elementos:

  • Nombre: el nombre deseado del proveedor de tipos. Utilizarás este nombre para hacer referencia al tipo y sus recursos de API relevantes.
  • Documento descriptor: la URL del documento descriptor para el tipo. Los documentos admitidos incluyen documentos de Google Discovery o especificaciones de OpenAPI 1.2.
  • Autenticación: todas las credenciales de autenticación necesarias para la API. Puedes especificar las autenticaciones básicas o, si tu API se ejecuta en Google Endpoints o en Google Kubernetes Engine, puedes usar las credenciales de la cuenta de servicio del proyecto como autenticación.
  • Opciones avanzadas: cualquier opción de API o asignación de entrada avanzada.

Nombre

El nombre del proveedor de tipos. Usarás este nombre para hacer referencia al tipo en las futuras configuraciones y plantillas. Por ejemplo, si creaste un proveedor de tipos y lo nombraste my-awesome-type-provider, lo usarás en las plantillas posteriores de la siguiente manera:

resources:
  name: a-deployment
  type: my-project/my-awesome-type-provider:some-collection
  properties:
  …

En el que my-project es el ID del proyecto al que pertenece el tipo y some-collection es la ruta de acceso al recurso de la API que estás creando.

Documento descriptor

El documento descriptor para el proveedor de tipos puede ser una especificación de OpenAPI 1.2 o 2.0, o un Documento de Google Discovery. Por ejemplo, puedes encontrar el Documento de Google Discovery para la API de Compute Engine Beta en esta URL:

https://content.googleapis.com/discovery/v1/apis/compute/beta/rest

Consulta una lista completa de los documentos de Google Discovery.

También se aceptan los documentos de OpenAPI 1.2 y OpenAPI 2.0.

Autenticación

Si la API requiere autenticación, puedes proporcionar los detalles de autenticación aquí. Deployment Manager admite credenciales de autenticación básicas como un nombre de usuario y una contraseña o, para Google Kubernetes Engine y Google Cloud Endpoints, puedes usar el encabezado Authorization para proporcionar un token de acceso desde la cuenta de servicio del proyecto.

Para especificar la autenticación básica, proporciona el nombre de usuario y la contraseña en la sección credentials:

credential:
  basicAuth:
    user: [USERNAME]
    password: [PASSWORD]

Solo tienes que especificar el nombre de usuario y la contraseña la primera vez que creas un proveedor de tipos.

Si tienes un clúster que se ejecuta en Google Kubernetes Engine, puedes agregar el clúster como proveedor de tipos y acceder a la API de Kubernetes mediante Deployment Manager. Aquí se da por hecho que ejecutas el clúster en el mismo proyecto en el que usas Deployment Manager. En este caso, puedes obtener el token de acceso de OAuth 2.0 de la cuenta de servicio de las API de Google del proyecto y proporcionar el token de acceso en el encabezado Authorization. A diferencia de la sección de credenciales ya mencionada, debes proporcionar esto como una asignación de entrada en tu solicitud:

- fieldName: Authorization
  location: HEADER
  value: >
    $.concat("Bearer ", $.googleOauth2AccessToken())

El método googleOauth2AccessToken() obtendrá automáticamente un token de acceso cuando el usuario llame a este proveedor de tipos. Para obtener un ejemplo completo, consulta el ejemplo de tipo y clúster de GKE.

Puedes utilizar el mismo método para autenticarte en Google Cloud Endpoints.

Opciones de tipo avanzadas

Ciertas API pueden tener idiosincrasias que dificulten que Deployment Manager asigne todas las propiedades de la API a Deployment Manager. En una situación ideal, suministras un documento descriptor y Deployment Manager determina automáticamente las rutas de acceso de solicitud a la API y las propiedades pertinentes de la API sin trabajo adicional de tu parte. En el caso de las API más complejas, Deployment Manager puede entender la mayor parte de la API, pero es posible que debas especificar de forma explícita las asignaciones de entrada del comportamiento de la API que no es obvio.

Para obtener más información sobre las asignaciones de entrada, lee la documentación para las Opciones de API avanzadas.

Crear un proveedor de tipos

Para crear un proveedor de tipos, realiza una solicitud a Deployment Manager con una carga útil de solicitud que contenga el nombre del proveedor de tipos deseado, la URL del descriptor y las credenciales de autenticación necesarias.

gcloud

Para crear un proveedor de tipos con la herramienta gcloud, usa el comando type-providers create:

gcloud beta deployment-manager type-providers create [TYPE_PROVIDER_NAME] --descriptor-url=[URL]

en el que:

  • [TYPE_PROVIDER_NAME] es el nombre que deseas darle a este tipo.
  • [URL] es la URL completamente calificada al documento descriptor que admite este tipo. Por ejemplo:

    http://petstore.swagger.io/v2/swagger.json
    

Si deseas proporcionar credenciales de autenticación o bien opciones de API avanzadas, puedes crear un archivo de opciones de API escrito en YAML y proporcionar tal archivo con la marca --api-options-file. Por ejemplo, el archivo puede tener el siguiente aspecto:

collectionOverrides:
- collection: /emailAddresses/v1beta/people
  options:
    inputMappings:
    - methodMatch: ^create$
      fieldName: emailAddress.displayName
      value: $.resource.properties.displayName
      location: BODY
    - methodMatch: ^update$
      fieldName: displayName
      value: $.resource.properties.displayName
      location: PATH
    virtualProperties: |
      schema: http://json-schema.org/draft-04/schema#
      type: object
      properties:
        displayName:
          type: string
      required:
      - displayName
credential:
  basicAuth:
    user: [USERNAME]
    password: [PASSWORD]

El comando gcloud sería el siguiente:

gcloud beta deployment-manager type-providers create [TYPE_NAME] --api-options-file=[FILE_NAME] \
    --descriptor-url [url]

API

Para crear un tipo base en la API, realiza una solicitud POST que contenga el descriptorUrl y opciones de configuración optativas en el cuerpo de la solicitud: Por ejemplo:

POST https://www.googleapis.com/deploymentmanager/v2beta/projects/[PROJECT_ID]/global/typeProviders

{ "description":"",
  "descriptorUrl":"https://www.example.com/api/v1beta1.json",
  "name":"my-type-provider",
  "collectionOverrides":[
    {
      "collection":"emailAddresses/v1beta/people",
      "options":{
        "inputMappings":[
          {
            "fieldName":"emailAddress.displayName",
            "location":"BODY",
            "methodMatch":"^create$",
            "value":"$.resource.properties.displayName"
          },
          {
            "fieldName":"displayName",
            "location":"PATH",
            "methodMatch":"^update$",
            "value":"$.resource.properties.displayName"
          }
        ],
        "virtualProperties":"schema: http://json-schema.org/draft-04/schema#\ntype: object\nproperties:\n  displayName:\n    type: string\nrequired:\n- displayName\n"
      }
    }
  ],
  "credential":{
    "basicAuth":{
      "password":"example-password",
      "user":"example-user"
    }
  }
}

Para obtener más información, consulta la documentación del método insert.

Probar el proveedor de tipos

Para verificar que tu clase de proveedor de tipos funcione según lo previsto:

  1. Llama al proveedor de tipos nuevos en una configuración.
  2. Implementa cada colección proporcionada por el proveedor de tipos para garantizar que la API funcione según lo previsto. Una colección es un recurso de API del proveedor de tipos especificado.
  3. Haz una actualización en cada colección.
  4. Borra cada colección.

Cuando un usuario crea una instancia de un tipo de tu proveedor de tipos, en realidad realiza una solicitud al Deployment Manager, no de forma explícita a la API subyacente. A su vez, Deployment Manager genera la solicitud con la información proporcionada a fin de realizar una solicitud a la API en nombre del usuario. El problema más común que puedes encontrar es que la API tenga propiedades cuyo reconocimiento automático sea difícil para Deployment Manager. Por ejemplo, algunas API requieren propiedades que solo pueden extraerse de una respuesta de la API. Otras API pueden utilizar el mismo nombre de campo con valores diferentes según la operación. En estos casos, deberás indicar explícitamente a Deployment Manager cómo manejar estas situaciones.

Si la API tiene alguna de estas características, usa las asignaciones de entrada para clarificar la ambigüedad de Deployment Manager.

Próximos pasos

© 2016 Swagger. Todos los derechos reservados.

¿Te ha resultado útil esta página? Enviar comentarios:

Enviar comentarios sobre...

Documentación de Cloud Deployment Manager