Melhores práticas para trabalhar com a API do Excel

Este artigo fornece recomendações para trabalhar com as APIs do Excel no Microsoft Graph.

Gerir sessões da forma mais eficiente

Se tiver mais do que uma chamada para efetuar num determinado período de tempo, recomendamos que crie uma sessão e transmita o ID da sessão a cada pedido. Para representar a sessão na API, use o cabeçalho workbook-session-id: {session-id}. Ao fazê-lo, pode utilizar as APIs do Excel da forma mais eficiente.

O exemplo seguinte mostra-lhe como adicionar um novo número a uma tabela e, em seguida, localizar um registo num livro com esta abordagem.

Passo 1: Criar uma sessão

Solicitação

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);



// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphdrives "github.com/microsoftgraph/msgraph-sdk-go/drives"
	  //other-imports
)

requestBody := graphdrives.NewCreateSessionPostRequestBody()
persistChanges := true
requestBody.SetPersistChanges(&persistChanges) 

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
createSession, err := graphClient.Drives().ByDriveId("drive-id").Items().ByDriveItemId("driveItem-id").Workbook().CreateSession().Post(context.Background(), requestBody, nil)


// 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);


const options = {
	authProvider,
};

const client = Client.init(options);

const workbookSessionInfo = {
  persistChanges: true
};

await client.api('/me/drive/items/{id}/workbook/createSession')
	.post(workbookSessionInfo);


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Drives\Item\Items\Item\Workbook\CreateSession\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 1.x
from msgraph import GraphServiceClient
from msgraph.generated.drives.item.items.item.workbook.create_session.create_session_post_request_body import CreateSessionPostRequestBody
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = CreateSessionPostRequestBody(
	persist_changes = True,
)

result = await graph_client.drives.by_drive_id('drive-id').items.by_drive_item_id('driveItem-id').workbook.create_session.post(request_body)

Resposta

Segue-se uma resposta bem-sucedida.

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

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

Passo 2: adicionar uma nova linha à tabela

Solicitação

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]]
}

Snippet not available

Snippet not available

Snippet not available


const options = {
	authProvider,
};

const client = Client.init(options);

const workbookTableRow = {
  values: [[“east”, “pear”, 4]]
};

await client.api('/me/drive/items/{id}/workbook/tables/{id|name}/rows/add')
	.post(workbookTableRow);

Snippet not available

Snippet not available

Resposta

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

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

Passo 3: procurar um valor na tabela atualizada

Solicitação

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
}


// 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.Kiota.Abstractions.Serialization;

var requestBody = new VlookupPostRequestBody
{
	LookupValue = new UntypedString("pear"),
	TableArray = new UntypedObject(new Dictionary<string, UntypedNode>
	{
		{
			"Address", new UntypedString("Sheet1!B2:C7")
		},
	}),
	ColIndexNum = new UntypedDouble(2),
	RangeLookup = new UntypedBoolean(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}");
});



// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  abstractions "github.com/microsoft/kiota-abstractions-go"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphdrives "github.com/microsoftgraph/msgraph-sdk-go/drives"
	  //other-imports
)

headers := abstractions.NewRequestHeaders()
headers.Add("workbook-session-id", "{session-id}")

configuration := &graphdrives.ItemItemsItemWorkbookFunctionsVlookupRequestBuilderPostRequestConfiguration{
	Headers: headers,
}
requestBody := graphdrives.NewVlookupPostRequestBody()
lookupValue := "pear"
requestBody.SetLookupValue(&lookupValue) 
tableArray := graph.NewUntypedNode()
address := "Sheet1!B2:C7"
tableArray.SetAddress(&address) 
requestBody.SetTableArray(tableArray)
colIndexNum := float64(2)
requestBody.SetColIndexNum(&colIndexNum) 
rangeLookup := false
requestBody.SetRangeLookup(&rangeLookup) 

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
vlookup, err := graphClient.Drives().ByDriveId("drive-id").Items().ByDriveItemId("driveItem-id").Workbook().Functions().Vlookup().Post(context.Background(), requestBody, configuration)


// 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");
UntypedNode tableArray = new UntypedNode();
tableArray.setAddress("Sheet1!B2:C7");
vlookupPostRequestBody.setTableArray(tableArray);
vlookupPostRequestBody.setColIndexNum(2d);
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}");
});


