Configuración de la Proxy de API

Introducción

Esta página describe cómo crear y configurar una API de proxy desde Mis APIs página de Harmony API Manager. Una API proxy es uno de los tres tipos de APIs configurada 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 del servicio OData.

Prerrequisitos

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 proxy no se enrutan a través de agentes de Harmony. La API que se está proxyizando debe ser accesible para la puerta de enlace que procesa la API:

• Puerta de enlace de API en la nube: Si se utiliza la puerta de enlace de API en la nube (alojado por Jitterbit) la API existente debe ser accesible públicamente, incluso si está protegida. Es decir, la API que intentas usar como proxy no puede estar detrás de un firewall. Para lista de permisos las direcciones IP de la puerta de enlace de la API en la nube para permitir que la puerta de enlace acceda a la API que se está usando como proxy, consulta Información sobre la lista de permitidos y navegar a https://services.jitterbit para su región.
• Puerta de enlace de API privada: Si se utiliza una puerta de enlace de API privada (alojado en una red privada) la API existente debe ser accesible mediante la puerta de enlace de API privada.

Si bien cada API de proxy permite que se asignen múltiples servicios a una URL única, la URL del proxy base es la que consume el derecho.

Crear una Nueva API de Proxy

Cuando accedes al API Manager Mis APIs página, si no existe ninguna API personalizada, servicio OData o API de proxy en la organización seleccionada, esta pantalla estará en blanco.

Para crear una nueva API de proxy, haga clic en Nuevo proxy:

Al hacer clic en Nuevo proxy, se abre la pantalla de configuración de la API de proxy. En Configurar una API de proxy se proporcionan detalles sobre cómo configurar una nueva API de proxy abajo.

Configurar una API de Proxy

La pantalla de configuración de la API de proxy incluye cinco pasos de configuración, cada uno de los cuales se describe 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 de servicio de una API es la URL que se utiliza para consumir la API mediante el método de autenticación configurado. Las partes de la URL de servicio de una API se describen en Introducción a API Manager en URL del servicio API.

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

Paso 1: Configuración Básica

• Nombre del proxy: Ingrese un nombre para que la API del proxy lo use con fines de identificación interna. Se permiten los siguientes caracteres especiales:

  ( ) - _

• Número de versión: Ingrese una versión opcional para usar 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. El uso de caracteres especiales distintos de un punto (.) o guión (-) no se recomienda. Las convenciones de nombres de ejemplo 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.

• Ambiente: Utilice el menú para seleccionar el ambiente en el que residirá la API. Puede escribir cualquier parte del nombre del ambiente en el menú para filtrar la lista de ambientes. Los resultados del menú se filtran en tiempo real con cada pulsación de tecla.

  Nota

  Después de crear la API, no se puede cambiar el ambiente. Para mover una API entre ambientes, puedes API o exportarla e importarla la API en otro ambiente.

• Raíz del servicio: El nombre público de la API que se utilizará como parte de la URL del servicio de la API. De manera predeterminada, este campo se completa con el Nombre del proxy convertido a camel case. Este campo no permite espacios ni determinados caracteres especiales. El uso de caracteres especiales distintos del guión bajo (_) no se recomienda. Se permiten estos caracteres especiales:

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

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

• Habilitar el modo de depuración hasta: Seleccione esta opción para habilitar el modo de depurar y permitir la introducción de una fecha y hora correspondientes en las que se deshabilitará el modo de depurar. La duración máxima de la habilitación es de dos semanas. El modo de depuración permite el seguimiento completo de cada solicitud recibida a través de la URL del servicio de la API. Cuando está habilitado, el sistema conserva el contenido completo de cada solicitud y respuesta de la API durante hasta 24 horas desde el momento en que se recibió la llamada a la API y se aplica a todas las operaciones activadas por la API.

  Nota

  Recorrer los datos de eventos puede resultar difícil con grandes volúmenes (pruebas de carga, pruebas de preproducción, etc.). El aumento de los datos retenidos puede generar problemas de seguridad y espacio de almacenamiento. No recomendamos usar el modo de depurar en un ambiente de producción.

• Tiempo de espera: Ingrese la cantidad de segundos que deben transcurrir antes de que se agote el tiempo de espera de la API. El valor predeterminado es 30 segundos. El máximo es 180 segundos.

  Nota

  Esta configuración es independiente de la configuración del tiempo de espera de la operación en Cloud Studio o Design Studio. Los ajustes de tiempo de espera de operación no se utilizan a menos que EnableAPITimeout configuración en el archivo de configuración del agente privado está habilitado.

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

  Si no se selecciona esta opción, los datos que se transmiten a través de solicitudes y respuestas de API no se cifran y otros pueden interceptarlos y verlos, lo que podría exponer información confidencial.

• Habilitar CORS: Seleccione para habilitar Intercambio de recursos entre orígenes (CORS) (no recomendado). La opción predeterminada no está seleccionada.

  Advertencia

  Habilitar CORS provoca operaciones que utilizan el OPTIONS método para ejecutar sin autenticación.

• Habilitar registro detallado: Seleccione esta opción 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. La opción predeterminada no está seleccionada.

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

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

paso 2: API Existente

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

  Nota

  Si la API proporciona un solo servicio, puede ingresar la URL completa de la API, incluida 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 cuadro de diálogo para cargar un documento OpenAPI en formato YAML o JSON desde una URL:

    

  • Cargar archivo: Abre un cuadro de diálogo para cargar un documento OpenAPI en formato YAML o JSON después de usar Explorar para seleccionar el archivo:

    

  • Borrar: Borra un documento OpenAPI que ya se ha proporcionado y cambia la selección Proporcionar documento OpenAPI a No.

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

