Saltar al contenido

¡Transforma tus conexiones en dinero para el final del año con nuestro nuevo Programa de Indicación de Clientes! Descubre más

✕

Configuración de API personalizada en Jitterbit API Manager

Introducción

Esta página describe cómo crear y configurar una API personalizada desde las APIs página de Jitterbit API Manager. Las APIs personalizadas son uno de los tres tipos de APIs configurado a través del API Manager. Para los otros dos tipos (servicio OData y API de proxy), consulte Configuración del servicio OData y Configuración de la proxy de API.

Como alternativa, se pueden crear APIs personalizadas en Integration Studio utilizando Publicar como API opción a la que se accede desde un menú de acciones de la operación.

Nota

Una vez publicada, cada API personalizada cuenta como una URL de API en su asignación de suscripción a Harmony.

Las APIs personalizadas (publicadas y borradores) se muestran en estas ubicaciones:

  • Las APIs página del API Manager.
  • La pestañaRecursos del panel del proyecto para el proyecto de Integration Studio asociado con la API personalizada.

Prerrequisitos

Dado que una API personalizada expone una operación de Harmony para su uso, dicha operación debe crearse e desplegarse primero en Harmony. Posteriormente, se hace referencia a la operación existente durante la configuración de la API personalizada. La operación que activa una API personalizada puede ser Integration Studio o Design Studio operación.

Para obtener instrucciones sobre cómo crear e desplegar una operación, consulte estos recursos:

Crear una nueva API personalizada

Cuando accedes al API ManagerAPIs página, si no existen APIs personalizadas, servicios OData o APIs de proxy en la organización seleccionada, esta pantalla estará en blanco.

Para crear una nueva API personalizada, haga clic en Nuevo > API personalizada:

no hay APIs nueva API

Al hacer clic en Nueva API, se abre la pantalla de configuración de la API personalizada. Encontrará información detallada sobre cómo configurar una nueva API personalizada en Configurar una API personalizada abajo.

Configurar una API personalizada

La pantalla de configuración incluye cuatro pasos, que se describen a continuación:

La URL de servicio de una API es la URL que se utiliza para consumir la API mediante un 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 después de completar el paso 1:

publicar nueva URL del servicio de configuración del paso 1 de la API

Paso 1: Configuración

publicar nueva configuración del paso 1 de la API

  • Nombre de la API: Introduzca un nombre para la API que se usará para fines de identificación interna. Se permiten los siguientes caracteres especiales:

    ( ) - _

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

    Nota

    Tras crear la API, no se puede modificar el ambiente. Para mover una API entre ambientes, puede API o exportar e importar la API en otro ambiente.

  • Raíz del servicio: El nombre público de la API que se usará como parte de la URL del servicio de la API. De forma predeterminada, este campo se rellena con el nombre de la API convertido a camel case(https://lodash.com/docs/4.17.15#camelCase). Este campo no admite espacios ni ciertos caracteres especiales. Usar caracteres especiales distintos del guion bajo No se recomienda. Se permiten los siguientes caracteres especiales:

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

  • Versión: Ingrese una versión opcional para usarla como parte de la URL del servicio de la API. Este campo permite un máximo de 48 caracteres y no admite espacios ni ciertos caracteres especiales. Uso de caracteres especiales que no sean un punto. (.)o un guion (-) No se recomienda. Las convenciones de nomenclatura comunes incluyen versiones incrementales, como v1.0, v1.1, v1.2, o usar una fecha en la que se publicó la API, como 2021-08-28.

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

  • Tiempo de espera: Introduzca el número de segundos antes de que la API expire. 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 Integration Studio o Design Studio. Las configuraciones de tiempo de espera de operación no se utilizan a menos que un agente privado se utiliza y el 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).

    Al desmarcar esta opción, los datos transmitidos a través de las solicitudes y respuestas de la API no se cifran y pueden ser interceptados y vistos por otros. Esto podría exponer información confidencial.

  • Habilitar CORS: Seleccione para habilitar Intercambio de recursos entre orígenes (CORS) (no recomendado). Habilitar CORS está seleccionado por defecto.

    Advertencia

    Habilitar CORS provoca que las 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 supervisar los datos entrantes y salientes y facilitar la depuración. Dado que esto puede generar archivos de registro grandes, el registro detallado está deshabilitado por defecto.

  • Habilitar 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 para su depurar. El tiempo máximo de 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 de servicio de la API. Cuando está habilitado, el sistema conserva el contenido completo de cada solicitud y respuesta de la API hasta 24 horas desde la recepción de la llamada a la API y se aplica a todas las operaciones activadas por la API.

    Nota

    El análisis de 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 espacio de almacenamiento y seguridad. No recomendamos usar el modo de depurar en un ambiente de producción.

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

  • Guardar cambios: Haga clic para guardar la configuración de este paso y navegar a Paso 4: Resumen y confirmación.

