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 de APIs de Jitterbit API Manager. Un servicio OData es uno de los tres tipos de APIs configurados a través del API Manager. Para los otros dos tipos — API personalizada y API proxy — consulte Configuración de API personalizada o Configuración de API proxy.

Requisitos previos

Dado que un servicio OData expone una operación de entidad API de Jitterbit iPaaS para su consumo, primero debe crearse y desplegarse dicha operación. La operación que un servicio OData activa debe ser una operación de entidad API de Design Studio. La operación de entidad API existente se referencia durante la configuración del servicio OData. En esta página, la palabra API se utiliza para referirse a un servicio OData.

Para obtener información sobre cómo crear y desplegar una operación de entidad API en Design Studio, consulte estos recursos:

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

Crear un nuevo servicio OData

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

Para crear un nuevo servicio OData, haz clic en Nuevo > API personalizada:

Al hacer clic en API personalizada, se abre la pantalla de configuración de la API. Los detalles sobre cómo configurar un nuevo servicio OData se proporcionan en Configurar un servicio OData a continuación.

Configurar un servicio OData

La pantalla de configuración incluye cuatro pasos de configuración, cada uno cubierto a continuación:

• Paso 1: Configuración
• Paso 2: Seleccionar tipo de servicio y asignar operaciones
• Paso 3: Asignar roles de usuario y perfiles de seguridad
• Paso 4: Resumen y confirmación

La URL del servicio de una API es la URL utilizada para consumir la API utilizando un 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

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

  ( ) - _

• 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 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 de la API 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:

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

• 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 2021-08-28.

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

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

  Nota

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

