Come gestire le chiamate API asincrone all’interno delle funzioni personalizzate di ONLYOFFICE

Le funzioni personalizzate sono un modo potente e flessibile per estendere le funzionalità dell’Editor di fogli di calcolo di ONLYOFFICE. Come parte del nostro continuo impegno a migliorare la piattaforma, la recente versione di ONLYOFFICE Docs 9.0 aggiunge il supporto per le chiamate API asincrone all’interno delle funzioni personalizzate. In questo post ti mostriamo come integrarle nelle tue soluzioni.

A proposito delle funzioni personalizzate di ONLYOFFICE 

Le funzioni personalizzate sono un’aggiunta versatile e potente alle macro di ONLYOFFICE nell’Editor di fogli. Consentono di creare funzioni proprie che possono essere esportate e utilizzate direttamente nel foglio di calcolo.

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

Dove si trova: Visualizza > Macro > Funzioni personalizzate

Cosa è cambiato

Con il rilascio di ONLYOFFICE Docs 9.0, è stata introdotta la possibilità di richiamare funzioni asincrone all’interno degli script personalizzati.

Ora puoi:

• Eseguire richieste web asincrone verso qualsiasi servizio.
• Effettuare richieste asincrone a provider di intelligenza artificiale.
• Utilizzare codice JS asincrono nelle funzioni async.
• Elaborare risposte asincrone.
• Esportare i risultati direttamente nel tuo foglio di calcolo.

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

Utilizzo delle chiamate API asincrone nelle funzioni personalizzate

In questo esempio utilizzeremo l’API Sales Tax di API Ninjas, che restituisce l’aliquota dell’imposta sulle vendite statale per qualsiasi codice postale statunitense fornito nella richiesta.

Nota! Per utilizzare questa funzione personalizzata di ONLYOFFICE, è necessario fornire la propria chiave API, che può essere ottenuta dal sito web di API Ninjas.

Creazione della macro

Per prima cosa definiamo una funzione asincrona chiamata getSalesTax:

let getSalesTax = async function (value) {
}

Accetta un parametro chiamato value, che dovrebbe essere un codice postale statunitense.

Se non viene fornito alcun codice postale, la funzione utilizza come valore predefinito 90210:

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

Poiché alcuni codici postali statunitensi iniziano con 0, dobbiamo assicurarci che il codice sia una stringa di 5 cifre:

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

Ad esempio, 31 diventa 00031.

Successivamente, costruiamo l’URL della richiesta per l’API aggiungendo il codice postale come parametro di query:

E inviamo una richiesta GET all’API:

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

Dopodiché analizziamo la risposta JSON trasformandola in un oggetto JavaScript utilizzabile:

  let jsonData = await request.json();

Estraiamo il campo state_rate dal primo elemento dell’array restituito. Si tratta dell’aliquota dell’imposta sulle vendite statale per il CAP fornito. E restituiamo questo numero:

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

Poi definiamo i parametri della funzione personalizzata:

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

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

Riceviamo la risposta dalla funzione asincrona:

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

E registriamo la funzione personalizzata:

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

Ora possiamo chiamare la funzione SALESTAX() direttamente all’interno di un foglio di calcolo.

Il codice completo è il seguente:

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

Adesso salviamo questa funzione personalizzata e vediamo come funziona!

Speriamo che questa nuova funzionalità ti permetta di creare soluzioni ancora più robuste e versatili per i tuoi compiti. In ONLYOFFICE, ci impegniamo a progettare e offrire tecnologie che possano essere adattate alle tue esigenze specifiche.

Ti invitiamo a sperimentare con le funzioni personalizzate asincrone e a sfruttare appieno questa funzionalità ampliata. Se hai idee o suggerimenti interessanti, ci piacerebbe sentire la tua opinione! Siamo sempre aperti a feedback e collaborazioni. Buona fortuna nelle tue esplorazioni!