Paso 2: Seleccione el tipo de servicio y asigne operaciones

seleccionar tipo de servicio

  • Tipo de servicio: Seleccione API personalizada.

  • Añadir servicio API: Haga clic para añadir un servicio API y exponer una operación de Harmony para su consumo. Al hacer clic, se abre la configuración individual del servicio API (descrita a continuación). Se pueden añadir varios servicios API a una API personalizada.

Después de hacer clic en Agregar servicio API, se abre la configuración de un servicio API:

publicar nueva API paso 2 asignar operaciones personalizadas

  • Método de solicitud: Use el menú para seleccionar el método de solicitud para el servicio API : GET, POST, PUT, DELETE, ALL o CUSTOM. Seleccionar ALL creará solicitudes independientes. GET, PUT, POST, y DELETE métodos para la Operación seleccionada (la CUSTOM El método no está incluido). Por defecto, el método de solicitud es GET.

    Nota

    Servicios API que utilizan una CUSTOM El método no tendrá documentación OpenAPI generada a través del Portal Manager debido a una limitación de la especificación OpenAPI.

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

  • Ruta: Opcionalmente, introduzca una ruta para la solicitud. La ruta debe comenzar con una barra diagonal. / y debe tener todos los parámetros de solicitud entre llaves { }No se permiten otros caracteres especiales.

    Nota

    La combinación del método de solicitud y Ruta debe ser única para cada servicio de API en la API personalizada.

  • Nombre del método personalizado: Visible cuando se selecciona CUSTOM como método de solicitud. Introduzca el nombre del método que se utilizará, por ejemplo, PATCH. (Caracteres alfabéticos, guiones) -, y subraya _ solo.)

  • Operación: Dentro de la pestaña Operación, selecciona un proyecto y una operación para asignar al servicio API (necesario para habilitar el botón Guardar):

    • Asignar proyecto: Use el menú para seleccionar un proyecto implementado del ambiente donde se está configurando la API (especificado en Paso 1: Configuración). Puede escribir cualquier parte del nombre del proyecto en el menú para filtrar la lista de proyectos. Los resultados del menú se filtran en tiempo real con cada pulsación de tecla.

    • Editar proyecto: Al seleccionar un proyecto de Integration Studio, este botón se activa. Al hacer clic en Editar proyecto, se abre el proyecto en Integration Studio en una nueva pestaña.

      Nota

      Debe desplegar cualquier cambio realizado en el proyecto para que surta efecto.

    • Asignar operación(es): Utilice los menús para seleccionar una Operación y un Tipo de respuesta para el servicio API:

      • Operación: Seleccione entre las operaciones implementadas en el proyecto seleccionado. Puede escribir cualquier parte del nombre de la operación en el menú para filtrar la lista de operaciones implementadas. Los resultados del menú se filtran en tiempo real con cada pulsación de tecla.

        Importante

        De forma predeterminada, las operaciones exitosas configuradas para una API personalizada no se incluyen en los registros de operación a menos que una de estas configuraciones esté habilitada:

        Las operaciones fallidas se incluyen en los registros de operación ya sea que las configuraciones anteriores estén habilitadas o no.

      • Tipo de respuesta: Seleccione uno de los siguientes: Objetivo final, Variable del sistema o Sin respuesta:

        • Objetivo final: La respuesta de la API es el objetivo final de la cadena de operación. Al seleccionar este tipo de respuesta, la operación seleccionada debe tener, como objetivo final de la cadena de operación, una actividad de respuesta de la API de Integration Studio o actividad de escritura variable, o un objetivo de respuesta de API de Design Studio o objetivo de variable global. Si se utiliza cualquier otro objetivo final, la respuesta de la API estará vacía.

        • Variable del sistema: La respuesta de la API se configura en una variable Jitterbit en la cadena de operación. Al seleccionar este tipo de respuesta, la operación seleccionada debe tener, como parte de la cadena de operación, un secuencia de comandos que configure la variable Jitterbit. jitterbit.api.response Igual a la respuesta que desea que la API devuelva. Si esta variable no está configurada, la respuesta de la API estará vacía.

        • Sin respuesta: La respuesta de la API está en blanco. Si se acepta la solicitud para ejecutar la operación seleccionada, la API devolverá inmediatamente una respuesta vacía con el código HTTP 202.

  • Parámetros de ruta: Cuando se incluyen parámetros de solicitud en la Ruta, esta pestaña se completa con estos campos:

    pestaña de parámetros de ruta

    • Parámetro: Muestra los parámetros de solicitud definidos en la Ruta.

    • Descripción: Opcionalmente, ingrese una descripción para los parámetros de la solicitud.

  • Parámetros de consulta: Esta pestaña le permite agregar cualquier parámetro de consultar al servicio API:

    pestaña de parámetros de consultar

    • Añadir parámetro: Haga clic para añadir un parámetro de consultar al servicio API. Al hacer clic, estos campos estarán disponibles:

      • Parámetro: Ingrese el nombre del parámetro de consultar.

      • Descripción: Opcionalmente, ingrese la descripción del parámetro de consultar.

      • Eliminar: Haga clic en el Eliminar icono junto a un parámetro de consultar para eliminar ese parámetro.

  • Encabezados: Esta pestaña le permite agregar cualquier encabezado de solicitud al servicio API:

    pestaña de encabezados

    • Añadir parámetro: Haga clic para añadir un encabezado de solicitud al servicio API. Al hacer clic, estos campos estarán disponibles:

      • Parámetro: Ingrese el nombre del encabezado de la solicitud.

      • Descripción: Opcionalmente, ingrese la descripción del encabezado de la solicitud.

      • Obligatorio: Seleccione si el encabezado de la solicitud debe ser obligatorio para cada solicitud de servicio de API.

      • Eliminar: Haga clic en el Eliminar icono junto a un encabezado de solicitud para eliminar ese encabezado.

  • Duplicar: Haga clic en el ícono de duplicado para crear un duplicado del servicio API.

    Nota

    Una vez que se duplica el servicio API, debe cambiar el método de solicitud o la Ruta, ya que cada servicio API debe tener una combinación única de esos campos.

  • Eliminar: Haga clic en el Eliminar icono junto a un servicio API para eliminarlo de la API personalizada.

  • Guardar: Haga clic para guardar el servicio API. Una vez completada la configuración de todos los servicios API, se habilitarán los botones Siguiente y Guardar cambios. Una configuración incompleta del servicio API se indica con un Icono de error junto al nombre del servicio API:

    servicio API incompleto

    Para resolver y habilitar los botones Siguiente y Guardar cambios, complete la configuración o elimine el servicio API.

  • Cancelar: Haga clic para cancelar la configuración del servicio API.

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

  • Guardar cambios: Haga clic para guardar la configuración de este paso y navegar a Paso 4: Resumen y confirmación.

