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 Studio. La opción Publicar como una 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 una API REST, incluida la configuración de respuestas y seguridad, consulta Exponer una operación de Studio como una API REST.

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

• La página APIs del Administrador de API.
• 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 una 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, comunícate con 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 una API en el menú de acciones de la operación, se abre un cajón 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 use con fines de identificación interna.

• Raíz del servicio: El nombre público de la API que se usa como parte de la URL del servicio de la API. De forma predeterminada, este campo se rellena con el nombre de la operación convertido a notación de camello. Este campo no permite espacios ni ciertos caracteres especiales. No se recomienda usar caracteres especiales que no sean un guión 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 actualmente en uso y no se puede cambiar.

• Número de versión: Ingresa una versión opcional para usar 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 guión (-). Las convenciones de nomenclatura comunes incluyen versiones incrementales, como v1.0, v1.1, v1.2, o usar una fecha de publicación de la API, como 2023-09-21.

Configuración

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

• Timeout: Ingresa el número de segundos antes de que la API agote el tiempo. El valor predeterminado es 30 segundos. El máximo es 180 segundos.

  Nota

  Este ajuste es independiente del ajuste Operation time out disponible en la pestaña Options de la operación. Los ajustes de timeout de operación no se utilizan para APIs de API Manager a menos que se utilice un agente privado y el ajuste EnableAPITimeout en el archivo de configuración del agente privado esté habilitado.

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

• CORS: Activa esta opción para habilitar Cross-Origin Resource Sharing (CORS) (no recomendado). Al activar esta opción, aparece el siguiente mensaje:

  Texto del diálogo

  Enable 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 se ejecute la operación asignada al método OPTIONS 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 Cross-Origin Resource Sharing en MDN.

  
  ContinueCancel

• Verbose logging: Activa esta opción 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, aparece el siguiente mensaje:

  Texto del diálogo

  Enable verbose logging
  El registro detallado para APIs permite que el usuario decida 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.

  
  ContinueCancel

• Enable debug mode until: Selecciona esta opción 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

  Enable debug mode
  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 e impacto potencial en el almacenamiento, el modo de depuración solo se puede habilitar por un máximo de dos semanas.

  
  ContinueCancel

Servicios

Configura servicios para tu API.

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

• Method: Selecciona entre ALL, CUSTOM, DELETE, GET, POST o PUT como el método de solicitud que se utilizará para la operación seleccionada. Si seleccionas ALL, se crearán métodos de solicitud DELETE, GET, POST y PUT separados 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 de la solicitud.

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

• Operación a activar: (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 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á 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 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 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 Parámetros de ruta

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

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

• Descripción: Opcionalmente, ingresa una descripción de 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 eliminación 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 ajustes 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. 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: Se pueden 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 de API 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. Se debe publicar la API para que el cambio surta efecto. Hasta que se publique la API, el perfil de seguridad se considera "en uso" y no se puede eliminar 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ónimo, 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. 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 los roles de la organización cuyos miembros tienen acceso a la API. Estas configuraciones son opcionales.

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

• Buscar: 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 administración de roles

    Estas reglas aplican para administrar roles en APIs:

    • Los usuarios con permiso Admin o acceso al 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 agrega a la tabla de roles.

  • Cancelar: Cierra el panel sin guardar los 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 Administració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 dependiendo de cuánto ya hayas configurado:

• Cancelar: Cierra el diálogo sin guardar.

• Anterior: Vuelve al paso anterior.

• Siguiente: Avanza al siguiente paso.

• Guardar como borrador: Guarda la API con 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 con estado Publicada. La API está activa y es accesible dentro de 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.