Configuración de API proxy en Jitterbit API Manager

Introducción

Esta página describe cómo crear y configurar una API proxy desde la página de APIs de Jitterbit API Manager. Una API proxy es uno de los tres tipos de APIs configurados a través del API Manager. Para los otros dos tipos — API personalizada y servicio OData — consulte Configuración de API personalizada y Configuración de servicio OData.

Requisitos previos

A diferencia de una API personalizada o un servicio OData, que expone una operación de Harmony para su consumo, una API proxy se utiliza con una API existente. Las APIs proxied no son enrutadas a través de agentes de Jitterbit. La API que se está proxyando debe ser accesible para la puerta de enlace que procesa la API:

• Puerta de enlace API en la nube: Si utiliza la puerta de enlace API en la nube (alojada por Jitterbit), la API existente debe ser accesible públicamente, incluso si está asegurada. Es decir, la API que está intentando proxyar no puede estar detrás de un firewall. Para permitir que las direcciones IP de la puerta de enlace API en la nube accedan a la API que se está proxyando, consulte la Información de lista de permitidos y navegue a https://services.jitterbit para su región.
• Puerta de enlace API privada: Si utiliza una puerta de enlace API privada (alojada en una red privada), la API existente debe ser accesible por la puerta de enlace API privada.

A pesar de que cada API proxy permite que múltiples servicios se asignen a una URL única, la URL proxy base está consumiendo el derecho.

Crear una nueva API proxy

Cuando accedes a la página de APIs del Administrador de API, si no existen API personalizadas, servicios OData o API proxy en la organización seleccionada, esta pantalla está en blanco.

Para crear una nueva API proxy, Nuevo > API Proxy:

Al hacer clic en API Proxy, se abre la pantalla de configuración de la API proxy. Los detalles sobre cómo configurar una nueva API proxy se proporcionan en Configurar una API proxy a continuación.

Configurar una API proxy

La pantalla de configuración de la API proxy incluye cinco pasos de configuración, cada uno cubierto a continuación:

• Paso 1: Configuración básica

• Paso 2: API existente

• Paso 3: Definir servicios y métodos

• Paso 4: Asignar perfiles de seguridad y encabezados de solicitud

• Paso 5: Resumen y confirmación

La URL del servicio de una API es la URL utilizada para consumir la API utilizando el método de autenticación configurado. Las partes de la URL del servicio de una API se describen en URL del servicio de API.

La URL del servicio se muestra en la parte superior de cada paso:

Paso 1: Configuración básica

• Nombre del proxy: Ingresa un nombre para la API proxy que se utilizará para fines de identificación interna. Se permiten estos caracteres especiales:

  ( ) - _

• Número de versión: Ingresa una versión opcional que se utilizará como parte de la URL del servicio de la API. Este campo permite un máximo de 48 caracteres y no permite espacios ni ciertos caracteres especiales. No se recomienda usar caracteres especiales distintos de un punto (.) o guion (-). Ejemplos de convenciones de nomenclatura incluyen versiones incrementales, como v1.0, v1.1, v1.2, etc., o usar una fecha en la que se publicó la API, como 2021-08-28.

• Entorno: Utiliza el menú para seleccionar el entorno donde residirá la API. Puedes escribir cualquier parte del nombre del entorno en el menú para filtrar la lista de entornos. Los resultados del menú se filtran en tiempo real con cada pulsación de tecla.

  Nota

  Después de la creación de la API, el entorno no se puede cambiar. Para mover una API entre entornos, puedes clonar la API o exportar e importar la API en otro entorno.

• Raíz del servicio: El nombre público de la API que se utilizará como parte de la URL del servicio de la API. Por defecto, este campo se completa con el Nombre del proxy convertido a camel case. Este campo no permite espacios ni ciertos caracteres especiales. No se recomienda usar caracteres especiales distintos de un guion bajo (_). Se permiten los siguientes caracteres especiales:

  . _ ~ ( ) $ ; / ? : @ = & ' ! * , + -

• Descripción: Ingresa una descripción opcional para la API.

