Guía de FileMaker 18 Data API
Acerca de FileMaker Data API
Introducción
FileMaker® Data API es una interfaz de programación de aplicaciones (API, por sus siglas en inglés) que permite que los servicios Web accedan a los datos de bases de datos alojadas. Como esta API se ajusta a la arquitectura de Transferencia de estado representacional (REST, por sus siglas en inglés), FileMaker Data API es una API REST.
La aplicación o el servicio Web llaman a FileMaker Data API para obtener un token de autenticación para acceder a una base de datos alojada y, a continuación, utilizan ese token en llamadas posteriores para crear, actualizar y eliminar registros, y realizar peticiones de búsqueda.
FileMaker Data API devuelve datos en la Notación de objetos de JavaScript (JSON, por sus siglas en inglés), un formato de texto que se utiliza habitualmente con las API REST porque es independiente de los formatos de lenguaje de programación específicos.
En esta guía, se presupone que está familiarizado con:
- El uso de FileMaker Pro Advanced para crear bases de datos. Debe conocer los conceptos básicos del diseño de base de datos de FileMaker Pro Advanced y los conceptos de campos, relaciones, presentaciones, portales y contenedores. Consulte la Ayuda de FileMaker Pro Advanced.
- El uso de FileMaker Server o un producto de FileMaker Cloud para alojar bases de datos. Debe saber cómo configurar el anfitrión, habilitar el acceso a las bases de datos alojadas y supervisar las bases de datos alojadas mediante la Admin Console.
- FileMaker Cloud es un servicio que proporciona acceso en la nube a las apps personalizadas que utilizan FileMaker Pro Advanced, FileMaker Go y FileMaker WebDirect. FileMaker Cloud utiliza el sistema de inicio de sesión del ID de FileMaker para autenticar a los usuarios. FileMaker Cloud se ofrece directamente desde FileMaker, Inc.
- FileMaker Cloud for AWS es un servicio que proporciona acceso en la nube a las apps personalizadas que utilizan FileMaker Pro Advanced, FileMaker Go y FileMaker WebDirect. FileMaker Cloud for AWS se ejecuta en la nube de Amazon Web Services (AWS) y se ofrece a través de AWS Marketplace.
- Los productos de FileMaker Cloud hacen referencia tanto a FileMaker Cloud como a FileMaker Cloud for AWS.
- El uso de las API REST en aplicaciones del servidor o servicios Web que llaman a los métodos POST, GET, PATCH y DELETE con datos en formato JSON. Puede utilizar todas las herramientas y los lenguajes de programación que elija.
Esta guía utiliza Admin Console para hacer referencia a la Admin Console para FileMakerServer, FileMaker Cloud for AWS y FileMaker Cloud, a menos que describa un producto específico. Admin Console de FileMaker Cloud hace referencia a la Admin Console de los dos productos de FileMaker Cloud a menos que describa un producto específico.
Para utilizar FileMaker Data API, siga estos pasos:
- Prepare la base de datos para acceder a FileMaker Data API mediante FileMaker Pro Advanced. Puede crear una base de datos o preparar una existente. Consulte Preparar bases de datos para el acceso mediante FileMaker Data API.
- Escriba el código que llame a los métodos de FileMaker Data API para buscar, crear, editar, duplicar y eliminar registros de una base de datos alojada. Consulte Escribir llamadas de FileMaker Data API.
- Aloje la solución con acceso mediante FileMaker Data API habilitado. Consulte Alojar una solución de FileMaker Data API.
- Compruebe que el acceso mediante FileMaker Data API funcione correctamente. Consulte Probar una solución de FileMaker Data API.
- Supervisar la solución alojada mediante la Admin Console. Consulte Supervisar soluciones de FileMaker Data API.
Cómo se procesa una llamada de FileMaker Data API
Cliente de API REST
1
6
Servidor Web
2
5
Motor de FileMaker Data API
3
4
Servidor de base de datos
-
Un cliente de API REST envía una llamada de FileMaker Data API (solicitud HTTPS) al servidor Web de a través del puerto HTTPS (puerto 443). No es necesario que FileMaker Pro Advanced esté instalado o ejecutándose.
- El servidor Web enruta la solicitud a través del módulo de servidor Web de FileMaker al motor de FileMaker Data API.
- El motor de FileMaker Data API convierte la solicitud HTTPS (datos de URL y JSON) en un formato que el componente de servidor de base de datos pueda comprender y solicita datos de la base de datos alojada por el servidor de base de datos.
- El servidor de base de datos devuelve los datos de FileMaker solicitados al motor de FileMaker Data API.
- El motor de FileMaker Data API convierte los datos de FileMaker en una respuesta HTTPS (URL con datos JSON) para responder a la llamada y transfiere los datos al servidor Web.
- El servidor Web envía la respuesta HTTPS al cliente de API REST que realiza la solicitud.
El motor de FileMaker Data API solicita que estén disponibles los puertos 3000 y 8989.
El servidor de base de datos solicita que esté disponible el puerto 5003.
Alternativas de Publicación en la Web
Si no tiene experiencia con las API REST, tenga en cuenta las siguientes alternativas para publicar datos de FileMaker en Internet.
FileMaker WebDirect™: los usuarios Web se conectan a la base de datos alojada para ver, editar, ordenar o buscar registros si se les concede privilegios de acceso. No necesitan instalar software adicional, solo un software de navegador Web compatible y acceso a Internet o a una intranet. La interfaz de usuario se asemeja a la aplicación de escritorio FileMaker Pro Advanced. Las páginas Web y los formularios con los que el usuario de la Web interactúa dependen de las presentaciones y las vistas definidas en la base de datos de FileMaker Pro Advanced.
Consulte la Guía de FileMaker WebDirect.
Publicación estática: si se producen muy pocos cambios en sus datos o si no desea que los usuarios tengan conexión en directo con la base de datos, puede utilizar la publicación estática. Con la publicación estática se exportan los datos de FileMaker Pro Advanced para crear una página Web que se puede personalizar posteriormente con HTML. La página Web no cambia cuando se modifica la información de la base de datos y los usuarios no se conectan a la base de datos.
Consulte Publicar datos en páginas Web estáticas en la Ayuda de FileMaker Pro Advanced.
Publicación en la Web personalizada: para integrar la base de datos de FileMaker en un sitio Web personalizado, utilice las tecnologías Publicación en la Web personalizada proporcionadas por FileMaker Server.
Consulte la Guía de Publicación en la Web personalizada de FileMaker Server.
Preparar bases de datos para el acceso mediante FileMaker Data API
Determinar los datos a los que se va a acceder
Puede crear una base de datos de FileMaker Pro Advanced para usarla con FileMaker Data API o utilizar una base de datos existente. Si crea una base de datos, puede diseñar las presentaciones y los campos necesarios para la solución de FileMaker Data API. Si utiliza una base de datos existente, considere la posibilidad de crear una presentación específicamente para la solución de FileMaker Data API.
Si accede a los datos de registro, las llamadas a FileMaker Data API requieren que especifique una presentación. FileMaker Data API utiliza la vista predeterminada que se ha definido para la presentación especificada.
Especifique una presentación que defina la vista Formulario como la vista predeterminada de la presentación. Si utiliza una presentación que define la vista Tabla como la vista predeterminada, FileMaker Data API solo podrá obtener datos del primer registro relacionado.
Proteger las soluciones de FileMaker Data API
FileMaker Data API requiere que la API REST inicie sesión en una base de datos con una cuenta protegida por contraseña. Asigne contraseñas a las cuentas de la base de datos que se utilizan para el acceso a la API REST o utilice un proveedor de servicios de OAuth para esas cuentas.
Notas
- Al definir los nombres de cuenta y las contraseñas para las soluciones de FileMaker Data API, utilice caracteres ASCII imprimibles, por ejemplo, a-z, A-Z y 0-9. Para aumentar la seguridad de los nombres de cuenta y las contraseñas, incluya caracteres de puntuación como "!" y "%," pero no incluya dos puntos. Consulte la Ayuda de FileMaker Pro Advanced.
- Para las bases de datos alojadas en FileMaker Cloud, debe utilizar cuentas del ID de FileMaker. Consulte la documentación de FileMaker Cloud en el Centro de Documentación del producto.
Habilitar el acceso mediante FileMaker Data API
Debe habilitar el privilegio ampliado fmrest, Acceso mediante FileMaker Data API, en cada base de datos a la que desee acceder mediante FileMaker Data API. Si no habilita el privilegio ampliado fmrest, las aplicaciones API REST no podrán utilizar FileMaker Data API para acceder a la base de datos, incluso aunque esté alojada.
Nota:por motivos de seguridad, habilite el privilegio ampliado fmrest solo en los conjuntos de privilegios para las cuentas que desea que accedan mediante FileMaker Data API.
Consulte "Editar privilegios ampliados para un conjunto de privilegios" en la Ayuda de FileMaker Pro Advanced.
Diseñar la solución de FileMaker Data API
Características de FileMaker Data API
FileMaker Data API proporciona una API REST para acceder a los datos de bases de datos alojadas. FileMaker Data API permite al código realizar lo siguiente:
- Obtener información sobre el anfitrión; por ejemplo, información del producto y los nombres de las bases de datos alojadas. Consulte Obtener metadatos.
- Obtener información sobre una base de datos alojada; por ejemplo, los nombres de guión, los nombres de presentación o los metadatos de presentación, incluidos los nombres de campo, los nombres de lista de valores y el contenido de la lista de valores. Consulte Obtener metadatos.
- Iniciar o cerrar la sesión de una base de datos alojada. Consulte Conectarse a una base de datos o desconectarse de ella.
- Crear, editar, duplicar o eliminar registros, u obtener un único registro o un intervalo de registros. Consulte Trabajar con registros.
- Ejecutar peticiones de búsqueda. Consulte Ejecutar una petición de búsqueda.
- Establecer valores de campos globales. Consulte Establecer valores de campos globales.
- Ejecutar guiones de FileMaker. Consulte Guiones de FileMaker y FileMaker Data API.
- Subir datos a campos contenedor. Consulte Subir datos del contenedor.
- Acceder a datos de tablas de FileMaker externas. Consulte Iniciar sesión en una fuente de datos externa.
- Utilizar una presentación diferente para los datos de respuesta al obtener un registro o un intervalo de registros. Consulte Obtener un único registro, Obtener un intervalo de registros y Ejecutar una petición de búsqueda.
FileMaker Data API no admite lo siguiente:
- El acceso a datos desde fuentes de datos ODBC externas.
- Los plug-ins de FileMaker.
- La habilitación de activadores de guiones a través de la interacción del usuario. Una solución de FileMaker Data API puede habilitar activadores de guiones solo mediante la ejecución de un guión de FileMaker.
- El acceso al sistema de archivos del equipo del servidor. Por ejemplo, FileMaker Data API no admite la función Get(TemporaryPath) de FileMaker Pro Advanced. Esta función devuelve una cadena vacía si se utiliza FileMaker Data API. Los archivos se pueden almacenar en un campo contenedor, pero no hay ningún acceso al sistema de archivos del servidor.
FileMaker Data API devuelve datos de campos, tal y como están almacenados en la base de datos, no como se muestra en FileMaker Pro Advanced.
Información de referencia de FileMaker Data API
La referencia de FileMaker Data API proporciona información detallada sobre todas las llamadas admitidas por FileMaker Data API.
Nota:para ver la información de referencia, compruebe que el acceso mediante FileMaker Data API se haya habilitado en la Admin Console. Consulte el Centro de Documentación del producto.
- Para ver la referencia en un anfitrión de FileMaker Cloud, abra un navegador e introduzca la dirección URL
https://anfitrión/fmi/data/apidoc/
dondeanfitriónes la dirección IP o el nombre de anfitrión del anfitrión de FileMaker Cloud. - Para ver la referencia en un equipo principal de FileMaker Cloud, abra un navegador e introduzca la dirección URL
https://anfitrión_local/fmi/data/apidoc/ - Para ver la referencia en un equipo remoto de FileMaker Cloud, abra un navegador e introduzca la dirección URL
https://anfitrión/fmi/data/apidoc/
dondeanfitriónes la dirección IP o el nombre de dominio del equipo principal de la implementación de FileMaker Server. En una instancia de FileMaker Server instalada en un servidor Windows, los archivos de referencia se encuentran en la carpeta
[unidad]:\Archivos de programa\FileMaker\FileMaker Server\Documentation\Data API Documentation
donde[unidad]es la unidad en la que reside la implementación de FileMaker Server.Si realiza la instalación mediante una ubicación no predeterminada en Windows, la ubicación de instalación sustituye al inicio de la ruta de instalación predeterminada
[unidad]:[ubicación_instalación]\FileMaker\FileMaker Server\Documentation\Data API Documentation- En una instancia de FileMaker Server instalada en un servidor macOS, los archivos de referencia se encuentran en la carpeta
/Library/FileMaker Server/Documentation/Data API Documentation
Notas
- Los archivos de referencia muestran variables en las URL mediante una palabra clave precedida por dos puntos (:). Por ejemplo,
:base de datos - En esta guía, se muestras las variables de las URL mediante una fuente en cursiva. Por ejemplo,
nombre-base-de-datos
Notas sobre las URL y los formatos de datos
- La longitud máxima de URI de FileMaker Data API puede verse influida por las diferencias en los sistemas operativos, servidores Web y navegadores Web. Para un uso óptimo entre plataformas, limite la longitud de URI a 2000 caracteres.
- Puede haber URL o partes de URL donde no sea necesario distinguir entre mayúsculas y minúsculas, pero, por lo general, tenga en cuenta esta distinción en las URL. Por ejemplo, si utiliza un nombre de base de datos en minúsculas para iniciar una sesión en la base de datos, siga utilizando un nombre de base de datos en minúsculas para todas las URL posteriores que transfieran el mismo token de sesión. De lo contrario, es posible que reciba un mensaje de error de token no válido.
- Las cadenas de las URL deben utilizar la codificación de URL, denominada también codificación de porcentaje, que es el método normal para las solicitudes HTTP. Por ejemplo, para especificar un nombre de presentación que incluya un carácter de barra diagonal, debe especificar este carácter como el siguiente valor codificado: "%2F".
- Los valores de cadena de datos especificados en los parámetros del cuerpo de la solicitud deben utilizar la codificación UTF-8.
- En general, FileMaker Data API trata los valores de datos numéricos como si presentaran un formato de punto flotante de doble precisión (binary64). Utilice el formato de datos correspondiente en el lenguaje de programación que utilice. (Los valores de datos numéricos no deben ir entre comillas ni utilizar la codificación de URL).
- Los valores de datos de campos numéricos, de fecha, de hora y de fecha y hora siguen los mismos límites que especifica FileMaker Pro Advanced. Consulte la Ayuda de FileMaker Pro Advanced.
- Los campos y los portales especificados deben encontrarse en la presentación que indique.
- Para especificar campos relacionados, utilice la sintaxis
portalData.Nota:aún se admite la sintaxis
tablename::related-field(repetition-number).record-idde versiones anteriores, pero es preferible utilizar la sintaxisportalData. - En el cuerpo de la respuesta, FileMaker Data API solo devuelve el nombre de campo para los campos de la tabla actual y el nombre completo para los campos de las tablas relacionadas. En los campos de portal, el nombre completo utiliza el nombre del portal si al portal se le ha asignado un nombre en el Inspector; de lo contrario, el nombre completo utiliza el nombre de ocurrencia de la tabla.
- Para los datos de campos contenedor, FileMaker Data API devuelve una URL con la referencia de ruta al objeto de datos del contenedor.
Guiones de FileMaker y FileMaker Data API
Un guión de FileMaker hace referencia a una o varias instrucciones (pasos de guión) que puede definir para automatizar tareas repetitivas o difíciles. Cuando se utilizan con FileMaker Data API, los guiones de FileMaker permiten que los servicios Web realicen más tareas o una serie de tareas. Consulte Ejecutar guiones de FileMaker.
Para ver los pasos de guión compatibles con FileMaker Data API, en el espacio de guiones de FileMaker Pro Advanced, haga clic en el botón Compatibilidad y seleccione FileMaker Data API. Los pasos de guión que no aparecen atenuados son compatibles con FileMaker Data API. Algunos pasos de guión funcionan de forma diferente o es posible que no se admitan en FileMaker Data API. Consulte la Ayuda de FileMaker Pro Advanced.
Los guiones ejecutados por FileMaker Data API no pueden ejecutar guiones en otros archivos de FileMaker a menos que se hayan alojado en el mismo anfitrión. Los demás archivos de FileMaker deben tener habilitado el privilegio ampliado fmrest.
En FileMaker Pro Advanced, tanto las acciones de guión como las de usuario (como el que un usuario haga clic en un campo) pueden habilitar los activadores de guiones. Sin embargo, en las soluciones de FileMaker Data API, solo los guiones pueden habilitar activadores de guiones. Para obtener más información sobre los activadores de guiones, consulte la Ayuda de FileMaker Pro Advanced.
Notas
- Tenga en cuenta la cantidad de datos y registros que puede devolver un guión y defina los guiones en consecuencia. En FileMaker Pro Advanced, un guión puede devolver todos los registros de una tabla o del conjunto encontrado actual. Sin embargo, si un guión devuelve todos los registros de una tabla, un servicio Web puede quedarse sin memoria al intentar procesar los registros.
- Utilice las cuentas y los privilegios para limitar el conjunto de guiones que puede ejecutar un servicio Web. Compruebe que los guiones contienen solo pasos de guión compatibles con Web y que solo ofrecen acceso a los guiones que deberían utilizarse desde un servicio Web.
- Tenga en cuenta los efectos secundarios de guiones que ejecuten una combinación de pasos controlados por medio de privilegios de acceso. Por ejemplo, si un guión incluye un paso para eliminar registros y el servicio Web no inicia sesión con una cuenta que permita eliminar registros, el guión no ejecutará el paso de guión Eliminar registros. Sin embargo, existe la posibilidad de que el guion siga ejecutándose, lo que podría provocar resultados inesperados.
- En el espacio de trabajo de guiones, conceda privilegios de acceso total a un guión para permitir que realice tareas a las que no concedería acceso a los usuarios. Por ejemplo, puede impedir que los usuarios eliminen registros con sus cuentas y privilegios, pero permitirles ejecutar un guión que elimine determinados registros según las condiciones definidas en él.
- Los puntos de conexión de FileMaker Data API se han diseñado para consignar cambios en los datos al instante, pero los guiones pueden dejar registros sin consignar. Por ejemplo, una sesión puede ejecutar un guión que edite un registro, pero no lo consigne; en la siguiente sesión, aparecerá un error al intentar editar el mismo registro. O bien, en una única sesión, un guión puede editar un registro, crear una nueva ventana y, a continuación, llamar a un segundo guión que intente editar el mismo registro. Asegúrese de comprobar los resultados del guión y buscar errores de guión.
- Todos los guiones que modifiquen los datos deben incluir el paso de guión Consignar registro/petición debido a que no se puede acceder a los datos hasta que se guarden en el servidor. Esto incluye los pasos de guión como Cortar, Copiar y Pegar. Muchas acciones de un solo paso se deben convertir en guiones para incluir el paso de guión Consignar registro/petición. Al diseñar guiones que se ejecutarán desde un servicio Web, incluya el paso Consignar registro/petición al final de un guión para asegurarse de que se guarden todos los cambios.
- Abra cada guión que puedan ejecutar los usuarios Web y compruebe que el guión se ejecute correctamente cuando la base de datos se haya alojado como una solución de FileMaker Data API. Compruebe que el guión utiliza utilice solo pasos de guión compatibles con FileMaker Data API, como se describe anteriormente.
Escribir llamadas de FileMaker Data API
Componentes de la llamada de la API REST
Las llamadas de FileMaker Data API constan de los siguientes componentes.
| Componente | Descripción |
|---|---|
Un método HTTP (denominado también verbo HTTP) |
FileMaker Data API utiliza los siguientes métodos HTTP:
|
Encabezados HTTP |
FileMaker Data API utiliza los siguientes encabezados:
|
| Una URL de llamada | Las URL de FileMaker Data API empiezan todas con uno de los siguientes elementos:
|
| Datos de parámetros en formato JSON | No es necesario con Cerrar la sesión de una base de datos, Obtener metadatos, Eliminar un registro, Duplicar un registro, Obtener un único registro, Obtener un intervalo de registros o Ejecutar un guión. |
Conectarse a una base de datos o desconectarse de ella
FileMaker Data API utiliza un token de acceso para definir una conexión a una base de datos. Ese token de acceso se debe utilizar en el encabezado de todas las llamadas posteriores a la base de datos alojada. El token de acceso es válido hasta que cierre la sesión de una base de datos o durante 15 minutos después de la última llamada que especificó el token. (Mientras el token sea válido, cada llamada que especifica el token restablece el contador de tiempo de espera de la sesión a cero).
Iniciar una sesión en una base de datos.
Para iniciar sesión en una base de datos alojada, utilice un método HTTP POST con el punto de conexión de API sessions y especifique el nombre de una base de datos alojada. El nombre de cuenta y la contraseña se especifican en una cadena "Authorization" del encabezado. Si se han autenticado el nombre de cuenta y la contraseña, el código recibe un token de acceso que define la conexión a la base de datos. Esta conexión recibe el nombre de sesión de la base de datos.
| Método HTTP | POST |
|---|---|
| URL | /fmi/data/versión/databases/nombre-base-de-datos/sessions
versión: la versión de FileMaker Data API solicitada, |
| Encabezado HTTP | Content-Type: application/json Authorization: una cadena codificada en base64 que representa el nombre de cuenta y la contraseña que se utilizarán para iniciar sesión en la base de datos alojada. Esta cadena codificada en base64 debe seguir el esquema de autenticación básica HTTP estándar. (El nombre de cuenta y la contraseña se separan con dos puntos). |
| Parámetros |
Un conjunto vacío de llaves. Por ejemplo:
Se puede utilizar de forma opcional el parámetro |
| Respuesta | El token de acceso, un cuerpo de respuesta con el token de acceso y una matriz de mensajes que muestra el código de error 0. El encabezado X-FM-Data-Access-Token se devuelve en la respuesta, que es el token de sesión que se utilizará para las siguientes llamadas a la API. Por ejemplo: Header:
"X-FM-Data-Access-Token": "c4d2e429122e9cdeda19bb23c55cd2a8f282c3cc50c60943a110",
{
Cuerpo:
"messages": [
{
"message": "OK",
"code": "0"
}
],
"response": {
"token": "c4d2e429122e9cdeda19bb23c55cd2a8f282c3cc50c60943a110"
},
"HTTPMessage": "OK",
"HTTPCode": 200
}
Consulte Respuestas de error. |
Iniciar sesión en una fuente de datos externa
Si la base de datos alojada debe iniciar sesión en una fuente de datos externa, el nombre de la base de datos alojada se especifica en la URL; el nombre de cuenta y la contraseña de la base de datos alojada se especifican en la cadena "Authorization" del encabezado, y el nombre de la base de datos, el nombre de cuenta y la contraseña de la fuente de datos externa se especifican en el parámetro fmDataSource como una matriz JSON.
| Método HTTP | POST |
|---|---|
| URL | /fmi/data/versión/databases/nombre-base-de-datos/sessions
versión: la versión de FileMaker Data API solicitada, |
| Encabezado HTTP | Content-Type: application/json Authorization: una cadena codificada en base64 que representa el nombre de cuenta y la contraseña que se utilizarán para iniciar sesión en la base de datos alojada. Esta cadena codificada en base64 debe seguir el esquema de autenticación básica HTTP estándar. |
| Parámetros | El parámetro Por ejemplo: { "fmDataSource":
[ { "database":"contacts", "username":"admin", "password":"admin" } ]
}
Para utilizar una cuenta de OAuth a fin de iniciar sesión en la fuente de datos externa, especifique el valor de encabezado X-FMS-Request-ID ( { "fmDataSource":
[ { "database":"contacts", "oAuthRequestId": "E65B98BB17429CO643B31119F", "oAuthIdentifier": "B164A3459A776E5177445DR223"} ]
}
|
| Respuesta | El token de acceso, un cuerpo de respuesta vacío y una matriz de mensajes que muestra el código de error 0. El encabezado X-FM-Data-Access-Token se devuelve en la respuesta, que es el token de sesión que se utilizará para las siguientes llamadas a la API. Por ejemplo: X-FM-Data-Access-Token: c13c0f486780f2187bde6f3859dabd4dcf8ea43be420dfeadf34
{
"response": {},
"messages":[{"code":"0","message":"OK"}]
}
Consulte Respuestas de error. |
Notas
- Las bases de datos de FileMaker son las únicas fuentes de datos externas admitidas. Especifique el nombre de la base de datos sin la extensión de nombre de archivo .fmp12.
- Los archivos que aparecen en el parámetro
fmDataSourcese abrirán según sea necesario; por ejemplo, cuando se ejecuta un guión o cuando se cambia el contexto a una presentación que requiere la fuente de datos externa. Como resultado, se producen errores al iniciar sesión en la fuente de datos externa cuando se intentan abrir los archivos, no cuando se inicia una sesión de la base de datos.
Iniciar una sesión en una base de datos mediante un proveedor de identidad de OAuth
Para iniciar sesión en una base de datos alojada mediante un proveedor de identidad de OAuth, utilice un método HTTP POST con el punto de conexión de API sessions y especifique la base de datos. Utilice las cadenas X-FM-Data-OAuth-Request-Id y X-FM-Data-OAuth-Identifier en el encabezado para autenticar el acceso a la base de datos alojada. Si se acepta la autenticación, el código recibe un token de acceso que define la conexión a la base de datos. Esta conexión recibe el nombre de sesión de la base de datos.
| Método HTTP | POST |
|---|---|
| URL | /fmi/data/versión/databases/nombre-base-de-datos/sessions
versión: la versión de FileMaker Data API solicitada, |
| Encabezado HTTP | Content-Type: application/json X-FM-Data-OAuth-Request-Id: ID-solicitud X-FM-Data-OAuth-Identifier: parámetro-identificador |
| Parámetros |
Un conjunto vacío de llaves. Por ejemplo: Se puede utilizar de forma opcional el parámetro |
| Respuesta | El token de acceso, un cuerpo de respuesta vacío y una matriz de mensajes que muestra el código de error 0. El encabezado X-FM-Data-Access-Token se devuelve en la respuesta, que es el token de sesión que se utilizará para las siguientes llamadas a la API. Por ejemplo: X-FM-Data-Access-Token: 823c0f48bb80f2187bde6f3859dabd4dcf8ea43be420dfeadf34
{
"response": {},
"messages":[{"code":"0","message":"OK"}]
}
Consulte Respuestas de error. |
Para obtener los parámetros de OAuth en formato JSON:
-
Obtenga la lista de proveedores de OAuth compatibles mediante un método HTTP GET con esta URL:
https://anfitrión/fmws/oauthproviderinfodonde anfitrión es la dirección IP o el nombre de dominio del equipo principal de la implementación de FileMaker Server, o la dirección IP o el nombre de dominio del anfitrión de FileMaker Cloud for AWS. La lista se devuelve en formato JSON.
- Seleccione un proveedor de OAuth admitido y obtenga un ID de seguimiento para la sesión.
-
Utilice un método HTTP GET con esta URL:
http://anfitrión/oauth/getoauthurl?trackingID=ID-seguimiento&provider=proveedor-OAuth&address=127.0.0.1&X-FMS-OAuth-AuthType=2donde anfitrión es la dirección IP o el nombre de dominio del equipo principal de la implementación de FileMaker Server, o la dirección IP o el nombre de dominio del anfitrión de FileMaker Cloud for AWS; ID-seguimiento es el ID de seguimiento de la sesión y proveedor-OAuth es el nombre del proveedor de OAuth seleccionado.
El encabezado de esta solicitud debe incluir lo siguiente:
- X-FMS-Application-Type: 9
- X-FMS-Application-Version: 15
- X-FMS-Return-URL: http://127.0.0.1/
- Lea el encabezado de respuesta de los datos de X-FMS-Request-ID. Este encabezado de respuesta contiene el ID de solicitud de OAuth que se utilizará para la cadena X-FM-Data-OAuth-Request-ID del encabezado.
- Lea el encabezado de respuesta de los datos de X-FMS-Return-URL. Llame a la URL devuelta en este parámetro para permitir que el usuario se autentique con el proveedor de OAuth.
- El "identificador" devuelto por el proveedor de OAuth es el parámetro de identificador de OAuth que se utilizará para la cadena X-FM-Data-OAuth-Identifier del encabezado.
Consulte "Editar el acceso a la cuenta de OAuth" en la Ayuda de FileMaker Pro Advanced.
Iniciar una sesión en una base de datos mediante una cuenta del ID de FileMaker
En los archivos alojados por FileMaker Cloud, los usuarios se autentican mediante las cuentas del ID de FileMaker. Las cuentas del ID de FileMaker se definen en el sistema del proveedor de identidad del ID de FileMaker.
Para iniciar sesión en una base de datos alojada mediante una cuenta del ID de FileMaker, utilice un método HTTP POST con el punto de conexión de API sessions y especifique el nombre de una base de datos alojada. El token del ID de FileMaker se especifica en la cadena de autorización del encabezado. El código recibe un token de acceso que define la conexión a la base de datos. Esta conexión recibe el nombre de sesión de la base de datos.
| Método HTTP | POST |
|---|---|
| URL | /fmi/data/versión/databases/nombre-base-de-datos/sessions
versión: la versión de FileMaker Data API solicitada, |
| Encabezado HTTP | Content-Type: application/json Authorization: FMID {FMID-token} FMID-token es el token del ID de FileMaker proporcionado por el proveedor de identidad del ID de FileMaker. Para obtener más información sobre el token del ID de FileMaker, consulte la Ayuda de FileMaker Customer Console en el Centro de documentación del producto. Consulte "Editar el acceso a la cuenta del ID de FileMaker" en la Ayuda de FileMaker Pro Advanced. |
| Parámetros |
Un conjunto vacío de llaves. Por ejemplo: |
| Respuesta | El token de acceso, un cuerpo de respuesta vacío y una matriz de mensajes que muestra el código de error 0. El encabezado X-FM-Data-Access-Token se devuelve en la respuesta, que es el token de sesión que se utilizará para las siguientes llamadas a la API. Por ejemplo: X-FM-Data-Access-Token: 823c0f48bb80f2187bde6f3859dabd4dcf8ea43be420dfeadf34
{
"response": {},
"messages":[{"code":"0","message":"OK"}]
}
Consulte Respuestas de error. |
Cerrar la sesión de una base de datos
Cuando el código termine de acceder a la base de datos alojada, utilice un método HTTP DELETE con el punto de conexión de API sessions, y especifique el nombre de la base de datos alojada y el token de acceso de la sesión. Si el código no cierra la sesión de la base de datos, el token de acceso dejará de ser válido cuando se agote el tiempo de espera de 15 minutos de la sesión de FileMaker Data API después de la última llamada que especificó el token.
| Método HTTP | DELETE |
|---|---|
| URL | /fmi/data/versión/databases/nombre-base-de-datos/sessions/token-sesión
versión: la versión de FileMaker Data API solicitada, nombre-base-de-datos: el nombre de la base de datos alojada. token-sesión: el X-FM-Data-Access-Token de la sesión de la base de datos. |
| Encabezado HTTP | Content-Type: application/json |
| Parámetros | Ninguno |
| Respuesta |
Un cuerpo de respuesta vacío y una matriz de mensajes que muestra el código de error 0. Por ejemplo: {
"response": {},
"messages":[{"code":"0","message":"OK"}]
}
Consulte Respuestas de error. |
Obtener metadatos
FileMaker Data API admite la recuperación de los siguientes metadatos:
- Información del producto sobre el anfitrión. Consulte Obtener información del producto.
- Los nombres de las bases de datos alojadas. Consulte Obtener los nombres de las bases de datos.
- Los nombres de los guiones de FileMaker disponibles en una base de datos alojada. Consulte Obtener los nombres de los guiones.
- Los nombres de las presentaciones disponibles en una base de datos alojada. Consulte Obtener los nombres de las presentaciones.
- Metadatos adicionales en relación con una presentación específica de una base de datos alojada. Consulte Obtener metadatos de la presentación.
Obtener información del producto
Para recuperar información del producto en relación con el anfitrión, utilice un método HTTP GET con el punto de conexión de API productInfo.
| Método HTTP | GET |
|---|---|
| URL |
Formato: /fmi/data/versión/productInfo
|
| Encabezado HTTP | Ninguno |
| Parámetros | Ninguno |
| Respuesta |
Una matriz de mensajes que muestra el código de error 0. Consulte Respuestas de error. El cuerpo del mensaje con los siguientes metadatos:
Por ejemplo: {
"response": {
"productInfo": {
"buildDate": "01/30/2020",
"dateFormat": "MM/dd/yyyy",
"timeStampFormat": "MM/dd/yyyy HH:mm:ss",
"version": "18.0.1.30",
"timeFormat": "HH:mm:ss",
"name": "FileMaker Data API Engine"
}
},
"messages": [
{
"code": "0",
"message": "OK"
}
]
}
|
Obtener los nombres de las bases de datos
Para recuperar los nombres de todas las bases de datos alojadas y habilitadas para el acceso mediante FileMaker Data API, utilice un método HTTP GET con el punto de conexión de API databases.
| Método HTTP | GET |
|---|---|
| URL | Formato: fmi/data/versión/databases
|
| Encabezado HTTP |
El encabezado de autorización depende de la opción Filtrar bases de datos en las aplicaciones cliente de la Admin Console.
|
| Parámetros | Ninguno |
| Respuesta |
Una matriz de bases de datos que muestra los nombres de las bases de datos y una matriz de mensajes que muestra el código de error 0. Por ejemplo: {
"response": {
"databases": [{
"name": "Clientes"
}, {
"name": "Ventas"
}]
},
"messages": [{
"code": "0",
"message": "OK"
}]
}
Consulte Respuestas de error. |
Obtener los nombres de los guiones
Para recuperar los nombres de todos los guiones disponibles para la base de datos especificada, utilice un método HTTP GET con el punto de conexión de API scripts.
| Método HTTP | GET |
|---|---|
| URL | Formato: /fmi/data/versión/databases/nombre-base-de-datos/scripts
|
| Encabezado HTTP | Authorization: Bearer token-sesión, donde token-sesión es el valor exclusivo de X-FM-Data-Access-Token para la sesión de la base de datos. |
| Parámetros | Ninguno |
| Respuesta |
Una matriz de guiones que muestra los nombres y las carpetas de los guiones, y una matriz de mensajes que muestra el código de error 0. Por ejemplo: {
"response": {
"scripts": [
{
"name": "IralPrimero",
"isFolder": false
},
{
"name": "Una carpeta",
"isFolder": true,
"folderScriptNames": [
{
"name": "guión1",
"isFolder": false
},
{
"name": "-",
"isFolder": false
},
{
"name": "guión2",
"isFolder": false
},
{
"name": "Otra carpeta",
"isFolder": true,
"folderScriptNames": [
{
"name": "guión3",
"isFolder": false
}
]
},
{
"name": "guión4",
"isFolder": false
}
]
}
]
},
"messages": [
{
"message": "OK",
"code": "0"
}
]
}
Consulte Respuestas de error. |
Obtener los nombres de las presentaciones
Para recuperar los nombres de todas las presentaciones disponibles para la base de datos especificada, utilice un método HTTP GET con el punto de conexión de API layouts.
| Método HTTP | GET |
|---|---|
| URL | Formato: /fmi/data/versión/databases/nombre-base-de-datos/layouts
|
| Encabezado HTTP | Authorization: Bearer token-sesión, donde token-sesión es el valor exclusivo de X-FM-Data-Access-Token para la sesión de la base de datos. |
| Parámetros | Ninguno |
| Respuesta |
Una matriz de presentaciones que muestra los nombres de las presentaciones y una matriz de mensajes que muestra el código de error 0. Por ejemplo: {
"messages": [
{
"message": "OK",
"code": "0"
}
],
"response": {
"layouts": [
{
"name": "Clientes"
},
{
"name": "Detalles"
},
{
"folderLayoutNames": [
{
"name": "Marcar como enviados"
},
{
"name": "Buscar elem. no enviados"
}
],
"isFolder": true,
"name": "Administración de paquetes"
}
]
}
}
Consulte Respuestas de error. |
Obtener metadatos de la presentación
Para recuperar metadatos de una presentación que incluyan campos de una presentación, portales y listas de valores, utilice un método HTTP GET con el punto de conexión de API layouts y especifique un nombre de presentación.
| Método HTTP | GET |
|---|---|
| URL | Formato 1: /fmi/data/versión/databases/nombre-base-de-datos/layouts/nombre-presentación
Formato 2: /fmi/data/versión/databases/nombre-base-de-datos/layouts/nombre-presentación?recordId=id-registro
|
| Encabezado HTTP | Authorization: Bearer token-sesión, donde token-sesión es el valor exclusivo de X-FM-Data-Access-Token para la sesión de la base de datos. |
| Parámetros | Ninguno |
| Respuesta |
Un cuerpo de respuesta con las matrices fieldMetaData, portalMetaData y valueLists, y una matriz de mensajes que muestra el código de error 0. Por ejemplo: {
"response": {
"fieldMetaData": [
{
"name": "NombreCliente",
"type": "normal",
"displayType": "editText",
"result": "text",
"valueList": "Texto",
"global": false,
"autoEnter": false,
"fourDigitYear": false,
"maxRepeat": 1,
"maxCharacters": 0
"notEmpty": false,
"numeric": false,
"timeOfDay": false,
"repetitionStart": 1,
"repetitionEnd": 1
}
],
"portalMetaData": {},
"valueLists": [
{
"name": "Región",
"type": "customList",
"values": [
{
"displayValue": "Oeste",
"value": "Oeste"
}
,
{
"displayValue": "Este",
"value": "Este"
}
]
}
]
},
"messages": [
{
"code": "0",
"message": "OK"
}
]
}
Consulte Respuestas de error. |
Notas
- En las listas de valores dinámicos, se devuelve una lista de valores vacía si la solicitud no incluye un parámetro
recordIdcomo parte de la dirección URL.
Trabajar con registros
Crear un registro
Para crear un registro, utilice un método HTTP POST con el punto de conexión de API records y especifique el nombre de la base de datos y la presentación.
| Método HTTP | POST |
|---|---|
| URL |
/fmi/data/versión/databases/nombre-base-de-datos/layouts/nombre-presentación/records
versión: la versión de FileMaker Data API solicitada, |
| Encabezado HTTP | Content-Type: application/json Authorization: Bearer token-sesión, donde token-sesión es el valor exclusivo de X-FM-Data-Access-Token para la sesión de la base de datos. |
| Parámetros | Registre datos en formato JSON que contengan pares de campo y valor que especifiquen valores para los campos incluidos en la presentación de destino. Los datos pueden especificar registros relacionados o portales que se encuentran en la presentación mediante la especificación portalData. Un nombre de portal puede ser el nombre del objeto que se muestra en el Inspector de FileMaker Pro Advanced o el nombre de la tabla relacionada. Por ejemplo: {"fieldData":
{
"String Field": "value_1",
"Number Field": 99.99,
"repetitionField(1)" : "fieldValue"
}
}
Nota:para crear un registro vacío con valores predeterminados para cada campo, especifique un objeto de datos vacío en formato JSON como parámetro. Por ejemplo: {"fieldData":
{
}
}
Puede ejecutar guiones de FileMaker como parte de esta solicitud. Para ello, incluya los parámetros |
| Respuesta |
El ID del registro que se ha creado y una matriz de mensajes que muestran el código de error 0. Por ejemplo: {
"response": {
"recordId":"147",
"modId":"0"
},
"messages": [
{
"code": "0",
"message":"OK"
}
]
}
Consulte Respuestas de error. |
Notas
- Al crear registros mediante FileMaker Data API, se debe aplicar la validación de campos. Si los datos no superan la validación de campos, recibirá un mensaje de error y no se creará el registro.
Editar un registro
Para editar un registro, utilice un método HTTP PATCH con el punto de conexión de API records y especifique el nombre de la base de datos, la presentación y el ID de registro.
| Método HTTP | PATCH |
|---|---|
| URL |
/fmi/data/versión/databases/nombre-base-de-datos/layouts/nombre-presentación/records/id-registro
versión: la versión de FileMaker Data API solicitada, |
| Encabezado HTTP |
Content-Type: application/json Authorization: Bearer token-sesión, donde token-sesión es el valor exclusivo de X-FM-Data-Access-Token para la sesión de la base de datos. |
| Parámetros | Datos de registros en formato JSON que contienen los pares de campo y valor que se van a actualizar. Los datos pueden especificar registros relacionados o portales que se encuentran en la presentación mediante la especificación portalData. Un nombre de portal puede ser el nombre del objeto que se muestra en el Inspector de FileMaker Pro Advanced o el nombre de la tabla relacionada. Solo se actualizarán los campos que especifique; los demás campos del registro no se modificarán. Si se especifica "{}" como valor de Parámetro opcional: ID de modificación ( Por ejemplo: {
"fieldData":
{
"First Name": "Juan"
},
"portalData":
{
"JobsTable": [
{
"recordId": "70",
"modId": "4",
"JobsTable::Name": "Contratista"
}
]
}
}
Puede ejecutar guiones de FileMaker como parte de esta solicitud. Para ello, incluya los parámetros |
| Respuesta |
El cuerpo de respuesta y una matriz de mensajes que muestra el código de error 0. Por ejemplo: {
"response": {
"modId": "3"
},
"messages": [
{
"code": "0",
"message": "OK"
}
]
}
Consulte Respuestas de error. |
Notas
- Al editar registros mediante FileMaker Data API, se debe aplicar la validación de campos. Si los datos no superan la validación de campos, recibirá un mensaje de error y no se actualizará el registro.
-
Para eliminar un registro relacionado, utilice la sintaxis
deleteRelated.Por ejemplo, para eliminar un único registro:
"deleteRelated" : "Orders.3"Por ejemplo, para eliminar varios registros:
"deleteRelated" : ["Orders.7", "Orders.9"]
Duplicar un registro
Para duplicar un registro, utilice un método HTTP POST con el punto de conexión de API records y especifique el nombre de la base de datos, el nombre de la presentación y el ID de registro.
| Método HTTP | POST |
|---|---|
| URL |
/fmi/data/versión/databases/nombre-base-de-datos/layouts/nombre-presentación/records/id-registro
versión: la versión de FileMaker Data API solicitada, |
| Encabezado HTTP |
Content-Type: application/json Authorization: Bearer token-sesión, donde token-sesión es el valor exclusivo de X-FM-Data-Access-Token para la sesión de la base de datos. |
| Parámetros | Ninguno Puede ejecutar guiones de FileMaker como parte de esta solicitud. Para ello, incluya los parámetros |
| Respuesta |
El ID del nuevo registro y una matriz de mensajes que muestran el código de error 0. Por ejemplo: {
"response": {
"recordId": "7",
"modId": "0"
},
"messages": [
{
"code": "0",
"message": "OK"
}
]
}
Consulte Respuestas de error. |
Eliminar un registro
Para eliminar un registro, utilice un método HTTP DELETE con el punto de conexión de API records y especifique el nombre de la base de datos, la presentación y el ID de registro.
| Método HTTP | DELETE |
|---|---|
| URL | /fmi/data/versión/databases/nombre-base-de-datos/layouts/nombre-presentación/records/id-registro
versión: la versión de FileMaker Data API solicitada, Puede ejecutar guiones de FileMaker como parte de esta solicitud. Para ello, incluya los parámetros |
| Encabezado HTTP | Authorization: Bearer token-sesión, donde token-sesión es el valor exclusivo de X-FM-Data-Access-Token para la sesión de la base de datos. |
| Parámetros | Ninguno |
| Respuesta |
Un cuerpo de respuesta vacío y una matriz de mensajes que muestra el código de error 0. Por ejemplo: {
"response": {},
"messages":[{"code":"0","message":"OK"}]
}
Consulte Respuestas de error. |
Obtener un único registro
Para obtener un registro, utilice un método HTTP GET con el punto de conexión de API records y especifique el nombre de la base de datos, la presentación y el ID de registro. También puede especificar información del portal para limitar el número de registros relacionados que se devuelven.
| Método HTTP | GET |
|---|---|
| URL | Formato 1: /fmi/data/versión/databases/nombre-base-de-datos/layouts/nombre-presentación/records/id-registro
versión: la versión de FileMaker Data API solicitada, Para la palabra clave del portal: La parte de portal de la URL es opcional. Si la presentación incluye portales, especifique los nombres de portal para mejorar el rendimiento. Si se omite la parte de portal, la llamada devolverá todos los registros relacionados de todos los portales de la presentación. En En Si desea obtener los datos de respuesta en el contexto de una presentación diferente, utilice el parámetro Puede ejecutar guiones de FileMaker como parte de esta solicitud. Para ello, incluya los parámetros |
| Encabezado HTTP | Authorization: Bearer token-sesión, donde token-sesión es el valor exclusivo de X-FM-Data-Access-Token para la sesión de la base de datos. |
| Parámetros | Ninguno |
| Respuesta | Los datos de registros en formato JSON y una matriz de mensajes que muestra el código de error 0. Por ejemplo: {
"response": {
"data": [
...
]
},
"messages": [{"code":"0","message":"OK"}]
}
Consulte Respuestas de error. |
Notas
- Para que se devuelvan datos de filas del portal específicas, utilice
_offset.nombre-portaly_limit.nombre-portal. Un nombre de portal puede ser el nombre del objeto que se muestra en el Inspector de FileMaker Pro Advanced o el nombre de la tabla relacionada. Si omite los valores de desplazamiento y límite de las filas del portal, el valor predeterminado para el desplazamiento es 1 y el límite predeterminado para los registros del portal es 50.
Obtener un intervalo de registros
Para obtener un intervalo de registros, utilice un método HTTP GET con el punto de conexión de API records y especifique el nombre de la base de datos, la presentación e información adicional para indicar el registro inicial y el número de registros. También puede especificar el tipo de ordenación de los registros. También puede especificar información del portal para limitar el número de registros relacionados que se devuelven.
| Método HTTP | GET |
|---|---|
| URL |
Formato 1 (devuelve hasta los 100 primeros registros):
versión: la versión de FileMaker Data API solicitada, En En En la especificación Para la palabra clave del portal: La parte de portal de la URL es opcional. Si la presentación incluye portales, es posible que desee especificar los nombres de portal por motivos de rendimiento. Si se omite la parte de portal, la llamada devolverá todos los registros relacionados de todos los portales de la presentación. En En Si desea obtener los datos de respuesta en el contexto de una presentación diferente, utilice el parámetro Puede ejecutar guiones de FileMaker como parte de esta solicitud. Para ello, incluya los parámetros |
| Encabezado HTTP | Authorization: Bearer token-sesión, donde token-sesión es el valor exclusivo de X-FM-Data-Access-Token para la sesión de la base de datos. |
| Parámetros | Ninguno |
| Respuesta |
Los datos de registros en formato JSON y una matriz de mensajes que muestra el código de error 0. Por ejemplo: {
"response": {
"data": [
...
]
},
"messages": [{"code":"0","message":"OK"}]
}
Consulte Respuestas de error. |
Notas
- Si omite los valores de desplazamiento y límite, el valor predeterminado del desplazamiento es 1 y el límite predeterminado para los registros es 100:
_offset=1&_limit=100 - Si omite la palabra clave sortOrder, el valor predeterminado es
ascend(ascendente). Por ejemplo,&_sort=[{ "fieldName": "recordId" }]se trata como:&_sort=[{ "fieldName": "recordId", "sortOrder": "ascend" }] - Para que se devuelvan datos de filas del portal específicas, utilice
_offset.nombre-portaly_limit.nombre-portal. Un nombre de portal puede ser el nombre del objeto que se muestra en el Inspector de FileMaker Pro Advanced o el nombre de la tabla relacionada. Si omite los valores de desplazamiento y límite de las filas del portal, el valor predeterminado para el desplazamiento es 1 y el límite predeterminado para los registros del portal es 50.
Subir datos del contenedor
Para subir datos del contenedor, utilice un método HTTP POST con el punto de conexión de API containers, y especifique el nombre de la base de datos, el nombre de la presentación, el ID de registro, el nombre de campo y una repetición de campo.
| Método HTTP | POST |
|---|---|
| URL | Formato: /fmi/data/versión/databases/nombre-base-de-datos/layouts/nombre-presentación/records/id-registro/containers/nombre-campo/repetición-campo
|
| Encabezado HTTP | Content-Type: multipart/form-data Authorization: Bearer token-sesión, donde token-sesión es el valor exclusivo de X-FM-Data-Access-Token para la sesión de la base de datos. |
| Parámetros | Una secuencia de datos MIME de varias partes (Content-Type: multipart/form-data) en la que el objeto de campo se define como una parte con Utilice una biblioteca que admita la especificación de multipart/form-data. |
| Respuesta |
Un cuerpo de respuesta vacío y una matriz de mensajes que muestra el código de error 0. Por ejemplo: {
"response": {},
"messages":[{"code":"0","message":"OK"}]
}
Consulte Respuestas de error. |
Notas
- El campo contenedor debe ser un campo de la ocurrencia de la tabla de la presentación especificada. No puede ser un campo contenedor de una tabla relacionada.
- FileMaker Data API admite todos los tipos MIME. No se comprueban los tipos MIME para limitarlos a los tipos admitidos por el software de FileMaker o el servidor Web.
- FileMaker Data API almacena en la memoria caché los datos del campo contenedor en una carpeta de caché del equipo principal durante la subida, pero los datos en caché se eliminan cuando finaliza la solicitud.
Realizar una petición de búsqueda
Para realizar una petición de búsqueda, utilice un método HTTP POST con el punto de conexión de API _find, y especifique el nombre de la base de datos y la presentación, e información adicional para indicar los campos de consulta y los criterios, el tipo de ordenación, el registro inicial y el número de registros. También puede especificar información del portal para limitar el número de registros relacionados que se devuelven.
| Método HTTP | POST |
|---|---|
| URL |
/fmi/data/versión/databases/nombre-base-de-datos/layouts/nombre-presentación/_find
versión: la versión de FileMaker Data API solicitada, |
| Encabezado HTTP |
Content-Type: application/json Authorization: Bearer token-sesión, donde token-sesión es el valor exclusivo de X-FM-Data-Access-Token para la sesión de la base de datos. |
| Parámetros | Una consulta en formato JSON que especifica los campos y los criterios de búsqueda. Parámetros opcionales que especifican solicitudes de omisión, el orden de clasificación, el registro inicial (desplazamiento), el número de registros (límite) y los portales para limitar el número de registros relacionados que se devuelven. Si desea obtener los datos de respuesta en el contexto de una presentación diferente, utilice el parámetro Por ejemplo: {
"query":[
{"Group": "=Cirujano"},
{"Lugar de trabajo" : "Madrid", "omit" : "true"}],
"sort":[
{"fieldName": "Lugar de trabajo","sortOrder": "ascend"},
{"fieldName": "Nombre", "sortOrder": "ascend"} ]
}
Ejemplo con desplazamiento, límite y portales: {
"query":[
{"Group": "=Cirujano"},
{"Lugar de trabajo" : "Madrid", "omit" : "true"}],
"portal": ["Portal1","Portal2"],
"limit": "10",
"offset": "1",
"offset.Portal1": "1",
"limit.Portal1": "5",
"layout.response": "Doctores"
}
Puede ejecutar guiones de FileMaker como parte de esta solicitud. Para ello, incluya los parámetros |
| Respuesta |
Los datos de registros en formato JSON y una matriz de mensajes que muestra el código de error 0. Por ejemplo: {
"response": {
"data": [
...
]
},
"messages": [{"code":"0","message":"OK"}]
}
Consulte Respuestas de error. |
Notas
- La ordenación y la devolución de registros pueden llevar mucho tiempo en completarse. Reduzca el tiempo de descarga de registros. Para ello, limite la cantidad de campos en la presentación solicitada y omita los campos que contienen comentarios.
- Para limitar el número de registros y filas que se muestran en un conjunto relacionado, especifique el desplazamiento.nombre-portal y límite.Parámetros de nombre-portal.
- No se pueden especificar campos globales como criterios de búsqueda. Si especifica un campo global con una petición de búsqueda, recibirá un mensaje de error. En su lugar, establezca el valor de campo global antes que la petición de búsqueda. Consulte Establecer valores de campos globales.
Establecer valores de campos globales
Para establecer los valores de campos globales, utilice un método HTTP PATCH con el punto de conexión de API globals y especifique el nombre de la base de datos.
| Método HTTP | PATCH |
|---|---|
| URL | /fmi/data/versión/databases/nombre-base-de-datos/globals
versión: la versión de FileMaker Data API solicitada, |
| Encabezado HTTP |
Content-Type: application/json Authorization: Bearer token-sesión, donde token-sesión es el valor exclusivo de X-FM-Data-Access-Token para la sesión de la base de datos. |
| Parámetros | Un objeto JSON con pares de campo y valor que especifican los campos globales que se van a establecer. Los campos globales deben especificarse mediante nombres de campo completos (nombre de tabla::nombre de campo). Por ejemplo: { "globalFields":
{
"baseTable::gCompany":"FileMaker",
"baseTable::gCode":"95054"
}
}
|
| Respuesta |
Un cuerpo de respuesta vacío y una matriz de mensajes que muestra el código de error 0. Por ejemplo: {
"response": {},
"messages":[{"code":"0","message":"OK"}]
}
|
Ejecutar guiones de FileMaker
FileMaker Data API puede ejecutar guiones de FileMaker:
- Mediante un método HTTP GET con el punto de conexión de API
script. Consulte Ejecutar un guión. - Como parte de esta solicitud. Para ello, incluya los parámetros
script.prerequest,script.presortyscripten el cuerpo de la petición. Consulte Ejecutar un guión con otra petición.
Ejecutar un guion
Para ejecutar de forma independiente un guión de FileMaker, utilice un método HTTP GET con el punto de conexión de API script.
| Método HTTP | GET |
|---|---|
| URL | /fmi/data/versión/databases/nombre-base-de-datos/layouts/nombre-presentación/script/nombre-guión
versión: la versión de FileMaker Data API solicitada, |
| Encabezado HTTP | Content-Type: application/json |
| Parámetros | script.param: la cadena de texto que se utilizará como parámetro para el guión al que nombre-guión le ha asignado un nombre. |
| Respuesta |
Un cuerpo de respuesta vacío y una matriz de mensajes que muestra el código de error 0. Por ejemplo: {
"response": {},
"messages":[{"code":"0","message":"OK"}]
}
Consulte Respuestas de error. |
Notas
- Al utilizar FileMaker Data API para ejecutar un guión, asegúrese de que el guión presente un nombre exclusivo. Si hay varios guiones con el mismo nombre, FileMaker Data API no podrá controlar a qué guión se llama, incluso aunque los guiones se encuentren en carpetas diferentes.
Ejecutar un guión con otra petición
Puede ejecutar un guión de FileMaker como parte de otra petición. Para ello, incluya los parámetros script.prerequest, script.presort y script en el cuerpo de la solicitud.
| Parámetro | Valor |
|---|---|
guión |
El nombre del guión que se ejecutará después de la acción especificada por la llamada de la API (obtener, crear, editar, duplicar, eliminar y buscar) y tras la ordenación posterior. |
script.param |
La cadena de texto que se utilizará como parámetro para el guión al que script le ha asignado un nombre. |
script.prerequest |
El nombre del guión que se ejecutará antes de la acción especificada por la llamada de la API y la ordenación posterior. |
script.prerequest.param |
La cadena de texto que se utilizará como parámetro para el guión al que script.prerequest le ha asignado un nombre. |
script.presort |
El nombre del guión que se ejecutará después de la acción especificada por la llamada de la API, pero antes de la ordenación posterior. |
script.presort.param |
La cadena de texto que se utilizará como parámetro para el guión al que script.presort le ha asignado un nombre. |
Orden de ejecución de los guiones
Puede especificar los parámetros script.prerequest, script.presort y script en una única llamada de la API. Cada palabra clave solo se puede especificar una vez. El anfitrión procesa estos parámetros como parte de la llamada de la API en este orden:
- Acceda a la presentación especificada en la URL.
- Ejecute el guión al que
script.prerequestle ha asignado un nombre, si se ha especificado. - Realice la acción especificada por la llamada de la API (obtener, crear, editar, duplicar, eliminar y buscar).
- Ejecute el guión al que
script.presortle ha asignado un nombre, si se ha especificado. - Realice la ordenación especificada en la llamada de la API:
- Para obtener un intervalo de registros, realice la ordenación especificada por el parámetro
_sort. - Para ejecutar una petición de búsqueda, realice la ordenación especificada por el parámetro
sort.
- Para obtener un intervalo de registros, realice la ordenación especificada por el parámetro
- Ejecute el guión al que
scriptle ha asignado un nombre, si se ha especificado. - Devuelva el conjunto de resultados para la llamada de la API con los parámetros de desplazamiento y límite aplicados, si se han especificado.
Notas
- En las llamadas que utilizan los métodos HTTP GET y HTTP DELETE, los parámetros de guiones se incluyen como parámetros de URL; consulte Obtener un único registro, Obtener un intervalo de registros y Eliminar un registro.
- En las llamadas que utilizan los métodos HTTP POST y HTTP PATCH, los parámetros de guiones se incluyen en el cuerpo de la solicitud; consulte Crear un registro, Editar un registro y Ejecutar una petición de búsqueda.
- Para los parámetros de guiones
script.param,script.prerequest.paramyscript.presort.param, solo puede especificar una única cadena de texto. Para transferir varios parámetros, puede crear una cadena que delimite los parámetros y permitir que el guión analice los parámetros individuales. Por ejemplo, transfiera "param1|param2|param3" con una lista con el carácter "|" con codificación de URL como:param1%7Cparam2%7Cparam3 - Los resultados del guión se devuelven mediante los parámetros
scriptResult,scriptResult.prerequestyscriptResult.presorten los datos JSON. Los errores del guión se devuelven mediante los parámetrosscriptError,scriptError.prerequestyscriptError.presorten los datos JSON. (Los errores del guión no se devuelven mediante un código de estado HTTP).
Por ejemplo:
https://<anfitrión>/fmi/data/v1/databases/clientes/layouts/entrada/records/14?script=UpdateProcessing&script.param=14
Por ejemplo:
{"query":[{"Title":"Jefe de oficina"}], "script.prerequest":"Eliminar duplicados"}
Respuestas de error
Si se produce un error, FileMaker Data API devuelve:
- Un código de estado HTTP de nivel 400 para los errores HTTP.
- Un código de estado HTTP de nivel 500 para los errores de FileMaker
| Código de estado HTTP | Categoría HTTP | Descripción |
|---|---|---|
| 400 | Solicitud incorrecta | Se produce cuando el servidor no puede procesar la petición porque está incompleta o no es válida. |
| 401 | No autorizado | Se produce cuando el cliente no tiene autorización para acceder a la API. Si se produce este error al intentar iniciar una sesión en la base de datos, hay un problema con la cuenta de usuario o la contraseña especificadas. Si se produce este error con otras llamadas, el token de acceso no se ha especificado o no es válido. |
| 403 | Prohibido | Se produce cuando el cliente tiene autorización, pero la llamada intenta realizar una acción que está prohibida por un motivo diferente. |
| 404 | No encontrado | Se produce si la llamada utiliza una URL con un esquema de URL no válido. Compruebe la URL especificada en busca de errores de sintaxis. |
| 405 | Método no permitido | Se produce cuando se utiliza un método HTTP incorrecto con una llamada. |
| 415 | Tipo de medio no admitido | Se produce si falta el encabezado necesario o no es correcto para la solicitud:
|
| 500 | Error de FileMaker | Incluye mensajes y códigos de error de FileMaker. Consulte los códigos de error de FileMaker en la Ayuda de FileMaker Pro Advanced. |
Notas
- Si el motor de FileMaker Data API no se está ejecutando o no se puede acceder a él, los códigos o los mensajes de error devueltos dependen del servidor Web (Apache o IIS).
- Para obtener información sobre los códigos de estado HTTP adicionales devueltos, visite www.w3.org.
Alojar, probar y supervisar las soluciones de FileMaker Data API
Alojar una solución de FileMaker Data API
- Complete todos los pasos descritos en Preparar bases de datos para el acceso mediante FileMaker Data API.
- Compruebe que el acceso mediante FileMaker Data API se haya habilitado y configurado correctamente en la Admin Console. Consulte el Centro de Documentación del producto.
- Compruebe que el servidor Web y el motor de FileMaker Data API se estén ejecutando.
-
Utilice el cifrado para la comunicación.
FileMaker Data API requiere que las aplicaciones de la API REST utilicen una conexión HTTP. Las conexiones HTTP utilizan el cifrado SSL (Capa de sockets seguros) para la comunicación.
FileMaker Server proporciona un certificado SSL estándar firmado por FileMaker, Inc., que no comprueba el nombre del servidor. El certificado predeterminado de FileMaker se ha diseñado solo para fines de prueba. Se necesita un certificado SSL personalizado para la producción. Consulte la Guía de instalación y configuración de FileMaker Server.
La tecnología o el lenguaje utilizados para llamar a FileMaker Data API deben ser compatibles con Transport Layer Security (TLS) v1.2 para comunicarse con el servidor Web.
Probar una solución de FileMaker Data API
Antes de pasar a producción la solución de FileMaker Data API, compruebe que presenta un funcionamiento correcto.
- Pruebe funciones como la búsqueda, la adición, la eliminación y la ordenación de registros con cuentas y conjuntos de privilegios diferentes.
- Compruebe que los distintos conjuntos de privilegios funcionan según lo esperado. Para ello, pruebe con cuentas diferentes. Asegúrese de que los usuarios no autorizados no acceden ni modifican los datos.
- Compruebe que la solución presenta el mismo comportamiento cuando se llama a ella desde diferentes sistemas operativos.
Supervisar las soluciones de FileMaker Data API
El administrador del servidor puede utilizar la Admin Console para iniciar o detener el motor de FileMaker Data API, supervisar los clientes de FileMaker Data API, realizar un seguimiento de uso de las llamadas de FileMaker Data API y descargar el archivo de registro de FileMaker Data API.
| Para | Use |
|---|---|
| Iniciar o detener el motor de FileMaker Data API. |
La pestaña Conectores > FileMaker Data API de la Admin Console. Consulte "Iniciar o detener los componentes de FileMaker Server" en la Ayuda de FileMaker Server o la documentación del producto de FileMaker Cloud en el Centro de Documentación del producto. Con FileMaker Server, también puede utilizar un comando de CLI. Consulte la Ayuda de CLI. |
| Supervisar los clientes de FileMaker Data API. |
La lista de clientes de la página Bases de datos de la Admin Console. En esta página, se muestra información sobre los clientes y las bases de datos a las que se accede. En esta página, puede desconectar los clientes de FileMaker Data API, pero no puede enviarles mensajes. Consulte "Administrar clientes" en la Ayuda de FileMaker Server o la documentación del producto de FileMaker Cloud en el Centro de Documentación del producto. |
| Realizar un seguimiento de uso de las llamadas de FileMaker Data API. |
La pestaña Conectores > FileMaker Data API de la Admin Console. En esta pestaña, se muestran el límite anual de FileMaker Data API establecido por la licencia, la cantidad de datos que se han transmitido desde la fecha de restablecimiento anual anterior y la fecha de restablecimiento anual de la licencia.
|
| Ver el registro de FileMaker Data API |
Mientras que los clientes de FileMaker Data API están conectados a una base de datos, los datos estadísticos sobre los clientes se registran en fmdapi.log. Consulte "Registro de FileMaker Data API" en la Ayuda de FileMaker Server o la documentación del producto de FileMaker Cloud en el Centro de Documentación del producto. |
Integración de FileMaker Data API con Tableau
Acerca de la integración con Tableau
Use un conector de datos Web para definir una conexión entre una base de datos de FileMaker alojada y Tableau. El conector de datos Web es una implementación de ejemplo que acepta llamadas de API REST en formato JSON. La conexión utiliza FileMaker Data API para importar datos de una base de datos de FileMaker alojada en Tableau.
Utilice FileMaker Server o un producto de FileMaker Cloud para alojar la base de datos de FileMaker. Estos anfitriones se pueden integrar en los siguientes productos de Tableau:
Tableau Desktop, versión 10, para Windows o macOS como mínimo. Utilice FileMaker Web Data Connector para Tableau Desktop para definir una conexión en Tableau Desktop.
Tableau Server, instalado en las instalaciones o alojado en el cliente. Aloje FileMaker Web Data Connector para Tableau Server en Tableau Server.
Tableau Cloud. Ejecute una instancia de Tableau Server para transferir datos a Tableau Cloud. Aloje FileMaker Web Data Connector para Tableau Server en Tableau Server.
Tableau Online. Requiere el uso de Tableau Bridge.
Requisitos de Web Data Connector
FileMaker Web Data Connector para Tableau requiere lo siguiente:
- Una base de datos de FileMaker Pro Advanced protegida por contraseña que contenga los datos que se van a importar. La base de datos debe estar alojada en FileMaker Server o en un anfitrión de FileMaker Cloud. FileMaker Server y FileMaker Cloud for AWS admiten la autenticación de archivos de FileMaker y la autenticación mediante OAuth. FileMaker Cloud requiere la autenticación mediante el ID de FileMaker.
-
Un punto de conexión de API REST válido.
En FileMaker Server, el punto de conexión hace referencia a un punto de conexión HTML que proporciona la información necesaria para los servicios Web. El punto de conexión presenta el formato
https://<nombre de anfitrión>/fmi/data/versión/tableau/fm_connector.html
dondenombre de anfitriónes el nombre completo del anfitrión de FileMaker Server.Por ejemplo:
https://myserver.mycompany.com/fmi/data/v1/tableau/fm_connector.html Un certificado SSL personalizado válido en el anfitrión. FileMaker Web Data Connector para Tableau no admitirá la importación de datos sin un certificado SSL personalizado válido.
Nota:si el anfitrión utiliza un certificado de nombre alternativo del firmante (SAN, por sus siglas en inglés), el nombre de anfitrión debe coincidir con el nombre común utilizado en el certificado de SAN.
Preparar la importación de datos en Tableau
Siga los pasos descritos en Preparar bases de datos para el acceso mediante FileMaker Data API para definir la presentación de importación y habilitar el acceso mediante FileMaker Data API en la base de datos.
Nota:para importar datos en Tableau, la tabla debe tener al menos un registro con datos de registro.
Se importan los siguientes tipos de campo de FileMaker como tipos de datos de Tableau.
| Tipo de campo de FileMaker | Tipo de datos de Tableau |
|---|---|
| Texto | Cadena |
| Fecha | Fecha |
| Hora | Cadena |
| Fecha y hora | Fecha/hora |
| Numérico | Flotante |
No se admiten los siguientes tipos de campo de FileMaker al realizar la importación en Tableau:
- Campos contenedor.
- Campos de sumario. Puede crear un campo de sumario en Tableau en función de los datos que importe desde FileMaker.
- Campos de cálculo. Puede crear un campo de cálculo en Tableau en función de los datos que importe desde FileMaker.
- Datos de gráficos
- Datos de los portales de FileMaker Pro Advanced. Para importar datos de registros relacionados, cree una presentación de FileMaker Pro Advanced basada en la tabla relacionada, o importe datos desde tablas independientes de FileMaker Pro en Tableau y, a continuación, una las tablas en Tableau.
- Repeticiones de campos en los que la visualización de campos repetidos de Mostrar repeticiones incluye varios valores. Se admite una única repetición.
- Valores no numéricos en campos numéricos. Si Tableau encuentra valores no numéricos en campos numéricos, no se importarán los datos.
No utilice palabras reservadas como nombres de campo en FileMaker Pro Advanced.
Configurar la conexión de datos en Tableau
Siga las instrucciones de la Ayuda en línea del producto Tableau que describen cómo utilizar los conectores de datos Web.
Por ejemplo, para configurar la conexión de datos con FileMaker Server Web Data Connector para Tableau Desktop:
- En Tableau Desktop, en Conectar (a la izquierda de la pantalla, seleccione Más Web Data Connector.
- Introduzca la URL del punto de conexión de FileMaker Server
https://<nombre de anfitrión>/fmi/data/v1/tableau/fm_connector.html
donde<nombre de anfitrión>es el nombre completo del anfitrión de FileMaker Server. -
En el cuadro de diálogo Importar datos de archivo de FileMaker:
-
Inicie sesión en la base de datos de FileMaker Pro Advanced. Para ello, introduzca la siguiente información o utilice un proveedor de identidad de OAuth.
- Nombre de base de datos de origen: el nombre de la base de datos de FileMaker Pro Advanced.
- Nombre de presentación de origen: el nombre de la presentación de FileMaker Pro Advanced.
- Nombre de cuenta: el nombre de la cuenta de FileMaker Pro Advanced con el privilegio fmrest.
- Contraseña: la contraseña de la cuenta de FileMaker Pro Advanced.
- Seleccione Activar actualización incremental para habilitar la actualización incremental.
-
- Haga clic en Importar datos de FileMaker.
Tableau importará los datos. El tiempo de procesamiento depende de la cantidad de registros importados, la carga del servidor y el rendimiento de la red. Tableau asigna nombres de campo y datos de FileMaker Pro Advanced a dimensiones y medidas. Por lo general, los datos de cadena se asignan a dimensiones, mientras que los datos numéricos se asignan normalmente a medidas. La asignación se produce automáticamente durante la importación, pero puede personalizarla.
Notas
-
Al especificar el Nombre de presentación de origen, asegúrese de que el nombre de presentación sea exclusivo. Si la base de datos incluye dos presentaciones con el mismo nombre, la conexión de datos de Tableau no puede distinguirlas. Tableau muestra solo un nombre, y puede que no se trate de la presentación que deseaba.
- Al configurar la conexión de datos en Tableau, no seleccione la opción para solicitar al usuario la autenticación.
-
Utilice Activar actualización incremental para importar solo los nuevos registros.
- Tras importar los datos de FileMaker con la actualización incremental habilitada, seleccione la pestaña Hoja en Tableau para acceder a la hoja de cálculo.
- Seleccione Datos > FM: nombre-base-de-datos / nombre-presentación > Extraer > Actualización (incremental).
- Seleccione la pestaña Fuente de datos.
- Haga clic en Actualizar ahora para visualizar los nuevos registros.
- Al habilitar la actualización incremental no se crea una conexión continua en directo entre Tableau y la base de datos de FileMaker alojada. Debe ejecutar de forma manual la actualización incremental.
- Con la actualización incremental se importan solo los nuevos registros. No se actualizarán los registros de FileMaker Pro Advanced que se hayan modificado o eliminado. Para obtener datos modificados o suprimir registros eliminados debe crear un nuevo libro en Tableau e importar de nuevo los datos.
- Con la actualización incremental se crea un campo denominado -recordId. Si realiza cambios en este campo, es posible que no pueda realizar una actualización incremental.
- En Tableau, puede cambiar el esquema y los datos que se han importado. Sin embargo, si modifica el esquema o los datos en Tableau, esos cambios no se transmiten al archivo de FileMaker Pro Advanced.
- Si modifica el esquema en el archivo de FileMaker Pro Advanced, debe crear un nuevo libro en Tableau e importar de nuevo los datos.
- Si cierra el libro de Tableau y lo vuelve a abrir, la importación incremental ya no funcionará.
- Después de establecer la conexión de datos a Tableau, FileMaker Web Data Connector almacena en la memoria caché la cuenta de usuario y la contraseña hasta que se cierra el libro, con las siguientes consideraciones:
- Si se agota el tiempo de espera de la sesión de FileMaker mientras está conectado a Tableau, FileMaker Web Data Connector intenta conectar de nuevo al usuario a la base de datos alojada.
- Si caduca la conexión de Tableau, FileMaker Web Data Connector intenta conectarse de nuevo a la base de datos alojada siempre que el libro de Tableau esté abierto.
- Si caduca el token de actualización de Tableau, debe volver a publicar la fuente de datos en Tableau Desktop.
- Si el libro está cerrado y se vuelve a abrir a continuación, deberá introducir de nuevo su nombre de cuenta y contraseña durante la importación de datos inicial.
- En la página de fuente de datos de Tableau, se muestran hasta 1.000.000 (un millón) de filas, incluso aunque se importen más registros.
- El uso de caracteres especiales en los nombres de bases de datos, tablas o presentaciones impide que Tableau pueda establecer una conexión de datos.