Share via

Chamada de API externa nos scripts do Office

  • Artigo

Scripts dão suporte a chamadas para serviços externos. Use esses serviços para fornecer dados e outras informações para sua pasta de trabalho.

Cuidado

Chamadas externas podem resultar em dados confidenciais sendo expostos a pontos de extremidade indesejáveis. Seu administrador pode estabelecer o IRM (Gerenciamento de Direitos de Informação) ou proteção de firewall contra essas chamadas.

Importante

Chamadas para APIs externas só podem ser feitas por meio do aplicativo Excel, não por meio do Power Automate em circunstâncias normais. Também não há suporte para chamadas externas para scripts armazenados em um site do SharePoint.

Configurar seu script para chamadas externas

As chamadas externas são assíncronas e exigem que o script seja marcado como async. Adicione o async prefixo à sua main função e faça com que ele retorne um Promise, conforme mostrado aqui:

async function main(workbook: ExcelScript.Workbook) : Promise <void>

Observação

Scripts que retornam outras informações podem retornar um Promise desse tipo. Por exemplo, se o script precisar retornar um Employee objeto, a assinatura de retorno será : Promise <Employee>

Você precisará aprender as interfaces do serviço externo para fazer chamadas para esse serviço. Se você estiver usando fetch ou APIs REST, precisará determinar a estrutura JSON dos dados retornados. Para entrada e saída do script, considere fazer um interface para corresponder às estruturas JSON necessárias. Isso dá ao script mais segurança de tipo. Você pode ver um exemplo disso em Usar buscar de Scripts do Office.

Limitações com chamadas externas de Scripts do Office

  • Não há como entrar ou usar o tipo OAuth2 de fluxos de autenticação. Todas as chaves e credenciais precisam ser codificadas (ou ler de outra fonte).
  • Não há infraestrutura para armazenar credenciais e chaves de API. Isso terá que ser gerenciado pelo usuário.
  • Não há suporte para cookies de documento, localStoragee sessionStorage objetos.
  • Chamadas externas podem resultar em dados confidenciais sendo expostos a pontos de extremidade indesejáveis ou dados externos a serem trazidos para pastas de trabalho internas. Seu administrador pode estabelecer proteção de firewall contra essas chamadas. Certifique-se de marcar com políticas locais antes de depender de chamadas externas.
  • Certifique-se de marcar a quantidade de taxa de transferência de dados antes de fazer uma dependência. Por exemplo, retirar todo o conjunto de dados externo pode não ser a melhor opção e, em vez disso, a paginação deve ser usada para obter dados em partes.

Recuperar informações com fetch

A API de busca recupera informações de serviços externos. É uma async API, portanto, você precisa ajustar a main assinatura do script. Faça a main função async. Você também deve ter certeza await da chamada e json recuperaçãofetch. Isso garante a conclusão dessas operações antes do término do script.

Todos os dados JSON recuperados por fetch devem corresponder a uma interface definida no script. O valor retornado deve ser atribuído a um tipo específico porque os Scripts do Office não dão suporte ao any tipo. Você deve consultar a documentação do serviço para ver quais são os nomes e tipos das propriedades retornadas. Em seguida, adicione a interface ou interfaces correspondentes ao script.

O script a seguir usa fetch para recuperar dados JSON do servidor de teste na URL fornecida. Observe a JSONData interface para armazenar os dados como um tipo correspondente.

async function main(workbook: ExcelScript.Workbook) {
  // Retrieve sample JSON data from a test server.
  let fetchResult = await fetch('https://jsonplaceholder.typicode.com/todos/1');

  // Convert the returned data to the expected JSON structure.
  let json : JSONData = await fetchResult.json();

  // Display the content in a readable format.
  console.log(JSON.stringify(json));
}

/**
 * An interface that matches the returned JSON structure.
 * The property names match exactly.
 */
interface JSONData {
  userId: number;
  id: number;
  title: string;
  completed: boolean;
}

Outros fetch exemplos

Restringir chamadas externas com o IRM (Gerenciamento de Direitos de Informação)

Você pode aplicar configurações de IRM a uma pasta de trabalho para evitar que chamadas externas sejam feitas por scripts. Desabilite a política Copiar/EXTRACT para evitar esse comportamento.

Chamadas externas do Power Automate

As chamadas de API externas falham quando um script é executado por meio do Power Automate. Uma fetch chamada fornecerá a mensagem de erro "Erro de runtime: Linha X: a busca não está definida". Certifique-se de marcar seus scripts para essas referências antes de transformá-los em um fluxo.

Você terá que usar HTTP com Azure AD ou outras ações equivalentes para extrair dados ou empurrá-los para um serviço externo.

Aviso

As chamadas externas feitas por meio do conector do Power Automate Excel Online falham para ajudar a manter as políticas de prevenção de perda de dados existentes. No entanto, scripts executados por meio do Power Automate são feitos fora da sua organização e fora dos firewalls da sua organização. Para proteção adicional contra usuários mal-intencionados nesse ambiente externo, o administrador pode controlar o uso de Scripts do Office. Seu administrador pode desabilitar o conector do Excel Online no Power Automate ou desativar scripts do Office para Excel por meio dos controles de administrador do Office Scripts.

Confira também