Página de registros de API en Jitterbit API Manager

Introducción

La página de Registros de API dentro del API Manager muestra una tabla de todos los registros de procesamiento de API, así como registros de depuración (si el registro de depuración está habilitado). Los registros se muestran para APIs personalizadas, OData y proxy cuando se llaman a través del gateway de API en la nube o gateway de API privado.

Hay cuatro tipos de registros que se pueden registrar para una llamada de API:

• Registros de API: Los registros de API se generan automáticamente en la página de Registros de API para cada llamada de API del API Manager. Los registros de API contienen información sobre la llamada de API, incluyendo la marca de tiempo de la solicitud de API, el código de estado HTTP, el ID de la solicitud, el método de la solicitud, la URI de la solicitud, el tiempo de respuesta, la IP de origen de la aplicación que llama, la aplicación de origen y cualquier mensaje de registro.
• Registros de depuración de API: Los registros de depuración de API son entradas adicionales en un registro de API existente que rastrean completamente cada solicitud recibida a través de la URL de servicio de un API del API Manager. El registro de depuración de API no está habilitado por defecto y debe ser habilitado en un API del API Manager individual para que los registros de depuración de API se incluyan en un registro de API.
• Registros detallados de API: Los registros detallados de API son entradas adicionales en un registro de API existente que consisten en datos de solicitud y respuesta recibidos o enviados a través de la URL de servicio de un API del API Manager. El registro detallado de API no está habilitado por defecto y debe ser habilitado en un API del API Manager individual para que los registros detallados de API se incluyan en un registro de API.
• Registros de operación de API: Los registros de operación de API contienen el inicio de una llamada de API y el tiempo transcurrido. A diferencia de los registros de API, registros de depuración y registros detallados, los registros de operación de API requieren el uso de un agente privado y están habilitados en el archivo de configuración del agente privado. Estos registros se graban en el agente privado en el archivo jitterbit.log ubicado en el directorio log.

Los datos de registro para registros de API, registros de depuración y registros detallados están disponibles en la página de Registros de API durante 90 días a partir de la fecha en que se consume la API.

Para obtener más información sobre cómo habilitar los registros de depuración y los registros detallados, consulte estos recursos:

• Paso 1: Configuración de configuración de API personalizada
• Paso 1: Configuración de configuración de servicio OData
• Paso 1: Configuración básica de configuración de API proxy

Para agregar información adicional de registro para APIs OData, incluyendo datos SQL enviados a la base de datos, edite el archivo de configuración del agente privado y establezca DebugJDML en true.

Acceder a la página de registros de API

Para acceder a la página de Registros de API, use el menú del portal Harmony para seleccionar API Manager > Registros de API.

Encabezado de la página de registros de API

El encabezado en la parte superior de la página de Registros de API incluye una barra de búsqueda, filtros y opciones adicionales:

Puede ajustar los datos mostrados utilizando los menús desplegables Filtrar por y Ver datos.

Filtrar por

Los menús desplegables Filtrar por permiten mostrar los registros de API según criterios específicos en cualquier combinación de entornos, APIs, perfiles, códigos de estado o métodos de solicitud.

Cada filtro muestra una lista desplegable de criterios de los cuales puede seleccionar uno o múltiples criterios.

Estos son los criterios disponibles para filtrar:

• Entornos: Use el menú desplegable para seleccionar los entornos donde se encuentran las APIs. Cuando todos los filtros están deseleccionados, se muestran los entornos de todas las APIs en la organización a la que tiene acceso.

• APIs: Utiliza el menú desplegable para seleccionar las APIs publicadas dentro de la organización. Cuando todos los filtros están deseleccionados, se muestran todas las APIs en la organización a las que tienes acceso.

  Nota

  Las APIs publicadas anteriormente que se vuelven no publicadas no aparecerán en el menú desplegable de APIs. Los registros de API para estas APIs estarán presentes en la página de Registros de API, pero no se pueden filtrar.

• Perfiles: Utiliza el menú desplegable para seleccionar los perfiles de seguridad asignados de las APIs. Cuando todos los filtros están deseleccionados, se muestran todos los perfiles de seguridad en la organización a la que tienes acceso.

