Bonnes pratiques pour l’utilisation de l’API Excel
Article
Cet article fournit des recommandations pour l’utilisation des API Excel dans Microsoft Graph.
Gérer les sessions de la manière la plus efficace
Si vous avez plusieurs appels à effectuer dans un délai donné, nous vous recommandons de créer une session et de passer l’ID de session avec chaque demande. Pour représenter la session de l’API, utilisez l’en-tête workbook-session-id: {session-id}. Ce faisant, vous pouvez utiliser les API Excel de la manière la plus efficace possible.
L’exemple suivant montre comment ajouter un nouveau nombre à une table, puis rechercher un enregistrement dans un classeur à l’aide de cette approche.
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);
<?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 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 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}");
});
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.DriveItemItemItemWorkbookCloseSessionRequestBuilderPostRequestConfiguration{
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}");
});
Vous remarquerez peut-être que certaines opérations prennent une durée indéterminée . par exemple, l’ouverture d’un classeur volumineux. Il est facile d’atteindre le délai d’expiration en attendant la réponse à ces demandes. Pour résoudre ce problème, nous fournissons le modèle d’opération de longue durée. Lorsque vous utilisez ce modèle, vous n’avez pas à vous soucier du délai d’expiration de la requête.
Actuellement, le modèle d’opération de longue durée est activé pour l’API Excel de création de session dans Microsoft Graph. Ce modèle implique les étapes suivantes :
Ajoutez un Prefer: respond-async en-tête à la requête pour indiquer qu’il s’agit d’une opération de longue durée lorsque vous créez une session.
Une opération de longue durée retourne une 202 Accepted réponse avec un en-tête Location pour récupérer l’opération status. Si la création de la session se termine en quelques secondes, elle retourne une réponse de session de création normale au lieu d’utiliser le modèle d’opération de longue durée.
Avec la 202 Accepted réponse, vous pouvez récupérer l’opération status à l’emplacement spécifié. Les valeurs status d’opération incluent notStarted, running, succeededet failed.
Une fois l’opération terminée, vous pouvez obtenir le résultat de la création de session via l’URL spécifiée dans la réponse réussie.
L’exemple suivant crée une session à l’aide du modèle d’opération de longue durée.
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.DriveItemItemItemWorkbookCreateSessionRequestBuilderPostRequestConfiguration{
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");
});
Dans certains cas, si la création réussit en quelques secondes, elle n’entre pas dans le modèle d’opération de longue durée . au lieu de cela, il retourne en tant que session de création normale et la demande réussie retourne une 201 Created réponse.
L’exemple suivant montre la réponse en cas d’échec de la demande.
Remarque : l’objet de réponse affiché ci-après peut être raccourci pour plus de lisibilité.
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."
}
}
}
}
Interroger status de la session de création de longue durée
Avec le modèle d’opération de longue durée, vous pouvez obtenir la status de création à l’emplacement spécifié à l’aide de la requête suivante. L’intervalle suggéré pour interroger status est d’environ 30 secondes. L’intervalle maximal ne doit pas être supérieur à 4 minutes.
Demande
GET https://graph.microsoft.com/v1.0/me/drive/items/{drive-item-id}/workbook/operations/{operation-id}
{
}
Réponse
Voici la réponse lorsque l’opération a une status de running.
L’acquisition d’informations de session dépend de la demande initiale. Vous n’avez pas besoin d’acquérir le résultat si la demande initiale ne retourne pas de corps de réponse.
Réduire les erreurs de limitation
Les API Excel dans Microsoft Graph affectent l’utilisation des ressources de plusieurs services de dépendance. L’impact peut varier selon les demandes : par exemple, vous pouvez vous attendre à ce que la mise à jour d’une chaîne courte dans une seule cellule d’un petit classeur consomme moins de ressources que l’ajout d’une grande table avec des formules complexes à un classeur volumineux.
Même avec la même API, les paramètres et les classeurs cibles peuvent introduire des différences significatives. Par conséquent, la limitation de l’API Excel n’est pas définie avec des nombres limites simples et universels, car elles entraîneraient des limites plus restrictives. Les meilleures pratiques suivantes vous aideront à effectuer des tâches plus rapidement avec moins d’erreurs de limitation.
en-tête Retry-After
Dans de nombreux cas, une réponse de limitation inclut un Retry-After en-tête. Le respect de la valeur de l’en-tête et le retard des demandes similaires aideraient le client à récupérer après la limitation. Pour plus d’informations sur la gestion des réponses aux erreurs des API Excel dans Microsoft Graph, consultez Gestion des erreurs pour les API Excel dans Microsoft Graph.
Limitation et concurrence
Un autre facteur lié à la limitation est l’accès concurrentiel des demandes. Nous vous déconseillons d’augmenter l’accès concurrentiel lors de l’utilisation des API Excel (par exemple, la parallélisation des requêtes dans le même classeur), en particulier pour les demandes d’écriture. Au lieu de cela, à moins qu’il n’y ait un problème spécifique, comme une surcharge réseau importante par rapport à un temps d’exécution très court des requêtes, nous recommandons une utilisation séquentielle dans le cas le plus courant : pour chaque classeur, n’envoyer la requête suivante qu’après avoir reçu une réponse réussie à la requête actuelle.
Les demandes d’écriture simultanées dans le même classeur ne s’exécutent généralement pas en parallèle (même si, dans certains cas, elles le font) ; Au lieu de cela, elles sont souvent à l’origine de la limitation, du délai d’expiration (lorsque les demandes sont mises en file d’attente sur des serveurs), des conflit de fusion (lorsque des sessions simultanées sont impliquées) et d’autres types d’échecs. Ils compliquent également la gestion des erreurs ; Par exemple, lorsque vous recevez une réponse d’échec, il n’existe aucun moyen de confirmer l’status d’autres demandes en attente, ce qui rend difficile la détermination ou la récupération de l’état du classeur.