• Siguiente: Haga clic para almacenar temporalmente la configuración de este paso y continuar con el 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 los cambios, haga clic para cerrar la configuración sin guardar los cambios realizados en ningún paso. Un mensaje le solicitará que confirme que desea 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 Proporcionar documento OpenAPI fue No o Sí:

• No: Si no se proporcionó un documento OpenAPI, los servicios y métodos deben definirse manualmente (consulte 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 (consulte Descubrimiento automático de documentos OpenAPI abajo).

Definición Manual

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

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

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

    Nota

    El uso de caracteres como llaves ({ }) en una ruta de servicio no es posible cuando se definen servicios manualmente. Para utilizar caracteres no permitidos en una ruta de servicio, proporcione en su lugar un documento OpenAPI que defina la ruta en Paso 2: API existente.

  • Métodos: Seleccione cada método que se creará para el servicio, seleccionando entre GET, PUT, POST, DELETE y Personalizado. Cuando se selecciona Personalizado, ingrese 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 hayan completado todos los campos, haga clic en Agregar servicio para agregar el servicio a la tabla que aparece a continuación. Se debe agregar 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, haga clic en el botón eliminar icono.

• Siguiente: Haga clic para guardar temporalmente la configuración de este paso y continuar con el siguiente paso.

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

Descubrimiento Automático de Documentos OpenAPI

• Definir servicios y métodos: Cuando se proporcionó un documento OpenAPI en Paso 2: API existente, sus servicios se descubren automáticamente desde el documento OpenAPI y se enumeran en una tabla con estas columnas:
  • Seleccionar: Seleccione los servicios que desea agregar a la API del proxy. La casilla de verificación en la columna de 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 con el 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 los cambios, haga clic para cerrar la configuración sin guardar los cambios realizados en ningún paso. Un mensaje le solicitará que confirme que desea descartar los cambios.

Paso 4: Asignar Perfiles de Seguridad y Encabezados de Solicitud

• Perfiles de seguridad: Los perfiles de seguridad se utilizan para restringir el acceso para el consumo de la 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. Es posible que se requiera asignar un perfil de seguridad para guardar la API, según las políticas de la organización Harmony.

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

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

  • Crear nuevo perfil: Haga clic para crear un nuevo perfil de seguridad. Para obtener instrucciones, consulte Configuración del perfil de seguridad.

• Perfiles asignados: Una tabla enumera los perfiles de seguridad asignados. Para eliminar un perfil asignado, haga clic en el botón eliminar icono.

• Encabezados de solicitud: Se pueden agregar nuevos encabezados de solicitud o se pueden anular los encabezados de solicitud existentes utilizando las siguientes configuraciones.

  Nota

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

  • Clave: Ingrese una clave para el encabezado de la solicitud.

  • Valor: Ingrese un valor para el encabezado de la solicitud.

  • Anular entrada: Seleccione esta opción para anular un encabezado de solicitud existente que use la misma clave. La opción predeterminada no está seleccionada.

  • Asignar campo de encabezado: Una vez que se hayan ingresado una Clave y un Valor, haga clic para asignar el encabezado de la 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, haga clic en el botón eliminar icono

• Siguiente: Haga clic para almacenar temporalmente la configuración de este paso y continuar con el siguiente. Si no se le asigna a la API un perfil de seguridad requerido, esta opción estará deshabilitada.

• Guardar cambios: Si está habilitado, haga clic para guardar la configuración de este paso y navegue a Paso 5: Resumen y confirmación. Si a la API no se le asigna un perfil de seguridad requerido, esta opción estará deshabilitada.

Paso 5: Resumen y Confirmación

• Nombre del proxy y Ambiente: El nombre de la API y el ambiente, tal como se configuraron 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 discapacitados (). Para realizar cambios en esas configuraciones, haga clic en el botón editar icono para volver 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 volver al primer paso.

• API existente: La URL de API base proporcionada en Paso 2: API existente. Para realizar cambios, haga clic en el editar icono para volver 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 editar icono para volver 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 el Paso 4: Asignar perfiles de seguridad y encabezados de solicitud. Para realizar cambios, haga clic en el editar icono para volver a Paso 4: Asignar perfiles de seguridad y encabezados de solicitud.

• Exportar: Genera e inicia una descarga de un archivo APK (apis-export.apk) que contiene una exportación de la API (consulte 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 antepone con Copia de, la Raíz del servicio se antepone con Copia de y la Versión se adjunta con -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. Aparecerá un cuadro de diálogo que le solicitará que confirme que desea 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 de la cantidad de URL de proxy utilizadas para el límite de su suscripción. Si el estado de la API era Borrador en el momento de la eliminación, la cantidad de URL de proxy utilizadas para el límite de su suscripción no cambia, ya que la API no era accesible mientras estaba en estado Borrador.

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

  • Borrador: Una API nueva o una API cuyo estado era Borrador en el momento en que se utilizó Guardar como borrador. Los borradores no se tienen en cuenta para el límite de suscripción de Proxy URL.
  • Publicado con borrador: Una API cuyo estado era Publicado en el momento en que se usa Guardar como borrador. Una API que se publica con un borrador se descuenta del límite de suscripción de Proxy URL, ya que la API es accesible aunque su borrador no lo sea.

• Guardar y publicar: Guarda la API en estado Publicado. La API está activa y accesible en cinco minutos. Una API publicada cuenta para el límite de suscripción de Proxy URL, ya que la API está accesible. Un cuadro de diálogo indica que la API está activa. Haga clic en Copiar URL para copiar la URL del servicio de la API (consulte URL del servicio de la API):