• Códigos de Estado: Utiliza el menú desplegable para seleccionar los grupos de códigos de estado de respuesta HTTP, seleccionando entre Éxito (2xx), Redirecciones (3xx), Errores del Cliente (4xx) y Errores del Servidor (5xx). Cuando todos los filtros están deseleccionados, se muestran todos los códigos de estado de respuesta HTTP para las APIs en las organizaciones a las que tienes acceso. Para más información sobre los códigos de estado, consulta definiciones de códigos de estado de w3.org.

• Métodos de Solicitud: Utiliza el menú desplegable para seleccionar los métodos de solicitud HTTP, seleccionando entre GET, PUT, POST, DELETE, PATCH y MERGE. Cuando todos los filtros están deseleccionados, se muestran todos los métodos de solicitud HTTP para las APIs en la organización a la que tienes acceso. Para más información sobre los métodos de solicitud HTTP, consulta métodos de solicitud de w3.org.

• API Gateway: Visible solo cuando una organización utiliza dos o más gateways de API en la nube. Utiliza el menú para seleccionar el dominio del gateway de API en la nube. La tabla de Registros de API mostrará registros solo para el dominio seleccionado.

Ver Datos

La opción Ver Datos te permite mostrar registros dentro de un período de tiempo específico. La configuración predeterminada para el período de tiempo es Últimos 7 Días.

Utiliza el menú desplegable Ver Datos para seleccionar el período de tiempo deseado. Selecciona uno de Últimos 10 Minutos, Última 1 Hora, Últimas 10 Horas, Últimas 24 Horas, Últimos 7 Días, Último 1 Mes o Período Personalizado.

Seleccionar Período Personalizado permite mostrar los registros de la API dentro de un período de tiempo específico en los últimos 90 días. Cuando se selecciona esta opción, se muestran campos de calendario adicionales Desde y Hasta:

• Desde: Haz clic para ajustar la fecha y hora de inicio para los registros de la API.
• Hasta: Haz clic para ajustar la fecha y hora de finalización para los registros de la API.

Después de hacer clic en los campos de calendario Desde o Hasta, se muestra un cuadro de diálogo de calendario donde seleccionas la fecha y la hora:

Buscar

La barra de búsqueda permite filtrar los registros según los criterios de búsqueda proporcionados a continuación:

• Solo Registros con Mensajes: Selecciona para restringir aún más los resultados de búsqueda solo a registros que incluyan detalles de registro. Los resultados de búsqueda se actualizarán automáticamente.

Criterios de búsqueda

Estos son los criterios de búsqueda que se pueden utilizar. Se incluyen ejemplos de criterios de búsqueda válidos e inválidos:

Combinar búsquedas

Las búsquedas pueden contener una combinación de criterios. Los criterios de búsqueda combinados deben estar separados por un punto y coma (;) entre cada criterio. Estos son ejemplos de búsquedas combinadas válidas:

message=%Access Denied%;requesturi=%contacts%;

requestid=%yzaccwui%;message=%REJECT%;
requesturi=%contacts%;responsetime<=2;
responsetime>=5;sourceapp=%Chrome%;
responsetime>=5;sourceip=70.5%;
sourceapp=%Chrome%;message=%REJECT%;

sourceapp=%Mozilla%;responsetime<=1;

sourceip=70.5%;requesturi=%contacts%;

Opciones adicionales

Las opciones adicionales de registro de API se muestran en el lado izquierdo de la página, directamente encima de la barra de búsqueda:

• Ver última actualización: Muestra la última vez que se actualizaron los datos, ya sea de forma dinámica o manual. La hora se muestra en el formato h:mm:ss.

• Actualizar: Haga clic para actualizar los datos del registro según los filtros y criterios de búsqueda aplicados.

• Descargar como CSV: Haga clic para descargar los datos actuales del registro según los filtros y criterios de búsqueda aplicados.

  Nota

  El campo de fecha dentro del archivo CSV es un timestamp UNIX que requerirá conversión si desea utilizar un formato de fecha y hora diferente.

