Publicar una operación como una API en Jitterbit Studio

Introducción

Esta página describe cómo configurar y publicar una API personalizada (para exponer una operación para su consumo) desde dentro de Studio. La opción Publicar como una API es accesible desde el menú de acciones de la operación.

Alternativamente, se pueden crear APIs personalizadas desde el API Manager utilizando la interfaz de usuario o el Asistente de IA.

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

• La página de APIs del API Manager.
• La pestaña de Recursos del panel del proyecto asociado con la API personalizada.

Requisitos previos

Para utilizar la opción Publicar como una API en el menú de acciones de la operación, se deben cumplir los siguientes requisitos previos:

• La organización a la que se accede debe tener una suscripción al API Manager y contar con los permisos de rol y niveles de acceso al entorno apropiados. Para obtener información sobre cómo agregar el API Manager a su licencia, comuníquese con su Gerente de Éxito del Cliente (CSM).

• La operación no debe tener ningún cambio no desplegado.

Configurar la API

Después de hacer clic en la opción Publicar como una API en el menú de acciones de la operación, se abre un panel de configuración de API en la parte inferior del diseñador de proyectos. Los cinco pasos del proceso de configuración se describen a continuación:

Perfil

Ingrese la siguiente información básica sobre la API.

• Nombre de la API: Ingrese un nombre para la API que se utilizará para fines de identificación interna.

• 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 operación convertido a camel case. Este campo no permite espacios ni ciertos caracteres especiales. No se recomienda el uso de caracteres especiales distintos de un guion bajo (_). Se permiten los siguientes caracteres especiales:

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

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

• Entorno: Este campo se establece en el entorno del proyecto que se está accediendo actualmente y no se puede cambiar.

• Número de versión: Ingrese una versión opcional que se utilizará como parte de la URL del servicio de la API. Este campo permite un máximo de 50 caracteres y no permite espacios ni ciertos caracteres especiales. No se recomienda el uso de 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 el uso de una fecha en que se publicó la API, como 2023-09-21.

Configuración

Continúe configurando la API. Estas configuraciones son opcionales.

• Tiempo de espera: Ingrese 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 operación disponible dentro de la pestaña Opciones de la operación. Las configuraciones de tiempo de espera de operación no se utilizan para las APIs del Administrador de API a menos que se utilice un agente privado y la configuración EnableAPITimeout en el archivo de configuración del agente privado esté habilitada.

• Solo SSL: Esta opción está activada por defecto y requiere el uso de cifrado SSL (recomendado).

• CORS: Actívelo para habilitar Cross-Origin Resource Sharing (CORS) (no recomendado). Activar este interruptor muestra el siguiente mensaje:

  Texto del diálogo

  Habilitar CORS
  Permitir que cualquier origen acceda a una API no se recomienda debido a posibles riesgos de seguridad. Una preocupación clave es que provoca que la operación asignada al método OPTIONS se ejecute sin autenticación. Antes de habilitar esta configuración, confirme que esté alineada con las políticas de seguridad de su organización.

  Para más información, consulte Cross-Origin Resource Sharing en MDN.

  
  ContinuarCancelar

• Registro detallado: Actívelo para habilitar el registro detallado. Los registros detallados para las APIs incluyen 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á desactivado por defecto. Activar este interruptor muestra el siguiente mensaje:

  Texto del diálogo

  Habilitar registro detallado
  El registro detallado para las APIs permite al usuario decidir si cada registro de API debe contener datos de solicitud y respuesta. Esta funcionalidad ayuda a monitorear los datos entrantes/salientes y depurar problemas de API.

  
  ContinuarCancelar

• Habilitar modo de depuración hasta: Seleccione para habilitar el modo de depuración y habilitar la entrada de 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. Activar este interruptor muestra el siguiente mensaje:

  Texto del diálogo

  Habilitar modo de depuración
  El modo de depuración habilita el seguimiento completo de todas las solicitudes recibidas a través de esta URL. Cuando está habilitado, el sistema captura el contenido completo de cada solicitud y respuesta de la API durante un máximo de 24 horas. Esto incluye todas las operaciones desencadenadas por la API. Debido al alto volumen de datos generados y al posible impacto en el almacenamiento, el modo de depuración solo se puede habilitar por un máximo de dos semanas.

  
  ContinuarCancelar

