Saltar al contenido

Configuración API Personalizada

Introducción

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

Alternativamente, se pueden crear APIs personalizadas en Cloud Studio usando Publicar como API opción a la que se accede desde un menú de acciones de operación.

Nota

Una vez publicada, cada API Personalizada cuenta como una URL de API para su asignación de suscripción a Jitterbit Harmony.

Requisitos Previos

Como una API Personalizada expone una operación de Jitterbit Harmony para su consumo, dicha operación primero debe crearse e desplegarse en Jitterbit Harmony. Luego se hace referencia a la operación existente durante la configuración de la API Personalizada. La operación que desencadena una API Personalizada puede ser Cloud 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 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 API Personalizada, haga clic en Nueva API:

sin apis nueva api

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

Configurar una API Personalizada

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

La URL de servicio de una API es la URL utilizada 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 al API Manager en URL del servicio API.

La URL del servicio se muestra en la parte superior de cada paso:

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 API: Introduzca un nombre para que la API lo utilice con fines de identificación interna.

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

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

  • 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 un guión (-) no es recomendado. Las convenciones de nomenclatura comunes incluyen versiones incrementales, como v1.0, v1.1, v1.2, o utilizando 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 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 un Agente Privado se utiliza y el EnableAPITimeout configuración en el archivo de configuración del Agente Privado está habilitado.

  • Solo SSL: Seleccione requerir el uso de cifrado SSL (recomendado). Sólo SSL está seleccionado de forma predeterminada.

  • Habilitar CORS: Seleccione para habilitar Compartir recursos entre orígenes (CORS) (no recomendado). Habilitar CORS está seleccionado de forma predeterminada.

    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. Como esto puede crear archivos de registro grandes, el valor predeterminado es que el registro detallado está deshabilitado.

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

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

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

Paso 2: Seleccionar el Tipo de Servicio y Asignar Operaciones

publicar nueva API paso 2 asignar operaciones personalizadas

  • Tipo de servicio: Seleccione API Personalizada.

  • Asignar proyecto: Utilice el menú para seleccionar un proyecto implementado del ambiente donde se está configurando la API (especificado en Paso 1: Configuración).

  • Editar proyecto: Cuando se selecciona un proyecto de Cloud Studio, este botón está habilitado. Al hacer clic en Editar proyecto, se abre el proyecto en Cloud Studio en una nueva pestaña.

    Nota

    Debe desplegar cualquier cambio realizado en el proyecto para que entre en vigor.

  • Asignar operación(es): Utilice los menús para seleccionar una Operación, Método y Tipo de respuesta para la API Personalizada:

    • Operación: Seleccione entre las operaciones implementadas en el proyecto seleccionado.

      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 si las configuraciones anteriores están habilitadas o no.

    • Método: Seleccione el método de solicitud que se utilizará para la operación seleccionada, uno de GET, PUT, POST, DELETE, TODO o PERSONALIZADO. Al seleccionar TODOS se crearán GET, PUT, POST, y DELETE métodos para la Operación seleccionada. Sólo se puede asignar una operación usando cada método.

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

    - **Objetivo final:** La respuesta API es el objetivo final de la cadena de operación. Cuando se selecciona este tipo de respuesta, la operación seleccionada debe tener, como destino final de la cadena de operación, una Cloud Studio [Actividad de respuesta API](/es/cloud-studio/cloud-studio-reference/connectors/api/request-activity) o [Actividad de escritura variable](/es/cloud-studio/cloud-studio-reference/connectors/variable/variable-write-activity/), o un objetivo de respuesta API de Design Studio o [objetivo de variable global](/es/design-studio/design-studio-reference/sources-and-targets/global-variable/global-variable-target/). Si se utiliza cualquier otro objetivo final, la respuesta de la API estará vacía.

- **Variable de sistema:** La respuesta API se establece en una variable Jitterbit en la cadena de operación. Cuando se selecciona este tipo de respuesta, la operación seleccionada debe tener, como parte de la cadena de operación, un secuencia de comandos que establezca la variable Jitterbit. `jitterbit.api.response` igual a la respuesta que desea que devuelva la API. 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á una respuesta vacía inmediata con el código HTTP 202.

  • Asignar operación: Una vez que se hayan seleccionado una Operación, un Método y un Tipo de respuesta, haga clic en Asignar operación para agregar la operación a la API Personalizada. Se debe agregar al menos una operación para habilitar el botón Siguiente.

    Nota

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

  • Operaciones asignadas: Una tabla muestra todas las operaciones que se han asignado a la API Personalizada. Para eliminar una operación asignada, haga clic en el icono de eliminación adjunto.

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

  • 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

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 enumeran a continuación. Los roles para elegir son aquellos definidos en la página Organizaciones de Management Console (consulte Administración de roles y permisos en Organizaciones).

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

    Acceso a los 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 eliminar de la selección. (En la captura de pantalla de ejemplo que se muestra arriba, las funciones Administrador y Operaciones no se pueden borrar por ese motivo).

    Nota

    Las APIs creadas antes de Harmony 10.22 tienen todas las funciones de usuario seleccionadas de forma predeterminada para garantizar el acceso continuo a 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. Es posible que sea necesario 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 Nombre de 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 Tipo es cualquier otro tipo, la columna Nombre de usuario muestra el mismo valor que Tipo. Para eliminar un perfil asignado, haga clic en el icono de eliminación adjunto.
    • 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 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. Si a la API no se le asigna un perfil de seguridad requerido, esta opción está deshabilitada.

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

Paso 4: Resumen y Confirmación

publicar nuevo resumen del paso 4 de la API

  • Nombre de API y Ambiente: El nombre de 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 ( marque 2) o deshabilitado (verificar 2). Para realizar cambios en esas configuraciones, haga clic en el ícono de edición Marque 2 para volver a Paso 1: Configuración.
    • Habilitar modo de depuración hasta: Esta opción es la misma que se describe 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 tipo de servicio y asignar operaciones con la información correspondiente al tipo de servicio seleccionado. Para realizar cambios, haga clic en el icono de edición adjunto para regresar al Paso 2: Seleccionar el 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 icono de edición adjunto para volver al 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 API, al Nombre de API 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 4: 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 como borrador en el momento de la eliminación, también se elimina de la cantidad de URL de API 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 API utilizadas para 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 API 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 API 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 en el límite de suscripción de API URL, ya que se puede acceder a la API. 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 API (consulte URL del servicio API).

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