• Habilitar modo de depuración hasta: Selecciona para habilitar el modo de depuración y habilitar la entrada de una fecha y hora correspondiente en la que se deshabilitará el modo de depuración. La duración máxima de habilitación es de dos semanas. El modo de depuración habilita el seguimiento completo para cada solicitud recibida a través de la URL del servicio de la API. Cuando está habilitado, el sistema retiene el contenido completo de cada solicitud y respuesta de la API durante un máximo de 24 horas desde el momento en que se recibió la llamada a la API y se aplica a todas las operaciones desencadenadas por la API.

  Nota

  Navegar a través de los datos del evento puede volverse difícil con grandes volúmenes (pruebas de carga, pruebas en preproducción, etc.). El aumento en los datos retenidos puede resultar en preocupaciones de espacio de almacenamiento y seguridad. No recomendamos usar el modo de depuración en un entorno de producción.

• Tiempo de espera: Ingresa el número de segundos antes de que la API se agote. El valor predeterminado es de 30 segundos. El máximo es de 180 segundos.

  Nota

  Esta configuración es independiente de la configuración de tiempo de espera de operación en Integration Studio o Design Studio. Las configuraciones de tiempo de espera de operación no se utilizan a menos que la configuración EnableAPITimeout en el archivo de configuración del agente privado esté habilitada.

• Solo SSL: Cuando se selecciona (por defecto), los datos se cifran a través de SSL y se aplica HTTPS para todas las solicitudes y respuestas de la API (recomendado).

  Cuando no se selecciona, los datos transmitidos a través de las solicitudes y respuestas de la API no están cifrados y pueden ser interceptados y vistos por otros. Esto podría potencialmente exponer información sensible.

• Habilitar CORS: Seleccione para habilitar Compartición de Recursos de Origen Cruzado (CORS) (no recomendado). El valor predeterminado es no seleccionado.

  Advertencia

  Habilitar CORS provoca que las operaciones que utilizan el método OPTIONS se ejecuten sin autenticación.

• Habilitar Registro Detallado: Seleccione para habilitar el registro detallado. El registro detallado para las APIs incluye datos de solicitud y respuesta en cada registro de API para ayudar a monitorear los datos entrantes y salientes y facilitar la depuración. El valor predeterminado es no seleccionado.

• Siguiente: Haga clic para almacenar temporalmente la configuración para este paso y continuar al siguiente paso.

• Guardar Cambios: Si está habilitado, haga clic para guardar la configuración para este paso y navegar a Paso 5: Resumen y confirmación.

Paso 2: API Existente

• URL Base de la API: Ingrese la URL base de la API a la que se va a hacer proxy.

  Nota

  Si la API proporciona un único servicio, puede ingresar la URL completa de la API, incluyendo la ruta del servicio. Las rutas de servicio adicionales se definen en Paso 3: Definir servicios y métodos.

• Proporcionar documento OpenAPI: Si se proporciona un documento OpenAPI, se utilizará para descubrir automáticamente los servicios de la API. Seleccione No para omitir o Sí para expandir un área adicional para proporcionar el documento OpenAPI:

  

  • Cargar URL: Abre un diálogo para cargar un documento OpenAPI en formato YAML o JSON desde una URL:

    

  • Subir archivo: Abre un diálogo para subir un documento OpenAPI en formato YAML o JSON después de usar Examinar para seleccionar el archivo:

    

  • Limpiar: Limpia un documento OpenAPI que ya ha sido proporcionado y cambia la selección de Proveer documento OpenAPI a No.

  • Editor de documentos: Permite ver y editar un documento OpenAPI proporcionado. También se puede proporcionar un documento OpenAPI ingresándolo directamente aquí. Para ver y editar el documento OpenAPI en un área más grande, haz clic en el ícono de expansión (después de abrir esa área, haz clic en el ícono de retorno para volver a esta pantalla).

• Siguiente: Haz clic para almacenar temporalmente la configuración de este paso y continuar al siguiente paso.

• Guardar cambios: Si está habilitado, haz clic para guardar la configuración de este paso y navegar a Paso 5: Resumen y confirmación.

• Descartar cambios: Después de realizar cambios, haz clic para cerrar la configuración sin guardar los cambios realizados en ningún paso. Un mensaje te pide que confirmes que deseas descartar los cambios.

Paso 3: Definir servicios y métodos

La forma en que se definen los servicios y métodos depende de si la selección en Paso 2: API existente para Proveer documento OpenAPI fue No o Sí:

• No: Si no se proporcionó un documento OpenAPI, los servicios y métodos deben definirse manualmente (ver Definición manual a continuación).
• Sí: Si se proporcionó un documento OpenAPI, los servicios y métodos se descubren automáticamente a partir del documento OpenAPI y luego se seleccionan (ver Descubrimiento automático del documento OpenAPI a continuación).