const options = {
	authProvider,
};

const client = Client.init(options);

const workbookFunctionResult = {
    lookupValue: 'pear',
    tableArray: {Address: 'Sheet1!B2:C7'},
    colIndexNum: 2,
    rangeLookup: false
};

await client.api('/me/drive/items/{id}/workbook/functions/vlookup')
	.post(workbookFunctionResult);


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Drives\Item\Items\Item\Workbook\Functions\Vlookup\VlookupRequestBuilderPostRequestConfiguration;
use Microsoft\Graph\Generated\Drives\Item\Items\Item\Workbook\Functions\Vlookup\VlookupPostRequestBody;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestBody = new VlookupPostRequestBody();
$requestBody->setLookupValue('pear');
$tableArray = new UntypedNode();
$tableArray->setAddress('Sheet1!B2:C7');
$requestBody->setTableArray($tableArray);
$requestBody->setColIndexNum(2);
$requestBody->setRangeLookup(false);
$requestConfiguration = new VlookupRequestBuilderPostRequestConfiguration();
$headers = [
		'workbook-session-id' => '{session-id}',
	];
$requestConfiguration->headers = $headers;


$result = $graphServiceClient->drives()->byDriveId('drive-id')->items()->byDriveItemId('driveItem-id')->workbook()->functions()->vlookup()->post($requestBody, $requestConfiguration)->wait();


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.drives.item.items.item.workbook.functions.vlookup.vlookup_request_builder import VlookupRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
from msgraph.generated.drives.item.items.item.workbook.functions.vlookup.vlookup_post_request_body import VlookupPostRequestBody
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = VlookupPostRequestBody(
	lookup_value = "pear",
	table_array = UntypedNode(
		address = "Sheet1!B2:C7",
	),
	col_index_num = 2,
	range_lookup = False,
)

request_configuration = RequestConfiguration()
request_configuration.headers.add("workbook-session-id", "{session-id}")


result = await graph_client.drives.by_drive_id('drive-id').items.by_drive_item_id('driveItem-id').workbook.functions.vlookup.post(request_body, request_configuration = request_configuration)

Resposta

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

{
    "value": 5
}

Passo 4: fechar a sessão depois de todos os pedidos estarem concluídos

Solicitação

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}");
});



// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  abstractions "github.com/microsoft/kiota-abstractions-go"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphdrives "github.com/microsoftgraph/msgraph-sdk-go/drives"
	  //other-imports
)

headers := abstractions.NewRequestHeaders()
headers.Add("workbook-session-id", "{session-id}")

configuration := &graphdrives.ItemItemsItemWorkbookCloseSessionRequestBuilderPostRequestConfiguration{
	Headers: headers,
}
requestBody := graphdrives.NewCloseSessionPostRequestBody()

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
graphClient.Drives().ByDriveId("drive-id").Items().ByDriveItemId("driveItem-id").Workbook().CloseSession().Post(context.Background(), requestBody, configuration)


// 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}");
});


const options = {
	authProvider,
};

const client = Client.init(options);

const closeSession = {
};

await client.api('/me/drive/items/{id}/workbook/closeSession')
	.post(closeSession);


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Drives\Item\Items\Item\Workbook\CloseSession\CloseSessionRequestBuilderPostRequestConfiguration;
use Microsoft\Graph\Generated\Drives\Item\Items\Item\Workbook\CloseSession\CloseSessionPostRequestBody;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestBody = new CloseSessionPostRequestBody();
$requestConfiguration = new CloseSessionRequestBuilderPostRequestConfiguration();
$headers = [
		'workbook-session-id' => '{session-id}',
	];
$requestConfiguration->headers = $headers;


$graphServiceClient->drives()->byDriveId('drive-id')->items()->byDriveItemId('driveItem-id')->workbook()->closeSession()->post($requestBody, $requestConfiguration)->wait();


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.drives.item.items.item.workbook.close_session.close_session_request_builder import CloseSessionRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
from msgraph.generated.drives.item.items.item.workbook.close_session.close_session_post_request_body import CloseSessionPostRequestBody
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = CloseSessionPostRequestBody(
)

request_configuration = RequestConfiguration()
request_configuration.headers.add("workbook-session-id", "{session-id}")


