Chamada de API externa nos scripts do Office

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

Cuidado

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

Importante

As 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.

Configure seu script para chamadas externas

As chamadas externas são assíncronas e exigem que o script seja marcado como async. Adicione o prefixo async à sua main função e faça com que ela retorne um Promise, como 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 seria : Promise <Employee>

Você precisará conhecer as interfaces do serviço externo para fazer chamadas para esse serviço. Se você estiver usando fetchAPIs REST, precisará determinar a estrutura JSON dos dados retornados. Para entrada e saída do seu 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 Usando a busca de scripts do Office.

Limitações com chamadas externas de Scripts do Office

  • Não há como entrar ou usar fluxos de autenticação do tipo OAuth2. Todas as chaves e credenciais devem ser codificadas (ou lidas 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 localStoragede documento e sessionStorage objetos.
  • As chamadas externas podem resultar na exposição de dados confidenciais a pontos de extremidade indesejáveis ou na entrada de dados externos em pastas de trabalho internas. Seu administrador pode estabelecer proteção de firewall contra essas chamadas. Certifique-se de marcar com as políticas locais antes de depender de chamadas externas.
  • Certifique-se de marcar a quantidade de taxa de transferência de dados antes de assumir uma dependência. Por exemplo, extrair 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.
  • Ao usar o Excel na Web em navegadores baseados no Chromium, fetch as chamadas para acesso à rede local exigem que os usuários permitam o script quando solicitado. Se o script ainda falhar, contate o administrador de TI.
    • Se uma solicitação de acesso à rede local foi negada, isso pode ser ajustado no Chrome acessandoas Configurações> do site de privacidade>Permissões> adicionaisAcesso à rede local.
    • Para obter mais informações, consulte Nova solicitação de permissão para Acesso à Rede Local no blog do Chrome.

Recupere informações com fetch

A API de busca recupera informações de serviços externos. É uma async API, então você precisa ajustar a main assinatura do seu script. Faça a main função async. Você também deve ter certeza await da chamada e json da fetch recuperação. Isso garante que essas operações sejam concluídas antes que o script termine.

Todos os dados JSON recuperados devem fetch 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 seu serviço para ver quais são os nomes e tipos das propriedades retornadas. Em seguida, adicione a(s) interface(s) correspondente(s) ao script.

Observação

Se você costuma fetch chamar um recurso externo com uma política de Compartilhamento de Recursos entre Origens (CORS), certifique-se de que o Access-Control-Allow-Origin cabeçalho desse recurso externo use a * diretiva. Se o Access-Control-Allow-Origin cabeçalho usar uma diretiva específica <origin> , sua fetch chamada de Scripts do Office poderá falhar. A origem do tempo de execução dos Scripts do Office pode ser alterada sem aviso prévio.

O script a seguir usa fetch para recuperar dados JSON do servidor de teste na URL especificada. 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;
}

Outras fetch amostras

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

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

Chamadas externas do Power Automate

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

Você precisará usar HTTP com o Azure AD ou outras ações equivalentes para extrair dados de um serviço externo ou enviá-los por push para um serviço externo.

Aviso

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

Confira também

  • Last updated on