Partilhar via

Chamada de API externa nos scripts do Office

Os scripts suportam chamadas para serviços externos. Utilize estes serviços para fornecer dados e outras informações ao seu livro.

Cuidado

As chamadas externas podem resultar na exposição de dados confidenciais a pontos finais indesejáveis. O seu administrador pode estabelecer a Gestão de Direitos de Informação (IRM) ou a proteção da firewall contra essas chamadas.

Importante

As chamadas para APIs externas só podem ser feitas através da aplicação Excel, não através do Power Automate em circunstâncias normais. As chamadas externas também não são suportadas para scripts armazenados num site do SharePoint.

Configurar o script para chamadas externas

As chamadas externas são assíncronas e exigem que o script esteja marcado como async. Adicione o async prefixo à sua main função e peça-lhe que devolva um Promise, conforme mostrado aqui:

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

Observação

Os scripts que devolvem outras informações podem devolver um Promise desse tipo. Por exemplo, se o script precisar de devolver um objeto, a assinatura de devolução Employee será : Promise <Employee>

Terá de aprender as interfaces do serviço externo para efetuar chamadas para esse serviço. Se estiver a utilizar fetch ou AS APIs REST, terá de determinar a estrutura JSON dos dados devolvidos. Para entrada e saída a partir do script, considere criar um interface para corresponder às estruturas JSON necessárias. Isto dá ao script mais segurança do tipo. Pode ver um exemplo disto em Utilizar a obtenção dos Scripts do Office.

Limitações com chamadas externas de Scripts do Office

  • Não existe forma de iniciar sessão ou utilizar o tipo OAuth2 de fluxos de autenticação. Todas as chaves e credenciais têm de ser codificadas (ou lidas a partir de outra origem).
  • Não existe nenhuma infraestrutura para armazenar credenciais e chaves de API. Esta ação terá de ser gerida pelo utilizador.
  • Os cookies de documentos, localStoragee sessionStorage os objetos não são suportados.
  • As chamadas externas podem resultar na exposição de dados confidenciais a pontos finais indesejáveis ou a dados externos a serem trazidos para livros internos. O seu administrador pode estabelecer proteção contra a firewall contra essas chamadas. Certifique-se de que marcar com políticas locais antes de depender de chamadas externas.
  • Certifique-se de que marcar a quantidade de débito de dados antes de assumir uma dependência. Por exemplo, extrair todo o conjunto de dados externos pode não ser a melhor opção e, em vez disso, a paginação deve ser utilizada para obter dados em segmentos.

Obter informações com fetch

A API de obtenção obtém informações de serviços externos. Trata-se de uma async API, pelo que tem de ajustar a main assinatura do script. Faça a main função async. Também deve certificar-se await da fetch chamada e json obtenção. Isto garante que essas operações são concluídas antes do script terminar.

Todos os dados JSON obtidos pelo fetch têm de corresponder a uma interface definida no script. O valor devolvido tem de ser atribuído a um tipo específico porque os Scripts do Office não suportam o any tipo. Deve consultar a documentação do seu serviço para ver quais são os nomes e tipos das propriedades devolvidas. Em seguida, adicione a interface ou interfaces correspondentes ao script.

Observação

Se utilizar fetch para chamar um recurso externo com uma política de Partilha de Recursos Transversais à Origem (CORS), certifique-se de que o Access-Control-Allow-Origin cabeçalho desse recurso externo utiliza a * diretiva. Se o Access-Control-Allow-Origin cabeçalho utilizar uma diretiva específica <origin> , a sua fetch chamada a partir dos Scripts do Office poderá falhar. A origem do runtime dos Scripts do Office pode ser alterada sem aviso prévio.

O script seguinte utiliza fetch para obter dados JSON do servidor de teste no URL especificado. Repare na 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 a Gestão de Direitos de Informação (IRM)

Pode aplicar definições de IRM a um livro para impedir que as chamadas externas sejam efetuadas por scripts. Desative a política Copiar/EXTRAÇÃO para impedir este comportamento.

Chamadas externas do Power Automate

As chamadas à API externa falham quando um script é executado através do Power Automate. Uma fetch chamada dará a mensagem de erro "Erro de runtime: Linha X: a obtenção não está definida". Certifique-se de que marcar os scripts para essas referências antes de os criar num fluxo.

Terá de utilizar HTTP com Azure AD ou outras ações equivalentes para extrair dados ou enviá-lo para um serviço externo.

Aviso

As chamadas externas efetuadas através do conector do Excel Online do Power Automate falham para ajudar a manter as políticas de prevenção de perda de dados existentes. No entanto, os scripts executados através do Power Automate são feitos fora da sua organização e fora das firewalls da sua organização. Para proteção adicional contra utilizadores maliciosos neste ambiente externo, o seu administrador pode controlar a utilização de Scripts do Office. O seu administrador pode desativar o conector do Excel Online no Power Automate ou desativar os Scripts do Office para Excel através dos controlos de administrador de Scripts do Office.

Confira também

  • Last updated on