Поделиться через

Поддержка внешнего вызова API в сценариях Office

  • Статья

Скрипты поддерживают вызовы внешних служб. Используйте эти службы для предоставления данных и других сведений в книгу.

Предостережение

Внешние вызовы могут привести к тому, что конфиденциальные данные будут предоставляться нежелательным конечным точкам. Администратор может установить управление правами на доступ к данным (IRM) или защиту брандмауэра от таких вызовов.

Важно!

Вызовы внешних API можно выполнять только через приложение Excel, а не Через Power Automate в обычных условиях. Внешние вызовы также не поддерживаются для скриптов, хранящихся на сайте SharePoint.

Настройка скрипта для внешних вызовов

Внешние вызовы являются асинхронными и требуют, чтобы скрипт был помечен как async. async Добавьте префикс в функцию main и верните Promise, как показано ниже:

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

Примечание.

Скрипты, возвращающие другие сведения, могут возвращать Promise объект этого типа. Например, если скрипту нужно вернуть Employee объект, то сигнатура возвращается. : Promise <Employee>

Вам потребуется изучить интерфейсы внешней службы для выполнения вызовов к этой службе. Если вы используете fetch rest API или, необходимо определить структуру возвращаемых данных в формате JSON. Для входных и выходных данных скрипта рассмотрите возможность создания interface в соответствии с необходимыми структурами JSON. Это обеспечивает скрипту большую безопасность типов. Пример см. в статье Использование извлечения из сценариев Office.

Ограничения внешних вызовов из сценариев Office

  • Нет способа войти или использовать потоки проверки подлинности типа OAuth2. Все ключи и учетные данные должны быть жестко закодированы (или считываются из другого источника).
  • Отсутствует инфраструктура для хранения учетных данных и ключей API. Этим должен управлять пользователь.
  • Файлы cookie документов, localStorageобъекты , и sessionStorage не поддерживаются.
  • Внешние вызовы могут привести к тому, что конфиденциальные данные будут переданы нежелательным конечным точкам или внешним данным, которые будут перенесены во внутренние книги. Администратор может установить защиту брандмауэра от таких вызовов. Перед использованием внешних вызовов обязательно проверка с локальными политиками.
  • Перед использованием зависимости обязательно проверка объем пропускной способности данных. Например, вытягивание всего внешнего набора данных может быть не лучшим вариантом, и вместо этого следует использовать разбиение на страницы для получения данных фрагментами.

Получение сведений с помощью fetch

API извлечения извлекает сведения из внешних служб. Это async API, поэтому необходимо настроить сигнатуру main скрипта. Сделайте функцию mainasync. Вы также должны быть уверены await в вызове fetch и json получении. Это гарантирует выполнение этих операций до завершения скрипта.

Все полученные fetch данные JSON должны соответствовать интерфейсу, определенному в скрипте. Возвращаемое значение должно быть присвоено определенному типу, так как скрипты Office не поддерживают этот any тип. Чтобы узнать имена и типы возвращаемых свойств, ознакомьтесь с документацией по службе. Затем добавьте соответствующий интерфейс или интерфейсы в скрипт.

Следующий скрипт использует fetch для получения данных JSON с тестового сервера по заданному URL-адресу. Обратите внимание на JSONData интерфейс для хранения данных в качестве соответствующего типа.

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

Другие fetch примеры

Ограничение внешних вызовов с помощью управления правами на доступ к данным (IRM)

Параметры IRM можно применить к книге, чтобы предотвратить внешние вызовы, выполняемые скриптами. Отключите политику копирования/EXTRACT, чтобы предотвратить такое поведение.

Внешние вызовы из Power Automate

Внешние вызовы API завершаются сбоем при выполнении скрипта с помощью Power Automate. Вызов fetch выдаст сообщение об ошибке "Ошибка среды выполнения: Строка X: выборка не определена". Не забудьте проверка скрипты для таких ссылок, прежде чем создавать их в поток.

Вам придется использовать HTTP с Azure AD или другими эквивалентными действиями, чтобы извлечь данные из внешней службы или отправить их во внешнюю службу.

Предупреждение

Внешние вызовы, выполненные через соединитель Power Automate Excel Online , завершаются сбоем, чтобы обеспечить поддержку существующих политик защиты от потери данных. Однако сценарии, выполняемые в Power Automate, выполняются за пределами организации и за пределами брандмауэров вашей организации. Для дополнительной защиты от злоумышленников в этой внешней среде администратор может контролировать использование сценариев Office. Администратор может отключить соединитель Excel Online в Power Automate или отключить сценарии Office для Excel с помощью элементов управления администратора сценариев Office.

См. также