Servicios

Configura los servicios para tu API.

• Nombre del servicio: Ingresa un nombre para el servicio de la API. Por defecto, este campo se establece en el nombre de la operación.

• Método: Selecciona uno de TODOS, PERSONALIZADO, ELIMINAR, OBTENER, PUBLICAR o PONER como el método de solicitud a utilizar para la operación seleccionada. Seleccionar TODOS creará métodos de solicitud separados ELIMINAR, OBTENER, PUBLICAR y PONER para la operación (el método PERSONALIZADO no está incluido).

  Nota

  Los servicios de API que utilizan un método PERSONALIZADO no tendrán documentación OpenAPI generada a través de la página Portal Manager debido a una limitación de la especificación OpenAPI.

• Ruta: La ruta para la solicitud.

• Proyecto: (Visible solo para APIs personalizadas y APIs OData.) El nombre del proyecto de Studio.

• Operación a desencadenar: (Visible solo para APIs personalizadas y APIs OData.) El nombre de la operación que se está llamando.

• Tipo de respuesta: (Visible solo para APIs personalizadas y APIs OData.) Selecciona uno de Destino Final, Variable del Sistema o Sin Respuesta:

  • Destino Final: La respuesta de la API es el destino final de la operación. Cuando se selecciona este tipo de respuesta, la operación debe tener (como el destino final de la cadena de operaciones) una actividad de respuesta de API de Studio. Si se utiliza cualquier otro destino final, la respuesta de la API estará vacía.

  • Variable del Sistema: La respuesta de la API se establece en una variable de Jitterbit en la operación. Cuando se selecciona este tipo de respuesta, la operación debe tener (como parte de una cadena de operaciones) un script que establezca la variable de Jitterbit jitterbit.api.response igual a la respuesta que deseas que la API devuelva. Si esta variable no se establece, 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.

• Acciones: Pasa el cursor sobre la fila del servicio para revelar acciones adicionales:

  • Copiar URL del servicio API: Haz clic para copiar la URL del servicio API en tu portapapeles. (Verás una confirmación de la acción.)

  • Ir al Servicio API: Abre la página de Resumen y Confirmación para la API, donde puedes editar la configuración de la API.

  • Duplicar: (Visible solo para APIs personalizadas y APIs OData.) Crea un duplicado del servicio API. Debes cambiar ya sea el método de solicitud o la Ruta, ya que cada servicio API debe tener una combinación única de esos campos.

  • Eliminar: Elimina el servicio API.

Cuando haces clic en una fila de servicio API personalizada, aparecen estas pestañas:

Pestaña de parámetros de ruta

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

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

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

Pestaña de parámetros de consulta

Esta pestaña te permite agregar parámetros de consulta al servicio API:

• Agregar Parámetro: Haz clic para agregar un parámetro de consulta al servicio API. Al hacer clic, estos campos se vuelven disponibles:

  • Parámetro: Ingresa el nombre del parámetro de consulta.

  • Descripción: Opcionalmente, ingresa la descripción del parámetro de consulta.

  • Eliminar: Haz clic en el ícono de eliminar junto a un parámetro de consulta para eliminar ese parámetro.

Pestaña de Encabezados

Esta pestaña permite agregar encabezados de solicitud al servicio API:

• Agregar Parámetro: Haz clic para agregar un encabezado de solicitud al servicio API. Al hacer clic, estos campos se vuelven disponibles:

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

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

  • Requerido: Selecciona si el encabezado de solicitud debe ser requerido para cada solicitud del servicio API.

  • Eliminar: Elimina el encabezado de solicitud.

Perfiles de Seguridad

Configura perfiles de seguridad para la API. Estas configuraciones son opcionales.

