Publicar una operación como 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 Studio. La opción Publicar como API es accesible desde el menú de acciones de una operación.

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

Para un recorrido orientado a tareas sobre la publicación de una operación como API REST, incluyendo configuración de respuestas y seguridad, consulta Exponer una operación de Studio como API REST.

Las API personalizadas (publicadas 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 Studio asociado a la API personalizada.

Requisitos previos

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

• La organización a la que se accede debe tener una suscripción a API Manager y tener los permisos de rol y niveles de acceso al entorno apropiados. Para obtener información sobre cómo agregar API Manager a tu licencia, contacta a tu Gestor de éxito del cliente (CSM).

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

Configurar la API

Después de hacer clic en la opción Publicar como 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

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

• Nombre de API: Ingresa 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 de servicio de la API. De forma predeterminada, este campo se completa con el nombre de la operación convertido a mayúsculas y minúsculas mixtas. Este campo no permite espacios ni ciertos caracteres especiales. No se recomienda utilizar caracteres especiales distintos de un guion bajo (_). Se permiten estos caracteres especiales:

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

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

• Entorno: Este campo se establece en el entorno del proyecto al que se accede actualmente y no se puede cambiar.

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

Configuración

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

• Timeout: Ingresa el número de segundos antes de que la API agote el tiempo de espera. 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 disponible en la pestaña Opciones de la operación. Los ajustes de tiempo de espera de la operación no se utilizan para APIs de API Manager 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: Esta opción está activada de forma predeterminada y requiere el uso de encriptación SSL (recomendado).

• CORS: Activa para habilitar Intercambio de recursos entre orígenes (CORS) (no recomendado). Al activar esta opción, aparece el siguiente mensaje:

  Texto del diálogo

  Habilitar CORS
  No se recomienda permitir que cualquier origen acceda a una API debido a posibles riesgos de seguridad. Una preocupación clave es que hace que la operación asignada al método OPTIONS se ejecute sin autenticación. Antes de habilitar esta configuración, confirma que se alinea con las políticas de seguridad de tu organización.

  Para obtener más información, consulta Intercambio de recursos entre orígenes en MDN.

  
  ContinuarCancelar

• Registro detallado: Activa para habilitar el registro detallado. Los registros detallados de 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á deshabilitado de forma predeterminada. Al activar esta opción, aparece el siguiente mensaje:

  Texto del diálogo

  Habilitar registro detallado
  El registro detallado de 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: Selecciona para habilitar el modo de depuración e ingresa 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. Al activar esta opción, aparece 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 API durante un máximo de 24 horas. Esto incluye todas las operaciones activadas por la API. Debido al alto volumen de datos generados y el posible impacto en el almacenamiento, el modo de depuración solo se puede habilitar durante un máximo de dos semanas.

  
  ContinuarCancelar

Servicios

Configura servicios para tu API.

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

• Método: Selecciona entre ALL, CUSTOM, DELETE, GET, POST, o PUT como el método de solicitud a ser usado para la operación seleccionada. Si seleccionas ALL, se crearán métodos de solicitud separados DELETE, GET, POST, y PUT para la operación (el método CUSTOM no se incluye).

  Nota

  Los servicios de API que usan un método CUSTOM 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 ejecutar: (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.) Este campo es obligatorio. Selecciona una de las siguientes opciones: 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 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 devuelva la API. Si no se establece esta variable, la respuesta de la API estará vacía.

  • Sin respuesta: La respuesta de la API está vacía. Si la solicitud para ejecutar la operación seleccionada se acepta, la API devolverá una respuesta vacía inmediata con código HTTP 202.

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

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

  • Ir a la operación: Abre el proyecto de Studio en una nueva pestaña del navegador. La operación en el campo Operación a ejecutar se resalta en el lienzo de diseño de Studio. Esta acción está deshabilitada para operaciones de Design Studio.

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

  • Eliminar: Elimina el servicio de API.

Cuando haces clic en una fila de servicio de 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 completa 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 de API:

• Agregar parámetro: Haz clic para agregar un parámetro de consulta al servicio de API. Cuando se hace 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 icono de eliminar junto a un parámetro de consulta para eliminar ese parámetro.

Pestaña de encabezados

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

• Agregar parámetro: Haz clic para agregar un encabezado de solicitud al servicio de API. Cuando se hace 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.

  • Obligatorio: Selecciona si el encabezado de solicitud debe ser obligatorio para cada solicitud del servicio de 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 (consulta Perfiles de Seguridad):

  

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

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

  Reglas de asignación de perfiles de seguridad

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

  • Cambios de publicación: Cuando desasignas un perfil de seguridad de una API usando el botón de alternancia, el cambio se guarda como borrador. Debes publicar la API para que el cambio tenga efecto. Hasta que se publique la API, el perfil de seguridad se considera "en uso" y no puede eliminarse desde la página Perfiles de Seguridad.

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

• Tipo: El tipo de autenticación, uno de Anónima, Clave de API, Básica, u OAuth 2.0.

• Nombre de Usuario: Muestra el nombre de usuario para cualquier perfil de seguridad que use autenticación Básica. En caso 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 del perfil de seguridad.

Funciones de usuario

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

Puedes ordenar la tabla por Función de Usuario haciendo clic en el encabezado de la columna correspondiente.

• Buscar: Ingresa cualquier parte de la función de usuario, permiso o estado 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.

• Nueva función de usuario: Abre un panel para configurar una nueva función de usuario:

  

  • Nombre de la función: Ingresa un nombre único para la función.

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

    Reglas de gestión de funciones

    Estas reglas se aplican para administrar funciones en APIs:

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

  • Guardar: Guarda la función y la agrega a la tabla de funciones.

  • Cancelar: Cierra el panel sin guardar los cambios.

• Permisos: Los permisos que actualmente tiene un usuario.

• Estado: Muestra si la función de usuario está asignada o no asignada a la API.

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

  • Ir a función de usuario: Abre la página Gestión de Usuarios de la Consola de Administración.

Pie de página

El pie de página del panel muestra estas opciones. Pueden habilitarse o deshabilitarse 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 se puede acceder desde la página APIs del Administrador de API. Una API en borrador no cuenta como una URL de API en tu límite de suscripción de Harmony. Puedes acceder y completar la configuración de la API en borrador desde la página APIs del Administrador de API.

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