Añadir una API como proveedor de tipos

En esta página se describe cómo añadir una API a Google Cloud Deployment Manager como proveedor de tipos. Para obtener más información sobre los tipos y los proveedores de tipos, consulta la documentación sobre la descripción general de los tipos.

Un proveedor de tipos expone todos los recursos de una API de terceros a Deployment Manager como tipos base que puedes usar en tus configuraciones. Estos tipos deben servirse directamente mediante una API RESTful que admita las operaciones Create, Read, Update y Delete (CRUD).

Si quiere usar una API que Google no proporciona automáticamente con Deployment Manager, debe añadirla como proveedor de tipos. Puedes añadir cualquier API como proveedor de tipos siempre que tenga una especificación OpenAPI (antes Swagger©) o un documento de descubrimiento de Google.

En este documento no se describe cómo configurar tu propio servicio de API. Se da por hecho que ya hay una API que quieres añadir o que ya has creado una API en funcionamiento a la que se puede acceder desde un endpoint público. Por ejemplo, para desplegar una API de ejemplo con Google Cloud Endpoints, puedes seguir la guía de inicio rápido de Cloud Endpoints.

Antes de empezar

Componentes de un proveedor de tipos

Un proveedor de tipos consta de lo siguiente:

  • Nombre: el nombre que quieras asignar al proveedor de tipos. Usarás este nombre para hacer referencia al tipo y a sus recursos de API relevantes.
  • Documento de descriptor: la URL del documento de descriptor del tipo. Entre los documentos admitidos se incluyen los documentos de Discovery de Google o las especificaciones de OpenAPI 1.2.
  • Autenticación: cualquier credencial de autenticación necesaria para la API. Puedes especificar la autenticación básica. Si tu API se ejecuta en Cloud Endpoints o Google Kubernetes Engine (GKE), también puedes usar las credenciales de la cuenta de servicio del proyecto como autenticación.
  • Opciones avanzadas: cualquier asignación de entrada avanzada u opción de API.

Nombre

Nombre del proveedor de tipos. Usarás este nombre para hacer referencia al tipo en configuraciones y plantillas futuras. Por ejemplo, si has creado un proveedor de tipos y lo has llamado my-awesome-type-provider, lo usarías en plantillas posteriores de la siguiente manera:

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

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

Documento de descriptor

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

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

Consulta la lista completa de documentos de Google Discovery.

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

Autenticación

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

Para especificar las credenciales de 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 crees un proveedor de tipos.

Si tienes un clúster que se ejecuta en Google Kubernetes Engine (GKE) en el mismo proyecto en el que usas Deployment Manager, puedes añadir el clúster como proveedor de tipos y usar Deployment Manager para acceder a la API de GKE. En este caso, puedes obtener el token de acceso OAuth 2.0 de la cuenta de servicio de las APIs de Google del proyecto y proporcionar el token de acceso en el encabezado Authorization. A diferencia de la sección de credenciales anterior, debes proporcionar este valor 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 ver un ejemplo completo, consulta el ejemplo de clúster y tipo de GKE.

Puedes usar el mismo método para autenticarte en los endpoints de Google Cloud.

(Opcional) Raíz de autoridad de certificación personalizada

Si quieres añadir una API como proveedor de tipos a Deployment Manager y el endpoint HTTPS de esa API usa un certificado que no proporciona una autoridad de certificación (CA) de confianza pública para cifrar la conexión, puedes añadir la API a tu configuración como en el siguiente ejemplo:

customCertificateAuthorityRoots:
- $(ref.my-gke-cluster.masterAuth.clusterCaCertificate)

donde my-gke-cluster es el clúster de GKE que estás usando. Para ver un ejemplo detallado, consulta el ejemplo de clúster de proveedor de GKE.

Opciones de tipo avanzadas

Es posible que algunas APIs tengan peculiaridades que dificulten que Deployment Manager asigne todas las propiedades de la API a Deployment Manager. En un escenario ideal, proporcionas un documento de descriptor y Deployment Manager determina automáticamente las rutas de solicitud de la API y las propiedades de la API pertinentes sin que tengas que hacer nada más. En el caso de las APIs más complejas, Deployment Manager puede entender la mayoría de las APIs, pero es posible que tengas que especificar explícitamente las asignaciones de entrada al comportamiento de la API que no sea obvio.

Para obtener más información sobre las asignaciones de entrada, consulta la documentación de las opciones avanzadas de la API.

Crear un proveedor de tipos

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

gcloud

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

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

donde:

  • [TYPE_PROVIDER_NAME] es el nombre que quieres asignar a este tipo.

  • [URL] es la URL completa del documento de descriptor que admite este tipo. Por ejemplo:

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

Si quieres proporcionar credenciales de autenticación u opciones avanzadas de la API, puedes crear un archivo de opciones de la API escrito en YAML y proporcionarlo mediante la marca --api-options-file. Por ejemplo, el archivo podría tener este 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]

Si quieres autenticarte mediante una autoridad de certificación (CA) personalizada, puedes añadir la CA como una marca al comando gcloud, como en el siguiente ejemplo:

gcloud beta deployment-manager type-providers create [TYPE_NAME] --api-options-file=[FILE_NAME] \
    --descriptor-url [url] \
    --custom-certificate-authority-roots=[CA_NAME]

API

Para crear un tipo base en la API, haz una solicitud POST que contenga el descriptorUrl y opciones de configuración opcionales 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 el tipo de proveedor de tipos funciona correctamente, sigue estos pasos:

  1. Llama a tu nuevo proveedor de tipos en una configuración.
  2. Implementa cada colección proporcionada por el proveedor de tipos para asegurarte de que la API funciona como se espera. Una colección es un recurso de API del proveedor de tipos especificado.
  3. Actualiza cada colección.
  4. Elimina cada colección.

Cuando un usuario crea una instancia de un tipo de tu proveedor de tipos, en realidad está haciendo una solicitud a Deployment Manager, no explícitamente a la API subyacente. A su vez, Deployment Manager crea la solicitud con la información proporcionada para enviar una solicitud a la API en nombre del usuario. El problema más habitual que puede surgir es que la API tenga propiedades que Deployment Manager no pueda reconocer automáticamente. Por ejemplo, algunas APIs requieren propiedades que solo se pueden extraer de una respuesta de la API. Otras APIs pueden usar el mismo nombre de campo con valores diferentes en función de la operación. En estos casos, debes indicar explícitamente a Deployment Manager cómo gestionar estas situaciones.

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

Siguientes pasos

© 2016 Swagger. Todos los derechos reservados.