Meilleures pratiques pour l’utilisation de l’API Excel dans Microsoft GraphBest practices for working with the Excel API in Microsoft Graph

Cet article fournit des recommandations pour utiliser les API Excel dans Microsoft Graph.This article provides recommendations for working with the Excel APIs in Microsoft Graph.

Gérer les sessions de la manière la plus efficaceManage sessions in the most efficient way

Si vous avez plusieurs appels à effectuer au cours d’une période donnée, nous vous recommandons de créer une session et de transmettre l’ID de session avec chaque requête.If you have more than one call to make within a certain period of time, we recommend that you create a session and pass the session ID with each request. Pour représenter la session de l’API, utilisez l’en-tête workbook-session-id: {session-id}.To represent the session in the API, use the workbook-session-id: {session-id} header. En procédant ainsi, vous pouvez utiliser les API Excel de la manière la plus efficace.By doing so, you can use the Excel APIs in the most efficient way.

L’exemple suivant montre comment ajouter un nouveau numéro à une table, puis Rechercher un enregistrement dans un classeur à l’aide de cette approche.The following example shows you how to add a new number to a table and then find one record in a workbook using this approach.

Étape 1 : créer une sessionStep 1: Create a session

DemandeRequest

POST https://graph.microsoft.com/v1.0/me/drive/items/{id}/workbook/createSession
Content-type: application/json
Content-length: 52

{
  "persistChanges": true
}

RéponseResponse

Voici une réponse réussie.The following is a successful response.

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

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

Étape 2 : ajouter une nouvelle ligne à la tableStep 2: Add a new row to the table

DemandeRequest

POST https://graph.microsoft.com/v1.0/me/drive/items/{id}/workbook/tables/Table1/rows/add
Content-type: application/json
workbook-session-id: {session-id}

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

RéponseResponse

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

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

Étape 3 : Rechercher une valeur dans la table mise à jourStep 3: Look up a value in the updated table

DemandeRequest

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
}

RéponseResponse

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

{
    "value": 5
}

Étape 4 : fermer la session une fois toutes les demandes terminéesStep 4: Close the session after all the requests are completed

DemandeRequest

POST https://graph.microsoft.com/v1.0/me/drive/items/{id}/workbook/closeSession
Content-type: application/json
workbook-session-id: {session-id}
Content-length: 0

{
}

RéponseResponse

HTTP/1.1 204 No Content

Pour plus d’informations, consultez la rubrique Create session et Close session.For more details, see Create session and Close session.

Utilisation des API qui prennent beaucoup de temps pour se terminerWorking with APIs that take a long time to complete

Vous pouvez remarquer que certaines opérations prennent une durée indéterminée. par exemple, l’ouverture d’un classeur de grande taille.You might notice that some operations take an indeterminate amount time to complete; for example, opening a large workbook. Il est facile d’atteindre un délai d’attente en attendant la réponse à ces demandes.It is easy to hit timeout while waiting for the response to these requests. Pour résoudre ce problème, nous fournissons le modèle d’opération longue durée.To resolve this issue, we provide the long-running operation pattern. Lorsque vous utilisez ce modèle, vous n’avez pas besoin de vous soucier du délai d’expiration de la demande.When you use this pattern, you don't need to worry about the timeout for the request.

Actuellement, l’API Excel de création de session dans Microsoft Graph a le modèle d’opération long activé.Currently, the session creation Excel API in Microsoft Graph has the long-running operation pattern enabled. Ce modèle implique les étapes suivantes :This pattern involves the following steps:

  1. Ajoutez un Prefer: respond-async en-tête à la demande pour indiquer qu’il s’agit d’une opération de longue durée lorsque vous importez une session.Add a Prefer: respond-async header to the request to indicate that it is a long-running operation when you crate a session.
  2. Une opération de longue durée renverra une 202 Accepted réponse avec un en-tête d’emplacement pour récupérer l’état de l’opération.A long-running operation will return a 202 Accepted response along with a Location header to retrieve the operation status. Si la création de la session se termine en quelques secondes, elle renverra une réponse de session de création normale au lieu d’utiliser le modèle d’opération de longue durée.If the session creation completes in several seconds, it will return a regular create session response instead of using the long-running operation pattern.
  3. Avec la 202 Accepted réponse, vous pouvez récupérer l’état de l’opération à l’emplacement spécifié.With the 202 Accepted response, you can retrieve the operation status at the specified location. Les valeurs d’état de l’opération incluent notStarted ,, running succeeded et failed .Operation status values include notStarted, running, succeeded, and failed.
  4. Une fois l’opération terminée, vous pouvez obtenir le résultat de la création de la session via l’URL spécifiée dans la réponse réussie.After the operation completes, you can get the session creation result through the specified URL in the succeeded response.

L’exemple suivant crée une session à l’aide du modèle d’opération de longue durée.The following example creates a session using the long-running operation pattern.

Demande initiale de création d’une sessionInitial request to create session

DemandeRequest

POST https://graph.microsoft.com/v1.0/me/drive/items/{drive-item-id}/workbook/worksheets({id})/createSession
Prefer: respond-async
Content-type: application/json
{
    "persistChanges": true
}

RéponseResponse

Le modèle d’opération de longue durée renverra une 202 Accepted réponse similaire à ce qui suit.The long-running operation pattern will return a 202 Accepted response similar to the following.

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

{
}

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 revient en tant que session de création normale et la demande réussie renvoie une 201 Created réponse.In some cases, if the creation succeeds within seconds, it won't enter the long-running operation pattern; instead, it returns as a regular create session and the successful request will return a 201 Created response.

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

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

L’exemple suivant montre la réponse en cas d’échec de la demande.The following example shows the response when the request fails.

Remarque : l’objet de réponse affiché ci-après peut être raccourci pour plus de lisibilité.Note: The response object shown here might be shortened for readability.

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

État d’interrogation de la session de création de longue duréePoll status of the long-running create session

Avec le modèle d’opération de longue durée, vous pouvez obtenir l’état de création à l’emplacement spécifié à l’aide de la requête suivante.With the long-running operation pattern, you can get the creation status at specified location by using the following request. L’État suggéré pour l’interrogation est d’environ 30 secondes.The suggested interval to poll status is around 30 seconds. L’intervalle maximal ne doit pas dépasser 4 minutes.The maximum interval should be no more than 4 minutes.

DemandeRequest

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

RéponseResponse

Voici la réponse lorsque l’état de l’opération est running .The following is the response when the operation has a status of running.

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

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

Voici la réponse lorsque l’état de l’opération est succeeded .The following is the response when the operation status is 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}')
}

Voici la réponse lorsque l’état de l’opération est failed .The following is the response when the operation status is 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."
      }
    }
  }
}

Pour plus d’informations sur les erreurs, consultez la rubrique codes d’erreurFor more details about errors, see Error codes

Obtenir des informations sur les sessionsAcquire session information

DemandeRequest

Avec l’état succeeded , vous pouvez obtenir les informations de session créées à l’aide d' resourceLocation une demande semblable à la suivante.With a status of succeeded, you can get the created session information through resourceLocation with a request similar to the following.

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

RéponseResponse

Voici la réponse.The following is the response.

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

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

Remarque : Les informations de session d’acquisition dépendent de la demande initiale.Note: Acquire session information depends on the initial request. Vous n’avez pas besoin d’acquérir le résultat si la demande initiale ne renvoie pas de corps de réponse.You don't need to acquire the result if the initial request doesn't return a response body.