Configuración del Servicio OData

Introducción

Esta página describe cómo crear y configurar un servicio OData desde Mis APIs página de Harmony API Manager. Un servicio OData es uno de los tres tipos de APIs configurada a través del API Manager. Para los otros dos tipos ( API personalizada y API de proxy), consulte Configuración de API Personalizada o Configuración de proxy de API.

Prerrequisitos

Como un servicio OData expone una operación de entidad API de Harmony para su consumo, dicha operación debe crearse e desplegarse primero en Harmony. La operación que desencadena un servicio OData debe ser una operación de entidad API de Design Studio. Luego, durante la configuración del servicio OData, se hace referencia a la operación de la entidad API existente. En esta página, se utiliza la palabra API para hacer referencia a un servicio OData.

Para obtener información sobre cómo crear e 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 accedes al API Manager Mis APIs 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 un nuevo servicio OData, haga clic en Nueva API:

Al hacer clic en Nueva API, se abre la pantalla de configuración del servicio OData. En Configurar un servicio OData se proporcionan detalles sobre cómo configurar un nuevo servicio OData se proporcionan detalles sobre cómo configurar un nuevo servicio OData abajo.

Configurar un Servicio OData

La pantalla de configuración incluye cuatro pasos de configuración, cada uno de los cuales se describe a continuación:

• Paso 1: Configuración
• Paso 2: Seleccionar el tipo de servicio y asignar operaciones
• Paso 3: Asignar roles de usuario y perfiles de seguridad
• Paso 4: Resumen y confirmació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:

Paso 1: Configuración

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

  ( ) - _

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

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

• 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 un guión (-) no se recomienda. Las convenciones de nombres 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: 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 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).

  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). Habilitar CORS está seleccionado de manera predeterminada.

  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. Como esto puede crear archivos de registro grandes, el registro detallado está deshabilitado de manera predeterminada.

• Habilitar modo de depuración hasta: Seleccione esta opción para habilitar el modo de depurar y habilitar la entrada 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 habilita 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 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.

• 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 al Paso 4: Resumen y confirmación.

Paso 2: Seleccione el Tipo de Servicio y Asigne Operaciones

• Tipo de servicio: Seleccione servicio OData.

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

  • Entidad (Proyecto): Seleccione entre los proyectos implementados que contienen una operación de entidad API de Design Studio en el ambiente donde se está configurando la API.

  • Operación: Seleccione de las operaciones de entidad API de Design Studio implementado en la Entidad (Proyecto) seleccionada. Solo se puede asignar una operación que utilice cada método.

    Importante

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

    • Agentes de la nube: Para las operaciones de API en un agente de la nube, registro de depurar de operación debe estar habilitado en la operación.
    • Agentes privados: Para las operaciones de API en un agente privado, registro de depurar de la operación debe estar habilitado en la operación o debe configurar EnableLogging=true en el [APIOperation] sección del archivo de configuración del agente privado.

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

  • Método: Seleccione uno de los siguientes: GET, PUT, POST, DELETE, PATCH, MERGE, o ALL el método que se creará para la Operación seleccionada. Seleccionar ALL creará por separado GET, PUT, POST, DELETE, PATCH, y MERGE métodos para la Operación seleccionada.

• Asignar entidad: Una vez que se hayan completado todos los menús desplegables, haga clic en Asignar entidad para agregar la entidad a la tabla siguiente. Se debe agregar 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 botón eliminar icono.

• Siguiente: Haga clic para guardar 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 hasta Paso 4: Resumen y confirmación.

Paso 3: Asignar Roles de Usuario y Perfiles de Seguridad

• 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 enumeran a continuación. Los roles que se pueden elegir son los definidos en la página Administración de usuarios de la Management Console.

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

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

  Acceso a los Perfiles de seguridad La página 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).

  Los roles de usuario definidos con el permiso Admin siempre tienen acceso total a todas las APIs y, por lo tanto, no se pueden eliminar de la selección. (En la captura de pantalla de ejemplo que se muestra arriba, los roles Administrator y Operations no se pueden 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 utilizará 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.

  • Asignar perfil: Haga clic para asignar un perfil de seguridad seleccionado a la API. Los perfiles de seguridad asignados se enumeran en la tabla con el Nombre de perfil y el Tipo tal como se configuraron 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, haga clic en el botón 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 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á habilitada, haga clic para guardar la configuración de este paso. Si no se le asigna a la API un perfil de seguridad requerido, esta opción estará deshabilitada.

• Omitir este paso: Si está presente, haga clic para continuar con el siguiente paso sin almacenar la configuración de este paso. Si no se le asigna a la API un perfil de seguridad requerido, esta opción no está presente.

Paso 4: Resumen y Confirmación

• 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 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 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 de la API se antepone con Copia de, la raíz del servicio se antepone con Copia de y la versión se anexa 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. 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 API 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 API 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 URL de API.

• 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 tiene en cuenta para el límite de suscripción de URL de API, 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 API URL, ya que la API está accesible. Un cuadro de diálogo indica que la API está activa:

  

• 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 API para el Portal página. Aunque este enlace aparece para los servicios OData, se puede generar documentación OpenAPI para APIs personalizadas solamente.
• Descartar: Cierra el diálogo.

Consultas del Servicio OData

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