Ver registros de API

Cada fila en la tabla de Registros de API muestra datos de registro de API para una llamada de API:

• Marca de tiempo: La marca de tiempo de la solicitud de API. Las horas se muestran en la zona horaria de su navegador.
• Código de estado: El código de estado HTTP. Para más información sobre los códigos de estado HTTP, consulte definiciones de códigos de estado de w3.org.
• ID de solicitud: Un ID único para la solicitud de API.
• Método de solicitud: El método de solicitud HTTP de la API (GET, PUT, POST, DELETE, PATCH o MERGE).
• URI de solicitud: La URL completa de la API que fue llamada. Pase el cursor sobre el campo URI de solicitud para ver la URL completa.
• Tiempo de respuesta: La cantidad de tiempo, en milisegundos, que la API tardó en ejecutarse.
• IP de origen: La dirección IP externa de la aplicación o servidor que llamó a la API.
• Aplicación de origen: La aplicación de origen para la llamada de API, presente solo cuando la llamada de API se pasa en un encabezado de solicitud. Pase el cursor sobre la columna Aplicación de origen para ver el contenido del campo.

Cada página muestra 20 registros. Se pueden ver todos los registros dentro de los criterios de filtro y búsqueda utilizando los botones Siguiente y Anterior.

Ver detalles del registro

Para ver detalles adicionales del registro o registros de depuración (si están habilitados), haz clic en el ícono de expansión en una entrada de registro:

Un registro de API típico contendrá estos detalles:

• Nombre de dominio de la región de Harmony, ruta del servicio y URL base (ver URL del servicio API)
• Tiempo de procesamiento de la llamada API
• Información del perfil de seguridad, como tipo de autorización y credenciales utilizadas
• Detalles de la carga útil, incluyendo la longitud de la carga útil y el tamaño de la respuesta
• Información de error (si aplica)
• Registros de depuración (si están habilitados)
• Registros detallados (si están habilitados)

Cuando el registro de depuración está habilitado para una API y la carga útil de la API contiene más de 10,000 caracteres, un botón de Descargar Carga Útil es visible para la entrada de registro. Al hacer clic, se descarga un archivo ZIP de la carga útil de la API en tu máquina local.

API Manager Log Service API (Beta)

Como alternativa a la descarga de un archivo de registro de API haciendo clic en Descargar como CSV, se puede recuperar un archivo de registro de API utilizando una API REST. Esto requiere el uso de utilidades de línea de comandos como curl o aplicaciones como Postman.

Para usar la API Manager Log Service API (Beta), después de habilitar los registros de API para la API del Administrador de API (descrito anteriormente en esta página), sigue estos pasos:

1. Recupera un token de autenticación utilizando la API del Controlador de Servicio de Usuario. Este token es necesario para usar la API Manager Log Service API (Beta).

   • Si tu organización de Harmony no tiene habilitada la autenticación de dos factores (TFA), recupera tu token de autenticación con una solicitud de inicio de sesión estándar.

   • Si tu organización de Harmony tiene habilitada la TFA, recuperar el token de autenticación requiere dos solicitudes:

     1. Recuperar un código TFA

     2. Usar el código TFA para recuperar un token de autenticación

2. Recuperar el archivo de registro utilizando la API del Servicio de Registro del Administrador de API (Beta).

Recuperar un token de autenticación

Recuperar un token de autenticación requiere el uso de la API del Controlador del Servicio de Usuario.

Un ejemplo de solicitud que muestra el inicio de sesión en la región NA y la recuperación del token de autorización:

curl --location --request PUT 'https://na-east.jitterbit.com/jitterbit-cloud-restful-service/user/login' \
--header 'Content-Type: application/json' \
--data-raw '{
    "email": "alice@jbexample.com",
    "password": "Jitterbit4Ever!"
}'

URL base

La URL base depende de la región en la que se encuentra la organización:

Encabezados

Estos encabezados son requeridos:

Parámetros del cuerpo

Estos parámetros requeridos se envían en el cuerpo de la solicitud:

