Práticas recomendadas para trabalhar com a API do Excel

Artigo
02/14/2024

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

Gerenciar sessões da maneira mais eficiente

Se você tiver mais de uma chamada para fazer dentro de um determinado período de tempo, recomendamos que você crie uma sessão e passe a ID da sessão a cada solicitação. Para representar a sessão na API, use o cabeçalho workbook-session-id: {session-id}. Ao fazer isso, você pode usar as APIs do Excel da maneira mais eficiente.

O exemplo a seguir mostra como adicionar um novo número a uma tabela e, em seguida, encontrar um registro em uma pasta de trabalho usando essa abordagem.

Etapa 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://video2.skills-academy.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);



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 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://video2.skills-academy.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://video2.skills-academy.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

A seguir está uma resposta bem-sucedida.

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

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

Etapa 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



mgc drives items workbook tables rows add post --drive-id {drive-id} --drive-item-id {driveItem-id} --workbook-table-id {workbookTable-id} --body '{\
  "values": [[“east”, “pear”, 4]]\
}\
'

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

Etapa 3: procure 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://video2.skills-academy.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}");
});



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 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.DriveItemItemItemWorkbookFunctionsVlookupRequestBuilderPostRequestConfiguration{
	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://video2.skills-academy.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://video2.skills-academy.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
}

Etapa 4: fechar a sessão depois que todas as solicitações forem concluídas

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://video2.skills-academy.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}");
});



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 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.DriveItemItemItemWorkbookCloseSessionRequestBuilderPostRequestConfiguration{
	Headers: headers,
}
requestBody := graphdrives.NewCloseSessionPostRequestBody()

// To initialize your graphClient, see https://video2.skills-academy.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://video2.skills-academy.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, confira Criar sessão e Fechar sessão.

Trabalhar com APIs que levam muito tempo para serem concluídas

Você pode notar que algumas operações levam um tempo indeterminado para serem concluídas; por exemplo, abrindo uma pasta de trabalho grande. É fácil atingir o tempo limite enquanto aguarda a resposta a essas solicitações. Para resolve esse problema, fornecemos o padrão de operação de execução longa. Quando você usa esse padrão, não precisa se preocupar com o tempo limite para a solicitação.

Atualmente, a API do Excel de criação de sessão no Microsoft Graph tem o padrão de operação de execução longa habilitado. Esse padrão envolve as seguintes etapas:

Adicione um Prefer: respond-async cabeçalho à solicitação para indicar que é uma operação de longa execução ao criar uma sessão.
Uma operação de longa execução retorna uma 202 Accepted resposta juntamente com um cabeçalho Local para recuperar a operação status. Se a criação da sessão for concluída em vários segundos, ela retornará uma resposta de sessão de criação regular em vez de usar o padrão de operação de execução longa.
Com a 202 Accepted resposta, você pode recuperar a operação status no local especificado. Os valores da operação status incluem notStarted, running, succeedede failed.
Após a conclusão da operação, você poderá obter o resultado da criação da sessão por meio da URL especificada na resposta bem-sucedida.

O exemplo a seguir cria uma sessão usando o padrão de operação de execução longa.

Solicitação 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://video2.skills-academy.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");
});



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 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.DriveItemItemItemWorkbookCreateSessionRequestBuilderPostRequestConfiguration{
	Headers: headers,
}
requestBody := graphdrives.NewCreateSessionPostRequestBody()
persistChanges := true
requestBody.SetPersistChanges(&persistChanges) 

// To initialize your graphClient, see https://video2.skills-academy.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://video2.skills-academy.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 longa retorna 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, ela não entrará no padrão de operação de execução longa; Em vez disso, ele retorna como uma sessão de criação regular e a solicitação bem-sucedida retornará uma 201 Created resposta.

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

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

O exemplo a seguir mostra a resposta quando a solicitação 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."
      }
    }
  }
}

Status de pesquisa da sessão de criação de longa duração

Com o padrão de operação de execução longa, você pode obter o status de criação no local especificado usando a solicitação a seguir. O intervalo sugerido para sondar 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

