Configuración del servicio OData en Jitterbit API Manager

Introducción

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

Alternativamente, crea servicios OData usando el Asistente de IA de APIM.

Los servicios OData (publicados y borrador) se muestran en estas ubicaciones:

• La página APIs de API Manager.
• La pestaña Recursos del panel de proyectos para el proyecto de Design Studio asociado al servicio OData.

Requisitos previos

Un servicio OData expone una operación de entidad de API de Jitterbit iPaaS para su consumo. Primero debes crear e implementar esta operación antes de poder configurar el servicio OData. La operación que activa un servicio OData debe ser una operación de entidad de API de Design Studio.

Para obtener información sobre cómo crear e implementar una operación de entidad de API en Design Studio, consulta estos recursos:

• Guía de inicio rápido de Design Studio
• Crear una entidad de Jitterbit
• Crear una operación de entidad de API

Crear un nuevo servicio OData

Para crear un nuevo servicio OData, haz clic en Nuevo y selecciona una de las siguientes opciones:

• Crear con IA: Abre el Asistente de APIM para crear una API usando indicaciones en lenguaje natural. Para obtener más información, consulta Usar el Asistente de IA.

  Nota

  Para usar el Asistente de IA de APIM, tu licencia de Harmony debe incluir la opción Asistente de IA de APIM. Contacta a tu Gerente de Éxito del Cliente (CSM) para agregar esta opción a tu licencia.

• Servicio OData: Abre la pantalla de configuración del servicio OData para crear manualmente un nuevo servicio OData. Esta opción se habilita solo si hay una URL de API correspondiente disponible.

Configurar un servicio OData

Cuando configuras un servicio OData manualmente, la pantalla de configuración incluye múltiples pestañas. La pantalla de configuración incluye dos pestañas requeridas y tres pestañas opcionales:

• Pestaña Perfil (requerida)
• Pestaña Configuración (opcional)
• Pestaña Servicios (requerida)
• Pestaña Perfiles de seguridad (opcional)
• Pestaña Roles de usuario (opcional)

Pestaña Perfil

Usa la pestaña Perfil para ingresar información básica que identifique la API.

Configura los siguientes parámetros:

• Nombre de la API: Ingresa un nombre para la API que se usará para propósitos de identificación interna. Se permiten los siguientes caracteres especiales: ( ) - _.

• 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 completa con el Nombre de la API convertido a mayúsculas y minúsculas mixtas. Este campo no permite espacios ni ciertos caracteres especiales. No se recomienda usar caracteres especiales que no sean un guion bajo (_). Se permiten los siguientes caracteres especiales: . _ ~ ( ) $ ; / ? : @ = & ' ! * , + -.

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

• Entorno: Usa 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 crear la API, no puedes cambiar el entorno. Para mover una API entre entornos, puedes clonar la API o exportar e importar la API en otro entorno.

• Número de versión: Ingresa 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. No se recomienda usar caracteres especiales distintos de un punto (.) o un guion (-). 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 2025-08-28.

Después de completar la pestaña Perfil, haz clic en Siguiente para ir a la pestaña Configuración, o haz clic en Guardar como borrador para guardar tu progreso.

Pestaña Configuración

La pestaña Configuración es opcional y contiene opciones de configuración avanzada para la API.

Configura los siguientes parámetros según sea necesario:

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

  Nota

  Este parámetro es independiente del parámetro de tiempo de espera de la operación en Studio o Design Studio. Los parámetros de tiempo de espera de la operación no se utilizan a menos que se use un agente privado y el parámetro EnableAPITimeout en el archivo de configuración del agente privado esté habilitado.

• Solo SSL: Este interruptor está habilitado de forma predeterminada y requiere HTTPS para la API. Cuando está habilitado, los datos se cifran mediante SSL y una solicitud HTTP devuelve un error. Cuando está deshabilitado, se admiten solicitudes HTTP y HTTPS.

  Advertencia

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

• CORS: Habilita este interruptor para admitir CORS (Intercambio de Recursos entre Orígenes). CORS es un mecanismo que permite que aplicaciones web que se ejecutan en un navegador web en un dominio accedan a recursos de un servidor en un dominio diferente.

  Advertencia

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

• Registro detallado: Habilita este interruptor para agregar datos de solicitud y respuesta sin procesar —incluyendo encabezados, parámetros y cuerpos— al registro de llamadas cuando se realiza una solicitud de API. Estos datos aparecen en la página Registros de API y en la página Tiempo de ejecución de la Consola de administración para ejecuciones exitosas e infructuosas. El registro detallado no genera entradas de registro de operación de Studio para ejecuciones exitosas. Para registrar ejecuciones de operación exitosas en Studio, usa Habilitar modo de depuración hasta en su lugar.

  Advertencia

  El registro detallado puede incluir datos sensibles como credenciales de autenticación o información de identificación personal. Los valores de encabezados enmascarados están ocultos, pero los parámetros y cuerpos se registran en su totalidad. Usa este parámetro con cuidado.