Cuerpo de la respuesta

El cuerpo de la respuesta devuelta contiene una lista de las organizaciones con las que el usuario está asociado, además del token de autenticación ("authenticationToken"). Este token es necesario para la autorización subsiguiente con la API del Servicio de Registro del Administrador de API (Beta). En este ejemplo, el token de autenticación es "1_70dfe7f7-1d47-4ad5-be5d-bc4a222dd2g4". El ID de la organización se muestra como "123456" para la primera organización a la que pertenece este usuario. Un ejemplo de la respuesta:

{
  "status": true,
  "operation": "User login",
  "authenticationToken": "1_70dfe7f7-1d47-4ad5-be5d-bc4a222dd2g4",
  "serverUrl": "https://na-east.jitterbit.com",
  "cloudAppsUrl": "https://na-east.jitterbit.com",
  "orgAttrs": [
    {
      "orgId": "123456",
      "orgName": "JB Example Company",
      "orgZoneUrl": "https://na-east.jitterbit.com"
    },
    {
      "orgId": "20970",
      "orgName": "example@jbexample.com",
      "orgZoneUrl": "https://na-east.jitterbit.com"
    }
  ],
  "defaultOrgId": "123456",
  "sessionTimeoutInSeconds": 14400
}

Recuperar un token de autenticación con TFA habilitado

Si la organización del usuario en Harmony tiene habilitada la autenticación de dos factores (TFA), recuperar el token de autenticación requiere dos solicitudes utilizando la API del Controlador de Servicio de Usuario:

1. Recuperar un código TFA

2. Usar el código TFA para recuperar un token de autenticación

Recuperar un código TFA

Se requiere un código TFA válido para recuperar un token de autenticación cuando TFA está habilitado. Un ejemplo de solicitud que muestra el inicio de sesión en la región NA y la solicitud de un código TFA:

curl --location --request PUT 'https://na-east.jitterbit.com/jitterbit-cloud-restful-service/user/login' \
--header 'Content-Type: application/json' \
--data-raw '{
    "email": "alice@jbexample.com",
    "password": "Jitterbit4Ever!",
    "deviceId": "abcd"
}'

URL base

La URL base depende de la región en la que se encuentra la organización:

Encabezados

Estos encabezados son requeridos:

Parámetros del cuerpo

Estos parámetros requeridos se envían en el cuerpo de la solicitud:

Cuerpo de la respuesta

El cuerpo de la respuesta devuelta contiene un mensaje de error que indica que se envió un código TFA a la dirección de correo electrónico del usuario.

{
  "status": false,
  "operation": "User login",
  "errorCode": "VALIDATE_TFA_LOGIN_EMAIL",
  "errorMessage": "Validate your login with authentication code. An email from Jitterbit with the code was sent to you.",
  "authenticationToken": null,
  "serverUrl": "https://na-east.jitterbit.com",
  "orgAttrs": [],
  "defaultOrgId": null
}

Utiliza el código TFA para recuperar un token de autenticación

El código TFA enviado a la dirección de correo electrónico del usuario ahora se puede utilizar en la segunda solicitud para recuperar el token de autenticación. Un ejemplo de solicitud que muestra el inicio de sesión en la región NA con un código TFA y la recuperación del token de autorización:

curl --location --request PUT 'https://na-east.jitterbit.com/jitterbit-cloud-restful-service/user/login/tfacode' \
--header 'Content-Type: application/json' \
--data-raw '{
    "email": "alice@jbexample.com",
    "password": "Jitterbit4Ever!",
    "code": "112233",
    "deviceId": "abcd"
}'

URL base

La URL base depende de la región en la que se encuentra la organización:

Encabezados

Estos encabezados son requeridos:

Parámetros del cuerpo

Estos parámetros requeridos se envían en el cuerpo de la solicitud:

Cuerpo de la respuesta

