Meilleures pratiques pour travailler avec l’API Excel dans Microsoft Graph

Cet article fournit des recommandations pour l’Excel api de microsoft Graph.

Gérer les sessions de la manière la plus efficace

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 demande. Pour représenter la session de l’API, utilisez l’en-tête workbook-session-id: {session-id}. Ainsi, vous pouvez utiliser les API Excel de manière la plus efficace.

L’exemple suivant montre comment ajouter un nouveau numéro à une table, puis trouver un enregistrement dans un workbook à l’aide de cette approche.

Étape 1 : Créer une session

Demande

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

{
  "persistChanges": true
}

Réponse

Voici une réponse réussie.

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

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

Étape 2 : Ajouter une nouvelle ligne au tableau

Demande

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éponse

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

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

Étape 3 : Rechercher une valeur dans le tableau mis à jour

Demande

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éponse

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

{
    "value": 5
}

Étape 4 : Fermer la session une fois toutes les demandes terminées

Demande

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

{
}

Réponse

HTTP/1.1 204 No Content

Pour plus d’informations, voir Créer une session et Fermer une session.

Travailler avec des API qui prennent beaucoup de temps

Vous remarquerez peut-être que certaines opérations prennent un temps indéterminé . par exemple, l’ouverture d’un grand workbook. Il est facile d’atteindre le délai d’attente 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 besoin de vous soucier du délai d’accès à la demande.

Actuellement, le modèle d’Excel de création de session dans Microsoft Graph le modèle d’opération de longue durée est activé. Ce modèle implique les étapes suivantes :

  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 lors de la gestion d’une session.
  2. Une opération de longue durée retourne une réponse 202 Accepted avec un en-tête Location pour récupérer l’état de l’opération. Si la création de session se termine en quelques secondes, elle retourne une réponse de création de session normale au lieu d’utiliser le modèle d’opération de longue durée.
  3. Avec la réponse 202 Accepted , vous pouvez récupérer l’état de l’opération à l’emplacement spécifié. Les valeurs d’état d’opération notStartedincluent , runninget succeeded``failed.
  4. Une fois l’opération terminée, vous pouvez obtenir le résultat de 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.

Demande initiale de création d’une session

Demande

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éponse

Le modèle d’opération de longue durée retourne une réponse 202 Accepted semblable à la suivante.

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 renvoie en tant que session de création normale et la demande réussie renvoie une 201 Created réponse.

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

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

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

État du sondage de la session de création de longue durée

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. L’intervalle suggéré pour l’interrogation de l’état 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 l’état 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.

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.

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, voir Codes d’erreur.

Acquérir des informations de session

Demande

Avec l’état succeeded« , vous pouvez obtenir les informations de session resourceLocation créées par le biais d’une demande semblable à la suivante.

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

Réponse

Voici la réponse.

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

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

Remarque : L’acquisition des informations de session dépend de la demande initiale. Vous n’avez pas besoin d’obtenir le résultat si la demande initiale ne retourne pas de corps de réponse.

Limitation

Excel API microsoft Graph l’utilisation des ressources de plusieurs services de dépendance. L’impact peut varier entre les différentes demandes : par exemple, vous pouvez vous attendre à ce que la mise à jour d’une chaîne courte dans une cellule unique d’un petit workbook consomme moins de ressources que l’ajout d’un tableau de grande taille avec des formules complexes à un grand workbook. Même avec la même API, les paramètres et les workbooks cibles peuvent introduire des différences significatives. Par conséquent, Excel limitation des API 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.

Retry-After-tête

Dans de nombreux cas, une réponse de limitation inclut un en-tête Retry-After . Respecter la valeur de l’en-tête et retarder des demandes similaires aiderait le client à récupérer à partir de la limitation. Pour plus d’informations sur la gestion des réponses d’erreur provenant Excel API de Microsoft Graph, voir Gestion des erreurs pour les API Excel dans Microsoft Graph.

Limitation et concurrence

Un autre facteur lié à la limitation est la concurrence des demandes. Nous vous déconseillons d’augmenter la concurrence lors de l’utilisation d’API Excel (par exemple, paralléliser les demandes vers le même workbook), en particulier pour les demandes d’écriture. Au lieu de cela, sauf s’il existe un problème spécifique, comme une surcharge réseau importante par rapport au temps d’exécution des demandes très court, nous recommandons une utilisation séquentielle dans le cas le plus courant : pour chaque workbook, envoyez uniquement la demande suivante après réception d’une réponse réussie à la demande actuelle.

Les demandes d’écriture simultanées dans le même workbook ne s’exécutent généralement pas en parallèle (bien que dans certains cas, elles le font) ; Elles sont souvent la cause de la limitation, du délai d’attente (lorsque les demandes sont en file d’attente sur les serveurs), du 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’état d’autres demandes en attente, ce qui complique la recherche ou la récupération de l’état du workbook.