Share via

Office 脚本中的外部 API 呼叫支持

  • 项目

脚本支持对外部服务的调用。 使用这些服务向工作簿提供数据和其他信息。

警告

外部调用可能会导致敏感数据公开到不需要的终结点。 管理员可以建立信息权限管理 (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 签名。 使 main 函数 async为 。 还应确保调用awaitfetch和json检索。 这可确保这些操作在脚本结束之前完成。

由 fetch 检索的任何 JSON 数据必须与脚本中定义的接口匹配。 返回的值必须分配给特定类型，因为 Office 脚本不支持该 any 类型。 应参阅服务的文档，了解返回的属性的名称和类型。 然后，将一个或多个匹配接口添加到脚本。

以下脚本使用 fetch 从给定 URL 中的测试服务器检索 JSON 数据。 请注意将数据 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 的外部调用

通过 Power Automate 运行脚本时，外部 API 调用失败。 fetch调用将显示错误消息“运行时错误：第 X 行：未定义提取”。 在将脚本生成为流之前，请务必为此类引用检查脚本。

必须结合使用 HTTP 和 Azure AD 或其他等效操作，才能从外部服务拉取数据或将其推送到外部服务。

警告

通过 Power Automate Excel Online 连接器 进行的外部调用失败，以帮助维护现有的数据丢失防护策略。 但是，通过 Power Automate 运行的脚本是在组织外部和组织的防火墙外部完成的。 为了进一步防止此外部环境中的恶意用户，管理员可以控制 Office 脚本的使用。 管理员可以在 Power Automate 中禁用 Excel Online 连接器，或通过 Office 脚本 管理员控件关闭 Excel Office 脚本。

另请参阅