Guía de FileMaker 18 Admin API

Esta guía ofrece información sobre cómo utilizar la versión 2 (v2) de FileMaker Admin API para realizar tareas administrativas en productos de FileMaker Cloud y FileMaker Server. (Para conocer la versión 1 (v1) de FileMaker Admin API, consulte la Referencia de FileMaker Admin API instalada con los productos compatibles).

En esta guía, se presupone que tiene experiencia en:

• el uso de FileMaker Pro Advanced para cargar bases de datos. Consulte la página de Ayuda de FileMaker Pro Advanced.
• el uso de FileMaker Server o un producto de FileMaker Cloud para alojar y gestionar bases de datos. Consulte la página de Ayuda de FileMaker Server, o la documentación del producto de FileMaker Cloud en el Centro de documentación del producto.
• 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.

Notas

• 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 integrado de inicio de sesión del ID de FileMaker para autenticar a los usuarios y lo ofrece directamente 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.
• Esta guía utiliza Admin Console para hacer referencia a Admin Console para FileMaker Server, 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.
• App personalizada, solución, base de datos y archivo hacen referencia a todos los términos utilizados para designar lo que crea y con lo que trabaja mediante los productos de FileMaker.
• Esta guía utiliza token de acceso para referirse al token de la web JSON necesario para la autenticación.

FileMaker Admin API^® es una interfaz de programación de aplicaciones (API) que permite a los servicios web realizar tareas administrativas en productos de FileMaker Cloud y FileMaker Server. Como esta API se ajusta a la arquitectura de Transferencia de estado representacional (REST, por sus siglas en inglés), FileMaker Admin API es una API REST.

FileMaker Admin 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 JSON es independiente de los formatos de lenguaje de programación específicos.

Para usar FileMaker Admin API:

1. Escriba el código que utiliza llamadas de FileMaker Admin API para realizar tareas administrativas.
2. Compruebe que el acceso mediante FileMaker Admin API funciona correctamente.
3. Supervise los resultados revisando el archivo gateway.log para un producto de FileMaker Cloud o el archivo fac.log para FileMaker Server, donde se registran todas las llamadas de la API. Puede descargar el archivo gateway.log desde la Admin Console de FileMaker Cloud. El archivo fac.log está ubicado en la carpeta siguiente: .../FileMaker Server/Admin/FAC/logs.

Notas

• Para acceder a los datos en bases de datos alojadas, consulte la Guía de FileMaker Data API

Cliente de API REST

1

6

Servidor web

2

5

Motor de FileMaker Admin API

3

4

Servidor de base de datos

Algunas de las llamadas de FileMaker Admin API, como las de autenticación, solo se procesan de acuerdo con los dos primeros pasos siguientes. Otras llamadas, como las relacionadas con la creación de programaciones o la actualización de la configuración, se procesan de acuerdo con todos los pasos siguientes.

1. Un cliente de la API REST envía una llamada de FileMaker Admin API (una solicitud HTTPS) al servidor web.
2. El servidor web enruta la solicitud a través del módulo de servidor web de FileMaker al motor de FileMaker Admin API.
3. El motor de FileMaker Admin API convierte la solicitud HTTPS (datos URL y JSON) en un formato compatible con el servidor de base de datos de FileMaker.
4. El servidor de base de datos devuelve los resultados de la solicitud al motor de FileMaker Admin API.
5. El motor de FileMaker Admin API convierte los resultados en una respuesta HTTPS (datos URL y JSON) y devuelve la respuesta al servidor web.
6. El servidor web envía la respuesta HTTPS al cliente de API REST que realiza la solicitud.

La referencia de FileMaker Admin API se instala junto con los productos de FileMaker Server y FileMaker Cloud. Esta referencia proporciona información detallada sobre todas las llamadas admitidas por FileMaker Admin API.

Para consultar la referencia del producto de FileMaker Cloud, introduzca la siguiente URL en una ventana del navegador:

https://host/fmi/admin/apidoc/

donde host es el nombre del anfitrión o la dirección IP del servidor virtual que ejecuta el producto de FileMaker Cloud.

Para acceder a la referencia para FileMaker Server:

• Para ver la referencia en una ventana del navegador del equipo principal, introduzca la siguiente URL:

  https://localhost/fmi/admin/apidoc/

• Para ver la referencia en una ventana del navegador de un equipo remoto, introduzca la siguiente URL:

  https://host/fmi/admin/apidoc/

• En un servidor Windows, la referencia se encuentra en la carpeta siguiente:

  [unidad]:\Archivos de programa\FileMaker\FileMaker Server\Documentation\Admin 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 el inicio de la ruta de instalación predeterminada:

  [unidad]:ubicación_instalación\FileMaker\FileMaker Server\Documentation\Admin API Documentation

• En un servidor macOS, los archivos de referencia se encuentran en la carpeta siguiente:

  /Library/FileMaker Server/Documentation/Admin API Documentation

Notas

• Si utiliza las URL de ejemplo de la referencia de Admin API y abre el archivo de referencia desde su unidad local, todos los ejemplos empezarán con archivo:///. Para usar las URL, reemplace archivo:/// por https://NombreDelAnfitrión/fmi/admin/api/v2.

