Como lidar com chamadas de API assíncronas dentro de funções personalizadas do ONLYOFFICE

As funções personalizadas são uma forma poderosa e flexível de estender a funcionalidade do Editor de Planilhas do ONLYOFFICE. Como parte do nosso esforço contínuo para aprimorar a plataforma, o lançamento recente do ONLYOFFICE Docs 9.0 adiciona suporte para chamadas de API assíncronas em funções personalizadas. Nesta publicação do blog, mostraremos como incorporá-las às suas próprias soluções.

Sobre as funções personalizadas do ONLYOFFICE

Funções customizadas são uma adição versátil e potente às macros do ONLYOFFICE no Editor de Planilhas. Elas permitem que você crie suas próprias funções que podem ser exportadas e usadas diretamente na planilha.

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

Onde encontrar: Exibir > Macros > Funções personalizadas

O que mudou

Com o lançamento do ONLYOFFICE Docs 9.0, introduzimos a capacidade de chamar funções assíncronas em seus scripts personalizados.

Agora você pode:

• Execute solicitações web assíncronas para quaisquer serviços.
• Faça solicitações assíncronas aos provedores de IA.
• Use código JS assíncrono em funções assíncronas.
• Processar respostas assíncronas.
• Exporte os resultados diretamente para sua planilha.

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

Usando chamadas de API assíncronas dentro de funções personalizadas

Neste exemplo, usaremos a API de imposto sobre vendas da API Ninjas, que retorna a taxa de imposto sobre vendas estadual para qualquer código postal dos EUA fornecido na solicitação.

Observação! Para usar esta função personalizada do ONLYOFFICE, você precisará fornecer sua própria chave de API, que pode ser obtida no site API Ninjas.

Construindo a macro

Primeiro definimos uma função assíncrona getSalesTax:

let getSalesTax = async function (value) {
}

Ele recebe um parâmetro de valor, que deve ser um código postal dos EUA.

Se nenhum código postal for fornecido, a função assumirá como padrão o 90210:

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

Como alguns códigos postais dos EUA começam com 0, garantimos que o código postal seja uma sequência de 5 dígitos:

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

Por exemplo, 31 se torna 00031.

Em seguida, criamos a URL de solicitação para a API anexando o CEP como parâmetro de consulta:

E enviamos uma solicitação GET para a API:

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

Depois disso, analisamos a resposta JSON em um objeto JavaScript utilizável:

  let jsonData = await request.json();

Nós extraímos o campo state_rate do primeiro item na matriz retornada. É a alíquota do imposto estadual sobre vendas para o CEP fornecido. E retornamos este número:

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

Em seguida, definimos os parâmetros da função personalizada:

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

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

Obtemos a resposta da função assíncrona:

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

E registramos a função personalizada:

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

Agora podemos chamar a função SALESTAX() diretamente em uma planilha.

O código completo é o seguinte:

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

Agora, vamos salvar esta função personalizada e ver como ela funciona!

Esperamos que este novo recurso capacite você a criar soluções ainda mais robustas e versáteis para suas tarefas. No ONLYOFFICE, temos o compromisso de projetar e fornecer tecnologias que podem ser adaptadas às suas necessidades específicas.

Incentivamos você a experimentar funções personalizadas assíncronas e aproveitar ao máximo essa funcionalidade expandida. Se você tiver alguma ideia ou sugestão interessante, adoraríamos ouvir você! Estamos sempre abertos a feedback e colaboração. Boa sorte em seus empreendimentos exploratórios!