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 APIs personalizadas desde API Manager usando la interfaz de usuario o el Asistente de IA.

Para un recorrido orientado a tareas sobre cómo publicar una operación como API REST, incluyendo configuración de respuesta y seguridad, consulta Exponer una operación de Studio como API REST.

Las APIs 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 con la API personalizada.

Requisitos previos

Para usar 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 de entorno apropiados. Para obtener información sobre cómo agregar API Manager a tu licencia, contacta a tu Gerente de éxito del cliente (CSM).

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

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 la API: Ingresa un nombre para la API que se usará para propósitos de identificación interna.

• Raíz del servicio: El nombre público de la API que se usará como parte de la URL del 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 usar caracteres especiales que no sean 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 para usarla 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 usar caracteres especiales que no sean 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 2023-09-21.

Configuración

Continúa configurando la API. Estos ajustes son opcionales.

• Tiempo de espera: 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

  Este ajuste es independiente del ajuste 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 las APIs de API Manager a menos que se use un agente privado y el ajuste EnableAPITimeout en el archivo de configuración del agente privado esté habilitado.

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

• CORS: Activa para habilitar Intercambio de recursos entre orígenes (CORS) (no recomendado). Al activar esta opción se muestra 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 este ajuste, 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 para APIs incluyen datos de solicitud y respuesta en cada registro de API para ayudar a monitorear 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 se muestra el siguiente mensaje:

  Texto del diálogo

  Habilitar registro detallado
  El registro detallado para APIs permite al usuario decidir si cada registro de API debe contener datos de solicitud y respuesta. Esta funcionalidad ayuda a monitorear 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 se muestra el siguiente mensaje:

  Texto del diálogo

  Habilitar modo de depuración
  El modo de depuración habilita el rastreo 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 e impacto potencial 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 que se utilizará para la operación seleccionada. Al seleccionar 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 utilizan un método CUSTOM no tendrán documentación de OpenAPI generada a través de la página Portal Manager debido a una limitación de la especificación de OpenAPI.

• Ruta: La ruta para la solicitud.

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

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

• Tipo de respuesta: (Visible solo para API personalizadas y API 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 se acepta la solicitud para ejecutar la operación seleccionada, la API devolverá una respuesta vacía inmediata con código HTTP 202.

• Acciones: Pasa el cursor sobre la fila del servicio para revelar 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 al servicio de API: Abre la página Resumen y confirmación de la API, donde puedes editar la configuración de la API.

  • Duplicar: (Visible solo para API personalizadas y API 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 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 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 están 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 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 están 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. Estos parámetros son opcionales.

• Búsqueda: 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. Solo se pueden usar caracteres alfanuméricos. La búsqueda no distingue mayúsculas de 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 basic y API key se pueden usar 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 surta efecto. Hasta que se publique la API, el perfil de seguridad se sigue considerando "en uso" y no se puede eliminar de la página Perfiles de seguridad.

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

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

• Nombre de usuario: Muestra el nombre de usuario para cualquier perfil de seguridad que use 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 del perfil de seguridad.

Roles de usuario

Configura roles de organización cuyos miembros tengan acceso a la API. Estos ajustes son opcionales.

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

• Búsqueda: Ingresa cualquier parte del rol de usuario, permiso o estado en el cuadro de búsqueda para filtrar la lista de servicios. Solo se pueden usar caracteres alfanuméricos. La búsqueda no distingue mayúsculas de 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ú y 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 permiso Admin o acceso de entorno Escritura pueden asignar o desasignar roles a APIs.
    • Los usuarios con permiso Admin pueden crear y asignar nuevos roles.
    • Los usuarios con permiso Admin 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 tiene actualmente un usuario.

• 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 Gestión de usuarios de la Consola de administración.

Pie de página

El pie de página del panel muestra estas opciones. Se pueden habilitar o deshabilitar según cuánto ya hayas configurado:

• 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 APIs del Administrador de API. Una API en borrador no cuenta como una URL de API contra tu asignación 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 Publicada. La API está activa y es accesible en cinco minutos. Una API publicada cuenta como una URL de API contra tu asignación de suscripción de Harmony. Puedes acceder a la API publicada desde la página APIs del Administrador de API.