Objeto REST en Jitterbit App Builder

Descripción general

Los Objetos REST permiten a los desarrolladores de App Builder utilizar APIs REST de manera similar a los Objetos de Datos de App Builder. Los Objetos REST admiten lo siguiente:

• Operaciones CRUD
• Integración con varios Controles de App Builder, como Paneles de Múltiples Filas/Sola Fila, Listas
• Eventos Personalizados
• Ordenamiento
• Filtrado (cadena de consulta de estilo OData)

Para las APIs REST que admiten operaciones de estilo CRUD, configurar un Objeto REST puede ser una forma sencilla de integrar una API con tu aplicación de App Builder.

Puntos finales CRUD

Para una API REST de estilo CRUD, querrás configurar Puntos Finales que permitan que los registros sean Creado, Leído, Actualizado y Eliminado. En general, esto significa configurar los siguientes Puntos Finales:

Ejemplo de configuración de API REST de App Builder

Los pasos a continuación demuestran cómo configurar puntos finales CRUD para un servidor REST de App Builder. En este ejemplo, asumiremos que existe una tabla como:

Esta API REST se expone desde el punto final "northwinds" como un recurso llamado "customers". Por lo tanto, la URL para acceder a este punto final sería:

https://api.example.com/rest/v1/northwinds/customers

Asegúrate de haber configurado la API REST en tu servidor y de haber creado la Fuente de Datos REST antes de continuar.

Endpoint de lectura

• Navega a IDE > Servidores de Datos > Tu Servidor de Datos REST > Detalles
• Haz clic en + Endpoint en el panel de Endpoints y configura la siguiente información:
  • Nombre: customers (get)
  • Endpoint: customers
  • Método: GET
• Haz clic en Guardar
• Haz clic en Descubrir
• Regresa a la página anterior
• Selecciona tu endpoint customers (get)
• Nota que hay tres tablas de Salida
• Haz doble clic en la tabla customers (get)/items
• Establece la columna customerId como la Clave Primaria
• Asegúrate de que las columnas estén utilizando el tipo de almacenamiento esperado
• Haz clic en Resultados y verifica que los datos devueltos sean los esperados

Crear

• Navega a IDE > Servidores de Datos > Tu Servidor de Datos REST > Detalles

• Haz clic en + Endpoint en el panel de Endpoints y configura la siguiente información:

  • Nombre: customers (insert)
  • Endpoint: customers
  • Método: POST

  • Entrada de Ejemplo - El App Builder espera que la entrada esté en el siguiente formato:

    {
      "item": {
        "customerId": "abcde",
        "name": "Test Customer",
        "daysActive": 10
      }
    }
    

• Haz clic en Guardar

• Haz clic en Descubrir
  • Ten en cuenta que hacer clic en Descubrir más de una vez puede causar una violación de clave primaria, ya que el registro 'abcde' ya existirá en el servidor. Si esto sucede, necesitarás eliminar el registro existente antes de que Descubrir funcione. Puedes eliminar el registro en el servidor de la API REST de App Builder o configurar e importar el endpoint "Eliminar".
• Regresa a la página anterior
• Selecciona tu Endpoint customers (insert)
• Haz doble clic en la tabla customers (insert)
• Establece la columna customerId como la Clave Primaria
• Establece las columnas customerId, name y daysActive en dirección Entrada/Salida.
  • Cuando creamos un registro, pasamos las tres columnas (Entrada). El servidor de la API REST de App Builder devuelve estas columnas en el JSON devuelto (Salida). Si por alguna razón el servidor devuelve un valor diferente al que enviamos (quizás formateando una cadena), querríamos que nuestro registro contenga los valores devueltos.
• Asegúrate de que las columnas estén utilizando el tipo de almacenamiento esperado

Actualizar

• Navega a IDE > Servidores de Datos > Tu Servidor de Datos REST > Detalles
• Haz clic en + Endpoint en el panel de Endpoints y configura la siguiente información
• Nombre: customers (actualizar)
• Endpoint: customers/{{item/customerId}}
• Método: POST

• Entrada de Ejemplo - App Builder espera que la entrada esté en el siguiente formato:

  {
    "item": {
      "customerId": "abcde",
      "name": "Test Customer (updated)",
      "daysActive": 10
    }
  }
  

• Haz clic en Guardar

• Haz clic en Descubrir
• Regresa a la página anterior
• Selecciona tu endpoint customers (actualizar)
• Haz doble clic en la tabla customers (actualizar)
• Establece la columna customerId como la Clave Primaria
• Establece las columnas customerId, name y daysActive en dirección Entrada/Salida.
• Asegúrate de que las columnas estén utilizando el tipo de almacenamiento esperado