• Habilitar modo de depuración hasta: Habilita este interruptor para activar el registro detallado para solucionar problemas, luego haz clic en el icono de calendario para seleccionar una fecha hasta dos semanas a partir de hoy cuando el modo de depuración se desactive automáticamente. Cuando está habilitado, los datos de solicitud y respuesta (conservados durante 30 días) aparecen en la página Registros de API, la página Tiempo de ejecución de la Consola de administración y los registros de operación de Studio para ejecuciones exitosas e infructuosas. El registro de depuración a nivel de actividad también está habilitado, capturando datos de entrada y salida de componentes en la pestaña Registro de depuración. Este parámetro anula Registro detallado y Mostrar cargas útiles de solicitud y respuesta en registros: cuando el modo de depuración está habilitado, los datos de solicitud y respuesta se incluyen en los registros independientemente de si esos parámetros están habilitados.

• Mostrar cargas útiles de solicitud y respuesta en registros: Activa este control para capturar y mostrar las cargas útiles de solicitud y respuesta en la página Registros de API y la página Tiempo de ejecución de la Consola de administración cuando se realiza una solicitud de API. Las cargas útiles aparecen en una vista formateada con paneles separados para los cuerpos de solicitud y respuesta, tanto para ejecuciones exitosas como fallidas. Esta configuración no genera entradas de registro de operaciones de Studio para ejecuciones exitosas. Para registrar ejecuciones de operaciones exitosas en Studio, usa Habilitar modo de depuración hasta en su lugar. Este control se aplica solo a API personalizadas y servicios OData.

  Advertencia

  Las cargas útiles de solicitud y respuesta pueden incluir datos sensibles como credenciales de autenticación o información de identificación personal. Usa esta configuración con cuidado.

Después de configurar la pestaña Configuración, haz clic en Siguiente para ir a la pestaña Servicios, o haz clic en Anterior para volver a la pestaña Perfil.

Pestaña Servicios

La pestaña Servicios es donde configuras los servicios de API que definen cómo responde la API a las solicitudes. Para servicios OData, asignas operaciones de entidad de Jitterbit que exponen datos a través del protocolo OData.

Haz clic en Nuevo servicio para agregar un nuevo servicio de API. Configura los siguientes parámetros para cada servicio:

• Entidad: Selecciona de los proyectos implementados que contienen una operación de entidad de API de Design Studio en el entorno donde estás configurando la API. El nombre de la entidad corresponde al nombre del proyecto en Design Studio.

• Proyecto: Muestra el nombre del proyecto de Design Studio que contiene la entidad seleccionada.

• Operación: Selecciona de las operaciones de entidad de API de Design Studio implementadas en la entidad seleccionada. Solo se puede asignar una operación usando cada método.

  Para obtener información sobre qué aparece en los registros de operaciones para operaciones activadas por API y cómo habilitar registro adicional, consulta Datos de solicitud y respuesta de API en Registros de operaciones.

• Método: Selecciona el método HTTP que se creará para la operación seleccionada. Los métodos disponibles incluyen GET, PUT, POST, DELETE, PATCH, MERGE o ALL. Al seleccionar ALL, se crean métodos GET, PUT, POST, DELETE, PATCH y MERGE separados para la operación seleccionada. Para usar un método que no aparezca en la lista, ingresa el nombre del método en el cuadro de texto Escribe un nuevo método y presiona Intro.

• Acciones: Pasa el cursor sobre una fila de servicio para revelar acciones adicionales.

  • Copiar URL del servicio de API: Haz clic para copiar la URL del servicio de la API.
  • Ir al servicio de API: Haz clic para ver una descripción general de una sola página de la configuración del servicio OData.
  • Duplicar: Haz clic para duplicar el servicio de API.
  • Eliminar: Haz clic para eliminar el servicio de API.

Puedes configurar varios servicios para un único servicio OData. Debes agregar al menos una entidad para proceder a la siguiente pestaña.

Después de configurar la pestaña Servicios, haz clic en Siguiente para ir a la pestaña Perfiles de seguridad, o haz clic en Anterior para volver a la pestaña Configuración.

Pestaña Perfiles de seguridad

La pestaña Perfiles de seguridad es opcional y te permite restringir el acceso para el consumo de la API.

