创建会话

命名空间:microsoft.graph

创建新的工作簿会话。

可以在以下任一模式下调用 Excel API:

  1. 永久会话 - 保持(保存)对工作簿所做的全部更改。 这是常用的操作模式。
  2. 非永久会话 - 不会将 API 所做的更改保存到源位置。 相反,Excel 后端服务器保留文件的临时副本,体现在特定 API 会话期间所做的更改。 Excel 会话过期时,这些更改将丢失。 此模式可用于需要进行分析或获得计算结果或图表图像的应用,但不会影响文档状态。

若要表示 API 中的会话,请使用 workbook-session-id: {session-id} 标头。

注意: Excel API 不需要会话标头也能起作用。 但是,建议你使用会话标头来提高性能。 如果不使用会话标头,API 调用过程中进行的更改保持在该文件中。

在某些情况下,创建新会话需要不确定的时间才能完成。 Microsoft Graph 还提供长时间运行的操作模式。 此模式提供了一种轮询创建状态更新的方法,而无需等待创建完成。 下面是步骤:

  1. 标头 Prefer: respond-async 将添加到请求中,以指示它是长时间运行的操作。
  2. 响应返回一个 Location 标头,指定用于轮询创建操作状态的 URL。 可以通过访问指定的 URL 来获取操作状态。 状态将为以下项之一: notStartedrunningsucceededfailed
  3. 操作完成后,可以再次请求状态,响应将显示 或 succeededfailed

此 API 可用于以下国家级云部署

全局服务 美国政府 L4 美国政府 L5 (DOD) 由世纪互联运营的中国

错误处理

此请求有时可能会收到 504 HTTP 错误。 此错误的适当响应做法是重复发出请求。

权限

为此 API 选择标记为最低特权的权限。 只有在应用需要它时,才使用更高的特权权限。 有关委派权限和应用程序权限的详细信息,请参阅权限类型。 要了解有关这些权限的详细信息,请参阅 权限参考

权限类型 最低特权权限 更高特权权限
委派(工作或学校帐户) Files.ReadWrite 不可用。
委派(个人 Microsoft 帐户) 不支持。 不支持。
应用程序 不支持。 不支持。

HTTP 请求

POST /me/drive/items/{id}/workbook/createSession
POST /me/drive/root:/{item-path}:/workbook/createSession

请求标头

名称 说明
Authorization 持有者 {token}。 必填。 详细了解 身份验证和授权

请求正文

在请求正文中,提供 WorkbookSessionInfo 对象的 JSON 表示形式。

响应

如果成功,此方法在 201 Created 响应正文中返回响应代码和 workbookSessionInfo 对象。 对于长时间运行的操作,它将返回 202 Accepted 响应代码和 Location 响应中正文为空的标头。

示例

示例 1:使用长时间运行的操作模式创建会话

请求

POST https://graph.microsoft.com/beta/me/drive/items/{drive-item-id}/workbook/createSession
Prefer: respond-async
Content-type: application/json

{
    "persistChanges": true
}

响应

注意:为了提高可读性,可能缩短了此处显示的响应对象。

HTTP/1.1 202 Accepted
Location: https://graph.microsoft.com/v1.0/me/drive/items/{drive-item-id}/workbook/operations/{operation-id}
Content-type: application/json

{
}

202 Accepted对于响应,请参阅使用需要很长时间才能完成的 API,了解如何检索操作状态并获取会话创建结果。

示例 2:基本会话创建

请求

POST https://graph.microsoft.com/beta/me/drive/items/{id}/workbook/createSession
Content-type: application/json

{
  "persistChanges": true
}

响应

注意:为了提高可读性,可能缩短了此处显示的响应对象。

HTTP/1.1 201 Created
Content-type: application/json

{
  "id": "id-value",
  "persistChanges": true
}