Definición manual

• Definir Servicios y Métodos: Cuando no se proporcionó un documento OpenAPI en Paso 2: API existente, debes definir sus servicios y métodos manualmente utilizando estos campos:

  • Nombre del servicio: Ingresa un nombre para identificar el servicio.

  • Ruta: Ingresa una ruta para el servicio. Si la API no tiene una ruta de servicio, ingresa una barra diagonal (/).

    Nota

    No es posible usar caracteres como llaves ({ }) en una ruta de servicio al definir servicios manualmente. Para usar caracteres no permitidos en una ruta de servicio, proporciona en su lugar un documento OpenAPI que defina la ruta en Paso 2: API existente.

  • Métodos: Selecciona cada método que se creará para el servicio, eligiendo entre GET, PUT, POST, DELETE y Personalizado. Cuando se selecciona Personalizado, ingresa uno o más métodos personalizados separados por una coma en el cuadro de texto que aparece a continuación:

    

• Agregar Servicio: Una vez que se completen todos los campos, haz clic en Agregar Servicio para añadir el servicio a la tabla a continuación. Debe añadirse al menos un servicio para habilitar el botón Siguiente.

• Servicios Agregados: Una tabla muestra todos los servicios que se han agregado. Para eliminar un servicio agregado, haz clic en el ícono de eliminar .

• Siguiente: Haga clic para almacenar temporalmente la configuración de este paso y continuar al siguiente paso.

• Guardar Cambios: Si está habilitado, haga clic para guardar la configuración de este paso y navegar a Paso 5: Resumen y confirmación.

Descubrimiento automático del documento OpenAPI

• Definir Servicios y Métodos: Cuando se proporciona un documento OpenAPI en Paso 2: API Existente, sus servicios se descubren automáticamente del documento OpenAPI y se enumeran en una tabla con estas columnas:
  • Seleccionar: Seleccione los servicios para agregar al API proxy. La casilla de verificación en la columna del encabezado se puede usar para agregar todos los servicios disponibles a la vez.
  • Nombre del Servicio: El nombre utilizado para identificar el servicio.
  • Método(s): Los métodos que se aplican al servicio.
  • Ruta: La ruta del servicio.
• Siguiente: Haga clic para almacenar temporalmente la configuración de este paso y continuar al siguiente paso.
• Guardar Cambios: Si está habilitado, haga clic para guardar la configuración de este paso y navegar a Paso 5: Resumen y confirmación.
• Descartar Cambios: Después de realizar cambios, haga clic para cerrar la configuración sin guardar los cambios realizados en ningún paso. Un mensaje le pide que confirme que desea descartar los cambios.

Paso 4: Asignar perfiles de seguridad y encabezados de solicitud

• Perfil(es) de Seguridad: Los perfiles de seguridad se utilizan para restringir el acceso para el consumo del API. Puede escribir cualquier parte del nombre del perfil de seguridad en el menú para filtrar la lista de perfiles de seguridad. Los resultados del menú se filtran en tiempo real con cada pulsación de tecla. Puede ser necesario asignar un perfil de seguridad para guardar el API, dependiendo de las políticas de la organización Harmony.

  • Perfiles disponibles: Utiliza el menú desplegable para seleccionar un perfil de seguridad existente.

  • Asignar perfil: Haz clic para asignar un perfil de seguridad seleccionado a la API.

  • Crear nuevo perfil: Haz clic para crear un nuevo perfil de seguridad. Para instrucciones, consulta Perfiles de seguridad.

• Perfiles asignados: Una tabla lista los perfiles de seguridad asignados. Para eliminar un perfil asignado, haz clic en el ícono de eliminar.

• Encabezados de solicitud: Se pueden agregar nuevos encabezados de solicitud o sobrescribir encabezados de solicitud existentes utilizando la siguiente configuración.

  Nota

  De forma predeterminada, el encabezado de solicitud disable-hyphen-replacement está configurado en true para todas las nuevas APIs proxy. Una vez que la API proxy se publica, el encabezado de solicitud se puede configurar en false para reemplazar guiones (-) con guiones bajos (_) en los encabezados de solicitud (excepto para los encabezados de solicitud Content-Type, Content-Length, Accept-Encoding y Transfer-Encoding).

  • Clave: Ingresa una clave para el encabezado de solicitud.

  • Valor: Ingresa un valor para el encabezado de solicitud.

  • Sobrescribir entrada: Selecciona para sobrescribir un encabezado de solicitud existente que utilice la misma Clave. La opción predeterminada es no seleccionada.

  • Asignar campo de encabezado: Una vez que se han ingresado una Clave y un Valor, haz clic para asignar el encabezado de solicitud a la API.