Objeto REST

Una vez que tus Endpoints CRUD han sido configurados, puedes crear el Objeto REST.

Crear objeto REST

• Navega a IDE > Servidores de Datos > Tu Servidor de Datos REST > Detalles
• Haz clic en Más > Super Objetos
• Haz clic en + Objeto REST
• Nombra tu Objeto REST... asumiremos Clientes
• Haz clic en el ícono de marca de verificación para guardar
• Haz clic en el ícono de lápiz para editar
• Habilita Insertar, Actualizar y Eliminar haciendo clic, según corresponda
• Haz clic en proceder o en el ícono de marca de verificación para guardar

Configurar comp único

• Haz clic en el ícono de Abrir Registro para el Objeto REST
• Haz clic en el ícono de Comp Único
• Agrega la tabla customers (get)/items al panel de Tablas
• Haz clic en el botón "*" para agregar todas las columnas
• Haz doble clic en la columna customerId y establece como Clave Primaria
• Revisa cada columna por turno y establece el Tipo de Datos Lógicos apropiadamente
• Ten en cuenta que si haces clic en Resultados antes de configurar el Comp Múltiple (a continuación) recibirás un mensaje de error "No hay secuencia". Necesitarás configurar primero el objeto Múltiple.
• Regresa a la pantalla de Objetos REST

Configurar comp múltiple

• Haz clic en el ícono de Comp Múltiple
• Agrega la tabla customers (get)/items al panel de Tablas
• Haz clic en el botón "*" para agregar todas las columnas
• Establece las columnas Objetivo a sus nombres de columna correspondientes
• Haz doble clic en la columna customerId y establece como Clave Primaria
• Haz clic en Resultados y verifica que veas los datos apropiados
• Regresa a la pantalla de Objetos REST

Configurar puntos finales CRUD

Para cada lista de operaciones CRUD, configura el Punto Final y los Vínculos según la tabla a continuación:

Ahora deberías poder hacer clic en el botón Resultados en tu Objeto REST y agregar/eliminar/actualizar filas.

Eventos personalizados

Los Objetos REST pueden definir eventos personalizados de manera similar a otros Objetos de Datos del Constructor de Aplicaciones. Para agregar un evento personalizado a tu Objeto REST, necesitarás:

• Crear un Punto Final de evento personalizado
• Crear una Regla CRUD para insertar en el Punto Final
  • Necesitarás una aplicación configurada con la fuente de datos
• Agregar un evento personalizado al Objeto REST

Crear punto final de evento personalizado

En el Constructor de Aplicaciones, un evento personalizado en una tabla se puede llamar utilizando esta notación de URL:

https://example.com/rest/v1/northwinds/mytable(myevent)/{{primaryKeyColumn}}

Por ejemplo, si continuamos usando el ejemplo anterior, el siguiente Punto Final apuntaría a un evento "mayúsculas" en la tabla "customers":

customers(uppercase)/{{item/customerId}}

Para configurar esto, haz lo siguiente:

• Agrega un evento mayúsculas a la tabla del Constructor de Aplicaciones
• Ahora configura el lado que consume el REST...
• Navega a IDE > Servidores de Datos > Tu Servidor de Datos REST > Detalles
• Haz clic en + Punto Final en el panel de Puntos Finales y configura la siguiente información
  • Nombre: customers (uppercase)
  • Punto Final: customers(uppercase)/{{item/customerId}}
  • Método: POST
  • Entrada de Ejemplo - El Constructor de Aplicaciones espera que la entrada esté en el siguiente formato:

text { "item": { "customerId": "abcde" } }

• Haz clic en Guardar
• Haz clic en Descubrir
• Selecciona tu endpoint de customers (mayúsculas)
• Haz doble clic en la tabla de customers (mayúsculas)
• Establece la columna customerId como la Clave Primaria
• Verifica que las direcciones de las columnas de salida y los tipos de almacenamiento sean los esperados.

Crear regla CRUD de evento personalizado

Para llamar al endpoint de Evento Personalizado desde tu Objeto REST, necesitas crear una regla que inserte en el Endpoint.

• Navega a App Workbench > Fuentes de Datos > Selecciona Tu Fuente de Datos REST > Lógica
• Selecciona el Endpoint de customer (mayúsculas)
• Haz clic en + Regla en el panel de Reglas y establece lo siguiente
  • Nombre: Customer (mayúsculas) Insertar
  • Propósito: CRUD
  • Acción: Insertar
  • Fuente/Destino Fuente de Datos: Tu fuente de datos
  • Destino: customers (mayúsculas)
