Guía de OData de FileMaker Cloud 2.18
Acerca del uso de OData con bases de datos de FileMaker
Introducción
OData (Open Data Protocol) es una implementación de API estándar del sector que proporciona un método estándar para consultar y actualizar datos, lo que permite a los clientes de API REST acceder a los datos de FileMaker® alojados por FileMaker Cloud®. OData se ajusta a la arquitectura de transferencia de estado representacional (REST) y, por lo tanto, es una API REST. OData es similar a Open Database Connectivity (ODBC) y Java Database Connectivity (JDBC), ya que proporciona a las aplicaciones de terceros, como Excel, un método estándar para acceder a los datos de FileMaker. Consulte Protocolo OData 4.0.
Además, OData devuelve datos en notación de objetos JavaScript (JSON) y el formato de redifusión Atom (Atom). JSON es un formato de texto que se utiliza habitualmente con las API REST porque es compacto y está en lenguaje natural. Atom es un formato XML utilizado para crear y actualizar recursos Web y es compatible con las aplicaciones que utilizan datos estructurados XML en lugar de JSON.
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, tablas, relaciones y contenedores. Consulte la Ayuda de FileMaker Pro Advanced.
- el uso de FileMaker Cloud para alojar bases de datos. Debe saber cómo configurar FileMaker Cloud, habilitar el acceso a las bases de datos alojadas y supervisar las bases de datos alojadas mediante la Admin Console de FileMaker Cloud. Consulte la documentación de FileMaker Cloud en el Centro de Documentación del producto.
- el uso de API REST en aplicaciones del servidor o servicios Web que llaman a los métodos POST, GET, PATCH y DELETE.
Pasos generales para el uso de OData con bases de datos de FileMaker
- Prepare la base de datos de FileMaker para acceder a OData mediante FileMaker Pro Advanced. Consulte Activar el acceso mediante OData.
- Escriba código que llame a los métodos de OData para buscar y modificar registros, ejecutar guiones de FileMaker y cambiar el esquema de una base de datos alojada. Consulte Escribir llamadas de OData.
- Aloje la base de datos de FileMaker mediante FileMaker Cloud con el acceso OData activado. Consulte Alojar bases de datos para el acceso mediante OData.
- Realice una prueba para asegurarse de que el acceso mediante OData funcione correctamente. Consulte Probar el acceso mediante OData.
- Supervise la base de datos alojada mediante la Admin Console de FileMaker Cloud. Consulte Supervisar el acceso mediante OData.
Cómo se procesan las llamadas de OData
Cliente de API REST
1
6
Servidor Web
2
5
OData Listener
3
4
Servidor de base de datos
- Un cliente de API REST envía una llamada de OData (solicitud HTTPS) al servidor Web a través del puerto HTTPS (puerto 443).
- El servidor Web enruta la solicitud a través del módulo de servidor Web de FileMaker a OData Listener de FileMaker.
- OData Listener convierte la solicitud HTTPS (URL con datos de JSON o Atom) 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 a OData Listener.
- OData Listener convierte los datos de FileMaker en una respuesta HTTPS (URL con datos de JSON o Atom) 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.
Comparación de las soluciones de API
La plataforma FileMaker proporciona dos API REST para acceder a los datos de las bases de datos de FileMaker alojadas. Determine la solución que mejor se ajuste a sus objetivos empresariales y entorno.
| Solución | Utilícela al | Ventajas |
|---|---|---|
| Norma OData |
|
|
| FileMaker Data API |
|
|
Terminología de OData y FileMaker
Siempre que sea posible, en esta guía, se utilizará la terminología de FileMaker. Para ofrecer claridad, los términos de OData se utilizan algunas veces junto con los de FileMaker. En la siguiente tabla, se muestran los términos equivalentes y sus definiciones.
Para obtener información sobre la terminología de FileMaker, consulte el Centro de Documentación del producto.
| Término de OData | Término de FileMaker |
|---|---|
| entity | registro |
| entity set | tabla |
| entity container | un grupo de campos que no es necesariamente un registro como, por ejemplo, una URL y un nombre de base de datos |
| collection of entity containers | una lista de un grupo de campos como, por ejemplo, una lista de nombres de base de datos |
| property | campo |
| path segment | un valor entre dos caracteres de barra diagonal (en una URL) |
| raw value | un valor binario que es una cadena de bytes en lugar de un valor de JSON o Atom estructurado en lenguaje natural |
Preparar las bases de datos para el acceso mediante OData
Activar el acceso mediante OData
Para permitir el acceso mediante OData a los datos de FileMaker, debe activar el privilegio ampliado fmodata en FileMaker Pro Advanced. Si no activa el privilegio ampliado fmodata, las aplicaciones de OData no podrán utilizar las llamadas de OData para acceder a la base de datos, incluso aunque esté alojada.
Nota: Por motivos de seguridad, active el privilegio ampliado fmodata solo en los conjuntos de privilegios para las cuentas que desea que accedan mediante OData.
Consulte "Editar privilegios ampliados para un conjunto de privilegios" en la Ayuda de FileMaker Pro Advanced.
Conformidad con la norma OData y compatibilidad con las funciones de OData
Funciones de OData admitidas
OData utiliza convenciones que funcionan con normas existentes (REST, JSON, XML y Atom) a fin de proporcionar representación para funciones habituales. La Plataforma FileMaker admite OData en el nivel de conformidad intermedio, con algunas excepciones. Consulte la guía de especificaciones y referencia de Protocolo OData 4.0.
Puede utilizar la API OData para:
- recuperar información sobre FileMaker Cloud; por ejemplo, nombres de bases de datos alojadas y nombres de tablas, y metadatos de una base de datos. Consulte Estructura y metadatos de bases de datos.
- crear, editar o eliminar un registro. Consulte Modificar datos.
- buscar un registro o todos los registros. Consulte Solicitar datos.
- especificar criterios para buscar un conjunto de registros. Consulte Opciones de consulta.
- ejecutar guiones de FileMaker. Consulte Ejecutar guiones.
- subir datos del contenedor. Consulte Trabajar con datos del contenedor.
Funciones de OData no admitidas
No se admiten las siguientes funciones de OData del nivel de conformidad intermedio:
- la opción de consulta
$search $expand(compatible solo como parte de una operación$crossjoin)- los operadores
lambdaanyyall $filteren entidades ampliadasfunciones y operadores canónicos integrados:
- indexof()
- fractionalseconds()
- isof()
- geo.distance()
- geo.length()
- geo.intersects()
Además, no se admiten las siguientes acciones:
- el acceso a datos desde fuentes de datos ODBC externas
- el uso de plug-ins de FileMaker.
- la activación de activadores de guiones mediante la interacción del usuario; OData solo habilita activadores de guiones mediante la ejecución de un guión de FileMaker
- el acceso al sistema de archivos del equipo del servidor; por ejemplo, OData no admite la función Get ( TemporaryPath ).
Información de referencia de OData
Varias referencias de API proporcionan especificaciones de OData:
Notas sobre las URL y los formatos de datos
- La longitud máxima de URL puede verse influida por las diferencias en los sistemas operativos, los servidores Web y los navegadores Web. Para un uso óptimo entre plataformas, limite la longitud de la URL a 2000 caracteres.
- 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.
- Los valores de cadena de datos especificados en los parámetros del cuerpo de la solicitud deben utilizar la codificación UTF-8.
Guiones de FileMaker y OData
Un guión de FileMaker es un conjunto de pasos de guión con nombre que automatiza las tareas que se realizan con frecuencia y que puede combinar varias tareas. Cuando se utilizan con OData, los guiones de FileMaker permiten que los servicios Web realicen más tareas o una serie de tareas. Consulte Ejecutar guiones.
Notas
- 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 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 el conjunto de privilegios Acceso total a un guión para permitir que realice tareas a las que no concedería acceso a usuarios individuales. 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.
- 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 cambios de datos hasta que se guarden en el servidor. Esto incluye los pasos de guión como Cortar, Copiar y Pegar. Convierta acciones únicas en guiones para incluir el paso de guión Consignar registro/petición. Al diseñar guiones que se ejecutan desde un servicio Web, incluya el paso de guión 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 para el acceso mediante OData. Compruebe que el guión utilice solo pasos de guión compatibles con OData, como se describe anteriormente.
Escribir llamadas de OData API
Componentes de las llamadas de OData
Las llamadas de OData incluyen los siguientes componentes.
| Componente | Descripción |
|---|---|
| Método HTTP | OData utiliza los siguientes métodos HTTP:
|
| Encabezados HTTP | OData utiliza los siguientes encabezados:
|
| URL | https://anfitrión/fmi/odata/versión/nombre-base-de-datos anfitrión - nombre del anfitrión de FileMaker Cloud Ejemplo: |
| Ejemplo de datos de parámetros en JSON y Atom | Solo para los métodos POST y PATCH. |
Crear una conexión autenticada en el anfitrión de FileMaker
OData requiere autenticación a través de una cuenta del ID de FileMaker.
Para definir una conexión al anfitrión de FileMaker:
- Genere un token del ID de FileMaker para la autenticación externa. Consulte la Ayuda de FileMaker Customer Console.
- Incluya el token del ID de FileMaker del paso 1 en el encabezado "Authorization" para todas las llamadas de OData.
Por ejemplo, utilice la siguiente URL y encabezado:
- URL:
https://anfitrión/fmi/odata/v4/nombre-base-de-datos/$metadataAnfitrión - nombre del anfitrión de FileMaker Cloud
nombre-base-de-datos - nombre de la base de datos de FileMaker - Encabezado:
Authorization FMID FileMaker_ID_Token
- URL:
Estructura y metadatos de base de datos
La información sobre las bases de datos alojadas y su estructura está disponible al ejecutar métodos HTTP GET.
Obtener los nombres de las bases de datos
Para obtener una lista de nombres de bases de datos, utilice el método GET sin especificar un nombre de base de datos en la URL.
| Componente | Descripción |
|---|---|
| Método HTTP | GET |
| URL | https://anfitrión/fmi/odata/versión anfitrión - nombre del anfitrión de FileMaker Cloud Ejemplo: |
Información de FileMaker
- OData devuelve una lista de nombres de bases de datos y sus URL de punto de conexión correspondientes.
Obtener una lista de tablas
Para recuperar una lista de tablas de una base de datos, utilice el método HTTP GET con el nombre de la base de datos añadido a la URL.
| Componente | Descripción |
|---|---|
| Método HTTP | GET |
| URL | https://anfitrión/fmi/odata/versión/nombre-base-de-datos anfitrión - nombre del anfitrión de FileMaker Cloud Ejemplo: |
Obtener metadatos
Para solicitar información de metadatos de la tabla, utilice el método HTTP GET.
Utilice la palabra clave $metadata con la raíz del servicio de base de datos para solicitar una lista completa de los metadatos de la base de datos.
| Componente | Descripción |
|---|---|
| Método HTTP | GET |
| URL | https://anfitrión/fmi/odata/versión/nombre-base-de-datos/$metadata anfitrión - nombre del anfitrión de FileMaker Cloud Ejemplo: |
Información de FileMaker
Para proporcionar información sobre las tablas de FileMaker de la base de datos, se añaden anotaciones (información no definida en la norma OData) a los resultados de metadatos como, por ejemplo, el número de versión del producto de FileMaker.
Las anotaciones mostradas a continuación presentan el valor booleano "true" si están presentes. De lo contrario, el valor es "false".
- AutoGenerated: determina si FileMaker Pro Advanced genera automáticamente el valor del campo
- Index: determina si se indexan los valores de los campos
- VersionID: determina si el campo es un campo de fecha y hora, y se genera un valor de fecha y hora cuando se modifica el registro
- Global: determina si el campo contiene un valor global
- Calculation: determina si el campo es un tipo de cálculo
- Summary: determina si el campo es un tipo de sumario
Otras anotaciones:
- MaxRepetitions: un valor de entero que indica el número máximo de repeticiones definido para un campo repetido. Si esta anotación no está presente, no se trata de un campo repetido.
- ExternalSecurePath: una cadena que indica la ruta relativa especificada para el almacenamiento seguro de un campo contenedor.
- BestRowID: siempre contiene ROWID, un campo del sistema que se incluye explícitamente en un conjunto de resultados al especificar
$select=ROWID. El valor del conjunto de resultados es el mismo que el de la función Get ( RecordID ) para un registro. - RowVersion: siempre contiene ROWMODID, un campo del sistema que se incluye explícitamente en un conjunto de resultados al especificar
$select=ROWMODID. El valor del conjunto de resultados es el mismo que el de la función Get ( RecordModificationCount ) para un registro.
Importante: OData requiere que cada tabla defina una clave principal. OData utiliza campos que no están vacíos y que requieren un valor exclusivo como clave principal. Por lo tanto, si no se han definido esos campos para las tablas, el campo del sistema ROWID se utiliza como clave principal. El campo del sistema ROWID contiene el mismo valor que la función Get ( RecordID ) para el registro.
Modificar datos
OData admite las operaciones de creación, actualización y eliminación de registros según los privilegios de acceso asignados a una cuenta.
Crear un registro
Para crear un registro para una tabla, utilice el método POST. El cuerpo de POST debe contener datos de un único registro en formato JSON.
| Componente | Descripción |
|---|---|
| Método HTTP | POST |
| URL | https://anfitrión/fmi/odata/versión/nombre-base-de-datos/nombre-tabla anfitrión - nombre del anfitrión de FileMaker Cloud Ejemplo: |
| Parámetros | Ejemplo de JSON: {Ejemplo de Atom: |
Información de FileMaker
- Para proporcionar los valores para las repeticiones individuales de un campo repetido, se debe especificar el número de repetición entre corchetes (por ejemplo,
Nombre[4]). - Si crea un registro con objetos de datos vacíos en formato JSON, al menos un campo debe permitir valores nulos.
- Los campos globales de FileMaker son de solo lectura y no se pueden actualizar con OData.
Eliminar un registro
Para eliminar un registro, utilice el método HTTP DELETE. Para ello, especifique el nombre de la tabla y el valor de la clave principal del registro en la URL.
| Componente | Descripción |
|---|---|
| Método HTTP | DELETE |
| URL | https://anfitrión/fmi/odata/versión/nombre-base-de-datos/nombre-tabla (valor-clave-principal) anfitrión - nombre del anfitrión de FileMaker Cloud Ejemplo: |
Información de FileMaker
- Para eliminar varios registros, especifique el criterio
$filter.
Actualizar un registro
Para actualizar un registro, utilice el método HTTP PATCH con el registro que desee actualizar en la URL.
| Componente | Descripción |
|---|---|
| Método HTTP | PATCH |
| URL | https://anfitrión/fmi/odata/versión/nombre-base-de-datos/nombre-tabla (valor-clave-principal) anfitrión - nombre del anfitrión de FileMaker Cloud Ejemplo: |
| Parámetros | Ejemplo de JSON: { |
Información de FileMaker
- Para actualizar los valores de contenedor, se debe proporcionar un valor codificado en Base64, como se describe en Actualizar un registro con un campo contenedor de imágenes o PDF, o los datos binarios descritos en Actualizar un registro con un campo contenedor de imágenes o PDF con datos binarios.
- Para proporcionar los valores para las repeticiones individuales de campos repetidos, se debe especificar el índice de repetición entre corchetes (por ejemplo,
Nombre[4]). No se puede especificar una repetición de un campo contenedor al actualizar un registro. - Para actualizar varios registros, especifique el criterio
$filter.
Trabajar con datos de contenedor
Puede enviar un método HTTP POST o PATCH para insertar imágenes o archivos PDF en campos contenedor. Los datos de los campos contenedor se incrustan en el campo, se guardan como referencia de archivo o se almacenan externamente.
Crear un registro con un campo contenedor de imágenes o PDF
Para crear un registro para una tabla con uno o más campos contenedor, configure el campo con datos codificados en Base64. Solo se admiten los tipos de archivo GIF, PNG, JPEG, TIFF y PDF. El cuerpo de POST debe contener una única representación de registro válida.
| Componente | Descripción |
|---|---|
| Método HTTP | POST |
| URL | https://anfitrión/fmi/odata/versión/nombre-base-de-datos/nombre-tabla anfitrión - nombre del anfitrión de FileMaker Cloud Ejemplo: |
| Parámetros | Ejemplo de JSON: { |
Información de FileMaker
- El tipo de contenido multimedia de un valor de contenedor codificado en Base64 se determina mediante la comparación de los primeros bytes de los datos con los valores esperados para los tipos de contenido multimedia admitidos.
Actualizar un registro con un campo contenedor de imágenes o PDF con datos binarios
La solicitud de esta tabla actualiza el valor de un campo de foto de un registro de contactos mediante el método PATCH con bytes GIF binarios (no estructurados) en el cuerpo de la solicitud. El encabezado de tipo de contenido debe especificar el tipo de datos incluidos en el cuerpo (image/gif, image/png, image/jpeg, image/tiff o application/pdf).
| Componente | Descripción |
|---|---|
| Método HTTP | PATCH |
| URL | https://anfitrión/fmi/odata/versión/nombre-base-de-datos/nombre-tabla (valor-clave-principal)/nombre-campo anfitrión - nombre del anfitrión de FileMaker Cloud Ejemplo: |
| Parámetros | "474946383961090009008001007F7F7FFFFFFF21F90401000001002C00000000090009 |
Actualizar un registro con un campo contenedor de imágenes o PDF
Para actualizar el valor de un campo contenedor de un registro, utilice el método HTTP PATCH con un valor codificado en Base64.
| Componente | Descripción |
|---|---|
| Método HTTP | PATCH |
| URL | https://anfitrión/fmi/odata/versión/nombre-base-de-datos/nombre-tabla (valor-clave-principal) anfitrión - nombre del anfitrión de FileMaker Cloud Ejemplo: |
| Parámetros | Ejemplo de JSON: { |
Solicitar datos
Solicitar registros de una tabla
Para obtener un conjunto de registros de la base de datos de FileMaker, utilice el método HTTP GET con el nombre de la tabla incluido en la URL.
| Componente | Descripción |
|---|---|
| Método HTTP | GET |
| URL | https://anfitrión/fmi/odata/versión/nombre-base-de-datos/nombre-tabla anfitrión - nombre del anfitrión de FileMaker Cloud Ejemplo: |
Información de FileMaker
- Los campos contenedor no se incluyen en el resultado de la respuesta al obtener todos los registros o un único registro. Consulte Solicitar un valor de campo individual para obtener información sobre cómo solicitar valores de campos contenedor.
Solicitar un registro individual
Para solicitar un registro individual de una tabla de base de datos, especifique el nombre de la base de datos y el nombre de la tabla, y el valor de clave principal del registro.
| Componente | Descripción |
|---|---|
| Método HTTP | GET |
| URL | https://anfitrión/fmi/odata/versión/nombre-base-de-datos/nombre-tabla (valor-clave-principal) anfitrión - nombre del anfitrión de FileMaker Cloud Ejemplo: |
Información de FileMaker
- El valor de clave principal especificado en la URL es el campo designado como clave principal o el campo del sistema ROWID si no se ha designado ninguna clave principal. Consulte Obtener metadatos. Para los campos repetidos, se incluye el valor de la primera repetición. Para obtener repeticiones individuales, consulte Solicitar un valor de campo individual.
Solicitar un valor de campo individual
Para solicitar un valor de campo individual, especifique el nombre de la tabla, el valor de la clave principal del registro y el nombre del campo.
| Componente | Descripción |
|---|---|
| Método HTTP | GET |
| URL | https://anfitrión/fmi/odata/versión/nombre-base-de-datos/nombre-tabla (valor-clave-principal)/nombre-campo anfitrión - nombre del anfitrión de FileMaker Cloud Ejemplo: |
Información de FileMaker
- En una URL, al solicitar una repetición individual, no se admite el uso de corchetes ([]) para especificar el índice de repetición.
- Si el campo de repetición es un campo contenedor, solo se devuelve la primera repetición. De lo contrario, se devuelven todas las repeticiones.
Solicitar el valor binario de un campo individual
Para solicitar un campo individual almacenado como un valor binario, utilice la opción de consulta $value.
El formato predeterminado del valor binario para el campo de FileMaker es text/plain. Para los campos contenedor, el formato predeterminado depende del tipo de campo de contenedor e incluye image/gif, image/png, image/jpeg, image/tiff, application/pdf o application/octet-stream.
| Componente | Descripción |
|---|---|
| Método HTTP | GET |
| URL | https://anfitrión/fmi/odata/versión/nombre-base-de-datos/nombre-tabla (valor-clave-principal)/nombre-campo/$value anfitrión - nombre del anfitrión de FileMaker Cloud Ejemplo: La solicitud anterior devuelve el valor binario del campo de nombre del registro de contactos. |
Información de FileMaker
- Cuando se solicita el valor binario (sin formato) de un campo de repetición, solo se devuelve el valor binario (sin formato) de la primera repetición.
Desplazarse por tablas relacionadas
Puede desplazarse por las relaciones entre las tablas de FileMaker sin especificar los campos de coincidencia para cada relación. Todas las operaciones y los resultados se asocian con la última tabla en la URL.
| Componente | Descripción |
|---|---|
| Método HTTP | GET |
| URL | https://anfitrión/fmi/odata/versión/nombre-base-de-datos/nombre-tabla (valor-clave-principal)/tabla-relacionada anfitrión - nombre del anfitrión de FileMaker Cloud Ejemplo: La solicitud anterior devuelve todos los productos adquiridos por un cliente con el ID especificado. |
Información de FileMaker
- Al utilizar la opción de consulta
$filter, los nombres de campo se desambiguan anteponiendo el nombre de tabla al nombre de campo en la expresión (por ejemplo,$filter=Compra/ID eq 7).
Solicitar una unión cruzada de tablas no relacionadas
Para solicitar una unión cruzada de tablas no relacionadas, utilice la palabra clave $crossjoin y enumere las tablas que desea unir. Al utilizar la opción de consulta $filter, especifique cada campo utilizado para unir las dos tablas.
Utilice las opciones de consulta $expand y $select para asegurarse de que se devuelven campos de datos en lugar de una lista de ID de registro, que es el comportamiento predeterminado. Consulte la sección sobre cómo solucionar la unión cruzada de conjuntos de entidades en Convenciones de URL de OData 4.0.
Nota: una unión cruzada es el único contexto en el que se admite la palabra clave $expand.
| Componente | Descripción |
|---|---|
| Método HTTP | GET |
| URL | https://anfitrión/fmi/odata/versión/nombre-base-de-datos/$crossjoin (tabla 1, tabla 2)?$filter= anfitrión - nombre del anfitrión de FileMaker Cloud Ejemplo: |
Opciones de consulta
OData admite varias opciones para la consulta de datos.
Opción de consulta $filter
Utilice la opción de consulta $filter para filtrar los registros. La expresión especificada con $filter se evalúa para cada registro del conjunto y solo los elementos en los que la expresión se evalúe como verdadera ("true") se incluirán en la respuesta.
OData admite un conjunto de funciones y operadores integrados que se utilizan en las operaciones de $filter. Para obtener más información sobre los operadores disponibles y las funciones integradas, consulte Protocolo OData 4.0.
| Componente | Descripción |
|---|---|
| Método HTTP | GET |
| URL | https://anfitrión/fmi/odata/versión/nombre-base-de-datos/nombre-tabla?$filter=(expresión) anfitrión - nombre del anfitrión de FileMaker Cloud Ejemplo: La solicitud mostrada anteriormente utiliza el método GET y la opción de consulta del sistema |
Información de FileMaker
No se admiten las siguientes funciones integradas:
- indexof()
- isof()
- geo.distance()
- geo.length()
- geo.intersects()
- fractionalseconds()
- Los formatos de fecha, hora, y fecha y hora cumplen la norma ISO 8601. Las desviaciones de zona horaria son relativas a la zona horaria del servidor.
- Escriba entre comillas dobles los nombres de los campos que incluyan caracteres especiales, como espacios o guiones bajos.
Opción de consulta $orderby
Utilice la opción de consulta $orderby para solicitar registros en orden ascendente o descendente. Si no se especifica un orden, el orden predeterminado es ascendente.
| Componente | Descripción |
|---|---|
| Método HTTP | GET |
| URL | https://anfitrión/fmi/odata/versión/nombre-base-de-datos/nombre-tabla?$orderby=nombre-campo {asc/desc} anfitrión - nombre del anfitrión de FileMaker Cloud Ejemplo: La solicitud anterior ordena los registros de contactos en orden descendente por el campo de empresa. |
Información de FileMaker
- Escriba entre comillas dobles los nombres de los campos que incluyan caracteres especiales, como espacios o guiones bajos.
- La opción de consulta
$orderbyno admite las funciones integradas de OData.
Opciones de consulta $top y $skip
Utilice las opciones de consulta $top y $skip para desplazarse por un conjunto de resultados más grande. Puede utilizar estas opciones de consulta individualmente o de forma conjunta en función de los registros que desee obtener en la respuesta.
| Componente | Descripción |
|---|---|
| Método HTTP | GET |
| URL | https://anfitrión/fmi/odata/versión/nombre-base-de-datos/nombre-tabla{?$top/?$skip}=número anfitrión - nombre del anfitrión de FileMaker Cloud Opciones de consulta {?$top/?$skip} - la opción de consulta Ejemplo:
|
Opción de consulta $count
Utilice la opción de consulta $count (valor establecido en "true") para solicitar un recuento de los registros coincidentes devueltos, junto con los registros, en la respuesta. La opción de consulta $count omite las opciones de consulta $top o $skip existentes y devuelve el número total de resultados en todos los registros, incluidos los resultados que coinciden con el criterio $filter (si se ha especificado).
| Componente | Descripción |
|---|---|
| Método HTTP | GET |
| URL | https://anfitrión/fmi/odata/versión/nombre-base-de-datos/nombre-tabla?$count=true anfitrión - nombre del anfitrión de FileMaker Cloud Ejemplo: |
Opción de consulta $select
Utilice la opción de consulta $select para solicitar un conjunto limitado de campos de cada tabla. De forma predeterminada, se devuelven todos los campos, excepto los campos contenedor.
| Componente | Descripción |
|---|---|
| Método HTTP | GET |
| URL | https://anfitrión/fmi/odata/versión/nombre-base-de-datos/nombre-tabla?$select=campo 1, campo 2 anfitrión - nombre del anfitrión de FileMaker Cloud Ejemplo: La solicitud anterior devuelve los datos de empresa y sitio Web de todos los registros de la tabla de contactos. |
Información de FileMaker
- Los campos de sistema ROWID y ROWMODID se incluyen en el conjunto de resultados al especificarlos con la opción de consulta
$select. Por ejemplo:$select=ROWID, ROWMODID. - ROWID es equivalente al valor devuelto por la función Get ( RecordID ) y ROWMODID es equivalente al valor devuelto por la función Get ( RecordModificationCount ).
Modificar el esquema
OData admite las operaciones de creación y eliminación de tablas e índices de acuerdo con los privilegios de acceso definidos para una cuenta.
Crear una tabla
Para crear una tabla, utilice el método HTTP POST. El cuerpo de POST debe contener una única representación de tabla válida, que incluya un identificador que sea el nombre de la tabla.
| Componente | Descripción |
|---|---|
| Método HTTP | POST |
| URL | https://anfitrión/fmi/odata/versión/nombre-base-de-datos/FileMaker_Tables anfitrión - nombre del anfitrión de FileMaker Cloud Ejemplo: |
| Parámetros | Ejemplo de JSON: { "tableName": "Empresa", "fields": [ { "name": "ID Empresa", "type": "int", "primary": true }, { "name": "ID Usuario", "type": "varchar(20)", "unique": true, "default": "CURRENT_USER" }, { "name": "Nombre Empresa", "type": "varchar(100)", "nullable": false }, { "name": "Notas", "type": "varchar(2000)", "global": true }, { "name": "Contrato Firmado", "type": "blob", "externalSecurePath": "Archivos/GestionDeContacto/" } ] } Ejemplo de Atom: <TableDefinition tableName="Empresa"> <FieldDefinition name="ID Empresa" type="int" primary="true"/> <FieldDefinition name="ID Usuario" type="varchar(20)"unique="true" default="CURRENT_USER"/> <FieldDefinition name="Nombre Empresa" type="varchar(100)" nullable="false"/> <FieldDefinition name="Notas" type="varchar(2000) global="true"/> </TableDefinition> |
Información de FileMaker
- FileMaker_Tables es una tabla del sistema utilizada para crear, modificar y eliminar tablas. El parámetro
typedebe ser uno de los siguientes tipos: NUMERIC, DECIMAL, INT, DATE, TIME, TIMESTAMP, VARCHAR, CHARACTER VARYING, BLOB, VARBINARY, LONGVARBINARY o BINARY VARYING. - Las repeticiones se especifican entre corchetes después del tipo (por ejemplo,
"INT[4]"). Puede especificar la longitud máxima de un campo de texto entre paréntesis (por ejemplo,"VARCHAR(200)"). Se utilizan parámetros opcionales con el nombre y el tipo de campo:
"primary": verdadero ("true") o falso ("false") para determinar si el campo es una clave principal; el valor predeterminado es "false"."unique": verdadero ("true") o falso ("false") para determinar si el campo debe tener un valor exclusivo; el valor predeterminado es "false"."nullable": verdadero ("true") o falso ("false") para determinar si el campo debe tener un valor; el valor predeterminado es "true"."global": verdadero ("true") o falso ("false") para determinar si el campo es global ; el valor predeterminado es "false"."default": una cadena que contiene una palabra clave adecuada para el tipo de datos; las palabras clave válidas son: USER, USERNAME, CURRENT_USER, CURRENT_DATE, CURDATE, CURRENT_TIME, CURTIME, CURRENT_TIMESTAMP y CURTIMESTAMP"externalSecurePath"(solo para campos contenedor): una cadena que contiene una ruta relativa para los archivos seguros en "externalSecurePath". Excluya la parte "[ubicación de la base de datos]/" del directorio base. Asegúrese de establecer esto para cada base de datos de FileMaker en FileMaker Pro Advanced. Consulte la Ayuda de FileMaker Pro Advanced.
Añadir campos a una tabla
Para crear un nuevo campo en una tabla existente, envíe una solicitud PATCH a la tabla del sistema FileMaker_Tables, seguida del nombre de la tabla en la URL. El cuerpo de PATCH debe contener una matriz de campos que se añadirán a la tabla.
Si se produce un error al añadir un campo en la solicitud, los demás campos aún podrán añadirse a la tabla.
| Componente | Descripción |
|---|---|
| Método HTTP | PATCH |
| URL | https://anfitrión/fmi/odata/versión/nombre-base-de-datos/FileMaker_Tables/nombre-tabla anfitrión - nombre del anfitrión de FileMaker Cloud Ejemplo: La solicitud anterior crea un campo de teléfono en la tabla de empresa. |
| Parámetros | Ejemplo de JSON: { "fields": [ { "name": "Teléfono", "type": "varchar(25)" } ] } Ejemplo de Atom: <TableDefinition tableName="Empresa"> <FieldDefinition name="Teléfono" type="varchar(25)"/> </TableDefinition>
|
Información de FileMaker
- FileMaker_Tables es una tabla del sistema utilizada para crear, modificar y eliminar tablas. Consulte Crear una tabla para obtener información sobre las opciones válidas.
Eliminar una tabla
Para eliminar una tabla y todos sus registros, utilice el método HTTP DELETE, y use el nombre de la tabla en la URL.
| Componente | Descripción |
|---|---|
| Método HTTP | DELETE |
| URL | https://anfitrión/fmi/odata/versión/nombre-base-de-datos/FileMaker_Tables/nombre-tabla anfitrión - nombre del anfitrión de FileMaker Cloud Ejemplo: |
Información de FileMaker
- FileMaker_Tables es una tabla del sistema utilizada para crear, modificar y eliminar tablas.
- Esta operación elimina una tabla y todos sus datos sin solicitar confirmación. Para evitar la pérdida de datos, cree una cuenta con privilegios de acceso para eliminar tablas y utilice esa cuenta exclusivamente para esta operación.
Eliminar un campo de una tabla
Para eliminar un campo de una tabla, utilice el método HTTP DELETE y añada el nombre de campo al nombre de la tabla en la URL.
| Componente | Descripción |
|---|---|
| Método HTTP | DELETE |
| URL | https://anfitrión/fmi/odata/versión/nombre-base-de-datos/FileMaker_Tables/nombre-tabla/nombre-campo anfitrión - nombre del anfitrión de FileMaker Cloud Ejemplo: |
Crear un índice de campos
Para crear un nuevo índice, envíe una solicitud POST al nombre de tabla después de la tabla del sistema FileMaker_Indexes. El cuerpo de POST debe contener una única representación de índice válida, que incluya un identificador que sea el nombre del campo.
| Componente | Descripción |
|---|---|
| Método HTTP | POST |
| URL | https://anfitrión/fmi/odata/versión/nombre-base-de-datos/FileMaker_Indexes/nombre-tabla anfitrión - nombre del anfitrión de FileMaker Cloud Ejemplo: |
| Parámetros | Ejemplo de JSON: { Ejemplo de Atom: <IndexDefinition indexName="Estado"/> |
Información de FileMaker
- FileMaker_Indexes es una tabla del sistema utilizada para crear y eliminar índices.
Eliminar un índice
Para eliminar un índice, envíe una solicitud HTTP DELETE a la tabla del sistema FileMaker_Indexes, seguida del nombre de la tabla y el nombre del campo en la URL.
| Componente | Descripción |
|---|---|
| Método HTTP | DELETE |
| URL | https://anfitrión/fmi/odata/versión/nombre-base-de-datos/FileMaker_Indexes/nombre-tabla/nombre-campo anfitrión - nombre del anfitrión de FileMaker Cloud Ejemplo: |
Información de FileMaker
- FileMaker_Indexes es una tabla del sistema utilizada para crear y eliminar índices en campos.
- Para eliminar un índice, la URL debe especificar primero el nombre de la tabla, seguido del nombre del campo.
Ejecutar guiones
Para ejecutar un guión, envíe una solicitud POST a la tabla del sistema Script, seguida del nombre del guión en la URL. El cuerpo de POST debe estar completamente vacío si el guión no utiliza un parámetro o debe contener un único campo con el nombre scriptParameterValue si se ha transferido un parámetro al guión. scriptParameterValue acepta valores de cadena, número y tipo de objeto JSON.
OData no admite los nombres de guión con caracteres especiales (por ejemplo, @, &, /) o que empiecen por un número. Si el guión contiene el paso de guión "Salir del guión", el resultado del texto de este paso de guión se devuelve en un campo denominado resultParameter en los resultados.
El guión HelloScript añade el valor del parámetro a la cadena "Hello" y devuelve el resultado. OData devuelve el resultado en el cuerpo de la respuesta con un elemento Content-Type "application/json":
{
"scriptResult":
{
"code": 0,
"resultParameter": "Hello World"
}
}
Nota: OData solo admite los guiones que se ejecutan sin la interacción del usuario.
Ejecutar un guion
Para ejecutar un guión, utilice el método HTTP POST.
| Componente | Descripción |
|---|---|
| Método HTTP | POST |
| URL | https://anfitrión/fmi/odata/versión/nombre-base-de-datos/Script.nombre-guión anfitrión - nombre del anfitrión de FileMaker Cloud Ejemplo: World. |
| Parámetros | Ejemplo de JSON: |
Información de FileMaker
- Para cumplir con el concepto de OData de una acción, todos los guiones son miembros de una tabla del sistema denominada Script.
Alojar, probar y supervisar OData
Alojar bases de datos para el acceso mediante OData
- Complete los pasos descritos en Activar el acceso mediante OData.
- Compruebe que el acceso mediante OData a las bases de datos de FileMaker se haya activado y configurado correctamente en la Admin Console de FileMaker Cloud. Consulte la documentación de FileMaker Cloud en el Centro de Documentación del producto.
- Compruebe que el servidor Web y OData Listener se estén ejecutando.
-
Utilice el cifrado para la comunicación.
OData requiere que utilice una conexión HTTPS. Las conexiones HTTP utilizan el cifrado SSL (Capa de sockets seguros) para la comunicación.
La tecnología o el lenguaje de programación utilizados para llamar a OData API deben ser compatibles con Transport Layer Security (TLS) v1.2 para comunicarse con el servidor Web.
Probar el acceso mediante OData
Antes de pasar a producción la solución OData 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, pruébelos 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 ejecuta en diferentes sistemas operativos.
Supervisar el acceso mediante OData
El administrador del servidor utiliza FileMaker Customer Console para iniciar o detener OData Listener, realizar un seguimiento del uso de las llamadas de OData y descargar el archivo de registro de OData.
| Para | Use |
|---|---|
| Iniciar o detener OData Listener. | La pestaña Conectores > OData de FileMaker Customer Console. Consulte la Ayuda de FileMaker Cloud en el Centro de Documentación del producto. |
| Realizar un seguimiento del uso de las llamadas de OData API. | La pestaña Conectores > OData de FileMaker Customer Console. En esta pestaña, se muestran el límite anual de OData establecido por su suscripción a FileMaker Cloud, la cantidad de datos que se han transmitido desde la fecha de restablecimiento anual anterior y la fecha de restablecimiento anual de la suscripción. Si se aproxima al límite anual, puede aumentarlo mediante la pestaña Suscripción de FileMaker Customer Console. Consulte la Ayuda de FileMaker Customer Console en el Centro de Documentación del producto. |
| Ver el registro de OData API | Mientras que los clientes de OData están conectados a una base de datos, los datos estadísticos sobre los clientes se registran en fmodata.log file. Consulte la Ayuda de FileMaker Cloud en el Centro de Documentación del producto. |