Configuración de Proxy de API¶

Introducción¶

Esta página describe cómo crear y configurar una proxy de API desde Mis APIs página de Harmony API Manager. La proxy de API es uno de los tres tipos de APIs configurado a través de API Manager. Para los otros dos tipos ( API Personalizada y Servicio OData ), consulte Configuración de API Personalizada y Configuración del 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 proxy de API se utiliza con una API existente. Las APIs proxy no se enrutan a través de Harmony Agents. La API que se está representando debe ser accesible para la puerta de enlace que procesa la API:

• Pasarela de API en Nube: Si usa Pasarela de API en Nube (alojado por Jitterbit), la API existente debe ser accesible públicamente, incluso si está protegida. Es decir, la API que está intentando utilizar como proxy no puede estar detrás de un firewall. Para lista de permisos en la lista de direcciones IP de Pasarela de API en Nube para permitir el acceso de la puerta de enlace a la API que se está representando, consulte Información de la lista de permitidos y navega hasta https://services.jitterbit para su región.
• Pasarela de API Privada: Si utiliza una Pasarela de API Privada (alojada en una red privada) la API existente debe ser accesible mediante Pasarela de API Privada.

Aunque cada proxy de API permite asignar varios servicios a una URL única, la URL de Proxy base consume el derecho.

Crear una Nueva Proxy de API¶

Cuando accede al API Manager Mis APIs, si no existen APIs personalizadas, servicios OData o APIs de proxy en la organización seleccionada, esta pantalla está en blanco.

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

Al hacer clic en Nuevo Proxy, se abre la pantalla de configuración de la proxy de API. Los detalles sobre la configuración de una nueva proxy de API se proporcionan en Configuración de una proxy de API abajo.

Configurar una Proxy de API¶

La pantalla de configuración de proxy de API 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 utilizada 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 al 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 de proxy: Introduzca un nombre para que la API de proxy lo utilice con fines de identificación interna. Se permiten estos caracteres especiales:

  ( ) - _

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

• Ambiente: El ambiente donde reside la API.

  Nota

  Después de la creación de la API, el ambiente no se puede cambiar. Para mover una API entre ambientes, puede clonar la API o exportar e importar 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 forma predeterminada, este campo se completa con el Nombre de proxy convertido a caso camello. Este campo no permite espacios ni ciertos caracteres especiales. Usar caracteres especiales distintos de un guión bajo (_) no es recomendado. Se permiten estos caracteres especiales:

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

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

• Habilitar modo de depuración hasta: Seleccione para habilitar el modo de depurar y habilitar el ingreso de la 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 retiene el contenido completo de cada solicitud y respuesta de API durante hasta 24 horas desde el momento en que se recibió la llamada de API y se aplica a todas las operaciones activadas por la API.

  Nota

  Recorrer los datos del evento 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 utilizar el modo de depurar en un ambiente de producción.

• Tiempo de espera: Ingrese la cantidad de segundos antes de que expire 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 operación en Cloud Studio o Design Studio. La configuración del tiempo de espera de operación no se utiliza a menos que EnableAPITimeout configuración en el archivo de configuración del Agente Privado está habilitado.

• Solo SSL: Seleccione utilizar cifrado SSL (recomendado). Se selecciona el valor predeterminado.

• Habilitar CORS: Seleccione para habilitar Compartir recursos entre orígenes (CORS) (no recomendado). El valor predeterminado no está seleccionado.

  Advertencia

  Habilitar CORS provoca que las operaciones utilicen el OPTIONS Método para ejecutar 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 no está seleccionado.

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

• 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 para proxy.

  Nota

  Si la API proporciona un único 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 Examinar 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 icono emergente (después de abrir esa área, haga clic en el icono de retorno para volver a esta pantalla).

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

• Guardar cambios: Si está habilitado, haga clic para guardar la configuración para este paso y navegue hasta 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 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 era No o Sí:

