Comment gérer les appels API asynchrones dans les fonctions personnalisées de ONLYOFFICE

Les fonctions personnalisées sont un moyen puissant et flexible d’étendre les fonctionnalités de l’éditeur de feuilles de calcul ONLYOFFICE. Dans le cadre de nos efforts continus pour améliorer la plateforme, la récente version d’ONLYOFFICE Docs 9.0 ajoute le support des appels API asynchrones dans les fonctions personnalisées. Dans ce billet de blog, nous vous montrerons comment les incorporer dans vos propres solutions.

À propos des fonctions personnalisées d’ONLYOFFICE

Les fonctions personnalisées sont un complément polyvalent et puissant aux macros ONLYOFFICE dans l’éditeur de feuilles de calcul. Elles vous permettent de créer vos propres fonctions qui peuvent être exportées et utilisées directement dans la feuille de calcul.

(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);
})();

Où trouver : Affichage > Macros > Fonctions personnalisées

Ce qui a changé

Avec la sortie d’ONLYOFFICE Docs 9.0, nous avons introduit la possibilité d’appeler des fonctions asynchrones dans vos scripts personnalisés.

Aujourd’hui, c’est possible :

• Effectuer des requêtes web asynchrones vers n’importe quel service.
• Effectuer des requêtes asynchrones auprès de fournisseurs d’IA.
• Utiliser du code JS asynchrone dans des fonctions asynchrones.
• Traiter les réponses asynchrones.
• Exporter les résultats directement dans votre tableur.

  (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);
  })();

Utilisation d’appels API asynchrones dans des fonctions personnalisées

Pour cet exemple, nous utiliserons l’API Sales Tax de API Ninjas, qui renvoie le taux de la taxe de vente de l’État pour tout code postal américain fourni dans la demande.

Remarque ! Pour utiliser cette fonction personnalisée ONLYOFFICE, vous devez fournir votre propre clé API, que vous pouvez obtenir sur le site web API Ninjas.

Construction de la macro

Nous commençons par définir une fonction asynchrone getSalesTax :

let getSalesTax = async function (value) {
}

Elle prend un paramètre de valeur, qui est censé être un code postal américain.

Si aucun code postal n’est fourni, la fonction prend par défaut la valeur 90210 :

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

Comme certains codes postaux américains commencent par 0, nous nous assurons que le code postal est une chaîne de 5 chiffres :

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

Par exemple, 31 devient 00031.

Ensuite, nous créons l’URL de demande pour l’API en ajoutant le code postal comme paramètre de requête :

Et envoyez une requête GET à l’API :

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

Ensuite, nous analysons la réponse JSON en un objet JavaScript utilisable :

  let jsonData = await request.json();

Nous extrayons le champ state_rate du premier élément du tableau retourné. Il s’agit du taux de la taxe sur les ventes de l’État pour le code postal fourni. Nous renvoyons ce chiffre :

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

Nous définissons ensuite les paramètres de la fonction personnalisée :

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

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

La fonction asynchrone nous répond :

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

Et nous enregistrons la fonction personnalisée :

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

Nous pouvons maintenant appeler la fonction SALESTAX() directement dans une feuille de calcul.

Le code complet est le suivant :

(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);
})();

Maintenant, sauvegardons cette fonction personnalisée et voyons comment elle fonctionne !

Nous espérons que cette nouvelle fonctionnalité vous permettra de créer des solutions encore plus robustes et polyvalentes pour vos tâches. Chez ONLYOFFICE, nous nous engageons à concevoir et à fournir des technologies qui peuvent être adaptées à vos besoins spécifiques.

Nous vous encourageons à expérimenter les fonctions personnalisées asynchrones et à tirer pleinement parti de cette fonctionnalité élargie. Si vous avez des idées ou des suggestions intéressantes, n’hésitez pas à nous en faire part ! Nous sommes toujours ouverts aux commentaires et à la collaboration. Nous vous souhaitons bonne chance dans vos explorations !