await graph_client.drives.by_drive_id('drive-id').items.by_drive_item_id('driveItem-id').workbook.close_session.post(request_body, request_configuration = request_configuration)

Resposta

HTTP/1.1 204 No Content

Para obter mais informações, consulte Criar sessão e Fechar sessão.

Trabalhar com APIs que demoram muito tempo a concluir

Poderá reparar que algumas operações demoram muito tempo a concluir; por exemplo, abrir um livro grande. É fácil atingir o tempo limite enquanto aguarda a resposta a estes pedidos. Para resolve este problema, fornecemos o padrão de operação de execução prolongada. Quando utiliza este padrão, não precisa de se preocupar com o tempo limite do pedido.

Atualmente, a API do Excel de criação da sessão no Microsoft Graph tem o padrão de operação de execução prolongada ativado. Este padrão envolve os seguintes passos:

Adicione um Prefer: respond-async cabeçalho ao pedido para indicar que se trata de uma operação de execução prolongada quando cria uma sessão.
Uma operação de execução prolongada devolve uma 202 Accepted resposta juntamente com um cabeçalho Localização para obter a operação status. Se a criação da sessão for concluída em vários segundos, devolve uma resposta de sessão de criação regular em vez de utilizar o padrão de operação de execução prolongada.
Com a 202 Accepted resposta, pode obter a operação status na localização especificada. Os valores da operação status incluem notStarted, running, succeedede failed.
Após a conclusão da operação, pode obter o resultado da criação da sessão através do URL especificado na resposta com êxito.

O exemplo seguinte cria uma sessão com o padrão de operação de execução prolongada.

Pedido inicial para criar sessão

Solicitação

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");
});



// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  abstractions "github.com/microsoft/kiota-abstractions-go"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphdrives "github.com/microsoftgraph/msgraph-sdk-go/drives"
	  //other-imports
)

headers := abstractions.NewRequestHeaders()
headers.Add("Prefer", "respond-async")

configuration := &graphdrives.ItemItemsItemWorkbookCreateSessionRequestBuilderPostRequestConfiguration{
	Headers: headers,
}
requestBody := graphdrives.NewCreateSessionPostRequestBody()
persistChanges := true
requestBody.SetPersistChanges(&persistChanges) 

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
createSession, err := graphClient.Drives().ByDriveId("drive-id").Items().ByDriveItemId("driveItem-id").Workbook().CreateSession().Post(context.Background(), requestBody, configuration)


// 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");
});


const options = {
	authProvider,
};

const client = Client.init(options);

const workbookSessionInfo = {
    persistChanges: true
};

await client.api('/me/drive/items/{drive-item-id}/workbook/createSession')
	.post(workbookSessionInfo);


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Drives\Item\Items\Item\Workbook\CreateSession\CreateSessionRequestBuilderPostRequestConfiguration;
use Microsoft\Graph\Generated\Drives\Item\Items\Item\Workbook\CreateSession\CreateSessionPostRequestBody;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestBody = new CreateSessionPostRequestBody();
$requestBody->setPersistChanges(true);
$requestConfiguration = new CreateSessionRequestBuilderPostRequestConfiguration();
$headers = [
		'Prefer' => 'respond-async',
	];
$requestConfiguration->headers = $headers;


$result = $graphServiceClient->drives()->byDriveId('drive-id')->items()->byDriveItemId('driveItem-id')->workbook()->createSession()->post($requestBody, $requestConfiguration)->wait();


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.drives.item.items.item.workbook.create_session.create_session_request_builder import CreateSessionRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
from msgraph.generated.drives.item.items.item.workbook.create_session.create_session_post_request_body import CreateSessionPostRequestBody
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = CreateSessionPostRequestBody(
	persist_changes = True,
)

request_configuration = RequestConfiguration()
request_configuration.headers.add("Prefer", "respond-async")


result = await graph_client.drives.by_drive_id('drive-id').items.by_drive_item_id('driveItem-id').workbook.create_session.post(request_body, request_configuration = request_configuration)

Resposta

O padrão de operação de execução prolongada devolve uma 202 Accepted resposta semelhante à seguinte.

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

{
}

Em alguns casos, se a criação for bem-sucedida em segundos, não introduzirá o padrão de operação de execução prolongada; em vez disso, devolve como uma sessão de criação regular e o pedido com êxito devolverá uma 201 Created resposta.

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

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