FileMaker Admin API ofrece una API REST que podrá usar para automatizar algunas tareas administrativas rutinarias mediante programación, en lugar de tener que usar Admin Console.

FileMaker Admin API realiza un seguimiento del estado de las interacciones. Puede empezar con una llamada de autenticación o utilizar otras llamadas para la autenticación. A continuación, puede usar el token de acceso devuelto para las siguientes llamadas.

El token es válido hasta que se invalida utilizando la llamada Invalidar token de acceso, o durante los 15 minutos siguientes a 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).

Las llamadas de la API relacionadas con las bases de datos y las llamadas a la API de programación, excepto las llamadas de creación y edición/ejecución de programaciones, son asíncronas y no esperan una respuesta del producto FileMaker Cloud o FileMaker Server. Es posible que desee continuar una llamada asíncrona con una llamada GET para confirmar que el estado del archivo ha cambiado. Por ejemplo, siga una llamada de base de datos cerrada con una llamada de base de datos GET para confirmar que la base de datos está cerrada. Si el estado no cambia de inmediato, siga con las comprobaciones.

El resto de las llamadas de la API son sincronizadas y esperan una respuesta del producto de FileMaker Cloud o FileMaker Server.

FileMaker Admin API utiliza un token de acceso para definir una conexión con el anfitrión. Utilice la llamada de autenticación para solicitar un token de acceso del anfitrión utilizando el nombre y la contraseña de la cuenta del administrador raíz. Incluya un encabezado de autorización con el valor Basic base64-encoded string. La cadena codificada en Base64 debería estar generada en base a nombre de usuario:contraseña. También puede utilizar el esquema básico de autenticación para otras llamadas.

Si utiliza el esquema básico de autenticación para la llamada de autenticación, la solicitud devuelve el token de acceso en el cuerpo de la respuesta. Si utiliza el esquema básico de autenticación para otras llamadas, la solicitud devuelve el token de acceso del campo X-FM-Access-Token en el encabezado de la respuesta.

Para llamadas posteriores de la API, utilice el esquema de autenticación de titular e incluya un encabezado de autorización con el valor de token de acceso de titular.

Notas

• Cada vez que utiliza el esquema básico de autenticación para obtener un token de acceso, se crea una nueva sesión de la API. Para evitar tener varias sesiones de API, utilice el mismo token de acceso con el esquema de autenticación de titular para todas las llamadas de API.

FileMaker Admin API utiliza un token de acceso para definir una conexión con el anfitrión.

Para autenticar cuentas de FileMaker Cloud:

1. Genere el token del ID de FileMaker. Consulte la ayuda de FileMaker Customer Console en el Centro de documentación del producto.

2. Incluya el token del ID de FileMaker del paso 1 en la llamada de autenticación o en otras llamadas para generar un token de acceso.

   Por ejemplo, utilice la siguiente URL y el encabezado para la llamada de autenticación:

   • URL: https://host/fmi/admin/api/v2/user/auth

     donde host es el nombre del anfitrión o la dirección IP del servidor virtual que ejecuta FileMaker Cloud.

   • Encabezado: Autorización de FMID FileMaker_ID_Token

   Si utiliza la llamada de autenticación, se devuelve el token de acceso en el cuerpo de la respuesta. Si utiliza otras llamadas, se devuelve el token en el campo X-FM-Access-Token del encabezado de la respuesta.

3. Para las llamadas de API posteriores, incluya el siguiente encabezado de autorización para la llamada de autenticación:

   Encabezado: token de acceso del titular de la autorización

Notas

• Cada vez que utiliza el esquema de autenticación del ID de FileMaker para obtener un token de acceso, se crea una nueva sesión de la API. Para evitar tener varias sesiones de API, utilice el mismo token de acceso con el esquema de autenticación de titular para todas las llamadas de API.

La siguiente tabla muestra las llamadas de FileMaker Admin API compatibles con los productos de FileMaker Server y FileMaker Cloud.

• El parámetro startupRestorationLogPath para FileMaker Server Admin API especifica la ruta de la carpeta para guardar registros de restauración. Para obtener los mejores resultados, cambie la ubicación de la carpeta del registro de restauración a una unidad diferente.
• Los productos de FileMaker Cloud utilizan la zona horaria de UTC para el parámetro startTimeStamp.
• Para filemakerScriptType, deberá facilitar tanto el parámetro fmScriptAccount como el fmScriptPassword para que el guion se ejecute.
• En FileMaker Cloud, para filemakerScriptType, utilice el parámetro fmScriptAccount para especificar el token del ID de FileMaker, y el parámetro fmScriptPassword para especificar el token de actualización del ID de FileMaker. Si no especifica el token de actualización, el guion no podrá ejecutarse después de que el token del ID de FileMaker haya caducado. Para saber cómo generar el token, consulte la ayuda de FileMaker Customer Console en el Centro de documentación del producto.
• Si el valor devuelto para el parámetro de estado de la llamada de Lista de bases de datos es Normal, la base de datos estará abierta.