Paso 3: Asignar roles de usuario y perfiles de seguridad

Publicar nuevos perfiles de seguridad de roles de usuario del paso 3 de la API

  • Asignar roles de usuario: Seleccione los roles de la organización cuyos miembros tendrán acceso a la API desde las páginas del API Manager que se muestran a continuación. Los roles disponibles son los definidos en la pestaña Roles de la página Administración de usuarios.

    Esto determina el acceso a esta API específica desde estas páginas:

    Acceso a los Perfiles de Seguridad La página y el acceso para usar la API no se ven afectados por esta selección. (El acceso para usar una API está controlado por perfiles de seguridad).

    Cualquier rol de usuario definido con el permiso Admin siempre tiene acceso completo a todas las APIs y, por lo tanto, no se puede eliminar de la selección. (En la captura de pantalla de ejemplo anterior, el rol Administrador no se puede eliminar por ese motivo).

    Nota

    Las APIs creadas antes de Harmony 10.22 tienen todos los roles de usuario seleccionados de forma predeterminada para garantizar el acceso continuo para todos los usuarios.

  • Asignar perfil(es) de seguridad: Utilice el menú desplegable para seleccionar un perfil de seguridad existente que se usará para restringir el acceso a la API. Puede escribir cualquier parte del nombre del perfil de seguridad en el menú para filtrar la lista de perfiles. Los resultados del menú se filtran en tiempo real con cada pulsación de tecla. Es posible que sea necesario asignar un perfil de seguridad para guardar la API, según las políticas de la organización de Harmony.

    • Asignar perfil: Haga clic para asignar un perfil de seguridad seleccionado a la API. Los perfiles de seguridad asignados se listan en la tabla con el Nombre de perfil y el Tipo configurados para el perfil de seguridad en Configuración del perfil de seguridad. Si el Tipo es Básico, la columna Nombre de usuario muestra el Nombre de usuario proporcionado durante la configuración. Si el Tipo es cualquier otro, la columna Nombre de usuario muestra el mismo valor que el Tipo. Para eliminar un perfil asignado, haga clic en el Eliminar icono.
    • Crear nuevo perfil: Haga clic para crear un nuevo perfil de seguridad. Para obtener instrucciones, consulte Configuración del perfil de seguridad.

  • Siguiente: Haga clic para guardar temporalmente la configuración de este paso y continuar con el siguiente. Si la API no tiene asignado un perfil de seguridad obligatorio, esta opción estará deshabilitada.

  • Guardar cambios: Si está habilitado, haga clic para guardar la configuración de este paso. Si la API no tiene asignado un perfil de seguridad obligatorio, esta opción estará deshabilitada.

  • Omitir este paso: Si está presente, haga clic para continuar al siguiente paso sin guardar la configuración. Si la API no tiene asignado un perfil de seguridad obligatorio, esta opción no está disponible.