• Campos de encabezado: Los campos de encabezado asignados anteriormente en la sección Encabezados de solicitud se muestran en una tabla. Para eliminar un campo de encabezado asignado, haz clic en el ícono de eliminar.

• Siguiente: Haz clic para almacenar temporalmente la configuración de este paso y continuar al siguiente paso. Si la API no tiene asignado un perfil de seguridad requerido, esta opción está deshabilitada.

• Guardar cambios: Si está habilitado, haz clic para guardar la configuración de este paso y navegar a Paso 5: Resumen y confirmación. Si la API no tiene asignado un perfil de seguridad requerido, esta opción está deshabilitada.

Paso 5: Resumen y confirmación

• Nombre del proxy y Entorno: El nombre de la API y el entorno, según se configuró en Paso 1: Configuración básica.

• Descripción, Tiempo de espera, Solo SSL, CORS habilitado y Registro detallado habilitado: La descripción de la API y otras configuraciones que están habilitadas () o deshabilitadas (). Para realizar cambios en esas configuraciones, haga clic en el ícono de edición para regresar a Paso 1: Configuración básica.

  • Habilitar modo de depuración hasta: Esta opción es la misma que la descrita en Paso 1: Configuración básica. Puede cambiar esta configuración directamente desde este paso en lugar de tener que regresar al primer paso.

• API existente: La URL base de la API proporcionada en Paso 2: API existente. Para realizar cambios, haga clic en el ícono de edición para regresar a Paso 2: API existente.

• Servicios y métodos: Los servicios definidos en Paso 3: Definir servicios y métodos. Para realizar cambios, haga clic en el ícono de edición para regresar a Paso 3: Definir servicios y métodos.

• Perfiles de seguridad y Encabezados de solicitud: Los perfiles de seguridad y los encabezados de solicitud asignados en Paso 4: Asignar perfiles de seguridad y encabezados de solicitud. Para realizar cambios, haga clic en el ícono de edición para regresar a Paso 4: Asignar perfiles de seguridad y encabezados de solicitud.

• Exportar: Genera e inicia la descarga de un archivo APK (apis-export.apk) que contiene una exportación de la API (ver Exportación e importación de APIs).

• Clonar: Crea una copia de una API existente. En la copia de la API, el Nombre del proxy se precede con Copia de, la Raíz del servicio se precede con Copia de y la Versión se le añade -2. La copia de la API se abre inmediatamente en su propio Paso 5: Resumen y confirmación.

• Eliminar: Elimina permanentemente la API y cierra la configuración. Un diálogo te pide que confirmes que deseas eliminar la API.

  Nota

  Si el estado de la API era Publicado o Publicado con Borrador en el momento de la eliminación, también se elimina del número de URLs Proxy utilizadas contra tu límite de suscripción. Si el estado de la API era Borrador en el momento de la eliminación, el número de URLs Proxy utilizadas contra tu límite de suscripción no cambia, ya que la API no era accesible mientras estaba en estado de Borrador.

• Guardar como Borrador: Guarda la API en estado de Borrador o estado de Publicado con Borrador:

  • Borrador: Una nueva API o una API cuyo estado era Borrador en el momento en que se utilizó Guardar como Borrador. Los borradores no cuentan contra tu límite de suscripción de URLs Proxy.
  • Publicado con Borrador: Una API cuyo estado era Publicado en el momento en que se utilizó Guardar como Borrador. Una API que está publicada con un borrador cuenta contra tu límite de suscripción de URLs Proxy, ya que la API es accesible aunque su borrador no lo sea.

• Guardar y Publicar: Guarda la API en estado de Publicado. La API está activa y accesible en cinco minutos. Una API publicada cuenta contra tu límite de suscripción de URLs Proxy, ya que la API es accesible. Un diálogo indica que la API está activa. Haz clic en Copiar URL para copiar la URL del servicio de la API (ver URL del servicio de API):

  

Editar la API

Después de guardar la API, puedes editarla desde estas ubicaciones:

• Usando vista de mosaico en la página de APIs, haz clic en Ver/Editar.
• Usando vista de lista en la página de APIs, haz clic en Editar en la columna de Acciones.