Airtable

El componente Airtable permite a los usuarios de Nappai leer, crear, actualizar o eliminar registros en una base de Airtable directamente desde el dashboard. Con una sola configuración puedes conectar tu cuenta de Airtable y trabajar con los datos de tus tablas sin salir de la plataforma.

¿Cómo funciona?

El componente se comunica con la API de Airtable mediante un token de acceso que el usuario debe haber guardado previamente como credencial Airtable API. Cuando seleccionas una operación (Read, Create, Update o Delete), el componente construye la solicitud HTTP correspondiente y envía los parámetros que has configurado (base, tabla, campos, filtros, etc.). La respuesta de Airtable se devuelve como un objeto Data que puede ser usado en otros componentes o como un Tool para que un agente de IA lo invoque.

Operaciones

Este componente ofrece varias operaciones que puedes seleccionar según lo que necesites hacer. Solo puedes usar una operación a la vez:

Read: Recupera registros de una tabla, con opciones de filtrado, vista y selección de campos.
Create: Inserta un nuevo registro en la tabla especificada.
Update: Modifica un registro existente identificándolo por su ID.
Delete: Elimina un registro existente por su ID.

Para usar el componente, primero selecciona la operación que necesitas en el campo “Operation” (Operación).

Entradas

Modo de Mapeo (Mapping Mode)

Este componente cuenta con un modo especial llamado “Mapping Mode” (Modo de Mapeo). Cuando activas este modo mediante el interruptor, se habilita una entrada adicional llamada “Mapping Data” y cada campo de entrada te ofrece tres formas diferentes de proporcionar datos:

Fixed (Fijo): Escribes el valor directamente en el campo.
Mapped (Mapeado): Conectas la salida de otro componente para usar su resultado como valor.
Javascript: Escribes código Javascript para calcular el valor dinámicamente.

Esta flexibilidad te permite crear flujos de trabajo más dinámicos y conectados.

Campos de Entrada

Los siguientes campos están disponibles para configurar este componente. Cada campo puede estar visible en diferentes operaciones:

Operation: Selecciona la operación que quieres ejecutar (Read, Create, Update o Delete).
- Visible en: Read, Create, Update, Delete
Access Token: Tu token de acceso personal de Airtable. Se utiliza para autenticar las peticiones a la API.
- Visible en: Read, Create, Update, Delete
Base Name: El nombre de la base de Airtable a la que te quieres conectar.
- Visible en: Read, Create, Update, Delete
Fields To Read: Campos específicos (columnas) que deseas recuperar de la tabla. Si no se seleccionan, se devuelven todos los campos.
- Visible en: Read
Filter by Formula: Fórmula de Airtable para filtrar los registros que se recuperan. Por ejemplo, {Status} = "Active".
- Visible en: Read
Mapping Mode: Habilita el modo de mapeo para procesar múltiples registros en lote.
- Visible en: Read, Create, Update, Delete
Max Records: Número máximo de registros a obtener (valor por defecto: 10). Útil para limitar la cantidad de datos devueltos.
- Visible en: Read
Mode: Elige entre una configuración simplificada con opciones predeterminadas o un control completo con ajustes avanzados.
- Visible en: Read
Record ID: Identificador único del registro que quieres modificar o eliminar.
- Visible en: Update, Delete
Table Name: El nombre de la tabla dentro de la base seleccionada.
- Visible en: Read, Create, Update, Delete
View Name: La vista de Airtable que determina el orden y el filtrado de los registros. Puedes usar vistas predefinidas para aplicar filtros y ordenamientos.
- Visible en: Read
Tool Name: Nombre del tool que se mostrará al agente cuando este componente se utilice como herramienta.
- Visible en: Read, Create, Update, Delete
Tool Description: Descripción detallada de lo que hace este tool. Ayuda al agente a decidir cuándo usarlo.
- Visible en: Read, Create, Update, Delete
Tools arguments metadata: Define los metadatos de los argumentos que el tool aceptará. Permite que el agente conozca los parámetros esperados.
- Visible en: Read, Create, Update, Delete

Nota sobre credenciales

Configura primero la credencial Airtable API en la sección de credenciales de Nappai.

Luego selecciona esa credencial en el campo Credential del componente.
Los campos de la credencial (como el token de acceso) no aparecen en la lista de entradas porque ya están gestionados por Nappai.

Salidas

Result: Devuelve los datos obtenidos o confirmación de la operación. El tipo de dato es Data y se gestiona mediante el método handle_operation.
Tool: Si el componente se usa como herramienta, devuelve un objeto Tool que puede ser llamado por un agente de IA. Se crea mediante el método to_toolkit.

Ejemplo de Uso

Operación Read

Selecciona Read en el campo Operation.
Elige la base y la tabla.
En Fields To Read selecciona los campos que necesitas (por ejemplo, Name, Email).
Opcionalmente, añade una fórmula en Filter by Formula (ej. {Status} = "Active").
Haz clic en Run.
El resultado aparecerá en la salida Result y podrás usarlo en otro componente, como un filtro o un gráfico.

Operación Create

Selecciona Create en el campo Operation.
Elige la base y la tabla.
En Fields Values (no listado en la tabla de inputs, pero disponible en modo mapeo) define los valores de los campos que quieres crear, por ejemplo:
```
{
  "Name": "Juan Pérez",
  "Email": "juan@example.com",
  "Status": "Active"
}
```
Haz clic en Run.
El nuevo registro se añadirá a Airtable y la salida Result mostrará la confirmación y el ID del registro creado.

Plantillas

(Esta sección se omite porque no hay plantillas que utilicen este componente.)

Componentes Relacionados

AirtableBase: Base de la que hereda la lógica de conexión y manejo de la API.
Data: Tipo de dato que se utiliza para transportar los registros entre componentes.
Tool: Tipo de dato que permite que el componente sea llamado por agentes de IA.

Consejos y Mejores Prácticas

Limita el número de registros: Usa Max Records para evitar sobrecargar la respuesta y mejorar el rendimiento.
Utiliza vistas: Configura vistas en Airtable con filtros y ordenamientos predefinidos y selecciona la vista en View Name para simplificar la consulta.
Evita exponer datos sensibles: No incluyas campos con información confidencial en Fields To Read a menos que sea necesario.
Prueba en modo de mapeo: Si necesitas procesar varios registros a la vez, activa Mapping Mode y conecta la salida de otro componente que genere la lista de datos.

Consideraciones de Seguridad

Token seguro: El token de acceso se almacena como credencial en Nappai y no se muestra en el dashboard.
Acceso restringido: Asegúrate de que solo los usuarios autorizados tengan acceso a la credencial Airtable API.
Registros sensibles: Si trabajas con datos personales, verifica que la política de privacidad de Airtable y Nappai cumpla con las regulaciones locales (GDPR, CCPA, etc.).