В этой статье приведены рекомендации по работе с API Excel в Microsoft Graph.
Наиболее эффективным способом управления сеансами
Если у вас есть несколько вызовов в течение определенного периода времени, рекомендуется создать сеанс и передать идентификатор сеанса с каждым запросом. Чтобы представить сеанс в API, используйте заголовок workbook-session-id: {session-id}. Это позволяет наиболее эффективно использовать API-интерфейсы Excel.
В следующем примере показано, как добавить новое число в таблицу, а затем найти одну запись в книге с помощью этого подхода.
POST https://graph.microsoft.com/v1.0/me/drive/items/{id}/workbook/createSession
Content-type: application/json
{
"persistChanges": true
}
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Drives.Item.Items.Item.Workbook.CreateSession;
var requestBody = new CreateSessionPostRequestBody
{
PersistChanges = true,
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Drives["{drive-id}"].Items["{driveItem-id}"].Workbook.CreateSession.PostAsync(requestBody);
// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc drives items workbook create-session post --drive-id {drive-id} --drive-item-id {driveItem-id} --body '{\
"persistChanges": true\
}\
'
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
com.microsoft.graph.drives.item.items.item.workbook.createsession.CreateSessionPostRequestBody createSessionPostRequestBody = new com.microsoft.graph.drives.item.items.item.workbook.createsession.CreateSessionPostRequestBody();
createSessionPostRequestBody.setPersistChanges(true);
var result = graphClient.drives().byDriveId("{drive-id}").items().byDriveItemId("{driveItem-id}").workbook().createSession().post(createSessionPostRequestBody);
<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Models\CreateSessionPostRequestBody;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestBody = new CreateSessionPostRequestBody();
$requestBody->setPersistChanges(true);
$result = $graphServiceClient->drives()->byDriveId('drive-id')->items()->byDriveItemId('driveItem-id')->workbook()->createSession()->post($requestBody)->wait();
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Drives.Item.Items.Item.Workbook.Functions.Vlookup;
using Microsoft.Graph.Models;
var requestBody = new VlookupPostRequestBody
{
LookupValue = "pear",
TableArray = new Json
{
AdditionalData = new Dictionary<string, object>
{
{
"Address" , "Sheet1!B2:C7"
},
},
},
ColIndexNum = 2,
RangeLookup = false,
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Drives["{drive-id}"].Items["{driveItem-id}"].Workbook.Functions.Vlookup.PostAsync(requestBody, (requestConfiguration) =>
{
requestConfiguration.Headers.Add("workbook-session-id", "{session-id}");
});
// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc drives items workbook functions vlookup post --drive-id {drive-id} --drive-item-id {driveItem-id} --body '{\
"lookupValue":"pear",\
"tableArray":{"Address":"Sheet1!B2:C7"},\
"colIndexNum":2,\
"rangeLookup":false\
}\
'
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
com.microsoft.graph.drives.item.items.item.workbook.functions.vlookup.VlookupPostRequestBody vlookupPostRequestBody = new com.microsoft.graph.drives.item.items.item.workbook.functions.vlookup.VlookupPostRequestBody();
vlookupPostRequestBody.setLookupValue("pear");
Json tableArray = new Json();
HashMap<String, Object> additionalData = new HashMap<String, Object>();
additionalData.put("Address", "Sheet1!B2:C7");
tableArray.setAdditionalData(additionalData);
vlookupPostRequestBody.setTableArray(tableArray);
vlookupPostRequestBody.setColIndexNum(2);
vlookupPostRequestBody.setRangeLookup(false);
var result = graphClient.drives().byDriveId("{drive-id}").items().byDriveItemId("{driveItem-id}").workbook().functions().vlookup().post(vlookupPostRequestBody, requestConfiguration -> {
requestConfiguration.headers.add("workbook-session-id", "{session-id}");
});
POST https://graph.microsoft.com/v1.0/me/drive/items/{id}/workbook/closeSession
Content-type: application/json
workbook-session-id: {session-id}
{
}
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Drives.Item.Items.Item.Workbook.CloseSession;
var requestBody = new CloseSessionPostRequestBody
{
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
await graphClient.Drives["{drive-id}"].Items["{driveItem-id}"].Workbook.CloseSession.PostAsync(requestBody, (requestConfiguration) =>
{
requestConfiguration.Headers.Add("workbook-session-id", "{session-id}");
});
// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc drives items workbook close-session post --drive-id {drive-id} --drive-item-id {driveItem-id} --body '{\
}\
'
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
com.microsoft.graph.drives.item.items.item.workbook.closesession.CloseSessionPostRequestBody closeSessionPostRequestBody = new com.microsoft.graph.drives.item.items.item.workbook.closesession.CloseSessionPostRequestBody();
graphClient.drives().byDriveId("{drive-id}").items().byDriveItemId("{driveItem-id}").workbook().closeSession().post(closeSessionPostRequestBody, requestConfiguration -> {
requestConfiguration.headers.add("workbook-session-id", "{session-id}");
});
Работа с API- интерфейсами, которые занимают много времени
Вы можете заметить, что для выполнения некоторых операций требуется неопределенное время; например, открытие большой книги. Легко достичь времени ожидания ответа на эти запросы. Чтобы устранить эту проблему, мы предоставляем шаблон длительных операций. При использовании этого шаблона вам не нужно беспокоиться о времени ожидания запроса.
В настоящее время для создания сеанса API Excel в Microsoft Graph включен шаблон длительной операции. Этот шаблон включает в себя следующие шаги:
Добавьте в Prefer: respond-async запрос заголовок, чтобы указать, что это длительная операция при создании сеанса.
Длительная операция возвращает 202 Accepted ответ вместе с заголовком Location для получения состояния операции. Если создание сеанса завершается в течение нескольких секунд, он возвращает обычный ответ сеанса создания вместо того, чтобы использовать шаблон длительной операции.
202 Accepted С помощью ответа можно получить состояние операции в указанном расположении. Значения состояния операции: notStarted, running, succeededи failed.
После завершения операции вы можете получить результат создания сеанса по указанному 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
}
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Drives.Item.Items.Item.Workbook.CreateSession;
var requestBody = new CreateSessionPostRequestBody
{
PersistChanges = true,
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Drives["{drive-id}"].Items["{driveItem-id}"].Workbook.CreateSession.PostAsync(requestBody, (requestConfiguration) =>
{
requestConfiguration.Headers.Add("Prefer", "respond-async");
});
// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc drives items workbook create-session post --drive-id {drive-id} --drive-item-id {driveItem-id} --body '{\
"persistChanges": true\
}\
'
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
com.microsoft.graph.drives.item.items.item.workbook.createsession.CreateSessionPostRequestBody createSessionPostRequestBody = new com.microsoft.graph.drives.item.items.item.workbook.createsession.CreateSessionPostRequestBody();
createSessionPostRequestBody.setPersistChanges(true);
var result = graphClient.drives().byDriveId("{drive-id}").items().byDriveItemId("{driveItem-id}").workbook().createSession().post(createSessionPostRequestBody, requestConfiguration -> {
requestConfiguration.headers.add("Prefer", "respond-async");
});
В некоторых случаях, если создание завершается успешно в течение нескольких секунд, оно не будет входить в шаблон длительной операции. Вместо этого он возвращается в виде обычного сеанса создания, и успешный запрос вернет 201 Created ответ.
В следующем примере показан ответ при сбое запроса.
Примечание. Объект отклика, показанный здесь, может быть сокращен для удобочитаемости.
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.
Получение сведений о сеансе зависит от первоначального запроса. Вам не нужно получать результат, если исходный запрос не возвращает текст ответа.
Уменьшение ошибок регулирования
API Excel в Microsoft Graph влияют на использование ресурсов нескольких служб зависимостей. Влияние может отличаться в разных запросах: например, можно ожидать, что обновление короткой строки в одной ячейке небольшой книги будет потреблять меньше ресурсов, чем добавление большой таблицы со сложными формулами в большую книгу.
Даже при использовании одного и того же API параметры и целевые книги могут привести к значительным различиям. Поэтому регулирование API Excel не определяется с простыми и универсальными номерами ограничений, так как они приводят к более строгим ограничениям. Приведенные ниже рекомендации помогут быстрее выполнять задачи с меньшим количеством ошибок регулирования.
заголовок Retry-After
Во многих случаях ответ регулирования включает заголовок Retry-After . Соблюдение значения заголовка и задержка аналогичных запросов помогут клиенту восстановиться после регулирования. Дополнительные сведения об обработке ответов на ошибки из API Excel в Microsoft Graph см. в статье Обработка ошибок для API Excel в Microsoft Graph.
Регулирование и параллелизм
Другим фактором, связанным с регулированием, является параллелизм запросов. Не рекомендуется увеличивать параллелизм при использовании API Excel (например, при параллелизации запросов к одной книге), особенно для запросов на запись. Вместо этого, если нет конкретных проблем, таких как значительные сетевые издержки по сравнению с очень коротким временем выполнения запроса, рекомендуется последовательное использование в наиболее распространенном случае: для каждой книги отправляется только следующий запрос после успешного получения ответа на текущий запрос.
Одновременные запросы на запись в одну книгу обычно не выполняются параллельно (хотя в некоторых случаях они выполняются); скорее, они часто являются причиной регулирования, истечения времени ожидания (когда запросы помещаются в очередь на серверах), конфликт слияния (при задействовании параллельных сеансов) и других типов сбоев. Они также усложняют обработку ошибок; Например, при получении ответа о сбое невозможно подтвердить состояние других ожидающих запросов, что затрудняет определение или восстановление состояния книги.
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.