Crear un conector personalizado

En esta página se describe cómo crear un conector personalizado. Para saber qué es un conector personalizado, consulta Conectores personalizados.

Para establecer la conectividad con tu backend mediante un conector personalizado, debes realizar las siguientes tareas:

  1. Crear un conector personalizado: en esta tarea, definirás el contrato entre Integration Connectors y tu endpoint (backend) proporcionando la especificación de OpenAPI del endpoint. Actualmente, solo se admite la versión 3.0 de OpenAPI y todas sus versiones secundarias. Especificar la especificación es una actividad que se realiza una sola vez.
  2. Crear una conexión de conector personalizado: en esta tarea, configurarás los detalles de conexión de tu backend, como el nombre de host y la autenticación. En el caso de un conector personalizado específico, puedes crear tantas conexiones como necesites.

Para entender la diferencia entre un conector y una conexión, consulta Conector y conexión.

Antes de empezar

Crear un conector personalizado

Como se describe en los casos de conectividad de backend, los conectores personalizados pueden tener cualquiera de los siguientes patrones de conectividad:

  • Conectividad directa al endpoint público de tu backend.
  • Conectividad indirecta a tu backend a través de un endpoint público intermediario.

Los pasos para crear conectores personalizados varían ligeramente en estos dos patrones.

Crear con conectividad directa

Para crear un conector personalizado con conectividad directa al endpoint de tu backend, sigue estos pasos:

Consola

  1. En la consola, ve a la página Integration Connectors > Custom connectors (Conectores de integración > Conectores personalizados) y, a continuación, selecciona o crea un Google Cloud proyecto.

    Ir a la página Conectores personalizados

  2. Haz clic en Crear para abrir la página Crear conector personalizado.
  3. En la sección Detalles del conector, define los siguientes campos:
    1. Nombre del conector: introduce un nombre para el conector.
    2. Nombre visible: introduce un nombre visible para el conector.
    3. Descripción: escribe una descripción.
    4. Cuenta de servicio: selecciona una cuenta de servicio que tenga los roles necesarios.
    5. Logotipo: suba la imagen a un segmento de Cloud Storage para usarla como logotipo del conector.
  4. Haz clic en Siguiente.
  5. En la sección Especificación del conector, defina los siguientes campos:
    1. Tipo de conector personalizado: selecciona el tipo de conector personalizado.
    2. Especificación del conector: introduce la URL pública de tu especificación de API abierta o sube el archivo de especificación a un segmento de Cloud Storage.
  6. Revisa los detalles de la configuración del conector y haz clic en Crear.

Si se crea correctamente, el conector recién creado se mostrará en la página Conectores personalizados. Si se trata de un conector nuevo, también se creará una primera versión del conector. Puedes ver los detalles de la versión en la pestaña Versión de la página Detalles del conector personalizado. Para obtener más información, consulta .

Sin embargo, ten en cuenta que, para conectarte a tu backend, debes crear una conexión para el conector que acabas de crear. Para obtener más información, consulta Crear una conexión de conector personalizado.

API

En los siguientes comandos de ejemplo se muestra cómo crear un conector personalizado mediante las APIs Integration Connectors:

  1. Crea el conector. 
    curl -X POST \
-H "authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json"
-d '{"customConnectorType":"OPEN_API", \
"displayName":"CUSTOM_CONNECTOR_NAME", \
"description": "an open api based custom connector for hrms"}' \
"https://connectors.googleapis.com/v1/projects/PROJECT_ID/locations/global/customConnectors?custom_connector_id=UNIQUE_IDENTIFIER"

    Haz los cambios siguientes:

    • CUSTOM_CONNECTOR_NAME: nombre del conector personalizado.
    • PROJECT_ID: el ID de tu proyecto de Google Cloud .
    • UNIQUE_IDENTIFIER: identificador único del conector. Por ejemplo, custom-connector-1.
  2. Configura la versión del conector personalizado. 
    curl -X POST \
-H "authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d '{"spec_location": "SPECIFICATION_URL",}' \
"https://connectors.googleapis.comv1/projects/PROJECT_ID/locations/global/customConnectors/openapi-customconnector/customConnectorVersions?custom_connector_version_id=VERSION_NUMBER"

    3. Haz los cambios siguientes:

    • SPECIFICATION_URL: la URL de la especificación de la API abierta. Por ejemplo, https://petstore3.swagger.io/api/v3/openapi.json.
    • PROJECT_ID: el ID de tu proyecto de Google Cloud .
    • VERSION_NUMBER: número de versión del conector. Por ejemplo, 2.

Crear con conectividad indirecta