El cuerpo de la respuesta devuelta contiene una lista de las organizaciones con las que el usuario está asociado, además del token de autenticación ("authenticationToken"). Este token es requerido para la autorización subsiguiente con la API del Servicio de Registro del Administrador de API (Beta). En este ejemplo, el token de autenticación es "1_70dfe7f7-1d47-4ad5-be5d-bc4a222dd2g4". El ID de la organización se muestra como "123456" para la primera organización a la que pertenece este usuario. Un ejemplo de la respuesta:

{
  "status": true,
  "operation": "User login",
  "authenticationToken": "1_70dfe7f7-1d47-4ad5-be5d-bc4a222dd2g4",
  "serverUrl": "https://na-east.jitterbit.com",
  "cloudAppsUrl": "https://na-east.jitterbit.com",
  "orgAttrs": [
    {
      "orgId": "123456",
      "orgName": "JB Example Company",
      "orgZoneUrl": "https://na-east.jitterbit.com"
    },
    {
      "orgId": "654321",
      "orgName": "example@jbexample.com",
      "orgZoneUrl": "https://na-east.jitterbit.com"
    }
  ],
  "defaultOrgId": "123456",
  "sessionTimeoutInSeconds": 14400
}

Recuperar registros de API de forma asíncrona (Beta)

Una vez que tengas el token de autenticación y el ID de la organización, puedes recuperar registros de API de forma asíncrona utilizando la API del Servicio de Registros del Administrador de API (Beta). Un ejemplo que muestra cómo recuperar todos los registros desde el 20 de enero de 2023 hasta el 20 de enero de 2024:

curl --location --request PUT 'https://na-east.jitterbit.com/jitterbit-cloud-restful-service/api/analytics/debuglogs-async' \
--header 'Content-Type: application/json' --header 'Accept: application/json' --header 'authToken: 1_70dfe7f7-1d47-4ad5-be5d-bc4a222dd2g4' \
--data-raw '{
    "ascendSort": false,
    "retrieveLogMessages": false,
    "timeRangeFrom": "01/20/2023 01:01:00 +0100",
    "timeRangeTo": "01/20/2024 01:01:00 +0100",
    "clientTimeZone": "Europe/Berlin",
    "queryString": "responsetime>5; sourceip=14.141%",
    "orgId": "123456",
    "csvFormat": true
}'

URL base

La URL base depende de la región en la que se encuentra la organización:

Encabezados

Estos encabezados se pueden usar en la solicitud:

Parámetros del cuerpo

Estos parámetros se pueden pasar en el cuerpo de la solicitud:

Cuerpo de respuesta

Si tiene éxito, el cuerpo de respuesta devuelto contiene una clave de referencia para rastrear y descargar el archivo de registro de la API basado en los parámetros suministrados:

{
    "key": "debug-log-E8D47FE1F172D3EE46C620791E614B78D111CE624485D2E1B3D482370690DC40",
    "status": "COMPLETE"
}

La clave de referencia se puede suministrar como parte de la siguiente llamada a la API para verificar el estado del archivo de registro o para descargarlo si el estado es COMPLETE:

curl --location --request GET 'https://na-east.jitterbit.com/jitterbit-cloud-restful-service/api/analytics/log-async/{orgId}/{key}' \
--header 'Content-Type: application/json' --header 'Accept: application/json' --header 'authToken: 1_70dfe7f7-1d47-4ad5-be5d-bc4a222dd2g4'

Los estados posibles incluyen:

• RECEIVED: Harmony recibió una solicitud válida para generar el archivo de registro. El estado cambiará a PROCESSING cuando se esté ejecutando la solicitud.
• PROCESSING: Se está generando el archivo de registro. El estado cambiará a COMPLETE cuando la generación del archivo esté completa.
• COMPLETE: El archivo de registro está listo para ser descargado usando la API log-async mencionada anteriormente.
• INVALID: No se pudo encontrar la clave de referencia. Este estado solo se informa si se suministra una clave de referencia desconocida o malformada a la API log-async.
• ERROR: Se encontró la clave de referencia después de que la API terminó de intentar generar el archivo de registro, pero se reportó un error. También se devolverá un mensaje de error detallando por qué falló la generación.
• NO_DATA: Los parámetros de filtrado que consultan datos en la llamada original a la API devolvieron 0 resultados.