• Buscar: Ingresa cualquier parte del nombre del perfil de seguridad, tipo o nombre de usuario en el cuadro de búsqueda para filtrar la lista de servicios. Usa solo caracteres alfanuméricos. La búsqueda no distingue entre mayúsculas y minúsculas.

• Nuevo perfil de seguridad: Abre un panel para configurar un nuevo perfil de seguridad (ver Perfiles de Seguridad):

  

La lista de perfiles de seguridad existentes para elegir se muestra en una tabla con las siguientes columnas:

• Asignar: Usa el interruptor para asignar o desasignar el perfil de seguridad a la API.

  Reglas de asignación de perfiles de seguridad

  • Múltiples perfiles: Puedes asignar múltiples perfiles de seguridad con el mismo tipo de autenticación a una API. Solo los tipos de autenticación básica y clave API pueden usarse juntos.

  • Publicación de cambios: Cuando desasignas un perfil de seguridad de una API usando el interruptor, el cambio se guarda como un borrador. Debes publicar la API para que el cambio surta efecto. Hasta que la API sea publicada, el perfil de seguridad se considera "en uso" y no puede ser eliminado de la página de Perfiles de Seguridad.

• Nombre del perfil: El nombre del perfil de seguridad.

• Tipo: El tipo de autenticación, uno de Anónimo, Clave API, Básico o OAuth 2.0.

• Nombre de usuario: Muestra el nombre de usuario para cualquier perfil de seguridad que utilice autenticación Básica. De lo contrario, se muestra el tipo de autenticación.

• Acciones: Pasa el cursor sobre la fila del perfil de seguridad para revelar una acción adicional:

  • Ir al perfil de seguridad: Abre la pantalla de configuración para el perfil de seguridad.

Roles de usuario

Configura los roles de la organización cuyos miembros tienen acceso a la API. Estas configuraciones son opcionales.

Puedes ordenar la tabla por Rol de usuario haciendo clic en la fila del encabezado respectivo.

• Buscar: Ingresa cualquier parte del rol de usuario, permiso o estado en el cuadro de búsqueda para filtrar la lista de servicios. Utiliza solo caracteres alfanuméricos. La búsqueda no distingue entre mayúsculas y minúsculas.

• Nuevo rol de usuario: Abre un panel para configurar un nuevo rol de usuario:

  

  • Nombre del rol: Ingresa un nombre único para el rol.

  • Permisos: Haz clic para abrir el menú, luego selecciona al menos un permiso de la lista.

    Reglas de gestión de roles

    Estas reglas se aplican para gestionar roles en APIs:

    • Los usuarios con Admin permiso o Escritura acceso al entorno pueden asignar o desasignar roles a las APIs.
    • Los usuarios con Admin permiso pueden crear y asignar nuevos roles.
    • Los usuarios con Admin permiso no pueden ser desasignados de ninguna API por ningún usuario.

  • Guardar: Guarda el rol y lo añade a la tabla de roles.

  • Cancelar: Cierra el panel sin guardar cambios.

• Permisos: Los permisos que un usuario tiene actualmente.

• Estado: Muestra si el rol de usuario está asignado o no asignado a la API.

• Acciones: Pasa el cursor sobre la fila del rol de usuario para revelar una acción adicional:

  • Ir al rol de usuario: Abre la página de Gestión de Usuarios de la Consola de Gestión.

Footer

El pie de página del panel muestra estas opciones. Pueden ser habilitadas o deshabilitadas dependiendo de cuánto hayas configurado ya:

• Cancelar: Cierra el diálogo sin guardar.

• Anterior: Regresa al paso anterior.

• Siguiente: Avanza al siguiente paso.

• Guardar como borrador: Guarda la API en estado Borrador y es accesible desde la página de APIs del Administrador de API. Una API en borrador no cuenta como una URL de API contra tu límite de suscripción de Harmony. Puedes acceder y completar la configuración de la API en borrador desde la página de APIs del Administrador de API.

• Publicar: Guarda la API en estado Publicado. La API está activa y accesible en cinco minutos. Una API publicada cuenta como una URL de API contra tu límite de suscripción de Harmony. Puedes acceder a la API publicada desde la página de APIs del Administrador de API.