Para crear un conector personalizado que se conecte a tu backend a través de un endpoint intermediario, sigue estos pasos:

Consola

  1. En la consola, ve a la página Integration Connectors > Custom connectors (Conectores de integración > Conectores personalizados) y, a continuación, selecciona o crea un Google Cloud proyecto.

    Ir a la página Conectores personalizados

  2. Haz clic en Crear para abrir la página Crear conector personalizado.
  3. En la sección Detalles del conector, define los siguientes campos:
    1. Nombre del conector: introduce un nombre para el conector.
    2. Nombre visible: introduce un nombre visible para el conector.
    3. Descripción: escribe una descripción.
    4. Configurar el destino del conector para el acceso al backend: habilita esta opción. Se mostrarán las secciones de configuración adicionales de la página.
    5. Cuenta de servicio: selecciona una cuenta de servicio que tenga los roles necesarios.
    6. Logotipo: suba la imagen a un segmento de Cloud Storage para usarla como logotipo del conector.
  4. Haz clic en Siguiente.
  5. En la sección Especificación del conector, defina los siguientes campos:
    1. Tipo de conector personalizado: selecciona el tipo de conector personalizado.
    2. Especificación del conector: introduce la URL pública de tu especificación de API abierta o sube el archivo de especificación a un segmento de Cloud Storage.
  6. Haz clic en Siguiente.
  7. En la sección Destino del conector, defina los siguientes campos:
    1. Tipo de destino: selecciona Dirección de host.
    2. Host: introduce el nombre de host en el que se ejecuta tu servicio intermediario e incluye el esquema http:// o https://.
    3. Puerto: introduce el número de puerto de tu servicio intermediario.
  8. Haz clic en Siguiente.
  9. En la sección Autenticación del conector, seleccione el tipo de autenticación del servicio intermediario y, a continuación, introduzca los detalles correspondientes según se le indique. Este paso consiste en configurar la autenticación de Integration Connectors al servicio intermediario.

    La configuración de autenticación del servicio intermediario al backend no se puede configurar en Integration Connectors. Depende del servicio intermediario cómo quiera autenticarse con el backend.

    Puede usar los siguientes tipos de autenticación para autenticarse en el servicio intermediario:

    • Autenticación con cuenta de servicio
    • Autenticación con clave de API
    • OAuth 2.0: autenticación con credenciales de cliente
    • Autenticación básica
    • Autenticación resumida

      • Para saber cómo configurar estos tipos de autenticación, consulta Configurar la autenticación.

    Si el acceso a los recursos de la API es ilimitado y no requiere autenticación, seleccione Sin autenticación.

  10. Haz clic en Siguiente.
  11. En la sección Variables de backend, introduzca los valores que quiera enviar a su backend a través del servicio intermediario. Debe configurar los valores como pares clave-valor. Para introducir un par clave-valor, haz lo siguiente: Haz clic en Añadir variable y, a continuación, define los siguientes campos:
    • Clave: introduce el nombre de la clave.
    • Tipo de valor: selecciona el tipo de datos de la variable.
    • Nombre visible: introduce un nombre visible.
    • Ubicación: especifica cómo quieres que el conector envíe las variables al servicio intermediario. Las opciones disponibles son Header, Request payload y Query parameter.
    • También puede seleccionar Required para especificar que la variable es obligatoria.
  12. Haz clic en Siguiente.
  13. Revisa los detalles de la configuración del conector y haz clic en Crear.

Si se crea correctamente, el conector se mostrará en la página de conectores personalizados y, si es un conector nuevo, también se creará la primera versión del conector. Puedes ver los detalles de la versión en la pestaña Versión de la página Detalles del conector personalizado. Para obtener información sobre cómo crear y editar una versión de un conector personalizado, consulta Gestionar versiones de conectores personalizados.

Sin embargo, ten en cuenta que, para conectarte a tu backend, debes crear una conexión para el conector que acabas de crear. Para obtener más información, consulta Crear una conexión de conector personalizado.

Configurar la autenticación