• Solo SSL: Cuando está seleccionado (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 está seleccionado, 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 exponer información sensible.

• Habilitar CORS: Selecciona para habilitar Cross-Origin Resource Sharing (CORS) (no recomendado). Habilitar CORS está seleccionado por defecto.

  Warning

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

• Habilitar Registro Detallado: Seleccionar para habilitar el registro detallado. El registro detallado para las API 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. Dado que esto puede crear archivos de registro grandes, la configuración predeterminada es que el registro detallado esté deshabilitado.

• Habilitar Modo de Depuración Hasta: Seleccionar para habilitar el modo de depuración y permitir ingresar 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.

  Note

  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 se recomienda utilizar el modo de depuración en un entorno de producción.

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

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

Paso 2: Seleccionar tipo de servicio y asignar operaciones

• Tipo de Servicio: Seleccionar servicio OData.

• Asignar Entidades Jitterbit: Utilizar los menús desplegables para seleccionar una Entidad (Proyecto), Operación y Método para el servicio OData:

  • Entidad (Proyecto): Seleccionar de los proyectos desplegados que contienen una operación de entidad API en el entorno donde se está configurando la API.

  • Operación: Seleccionar de las operaciones de entidad API desplegadas en la Entidad (Proyecto) seleccionada. Solo se puede asignar una operación utilizando cada método.

    Importante

    De forma predeterminada, las operaciones exitosas configuradas para un servicio OData no se incluyen en los registros de operaciones a menos que se habilite una de estas configuraciones:

    • Agentes en la nube: Para operaciones de API en un agente en la nube, se debe habilitar el registro de depuración de operaciones en la operación.
    • Agentes privados: Para operaciones de API en un agente privado, se debe habilitar el registro de depuración de operaciones en la operación o se debe establecer EnableLogging=true en la sección [APIOperation] del archivo de configuración del agente privado.

    Las operaciones no exitosas se incluyen en los registros de operaciones independientemente de si las configuraciones anteriores están habilitadas o no.

  • Método: Seleccione uno de GET, PUT, POST, DELETE, PATCH, MERGE, o ALL como el método a crear para la Operación seleccionada. Seleccionar ALL creará métodos separados GET, PUT, POST, DELETE, PATCH y MERGE para la Operación seleccionada.

• Asignar entidad: Una vez que se completen todos los menús desplegables, haga clic en Asignar entidad para agregar la entidad a la tabla a continuación. Debe agregarse al menos una entidad para habilitar el botón Siguiente.

  Nota

  Después de hacer clic en Asignar entidad, ya no podrá cambiar el Tipo de servicio.

• Entidades asignadas: Una tabla muestra todas las entidades que han sido asignadas. Para eliminar una entidad asignada, haga clic en el ícono de eliminar .

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

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

Paso 3: Asignar roles de usuario y perfiles de seguridad

• Asignar Roles de Usuario: Selecciona los roles de la organización cuyos miembros tendrán acceso a la API desde las páginas del Administrador de API que se enumeran a continuación. Los roles de los que se puede elegir son aquellos definidos en la página de Gestión de Usuarios del Consola de Gestión.

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

  • APIs
  • Administrador del Portal, incluida la generación de documentación de API
  • Portal
  • Registros de API
  • Analítica

  El acceso a la página de Perfiles de Seguridad y el acceso para consumir la API no se ven afectados por esta selección. (El acceso para consumir 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 desmarcar. (En la captura de pantalla de ejemplo mostrada arriba, los roles Administrador y Operaciones no se pueden desmarcar por esa razón.)

  Nota

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

• Asignar Perfil(es) de Seguridad: Usa el menú desplegable para seleccionar un perfil de seguridad existente que se utilizará para restringir el acceso para el consumo de la API. Puedes 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 la API, dependiendo de las políticas de la organización de Harmony.

  • Asignar Perfil: Haz clic para asignar un perfil de seguridad seleccionado a la API. Los perfiles de seguridad asignados se enumeran en la tabla con el Nombre del Perfil y Tipo según lo configurado 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 tipo, la columna Nombre de Usuario muestra el mismo valor que el Tipo. Para eliminar un perfil asignado, haz clic en el ícono de eliminar.

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

• Siguiente: Haga 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, haga clic para guardar la configuración de este paso. Si la API no tiene asignado un perfil de seguridad requerido, esta opción está deshabilitada.

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

Paso 4: Resumen y confirmación

• Nombre de la API y Entorno: El nombre de la API seguido del entorno entre paréntesis, según lo configurado 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 deshabilitadas (). Para realizar cambios en esas configuraciones, haga clic en el ícono de edición para regresar 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 regresar al primer paso.

• Operaciones: Las operaciones asignadas en Paso 2: Seleccionar tipo de servicio y asignar operaciones con la información correspondiente para el tipo de servicio seleccionado. Para realizar cambios, haga clic en el ícono de edición para regresar 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 Paso 3: Asignar roles de usuario y perfiles de seguridad. Para realizar cambios, haga clic en el ícono de edición para regresar 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 (ver 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 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 4: Resumen y confirmación.

• Eliminar: Elimina permanentemente la API y cierra la configuración. Un diálogo le pide 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 del número de URLs de API utilizadas contra su 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 de API utilizadas contra su 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 su límite de suscripción de URLs de API.

• Publicado con borrador: Una API cuyo estado era Publicado en el momento en que se utilizó Guardar como borrador. Una API que se publica con un borrador cuenta contra su límite de suscripción de URLs de API, 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 su límite de suscripción de URLs de API, ya que la API es accesible. Un diálogo indica que la API está activa:

  

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

• Generar documento OpenAPI: Abre la página del Portal Manager, donde puedes generar documentación de la API para la página del Portal. Aunque este enlace aparece para servicios OData, la documentación OpenAPI solo se puede generar para APIs personalizadas.
• Descartar: Cierra el diálogo.

Consultas de servicio OData

Dependiendo de la base de datos, puedes filtrar los datos que se devuelven al agregar parámetros de consulta OData (como $count, $inlinecount y $filter) a una URL de servicio OData.

Editar la API

Después de guardar el servicio OData, puedes editarlo 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.