使用 Excel API 的最佳做法

  • 项目

本文提供有关在 Microsoft Graph 中使用 Excel API 的建议。

以最有效的方式管理会话

如果在特定时间段内要进行多个调用，建议创建一个会话，并通过每个请求传递会话 ID。 若要表示 API 中的会话，请使用 workbook-session-id: {session-id} 标头。 通过这样做，你可以以最有效的方式使用 Excel API。

以下示例演示如何将新数字添加到表中，然后使用此方法在工作簿中查找一条记录。

步骤 1：创建会话

请求

POST https://graph.microsoft.com/v1.0/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
}

步骤 2：向表添加新行

请求

POST https://graph.microsoft.com/v1.0/me/drive/items/{id}/workbook/tables/{id|name}/rows/add
Content-type: application/json
workbook-session-id: {session-id}

{
  "values": [[“east”, “pear”, 4]]
}

响应

HTTP/1.1 200 OK
Content-type: application/json

{
  "index": 6,
  "values": [[“east”, “pear”, 4]]
}

步骤 3：在更新的表中查找值

请求

POST https://graph.microsoft.com/v1.0/me/drive/items/{id}/workbook/functions/vlookup
Content-type: application/json
workbook-session-id: {session-id}

{
    "lookupValue":"pear",
    "tableArray":{"Address":"Sheet1!B2:C7"},
    "colIndexNum":2,
    "rangeLookup":false
}

响应

HTTP code: 200 OK
content-type: application/json

{
    "value": 5
}

步骤 4：完成所有请求后关闭会话

请求

POST https://graph.microsoft.com/v1.0/me/drive/items/{id}/workbook/closeSession
Content-type: application/json
workbook-session-id: {session-id}

{
}

响应

HTTP/1.1 204 No Content

有关详细信息，请参阅 创建会话 和 关闭会话。

使用需要很长时间才能完成的 API

你可能会注意到，某些操作需要不确定的时间才能完成;例如，打开大型工作簿。 在等待这些请求的响应时，很容易达到超时。 为了解决此问题，我们提供了长时间运行的操作模式。 使用此模式时，无需担心请求超时。

目前，Microsoft Graph 中的会话创建 Excel API 已启用长时间运行的操作模式。 此模式涉及以下步骤：

  1. Prefer: respond-async在创建会话时，向请求添加标头以指示它是长时间运行的操作。
  2. 长时间运行的操作返回 202 Accepted 响应以及 Location 标头以检索操作状态。 如果会话创建在几秒钟内完成，它将返回常规的创建会话响应，而不是使用长时间运行的操作模式。
  3. 202 Accepted通过响应，可以在指定位置检索操作状态。 操作状态值包括 notStarted、 running、 succeeded和 failed。
  4. 操作完成后，可以通过成功响应中的指定 URL 获取会话创建结果。

以下示例使用长时间运行的操作模式创建会话。

创建会话的初始请求

请求

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

响应

长时间运行的操作模式返回 202 Accepted 如下响应。

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

{
}

在某些情况下，如果创建在几秒钟内成功，则不会进入长时间运行的操作模式;相反，它将作为常规创建会话返回，成功的请求将返回 201 Created 响应。

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

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

以下示例演示请求失败时的响应。

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

HTTP/1.1 500 Internal Server Error
Content-type: application/json

{
  "error":{
    "code": "internalServerError",
    "message": "An internal server error occurred while processing the request.",
    "innerError": {
      "code": "internalServerErrorUncategorized",
      "message": "An unspecified error has occurred.",
      "innerError": {
        "code": "GenericFileOpenError",
        "message": "The workbook cannot be opened."
      }
    }
  }
}

长时间运行的创建会话的轮询状态

使用长时间运行的操作模式，可以使用以下请求获取指定位置的创建状态。 建议的轮询状态间隔约为 30 秒。 最大间隔应不超过 4 分钟。

请求

GET https://graph.microsoft.com/v1.0/me/drive/items/{drive-item-id}/workbook/operations/{operation-id}
{
}

响应

以下是操作状态 running为 时的响应。

HTTP/1.1 200 OK
Content-type: application/json

{
    "id": {operation-id},
    "status": "running"
}

下面是操作状态为 succeeded时的响应。

HTTP/1.1 200 OK
Content-type: application/json

{
    "id": {operation-id},
    "status": "succeeded",
    "resourceLocation": "https://graph.microsoft.com/v1.0/me/drive/items/{drive-item-id}/workbook/sessionInfoResource(key='{key}')
}

下面是操作状态为 failed时的响应。

HTTP/1.1 200 OK
Content-type: application/json

{
  "id": {operation-id},
  "status": "failed",
  "error":{
    "code": "internalServerError",
    "message": "An internal server error occurred while processing the request.",
    "innerError": {
      "code": ""internalServerErrorUncategorized",
      "message": "An unspecified error has occurred.",
      "innerError": {
        "code": "GenericFileOpenError",
        "message": "The workbook cannot be opened."
      }
    }
  }
}

有关错误的详细信息，请参阅 错误代码和消息。

获取会话信息

请求

状态为 ， succeeded可以使用如下所示的请求获取 resourceLocation 创建的会话信息。

GET https://graph.microsoft.com/v1.0/me/drive/items/{drive-item-id}/workbook/sessionInfoResource(key='{key}')
{
}

响应

以下是答复。

HTTP/1.1 200 OK
Content-type: application/json

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

注意

获取会话信息取决于初始请求。 如果初始请求不返回响应正文，则无需获取结果。

减少限制错误

Microsoft Graph 中的 Excel API 会影响多个依赖项服务的资源使用情况。 不同请求的影响可能有所不同：例如，你可能预期更新小型工作簿的单个单元格中的短字符串比将包含复杂公式的大表添加到大型工作簿消耗的资源更少。

即使使用相同的 API，参数和目标工作簿也会带来显著差异。 因此，Excel API 限制不是使用简单且通用的限制数字定义的，因为它们会导致限制性更高的限制。 以下最佳做法将帮助你更快地完成任务，并减少限制错误。

Retry-After 标头

在许多情况下，限制响应包括 Retry-After 标头。 遵循标头的值并延迟类似的请求将有助于客户端从限制中恢复。 有关在 Microsoft Graph 中处理 Excel API 的错误响应的详细信息，请参阅 Microsoft Graph 中 Excel API 的错误处理。

限制和并发

与限制相关的另一个因素是请求并发。 建议不要在使用 Excel API 时增加并发性 (，例如，将请求并行化到同一工作簿) ，尤其是写入请求。 相反，除非存在特定问题（例如与非常短的请求执行时间相比，网络开销很大），否则我们建议在最常见的情况下按顺序使用：对于每个工作簿，仅在收到对当前请求的成功响应后发送下一个请求。

对同一工作簿的并发写入请求通常不会 (并行运行，尽管在某些情况下它们) ;相反，当请求在) 服务器上排队时，它们通常是限制、超时 (的原因，合并冲突 (并发会话涉及) 和其他类型的故障时。 它们还会使错误处理复杂化;例如，收到失败响应时，无法确认其他挂起请求的状态，这使得很难确定或恢复工作簿的状态。

相关内容