Introduce los detalles en función de la autenticación que quieras usar.

  • Autenticación de cuentas de servicio

    Selecciona esta opción para autenticarte con una cuenta de servicio de Google Cloud. Asegúrate de que has proporcionado a la cuenta de servicio los roles y permisos de gestión de identidades y accesos pertinentes necesarios para la autenticación.

    • Permisos: selecciona los permisos de OAuth 2.0 necesarios en el menú desplegable. Para obtener más información, consulta Ámbitos de acceso.
  • Autenticación con clave de API

    Seleccione esta opción para autenticarse mediante una clave de API.

    • Clave de API: selecciona el secreto de Secret Manager de la clave de API.
    • Versión del secreto: selecciona la versión del secreto.
    • Nombre del parámetro de la clave de API: introduce un nombre de parámetro para la clave de API. Una clave de API se envía a tu servidor backend como un par clave-valor. El valor que introduzcas aquí se usará como nombre de la clave de API que hayas seleccionado anteriormente.
    • Ubicación de la clave de API: selecciona dónde quieres añadir la clave de API en la solicitud.
  • OAuth 2.0: concesión de credenciales de cliente
    • ID de cliente: el ID de cliente que se usará para autenticar el servicio intermediario.
    • Secreto de cliente: secreto de Secret Manager que contiene el secreto de cliente para autenticar el servicio intermediario.
    • Formato de solicitud del token de acceso: formato de solicitud que se debe usar en las solicitudes para obtener el token de acceso del servidor de autorización. Selecciona body para enviar el ID y el secreto de cliente como cuerpo de la solicitud, o header para enviarlos como encabezado codificado.
    • Ruta de solicitud de token: ruta de solicitud que se debe añadir a la URL del servidor de autorización para obtener la URL del token de acceso.
  • Autenticación básica
    • Nombre de usuario: nombre de usuario utilizado para autenticarse en el servicio intermediario.
    • Contraseña: secreto de Secret Manager que contiene la contraseña asociada al nombre de usuario proporcionado.
  • Autenticación Digest
    • Nombre de usuario: nombre de usuario utilizado para autenticarse en el servicio intermediario.
    • Contraseña: secreto de Secret Manager que contiene la contraseña asociada al nombre de usuario proporcionado.

API

En los siguientes comandos de ejemplo se muestra cómo crear un conector personalizado mediante las APIs Integration Connectors:

  1. Crea el conector. 
    curl -X POST \
-H "authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json"
-d '{"customConnectorType":"OPEN_API", \
"displayName":"CUSTOM_CONNECTOR_NAME", \
"description": "an open api based custom connector for hrms"}' \
"https://connectors.googleapis.com/v1/projects/PROJECT_ID/locations/global/customConnectors?custom_connector_id=UNIQUE_IDENTIFIER"

    Haz los cambios siguientes:

    • CUSTOM_CONNECTOR_NAME: nombre del conector personalizado.
    • PROJECT_ID: el ID de tu proyecto de Google Cloud .
    • UNIQUE_IDENTIFIER: identificador único del conector. Por ejemplo, custom-connector-1.
  2. Configura la versión del conector personalizado y la autenticación. 
    curl -X POST \
-H "authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d '{"spec_location": "SPECIFICATION_URL", \
"service_account":"test-sa", \
"enable_backend_destination_config": true, \
"auth_config": { \
"auth_type":"USER_PASSWORD", \
"auth_key": "basic", \
"user_password": { \
"username":"USERNAME", \
"password": {"secret_version":"projects/PROJECT_ID/secrets/fidelity-secret/versions/SECRET_VERSION_NUMBER"} \
}}, \
"backend_variable_templates": [{ \
"key":"authkey", \
"value_type":"SECRET", \
"display_name":"Authorization Key", \
"required":true, \
"location_type": "HEADER" \
}], \
"destination_configs":[{ \
"key":"base_url", \
"destinations": [{ \
"host":"DESTINATION_HOST_ADDRESS" \
}]} \
]}' \
"https://connectors.googleapis.com/v1/projects/PROJECT_ID/locations/global/customConnectors/facade-connector/customConnectorVersions?custom_connector_version_id=CONNECTOR_VERSION_NUMBER"

    3. Haz los cambios siguientes:

    • SPECIFICATION_URL: la URL de la especificación de la API abierta. Por ejemplo, https://petstore3.swagger.io/api/v3/openapi.json.
    • PROJECT_ID: el ID de tu proyecto de Google Cloud .
    • USERNAME: nombre de usuario para la autenticación con el servicio intermediario.
    • SECRET_VERSION_NUMBER: número de versión del secreto de Secret Manager. Por ejemplo, 2.
    • DESTINATION_HOST_ADDRESS: dirección de host del servicio intermediario. Por ejemplo, http://www.test.com:80.
    • CONNECTOR_VERSION_NUMBER: número de versión del conector personalizado. Por ejemplo, 1.

Crear una conexión de conector personalizado

