Agrega una API como proveedor de tipos

En esta página, se describe cómo agregar 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, 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.

Si deseas usar una API que Google no proporciona de forma automática con Deployment Manager, debes agregar la API como un proveedor de 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.

Este documento no 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 creaste una API en ejecución a la que se puede acceder desde un extremo público. Por ejemplo, para implementar una API de muestra con Google Cloud Endpoints, puedes seguir la Guía de inicio rápido de Cloud Endpoints.

Antes de comenzar

Si deseas usar los ejemplos de línea de comandos de esta guía, instala la herramienta de línea de comandos de gcloud.
Si deseas usar los ejemplos de la API en esta guía, configura el acceso a la API.
Configura el acceso a la API de v2beta si deseas usar los ejemplos de la API incluidos en esta guía.

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 la autenticación básica. Si tu API se ejecuta en Cloud Endpoints o en Google Kubernetes Engine (GKE), también 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.

Authentication

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

A fin de especificar las credenciales de autenticación básicas, 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 (GKE) en el mismo proyecto en el que usas Deployment Manager, puedes agregar 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 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 anterior, 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.

Raíz de autoridad certificadora personalizada (opcional)

Si deseas agregar una API como proveedor de tipos a Deployment Manager y el extremo HTTPS de esa API usa un certificado que no proporciona una autoridad certificadora (CA) de confianza pública para encriptar la conexión, puedes agregar la API a tu configuración, como en el siguiente ejemplo:

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

Aquí my-gke-cluster es el clúster de GKE que usas. Para obtener un ejemplo detallado, consulta el ejemplo de clúster de proveedores de GKE.

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 gcloud CLI, 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 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]

Si deseas autenticarte mediante una autoridad certificadora (CA) personalizada, puedes agregar 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, 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:

Llama al proveedor de tipos nuevos en una configuración.
Implementa cada colección que proporcione el proveedor de servicios para garantizar que la API funcione según lo previsto. Una colección es un recurso de API del proveedor de tipos especificado.
Haz una actualización en cada colección.
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, utiliza las asignaciones de entrada para clarificar la ambigüedad de Deployment Manager.

¿Qué sigue?

Aprende a llamar a un proveedor de servicios.
Comparte el proveedor de tipos con otros proyectos.
Obtén más información sobre los tipos.
Lee sobre crear una configuración.
Crea una implementación.
Obtén más información sobre las Opciones de API avanzadas.