Paso 4: Resumen y confirmación

publicar nuevo resumen del paso 4 de la API

  • Nombre de API **y Ambiente:** El nombre de la API seguido del ambiente entre paréntesis, tal como se configuró en Paso 1: Configuración.

    • 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 Editar icono para volver a Paso 1: Configuración.
    • Habilitar modo de depuración hasta: Esta opción es la misma que la descrita en Paso 1: Configuración puede cambiar esta configuración directamente desde este paso en lugar de tener que volver al primer paso.

  • Operaciones: Las operaciones asignadas en el Paso 2: Seleccionar el tipo de servicio y asignar operaciones con la información correspondiente al tipo de servicio seleccionado. Para realizar cambios, haga clic en el botón Editar icono para volver a Paso 2: Seleccionar tipo de servicio y asignar operaciones.

  • Roles de usuario y Perfiles de seguridad: Los roles y perfiles de seguridad asignados en el Paso 3: Asignar roles de usuario y perfiles de seguridad. Para realizar cambios, haga clic en el Editar icono para volver a Paso 3: Asignar roles de usuario y perfiles de seguridad.

  • 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 la API, el nombre de la API se antepone con Copia de, la raíz del servicio se antepone con Copia de y la versión se antepone con -2. La copia de la API se abre inmediatamente en su propio Paso 4: Resumen y confirmación.

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

    Nota

    Si el estado de la API era Publicado o Publicado con Borrador al momento de la eliminación, también se elimina del número de URL de API utilizadas para su límite de suscripción. Si el estado de la API era Borrador al momento de la eliminación, el número de URL de API utilizadas para su límite de 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 al usar Guardar como Borrador. Los borradores no se contabilizan para el límite de suscripción de API URL.

  • Publicado con borrador: Una API cuyo estado era Publicado al usar Guardar como borrador. Una API publicada con un borrador se descuenta del límite de suscripción de API 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 se contabiliza en el límite de suscripción de API URL, ya que la API está accesible. Un cuadro de diálogo indica que la API está activa:

    todo configurado, su API es una API personalizada en vivo

  • Copiar URL: Copia la URL del servicio de la API (vea URL del servicio de la API).

  • Generar documento OpenAPI: Abre el Administrador del portal página, donde puede generar documentación de API para el Portal página.
  • Descartar: Cierra el diálogo.