Partager via

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.

É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 à la table

Demande

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

Réponse

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

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

Étape 3 : Rechercher une valeur dans la table mise à 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, consultez Créer une session et Fermer la session.

Utiliser des API qui prennent beaucoup de temps

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 :

  1. 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.
  2. 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.
  3. 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.
  4. 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.

Demande initiale de création d’une session

Demande

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

Réponse

Le modèle d’opération de longue durée retourne une 202 Accepted réponse similaire à ce qui suit.

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 retourne en tant que session de création normale et la demande réussie retourne 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."
      }
    }
  }
}

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.

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

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

Voici la réponse lorsque l’opération status 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’opération status 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, consultez Codes d’erreur et messages.

Acquérir des informations de session

Demande

Avec un status de succeeded, vous pouvez obtenir les informations de session créées via resourceLocation avec une requête similaire à ce qui suit.

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

Contenu connexe