O exemplo seguinte mostra a resposta quando o pedido falha.

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."
      }
    }
  }
}

Consulta status da sessão de criação de longa duração

Com o padrão de operação de execução prolongada, pode obter a criação status na localização especificada com o seguinte pedido. O intervalo sugerido para consultar status é de cerca de 30 segundos. O intervalo máximo não deve ser superior a 4 minutos.

Solicitação

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

Resposta

Segue-se a resposta quando a operação tem uma status de running.

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

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

Segue-se a resposta quando a operação status é 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}')
}

Segue-se a resposta quando a operação status é 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."
      }
    }
  }
}

Para obter mais informações sobre erros, veja Códigos de erro e mensagens.

Adquirir informações de sessão

Solicitação

Com uma status de succeeded, pode obter as informações de sessão criadas através resourceLocation de um pedido semelhante ao seguinte.

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

Resposta

Esta é a resposta.

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

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

Observação

Adquirir informações de sessão depende do pedido inicial. Não precisa de adquirir o resultado se o pedido inicial não devolver um corpo de resposta.

Reduzir erros de limitação

As APIs do Excel no Microsoft Graph afetam a utilização de recursos de vários serviços de dependência. O impacto pode variar entre diferentes pedidos: por exemplo, pode esperar que atualizar uma cadeia curta numa única célula de um livro pequeno consuma menos recursos do que adicionar uma grande tabela com fórmulas complexas a um livro grande.

Mesmo com a mesma API, os parâmetros e os livros de destino podem introduzir diferenças significativas. Por conseguinte, a limitação da API do Excel não é definida com números de limite simples e universais, pois resultariam em limites mais restritivos. As seguintes melhores práticas irão ajudá-lo a concluir tarefas mais rapidamente com menos erros de limitação.

cabeçalho Retry-After

Em muitos casos, uma resposta de limitação inclui um Retry-After cabeçalho. Respeitar o valor do cabeçalho e atrasar pedidos semelhantes ajudaria o cliente a recuperar da limitação. Para obter detalhes sobre como lidar com respostas de erros de APIs do Excel no Microsoft Graph, veja Processamento de erros para APIs do Excel no Microsoft Graph.

Limitação e simultaneidade

Outro fator relacionado com a limitação é a simultaneidade do pedido. Não recomendamos aumentar a simultaneidade ao utilizar as APIs do Excel (por exemplo, paralelizar os pedidos para o mesmo livro), especialmente para pedidos de escrita. Em vez disso, a menos que exista uma preocupação específica, como uma sobrecarga de rede significativa em comparação com o tempo de execução de pedidos muito curto, recomendamos a utilização sequencial no caso mais comum: para cada livro, envie apenas o pedido seguinte depois de receber uma resposta bem-sucedida ao pedido atual.

Normalmente, os pedidos de escrita simultâneos no mesmo livro não são executados em paralelo (embora, em alguns casos, o façam); Em vez disso, são frequentemente a causa da limitação, tempo limite (quando os pedidos são colocados em fila nos servidores), conflito de merge (quando estão envolvidas sessões simultâneas) e outros tipos de falhas. Também complicam o processamento de erros; por exemplo, quando recebe uma resposta de falha, não há forma de confirmar a status de outros pedidos pendentes, o que dificulta a determinação ou recuperação do estado do livro.

Usar a API REST do Excel

Comentários

Esta página foi útil?

Last updated on 2025-07-24

Compartilhar via

Melhores práticas para trabalhar com a API do Excel

Gerir sessões da forma mais eficiente

Passo 1: Criar uma sessão

Solicitação

Resposta

Passo 2: adicionar uma nova linha à tabela

Solicitação

Resposta

Passo 3: procurar um valor na tabela atualizada

Solicitação

Resposta

Passo 4: fechar a sessão depois de todos os pedidos estarem concluídos

Solicitação

Resposta

Trabalhar com APIs que demoram muito tempo a concluir

Pedido inicial para criar sessão

Solicitação

Resposta

Consulta status da sessão de criação de longa duração

Solicitação

Resposta

Adquirir informações de sessão

Solicitação

Resposta

Reduzir erros de limitação

cabeçalho Retry-After

Limitação e simultaneidade

Conteúdo relacionado

Comentários

Recursos adicionais