• No: Si no se proporcionó un documento OpenAPI, los servicios y métodos deben definirse manualmente (consulte Definición manual abajo).
• 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, debes definir sus servicios y métodos manualmente usando estos campos:

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

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

    Nota

    Usar 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 un documento OpenAPI que defina la ruta en Paso 2: API existente.

  • Métodos: Seleccione cada método a 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 completen todos los campos, haga clic en Agregar servicio para agregar el servicio a la siguiente tabla. 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 icono de eliminación .

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

• Guardar cambios: Si está habilitado, haga clic para guardar la configuración para este paso y navegue 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 el Paso 2: API existente, sus servicios se descubren automáticamente a partir del documento OpenAPI y se enumeran en una tabla con estas columnas:
  • Seleccionar: Seleccione los servicios para agregar a la proxy de API. 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 para este paso y continuar con el siguiente.
• Guardar cambios: Si está habilitado, haga clic para guardar la configuración de este paso y navegar hasta 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: Asigne 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. Es posible que sea necesario 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 icono de eliminación .
• Encabezados de solicitud: Se pueden agregar nuevos encabezados de solicitud o se pueden anular los encabezados de solicitud existentes usando esta configuración:
  • Clave: Ingrese una clave para el encabezado de la solicitud.
  • Valor: Ingrese un valor para el encabezado de la solicitud.
  • Anular entrante: Seleccione para anular un encabezado de solicitud existente que utilice la misma Clave. El valor predeterminado no está seleccionado.
  • Asignar campo de encabezado: Una vez que se hayan ingresado una Clave y un Valor, haga 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, haga clic en el icono de eliminación .
• Siguiente: Haga clic para almacenar temporalmente la configuración para este paso y continuar con el siguiente. Si a la API no se le asigna un perfil de seguridad requerido, esta opción está deshabilitada.
• Guardar cambios: Si está habilitado, haga clic para guardar la configuración para este paso y navegue hasta Paso 5: Resumen y confirmación. Si a la API no se le asigna un perfil de seguridad requerido, esta opción está deshabilitada.

Paso 5: Resumen y Confirmación¶

• Nombre de proxy y Ambiente: El nombre y el ambiente de la API, tal como 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 discapacitado (). Para realizar cambios en esa configuración, haga clic en el ícono Editar para volver al Paso 1: Configuración básica.

  • Habilitar modo de depuración hasta: Esta opción es la misma que se describe 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 ícono Editar para volver al 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 Editar para volver al Paso 3: Definir servicios y métodos.

• Perfiles de seguridad y Encabezados de solicitud: Los perfiles de seguridad y encabezados de solicitud asignados en Paso 4: Asignar perfiles de seguridad y encabezados de solicitud. Para realizar cambios, haga clic en el ícono Editar para volver al 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 (consulte Exportación e importación de APIs).

• Clonar: Crea una copia de una API existente. En la copia de API, al Nombre de proxy se le antepone Copia de, a la Raíz de servicio se le antepone Copyof y a la Versión se le agrega -2. La copia de API se abre inmediatamente por sí sola Paso 5: Resumen y confirmación.

• Eliminar: Elimina permanentemente la API y cierra la configuración. Un cuadro de diálogo le pide que confirme que desea eliminar la API.

  Nota

  Si el estado de la API era Publicada o Publicada con borrador en el momento de la eliminación, también se elimina de la cantidad de URL de proxy utilizadas para su límite de suscripción. Si el estado de la API era Borrador en el momento de la eliminación, la cantidad de URL de proxy utilizadas contra su límite de suscripción no cambia, ya que no se podía acceder a la API mientras estaba en estado Borrador.

• Guardar como borrador: Guarda la API en estado Borrador o Publicado con estado 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 cuentan para el límite de suscripción de Proxy URL.
  • Publicado con borrador: Se utiliza una API cuyo estado era Publicado en el momento en que se utiliza Guardar como borrador. Una API que se publica con un borrador cuenta en el límite de suscripción de Proxy URL, ya que se puede acceder a la API aunque no se pueda acceder al borrador.

• Guardar y publicar: Guarda la API en estado Publicada. 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 se puede acceder a la API. Un cuadro de diálogo indica que la API está activa. Haga clic en Copiar URL para copiar la URL del servicio API (consulte URL del servicio API):