Partager via


workbook : createSession

Espace de noms: microsoft.graph

Créez une session de classeur.

Les API Excel peuvent être appelées dans l’un des deux modes :

  1. Session permanente : toutes les modifications apportées au classeur sont conservées (enregistrées). Il s’agit du mode de fonctionnement normal.
  2. Session non permanente : les modifications apportées par l’API ne sont pas enregistrées à l’emplacement source. À la place, le serveur principal Excel conserve une copie temporaire du fichier qui reflète les modifications apportées au cours de cette session API. Les modifications sont perdues à l’expiration de la session Excel. Ce mode est utile pour les applications qui doivent effectuer une analyse ou obtenir les résultats d’un calcul ou l’image d’un graphique, sans affecter l’état du document.

Pour représenter la session de l’API, utilisez l’en-tête workbook-session-id: {session-id}.

Remarque : l’en-tête de la session n’est pas nécessaire pour faire fonctionner une API Excel. Toutefois, nous vous recommandons d’utiliser l’en-tête de session pour obtenir de meilleures performances. Si vous n’utilisez pas un en-tête de session, les modifications apportées pendant l’appel de l’API sont conservées dans le fichier.

Dans certains cas, la création d’une session nécessite une durée indéterminée. Microsoft Graph fournit également un modèle d’opérations de longue durée. Ce modèle permet d’interroger la création status mises à jour, sans attendre la fin de la création. Les étapes suivantes sont les suivantes :

  1. Un Prefer: respond-async en-tête est ajouté à la requête pour indiquer qu’il s’agit d’une opération de longue durée.
  2. La réponse retourne un Location en-tête pour spécifier l’URL d’interrogation de l’opération de création status. Vous pouvez obtenir l’opération status en accédant à l’URL spécifiée. Le status sera l’un des suivants : notStarted, running, succeededou failed.
  3. Une fois l’opération terminée, vous pouvez demander à nouveau le status et la réponse s’affiche succeededfailedou .

Cette API est disponible dans les déploiements de cloud national suivants.

Service global Gouvernement des États-Unis L4 Us Government L5 (DOD) Chine gérée par 21Vianet

Gestion des erreurs

Cette demande peut parfois générer une erreur HTTP 504. Pour la corriger, il suffit de répéter la demande.

Autorisations

Choisissez l’autorisation ou les autorisations marquées comme moins privilégiées pour cette API. Utilisez une autorisation ou des autorisations privilégiées plus élevées uniquement si votre application en a besoin. Pour plus d’informations sur les autorisations déléguées et d’application, consultez Types d’autorisations. Pour en savoir plus sur ces autorisations, consultez les informations de référence sur les autorisations.

Type d’autorisation Autorisations avec privilèges minimum Autorisations privilégiées plus élevées
Déléguée (compte professionnel ou scolaire) Files.ReadWrite Non disponible.
Déléguée (compte Microsoft personnel) Non prise en charge. Non prise en charge.
Application Non prise en charge. Non prise en charge.

Requête HTTP

POST /me/drive/items/{id}/workbook/createSession
POST /me/drive/root:/{item-path}:/workbook/createSession

En-têtes de demande

Nom Description
Autorisation Porteur {token}. Obligatoire. En savoir plus sur l’authentification et l’autorisation.

Corps de la demande

Dans le corps de la demande, fournissez une représentation JSON de l’objet workbookSessionInfo .

Réponse

Si elle réussit, cette méthode renvoie un 201 Created code de réponse et un objet workbookSessionInfo dans le corps de la réponse. Pour une opération de longue durée, elle retourne un 202 Accepted code de réponse et un Location en-tête avec un corps vide dans la réponse.

Exemples

Exemple 1 : Création de session avec modèle d’opération de longue durée

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

Remarque : l’objet de réponse affiché ci-après peut être raccourci pour plus de lisibilité.

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

{
}

Avec la 202 Accepted réponse, consultez Utiliser des API qui prennent beaucoup de temps pour savoir comment récupérer l’opération status et obtenir le résultat de la création de session.

Exemple 2 : création de session de base

Demande

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

{
  "persistChanges": true
}

Réponse

Remarque : l’objet de réponse affiché ci-après peut être raccourci pour plus de lisibilité.

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

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