Después de crear el conector personalizado, para conectarte a tu backend, debes crear una conexión del tipo de conector personalizado. Estos son los pasos generales para crear una conexión:

  1. En la consola de Cloud, ve a la página Integration Connectors > Connections (Conectores de integración > Conexiones) y, a continuación, selecciona o crea un proyecto de Google Cloud.

    Ve a la página Conexiones.

  2. Haz clic en Crear para abrir la página Crear conexión.
  3. En la sección Ubicación, selecciona una ubicación para la conexión en el campo Región.

    Para ver la lista de todas las regiones admitidas, consulta Ubicaciones.

  4. Haz clic en Siguiente.
  5. En la sección Detalles de la conexión, define los siguientes campos:
    1. Conector: selecciona tu conector personalizado en la lista desplegable de conectores disponibles.
    2. Versión del conector: seleccione la versión del conector en la lista desplegable de versiones disponibles.
    3. En el campo Nombre de la conexión, escriba un nombre para la conexión.

      Los nombres de las conexiones deben cumplir los siguientes criterios:

      • Los nombres de conexión pueden contener letras, números o guiones.
      • Las letras deben estar en minúsculas.
      • Los nombres de conexión deben empezar por una letra y terminar por una letra o un número.
      • Los nombres de conexión no pueden tener más de 63 caracteres.
    4. Si quiere, puede introducir una Descripción de la conexión.
    5. También puedes seleccionar Habilitar registro en la nube para habilitar el registro en la nube.
    6. Cuenta de servicio: selecciona una cuenta de servicio que tenga los roles necesarios.
    7. Si quieres, configura los ajustes del nodo de conexión:

      • Número mínimo de nodos: introduce el número mínimo de nodos de conexión.
      • Número máximo de nodos: introduce el número máximo de nodos de conexión.

      Un nodo es una unidad (o réplica) de una conexión que procesa transacciones. Se necesitan más nodos para procesar más transacciones en una conexión y, a la inversa, se necesitan menos nodos para procesar menos transacciones. Para saber cómo influyen los nodos en el precio de tu conector, consulta la sección Precios de los nodos de conexión. Si no introduces ningún valor, de forma predeterminada, el número mínimo de nodos se establece en 2 (para mejorar la disponibilidad) y el máximo en 50.

    8. Si quieres, haz clic en Añadir etiqueta para añadir una etiqueta a la conexión en forma de par clave-valor.
  6. Haz clic en Siguiente.
  7. Si el conector usa un servicio intermediario para conectarse a tu backend, haz lo siguiente:

    En la sección Destinos, defina los siguientes campos:

    1. Tipo de destino: selecciona Dirección de host.
    2. Host: introduce el nombre de host en el que se ejecuta tu servicio intermediario e incluye el esquema http:// o https://.
    3. Puerto: introduce el número de puerto de tu servicio intermediario.

    El campo de destino contiene la URL de la especificación de OpenAPI de forma predeterminada. Si hay varias URLs de servidor, se muestra la primera.

  8. Haz clic en Siguiente.
  9. En la sección Autenticación, introduce los detalles de autenticación de tu backend.
    • Si te conectas directamente a tu backend, Integration Connectors te pedirá que configures la autenticación de tu backend.
    • Si te conectas indirectamente a tu backend a través de un servicio intermediario, Integration Connectors no te pedirá que configures los detalles de autenticación. Al crear el conector, ya habrás configurado la autenticación entre Integration Connectors y el servicio intermediario. Integration Connectors no requiere que configures la autenticación entre el servicio intermediario y el backend. El servicio intermediario decide cómo quiere autenticarse con el backend.
  10. Haz clic en Siguiente.
  11. Revise los detalles de la configuración de la conexión y, a continuación, haga clic en Crear.

Si la conexión se crea correctamente, se mostrará en la página Todas las conexiones y estará disponible en Integración de aplicaciones. Puedes usar la conexión en tu integración a través de la tarea Conectores.

Cuestiones importantes

Ten en cuenta los siguientes puntos al crear un conector personalizado:

  • Integration Connectors solo admite la versión 3.0 de OpenAPI y todas sus versiones secundarias.
  • La especificación de la API abierta no se valida durante la creación del conector personalizado. Cuando creas una conexión para el conector personalizado, Integration Connectors valida la especificación y, si tiene errores, la conexión estará en el estado Error.
  • Integration Connectors no diferencia entre entidades y acciones. Por lo tanto, tanto las entidades como las acciones de tu backend se mostrarán como Actions en tu conector personalizado.
  • Los conectores personalizados no se admiten en los Google Cloud proyectos que tienen habilitado Controles de Servicio de VPC.
  • Tanto el endpoint de la especificación de la API abierta como el endpoint de backend deben ser accesibles públicamente. Esto significa que no puedes establecer una conexión privada con tu backend.
  • El tipo de contenido multimedia de varias partes no se admite en la especificación de la API abierta.
  • No puedes editar los detalles de la versión de un conector personalizado.