A seguir está a resposta quando a operação tem um status de running.

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

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

A seguir está 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}')
}

A seguir está 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, consulte Códigos de erro e mensagens.

Adquirir informações da sessão

Solicitação

Com um status de succeeded, você pode obter as informações de sessão criadas por meio resourceLocation de uma solicitação semelhante à 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

A aquisição de informações de sessão depende da solicitação inicial. Você não precisará adquirir o resultado se a solicitação inicial não retornar um corpo de resposta.

Reduzir erros de limitação

As APIs do Excel no Microsoft Graph afetam o uso de recursos de vários serviços de dependência. O impacto pode variar entre solicitações diferentes: por exemplo, você pode esperar que atualizar uma cadeia de caracteres curta em uma única célula de uma pasta de trabalho pequena consumiria menos recursos do que adicionar uma grande tabela com fórmulas complexas a uma pasta de trabalho grande.

Mesmo com a mesma API, parâmetros e pastas de trabalho de destino podem introduzir diferenças significativas. Portanto, 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 práticas recomendadas a seguir ajudarão você 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 solicitações semelhantes ajudaria o cliente a se recuperar da limitação. Para obter detalhes sobre como lidar com respostas de erro de APIs do Excel no Microsoft Graph, confira Tratamento de erros para APIs do Excel no Microsoft Graph.

Limitação e simultaneidade

Outro fator relacionado à limitação é a simultaneidade da solicitação. Não recomendamos aumentar a simultaneidade ao usar APIs do Excel (por exemplo, paralelizando as solicitações com a mesma pasta de trabalho), especialmente para solicitações de gravação. Em vez disso, a menos que haja uma preocupação específica, como uma sobrecarga de rede significativa em comparação com o tempo de execução da solicitação muito curto, recomendamos o uso sequencial no caso mais comum: para cada pasta de trabalho, envie apenas a próxima solicitação após receber uma resposta bem-sucedida à solicitação atual.

As solicitações de gravação simultâneas para a mesma pasta de trabalho geralmente não são executadas em paralelo (embora, em alguns casos, elas o façam); em vez disso, geralmente são a causa da limitação, tempo limite (quando as solicitações são enfileiradas em servidores), conflito de mesclagem (quando sessões simultâneas estão envolvidas) e outros tipos de falhas. Eles também complicam o tratamento de erros; por exemplo, quando você recebe uma resposta de falha, não há como confirmar o status de outras solicitações pendentes, o que dificulta a determinação ou recuperação do estado da pasta de trabalho.

Usar a API REST do Excel

Compartilhar via

Práticas recomendadas para trabalhar com a API do Excel

Gerenciar sessões da maneira mais eficiente

Etapa 1: criar uma sessão

Solicitação

Resposta

Etapa 2: Adicionar uma nova linha à tabela

Solicitação

Resposta

Etapa 3: procure um valor na tabela atualizada

Solicitação

Resposta

Etapa 4: fechar a sessão depois que todas as solicitações forem concluídas

Solicitação

Resposta

Trabalhar com APIs que levam muito tempo para serem concluídas

Solicitação inicial para criar sessão

Solicitação

Resposta

Status de pesquisa da sessão de criação de longa duração

Solicitação

Resposta

Adquirir informações da sessão

Solicitação

Resposta

Reduzir erros de limitação

cabeçalho Retry-After

Limitação e simultaneidade

Comentários

Recursos adicionais

Compartilhar via

Práticas recomendadas para trabalhar com a API do Excel

Gerenciar sessões da maneira mais eficiente

Etapa 1: criar uma sessão

Solicitação

Resposta

Etapa 2: Adicionar uma nova linha à tabela

Solicitação

Resposta

Etapa 3: procure um valor na tabela atualizada

Solicitação

Resposta

Etapa 4: fechar a sessão depois que todas as solicitações forem concluídas

Solicitação

Resposta

Trabalhar com APIs que levam muito tempo para serem concluídas

Solicitação inicial para criar sessão

Solicitação

Resposta

Status de pesquisa da sessão de criação de longa duração

Solicitação

Resposta

Adquirir informações da 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