Cómo manejar llamadas a la API asíncronas dentro de funciones personalizadas en ONLYOFFICE

Las funciones personalizadas son una forma potente y flexible de ampliar la funcionalidad del Editor de hojas de cálculo ONLYOFFICE. Como parte de nuestro esfuerzo continuo por mejorar la plataforma, la reciente versión ONLYOFFICE Docs 9.0 añade soporte para llamadas a la API asíncronas dentro de las funciones personalizadas. En esta publicación del blog, te mostraremos cómo incorporarlas en tus propias soluciones.

Acerca de las funciones personalizadas de ONLYOFFICE

Las funciones personalizadas son una incorporación versátil y potente a las macros de ONLYOFFICE en el Editor de hojas de cálculo. Permiten crear tus propias funciones que pueden exportarse y utilizarse directamente dentro de la hoja de cálculo.

(function () {
    /**
      * This is a custom function that can be used in the editor.
      * @customfunction

      * @param {number} value - description of the parameter.
      * @returns {number} Description of the returned data.
      */
    function customFunctionName(value) {
        // Add your custom calculation logic here
        return // your calculation result;
    }
    // Register the custom function with the editor
    Api.AddCustomFunction(customFunctionName);
})();

Dónde encontrar: Vista > Macros > Funciones personalizadas

Qué ha cambiado

Con el lanzamiento de ONLYOFFICE Docs 9.0, hemos introducido la posibilidad de llamar a funciones asíncronas dentro de tus scripts personalizados.

Ahora puedes:

• Realizar solicitudes web asíncronas a cualquier servicio.
• Hacer solicitudes asíncronas a proveedores de IA.
• Usar código JavaScript asíncrono en funciones async.
• Procesar respuestas asíncronas.
• Exportar resultados directamente a tu hoja de cálculo.

  (function () {
    // Make an asynchronous request
    let asyncFunc = async function (value) {
      let request = await fetch("https://yourURL");
      const jsonData = await request.json();
      if (value === undefined) {
        value = 2;
      }
      return jsonData;
    };
    /**
     * This is a custom function that can be used in the editor.
     * @customfunction

     * @param {number} value - description of the parameter.
     * @returns {number} Description of the returned data.
     */
    async function customFunctionName(value) {
      // Call the asynchronous function and return its result
      return await asyncFunc(value);
    }
    // Register the custom function with the editor
    Api.AddCustomFunction(customFunctionName);
  })();

Uso de llamadas a la API asíncronas dentro de funciones personalizadas

Para este ejemplo, usaremos la API de Impuestos sobre Ventas de la API Ninjas, que devuelve la tasa de impuestos sobre ventas estatal para cualquier código postal de EE. UU. proporcionado en la solicitud.

¡Importante! Para usar esta función personalizada de ONLYOFFICE, deberás proporcionar tu propia clave de la API, la cual puedes obtener en el sitio web de la API Ninjas.

Creación de la macro

Primero, definimos una función asincrónica llamada getSalesTax:

let getSalesTax = async function (value) {
}

Toma un parámetro llamado value, que se espera sea un código postal (ZIP) de EE. UU.

Si no se proporciona ningún código postal, la función usa 90210 como valor predeterminado:

let getSalesTax = async function (value) {
}
 if (undefined === value) {
      value = 90210;
    }

Dado que algunos códigos postales en EE. UU. comienzan con cero, nos aseguramos de que el ZIP tenga cinco dígitos:

 // Convert to string and add missing zeros if needed
    let zipStr = value.toString();
    while (zipStr.length < 5) {
      zipStr = '0' + zipStr;
    }

Por ejemplo, el valor 31 se convierte en 00031.

Luego, construimos la URL de la solicitud para la API, agregando el código ZIP como un parámetro de consulta:

Y enviamos una solicitud GET a la API:

 let request = await fetch(url, {
      method: 'GET',
      headers: {
        'X-Api-Key': 'yourAPIkey',
        'Content-Type': 'application/json'
      }
    });

Después, analizamos la respuesta JSON para convertirla en un objeto JavaScript utilizable:

  let jsonData = await request.json();

Extraemos el campo state_rate del primer elemento del arreglo devuelto. Este valor representa la tasa de impuestos sobre ventas estatal para el código postal proporcionado. Finalmente, devolvemos este número:

 const taxRate = jsonData[0].state_rate;
    return taxRate;

A continuación, definimos los parámetros de la función personalizada:

 /**
   * Function that returns state sales tax.
   * @customfunction

   * @param {number} value - zip code.
   * @returns {number} Returns state sales tax data.
   */

Obtenemos la respuesta desde la función asincrónica:

 async function salestax(value) {
    return await getSalesTax(value);
  }

Y registramos la función personalizada:

  // Add the custom function 
  Api.AddCustomFunction(salestax);
})();

Ahora podemos llamar a la función SALESTAX() directamente dentro de una hoja de cálculo.

El código completo es el siguiente:

(function () {
  // Function that returns sales tax data from api-ninjas.com
  let getSalesTax = async function (value) {


    if (undefined === value) {
      value = 90210;
    }


    // Convert to string and add missing zeros if needed
    let zipStr = value.toString();
    while (zipStr.length < 5) {
      zipStr = '0' + zipStr;
    }


    const url = 'https://api.api-ninjas.com/v1/salestax?zip_code=' + zipStr;


    let request = await fetch(url, {
      method: 'GET',
      headers: {
        'X-Api-Key': 'yourAPIkey',
        'Content-Type': 'application/json'
      }
    });


    let jsonData = await request.json();
    const taxRate = jsonData[0].state_rate;
    return taxRate;
  };


  /**
   * Function that returns state sales tax.
   * @customfunction

   * @param {number} value - zip code.
   * @returns {number} Returns state sales tax data.
   */
  async function salestax(value) {
    return await getSalesTax(value);
  }


  // Add the custom function 
  Api.AddCustomFunction(salestax);
})();

Ahora, guarda esta función personalizada y ¡prueba cómo funciona!

Esperamos que esta nueva funcionalidad te permita crear soluciones aún más robustas y versátiles para tus tareas. En ONLYOFFICE, estamos comprometidos con diseñar y ofrecer tecnologías que puedan adaptarse a tus necesidades específicas.

Te animamos a experimentar con las funciones personalizadas asincrónicas y aprovechar al máximo esta funcionalidad ampliada. Si tienes ideas interesantes o sugerencias, ¡nos encantaría escucharlas! Siempre estamos abiertos a recibir comentarios y colaborar contigo.