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


Рекомендации по работе с API Excel

В этой статье приведены рекомендации по работе с API Excel в Microsoft Graph.

Наиболее эффективным способом управления сеансами

Если у вас есть несколько вызовов в течение определенного периода времени, рекомендуется создать сеанс и передать идентификатор сеанса с каждым запросом. Чтобы представить сеанс в API, используйте заголовок workbook-session-id: {session-id}. Это позволяет наиболее эффективно использовать API-интерфейсы Excel.

В следующем примере показано, как добавить новое число в таблицу, а затем найти одну запись в книге с помощью этого подхода.

Шаг 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- интерфейсами, которые занимают много времени

Вы можете заметить, что для выполнения некоторых операций требуется неопределенное время; например, открытие большой книги. Легко достичь времени ожидания ответа на эти запросы. Чтобы устранить эту проблему, мы предоставляем шаблон длительных операций. При использовании этого шаблона вам не нужно беспокоиться о времени ожидания запроса.

В настоящее время для создания сеанса API Excel в Microsoft Graph включен шаблон длительной операции. Этот шаблон включает в себя следующие шаги:

  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
}

Примечание.

Получение сведений о сеансе зависит от первоначального запроса. Вам не нужно получать результат, если исходный запрос не возвращает текст ответа.

Уменьшение ошибок регулирования

API Excel в Microsoft Graph влияют на использование ресурсов нескольких служб зависимостей. Влияние может отличаться в разных запросах: например, можно ожидать, что обновление короткой строки в одной ячейке небольшой книги будет потреблять меньше ресурсов, чем добавление большой таблицы со сложными формулами в большую книгу.

Даже при использовании одного и того же API параметры и целевые книги могут привести к значительным различиям. Поэтому регулирование API Excel не определяется с простыми и универсальными номерами ограничений, так как они приводят к более строгим ограничениям. Приведенные ниже рекомендации помогут быстрее выполнять задачи с меньшим количеством ошибок регулирования.

заголовок Retry-After

Во многих случаях ответ регулирования включает заголовок Retry-After . Соблюдение значения заголовка и задержка аналогичных запросов помогут клиенту восстановиться после регулирования. Дополнительные сведения об обработке ответов на ошибки из API Excel в Microsoft Graph см. в статье Обработка ошибок для API Excel в Microsoft Graph.

Регулирование и параллелизм

Другим фактором, связанным с регулированием, является параллелизм запросов. Не рекомендуется увеличивать параллелизм при использовании API Excel (например, при параллелизации запросов к одной книге), особенно для запросов на запись. Вместо этого, если нет конкретных проблем, таких как значительные сетевые издержки по сравнению с очень коротким временем выполнения запроса, рекомендуется последовательное использование в наиболее распространенном случае: для каждой книги отправляется только следующий запрос после успешного получения ответа на текущий запрос.

Одновременные запросы на запись в одну книгу обычно не выполняются параллельно (хотя в некоторых случаях они выполняются); скорее, они часто являются причиной регулирования, истечения времени ожидания (когда запросы помещаются в очередь на серверах), конфликт слияния (при задействовании параллельных сеансов) и других типов сбоев. Они также усложняют обработку ошибок; Например, при получении ответа о сбое невозможно подтвердить состояние других ожидающих запросов, что затрудняет определение или восстановление состояния книги.