• Haz clic en Guardar
• Desde la pestaña de Tablas:
  • Selecciona la columna customerId y establece el elemento correspondiente/customerId como la columna de destino

Crear evento en mayúsculas en objeto REST

Ahora, para conectar todo, queremos crear el evento en Mayúsculas en el Objeto REST.

• Navega a App Workbench > Fuentes de Datos > Selecciona Tu Fuente de Datos REST > Lógica
• Haz clic en el ícono de Eventos para tu Objeto REST
• En el panel de Eventos, haz clic en + Evento de Tabla
• Establece el Nombre en Mayúsculas
• Haz clic en Guardar
• En el panel de Acciones, haz clic en Registrar Existente
• Selecciona la Regla de Customers (mayúsculas) Insertar
• Haz clic en Guardar
• Inserta enlaces explícitos para customerId a customerId
• Regresa a la página de Eventos
• Haz doble clic en el evento en Mayúsculas
• Establece el alcance de Actualización en Fila

Deberías estar listo para llamar al evento personalizado. Para probar, puedes crear una página con un Panel de Múltiples Filas que tenga un botón para llamar al evento.

Ordenamiento, paginación y filtrado - Tipo de uso

Las siguientes secciones sobre Ordenamiento, Paginación y Filtrado describen cómo establecer el Tipo de Uso en Parámetros específicos. Los ejemplos dados son los nombres de Parámetros que utiliza App Builder cuando accedes a App Builder a través de una interfaz de API REST. Si estás accediendo a otros endpoints de servidores API REST externos, tendrán su propia lista única de nombres de Parámetros y formatos de valor para Ordenamiento, Paginación y Filtrado. La información presentada en estas secciones es para ayudarte a entender cuáles son cada uno de los Tipos de Uso y cómo utilizarlos, independientemente del nombre de Parámetro utilizado por la API REST a la que estás accediendo. Los parámetros de la API de App Builder utilizados en estas secciones están documentados en el artículo REST API.

Ordenamiento

El tipo de uso que se ocupa del ordenamiento es Request Sort.

• Request Sort - Establezca este tipo de uso en el parámetro REST que la API utiliza para ordenar. El nombre y el contenido de este parámetro serán definidos por el proveedor de la API. Para este ejemplo, utilizamos el nombre del parámetro de la API de App Builder como $sort.

Para habilitar el ordenamiento (con un servidor REST de App Builder):

• Navegue a IDE > Servidores de Datos
• Seleccione su fuente de datos REST
• Haga clic en Detalles
• En Parámetros del Servicio Web, haga clic en + Parámetro
• Establezca el Tipo en Consulta
• Establezca el Nombre en $sort
• Deje el Valor en blanco
• Establezca el Tipo de Uso en Request Sort
• Haga clic en el ícono de marca de verificación para guardar

Ahora debería poder ordenar cualquier dato que se obtenga utilizando esta fuente de datos REST de App Builder.

Paginación

Los tipos de uso que se ocupan de la paginación son Request Count, Request Limit, Request Offset, Request Page Number, y Response Total Rows.

• Request Count - Establezca este tipo de uso en el parámetro REST que la API utiliza para indicar que le gustaría recibir un conteo total de filas. Algunas APIs no devuelven automáticamente un conteo total en su respuesta y requieren un parámetro específico como desencadenador. Para este ejemplo, utilizamos el nombre del parámetro de la API de App Builder como $count.
• Request Limit - Establezca este tipo de uso en el parámetro REST que la API utiliza para indicar que le gustaría recibir un conteo total de filas. Algunas APIs no devuelven automáticamente un conteo total en su respuesta y requieren un parámetro específico como desencadenador. Para este ejemplo, utilizamos el nombre del parámetro de la API de App Builder como $limit.
• Request Offset - Establezca este tipo de uso en el parámetro REST que la API utiliza para indicar en qué fila le gustaría comenzar a devolver datos. Para este ejemplo, utilizamos el nombre del parámetro de la API de App Builder como $offset.
• Request Page Number - Establezca este tipo de uso en el parámetro REST que la API utiliza para indicar en qué página le gustaría comenzar a devolver datos. Algunas APIs utilizan el Número de Página en lugar de Offset, o pueden ofrecer ambos. Debe definir solo uno para su punto final, no ambos. La API de App Builder no define un parámetro para el número de página.
• Response Total Rows - Establezca este tipo de uso en el parámetro REST que la API utiliza para devolver un conteo total de filas en la respuesta. Algunas APIs no devuelven automáticamente un conteo total en su respuesta y requieren un parámetro específico como desencadenador. Consulte el tipo de uso Request Count mencionado anteriormente.