Configura los siguientes parámetros:

• Asignar: Usa el botón para asignar o desasignar perfiles de seguridad para la API.

• Nombre del perfil: El nombre del perfil de seguridad tal como se configuró en Perfiles de seguridad.

• Tipo: El tipo de autenticación para el perfil de seguridad, como Básica, OAuth 2.0 o Clave de API.

• Nombre de usuario: Para autenticación básica, se muestra el nombre de usuario. Para otros tipos de autenticación, se muestra el mismo valor que la columna Tipo.

• Acciones: Pasa el cursor sobre una fila de perfil de seguridad para revelar acciones adicionales.

  • Ir al perfil de seguridad: Haz clic para abrir la configuración del perfil de seguridad.

Dependiendo de las políticas de la organización Harmony, es posible que se requiera asignar un perfil de seguridad para guardar la API.

Haz clic en Nuevo perfil de seguridad para crear un nuevo perfil de seguridad. Para obtener instrucciones, consulta Configurar perfiles de seguridad.

Después de configurar la pestaña Perfiles de seguridad, haz clic en Siguiente para ir a la pestaña Roles de usuario, o haz clic en Anterior para volver a la pestaña Servicios.

Pestaña Roles de usuario

La pestaña Roles de usuario es opcional y determina qué roles de la organización tienen acceso a la API dentro de API Manager.

Configura los siguientes parámetros:

• Rol de usuario: El nombre del rol de la organización tal como se define en la pestaña Roles de la página Gestión de usuarios.

• Permisos: Los permisos asignados a este rol, como Lectura o Administrador.

• Estado: Indica si el rol está asignado a esta API. Alterna el estado para asignar o desasignar roles.

• Acciones: Pasa el cursor sobre una fila de rol de usuario para revelar acciones adicionales.

  • Ir al rol de usuario: Haz clic para abrir la configuración del rol de usuario.

Los roles que selecciones aquí determinan el acceso a esta API específica desde estas páginas:

• APIs
• Gestor de portal, incluida la generación de documentación de API
• Portal de API
• Registros de API
• Análisis

El acceso a la página Perfiles de seguridad y el acceso para consumir la API no se ven afectados por esta selección. El acceso para consumir una API se controla mediante perfiles de seguridad.

Cualquier rol de usuario definido con permiso de Administrador siempre tiene acceso completo a todas las APIs y, por lo tanto, no se puede deseleccionar.

Haz clic en Nuevo rol de usuario para crear un nuevo rol de usuario. Para obtener instrucciones, consulta Roles en Gestión de usuarios.

Después de configurar la pestaña Roles de usuario, haz clic en Publicar para publicar la API, o haz clic en Guardar como borrador para guardar tu progreso.

Opciones de guardar y publicar

Después de configurar todas las pestañas requeridas, puedes guardar o publicar la API:

• Guardar como borrador: Guarda la API con estado Borrador o Publicada con borrador. Los borradores de API no cuentan contra tu límite de suscripción de URL de API. Una API cuyo estado era Publicada en el momento en que usas Guardar como borrador se guarda como Publicada con borrador. Una API publicada cuenta contra tu límite de suscripción de URL de API, aunque su borrador no sea accesible.

• Publicar: Guarda la API en estado Publicado. La API está activa y accesible en cinco minutos. Una API publicada cuenta contra el límite de suscripción de URL de API. Un diálogo indica que la API está activa:

  

  El diálogo proporciona estas opciones:

  • Copiar URL: Copia la URL del servicio de la API al portapapeles.
  • Generar documento OpenAPI: Abre la página Portal Manager. Para generar documentación de APIs individuales, usa la pestaña Documentación al editar la API desde la página APIs.
  • Cerrar: Cierra el diálogo.

Parámetros de consulta OData

Se pueden filtrar los datos que se devuelven agregando parámetros de consulta OData a la URL del servicio de un servicio OData. Los parámetros de consulta específicos admitidos dependen de la base de datos subyacente.

Los parámetros de consulta OData comunes incluyen:

https://jbexample.jitterbit.net/Sandbox/customers?$top=10&$orderby=name

Editar la API

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

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

Al editar una API publicada desde la vista de lista, también está disponible una pestaña Documentación. Usa esta pestaña para ver, editar y publicar documentación OpenAPI para APIs individuales. Para obtener más detalles, consulta la pestaña Documentación en la página APIs.

Solución de problemas

Para la solución de problemas relacionada, consulta lo siguiente en la guía de solución de problemas de API Manager:

• OData $count o $inlinecount devuelve un error cuando no hay registros coincidentes