So handhaben Sie asynchrone API-Aufrufe in benutzerdefinierten ONLYOFFICE-Funktionen

Benutzerdefinierte Funktionen sind eine leistungsstarke und flexible Möglichkeit, die Funktionalität des ONLYOFFICE-Tabelleneditors zu erweitern. Im Rahmen unserer kontinuierlichen Bemühungen, die Plattform zu verbessern, bietet die aktuelle Version von ONLYOFFICE Docs Unterstützung für asynchrone API-Aufrufe innerhalb benutzerdefinierter Funktionen. In diesem Blogbeitrag zeigen wir Ihnen, wie Sie diese in Ihre eigenen Lösungen integrieren können.

Über benutzerdefinierte ONLYOFFICE-Funktionen

Benutzerdefinierte Funktionen sind eine vielseitige und leistungsstarke Ergänzung zu ONLYOFFICE-Makros im Tabellenkalkulationseditor. Sie ermöglichen Ihnen die Erstellung eigener Funktionen, die exportiert und direkt in der Tabelle verwendet werden können.

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

Wo zu finden: Ansicht > Makros > Benutzerdefinierte Funktionen

Was sich geändert hat

Mit der Veröffentlichung von ONLYOFFICE Docs 9.0 haben wir die Möglichkeit eingeführt, asynchrone Funktionen in Ihren benutzerdefinierten Skripten aufzurufen.

Jetzt können Sie:

• Asynchrone Webanfragen an beliebige Dienste stellen.
• Asynchrone Anfragen an KI-Anbieter stellen.
• Asynchronen JS-Code in asynchronen Funktionen verwenden.
• Asynchrone Antworten verarbeiten.
• Ergebnisse direkt in Ihre Tabelle exportieren.

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

Asynchrone API-Aufrufe in benutzerdefinierten Funktionen verwenden

Für dieses Beispiel verwenden wir die Umsatzsteuer-API von API Ninjas. Sie gibt den Umsatzsteuersatz für alle in der Anfrage angegebenen US-Postleitzahlen zurück.

Hinweis: Um diese benutzerdefinierte ONLYOFFICE-Funktion zu verwenden, benötigen Sie Ihren eigenen API-Schlüssel, den Sie auf der API Ninjas-Website erhalten.

Erstellen des Makros

Zuerst definieren wir die asynchrone Funktion getSalesTax:

let getSalesTax = async function (value) {
}

Sie benötigt als Wertparameter eine US-Postleitzahl.

Wenn keine Postleitzahl angegeben ist, wird standardmäßig 90210 verwendet:

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

Da einige US-Postleitzahlen mit 0 beginnen, stellen wir sicher, dass die Postleitzahl eine fünfstellige Zeichenfolge ist:

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

Beispiel: Aus 31 wird 00031.

Anschließend erstellen wir die Anfrage-URL für die API, indem wir die Postleitzahl als Abfrageparameter anhängen:

Und senden eine GET-Anfrage an die API:

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

Anschließend parsen wir die JSON-Antwort in ein verwendbares JavaScript-Objekt:

  let jsonData = await request.json();

Wir extrahieren das Feld state_rate aus dem ersten Element des zurückgegebenen Arrays. Es gibt den staatlichen Umsatzsteuersatz für die angegebene Postleitzahl an. Und wir geben diese Zahl zurück:

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

Dann definieren wir die Parameter der benutzerdefinierten Funktion:

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

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

Wir erhalten die Antwort der asynchronen Funktion:

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

Und wir registrieren die benutzerdefinierte Funktion:

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

Jetzt können wir die Funktion SALESTAX() direkt in einer Tabelle aufrufen.

Der gesamte Code lautet wie folgt:

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

Speichern wir nun diese benutzerdefinierte Funktion und sehen, wie sie funktioniert!

Wir hoffen, dass diese neue Funktion Ihnen hilft, noch robustere und vielseitigere Lösungen für Ihre Aufgaben zu entwickeln. Bei ONLYOFFICE entwickeln und liefern wir Technologien, die auf Ihre spezifischen Bedürfnisse zugeschnitten sind.

Wir ermutigen Sie, mit asynchronen benutzerdefinierten Funktionen zu experimentieren und diese erweiterte Funktionalität voll auszunutzen. Wenn Sie interessante Ideen oder Vorschläge haben, freuen wir uns über Ihre Nachricht! Wir sind immer offen für Feedback und Zusammenarbeit. Viel Erfolg bei Ihren Erkundungstouren!