Para habilitar la paginación (con un servidor REST de App Builder):

• Navega a IDE > Servidores de Datos
• Selecciona tu fuente de datos REST
• Haz clic en Detalles
• En Parámetros del Servicio Web haz clic en + Parámetro
  • Establece el Tipo en Consulta
  • Establece el Nombre en $count
  • Establece el Valor en true
  • Establece el Tipo de Uso en Conteo de Solicitudes
  • Haz clic en el ícono de marca de verificación para guardar
• En Parámetros del Servicio Web haz clic en + Parámetro
  • Establece el Tipo en Consulta
  • Establece el Nombre en $limit
  • Deja el Valor en blanco
  • Establece el Tipo de Uso en Límite de Solicitudes
  • Haz clic en el ícono de marca de verificación para guardar
• En Parámetros del Servicio Web haz clic en + Parámetro
  • Establece el Tipo en Consulta
  • Establece el Nombre en $offset
  • Deja el Valor en blanco
  • Establece el Tipo de Uso en Desplazamiento de Solicitudes
  • Haz clic en el ícono de marca de verificación para guardar
• Para todos los Puntos Finales que soportan paginación, navega a la tabla de Puntos Finales que contiene el parámetro "count".
  • En nuestro ejemplo anterior, esta sería la tabla de clientes (get)
  • Establece el tipo de uso de la columna count en Total de Filas de Respuesta

El botón Cargar Más Filas debería funcionar ahora para cualquier dato obtenido de este Punto Final.

Opciones de visualización del panel

Cuando configuras un panel para mostrar datos de Objetos REST, hay opciones disponibles en Edge Case que proporcionan control sobre cómo el panel muestra los registros. Puedes controlar si App Builder carga un número establecido de registros junto con un botón Cargar Más Filas, o si muestra un número establecido de registros junto con controles de navegación de paginación en la región de la barra de herramientas para cargar más registros.

Además, si la configuración de la API REST lo soporta, puedes establecer el número de registros que App Builder muestra inicialmente en el panel.

Para cargar más filas

• Navega al panel utilizando el Objeto REST como Fuente
• Ve a Diseñar Esta Página
• Ve a Más > Edge Case para el panel
• Establece la Opción de Paginación en Cargar Más Filas

Para habilitar la paginación

• Navega al panel utilizando el Objeto REST como Fuente
• Ve a Diseñar Esta Página
• Ve a Más > Edge Case para el panel
• Establece la Opción de Paginación en Paginación

Para establecer el número de registros iniciales cargados

• Navega al panel utilizando el Objeto REST como Fuente
• Ve a Diseñar Esta Página
• Ve a Más > Caso Especial para el panel
• Establece Filas Por Solicitud al valor numérico que deseas cargar inicialmente

Filtrado

Los Tipos de Uso que se ocupan del filtrado son Filtro de Solicitud y Filtro de Solicitud (OData). Establece este tipo de uso en el parámetro REST que la API utiliza para filtrar. El Filtro de Solicitud es para filtrado simple, mientras que el Filtro de Solicitud (OData) es para filtrado utilizando el estándar OData. Este estándar define diferentes condiciones de filtrado. La API de App Builder utiliza el estilo de filtrado OData como se usa en nuestro ejemplo. Consulta la documentación específica de tu API para ver si se admite el filtrado OData antes de usarlo. Más información sobre el filtrado OData se puede encontrar aquí en este artículo de recomendaciones de API REST.

Para habilitar el filtrado (con un servidor REST de App Builder):

• Navega a IDE > Servidores de Datos
• Selecciona tu fuente de datos REST
• Haz clic en Detalles
• Bajo Parámetros del Servicio Web haz clic en + Parámetro
  • Establece el Tipo en Consulta
  • Establece el Nombre en $filter
  • Deja el Valor en blanco
  • Establece el Tipo de Uso en Filtro de Solicitud (OData)
  • Haz clic en el ícono de marca de verificación para guardar

Ahora deberías poder filtrar cualquier dato que se obtenga utilizando esta fuente de datos REST de App Builder.

El filtrado a través de un Servicio REST admite lo siguiente:

Operadores

• eq – Igual
• neq – No igual
• gt – Mayor Que
• ge – Mayor Que o Igual
• lt – Menor Que
• le – Menor Que o Igual

Limitaciones

• Sin operadores aritméticos
• Sin operadores lógicos or/no
• Sin operadores de agrupamiento
• Sin funciones de consulta
• Sin alias de parámetros