workbook: createSession

Namespace: microsoft.graph

Erstellen Sie eine neue Arbeitsmappensitzung.

Excel-APIs können in einem der beiden folgenden Modi aufgerufen werden:

  1. Beständige Sitzung: Alle an der Arbeitsmappe vorgenommenen Änderungen werden gespeichert. Dies ist die übliche Vorgehensweise.
  2. Nicht beständige Sitzung: Die von der API vorgenommenen Änderungen werden nicht am Quellspeicherort gespeichert. Stattdessen behält der Excel-Back-End-Server eine temporäre Kopie der Datei bei, welche die während dieser API-Sitzung vorgenommenen Änderungen enthält. Wenn die Excel-Sitzung abläuft, gehen die Änderungen verloren. Dieser Modus eignet sich für Apps, die Analysen durchführen oder die Ergebnisse einer Berechnung oder eines Diagrammbilds abrufen, aber nicht den Dokumentstatus betreffen.

Um die Sitzung in der API darzustellen, verwenden Sie den workbook-session-id: {session-id}-Header.

Hinweis: Der Sitzungsheader ist für das Funktionieren einer Excel-API nicht erforderlich. Die Verwendung des Sitzungsheaders wird jedoch empfohlen, um die Leistung zu verbessern. Wenn Sie keinen Sitzungsheader verwenden, werden die während des API-Aufrufs vorgenommenen Änderungen in der Datei gespeichert.

In einigen Fällen erfordert das Erstellen einer neuen Sitzung unbestimmte Zeit. Microsoft Graph bietet auch ein Zeitintensives Vorgangsmuster. Dieses Muster bietet eine Möglichkeit, die Erstellung status Updates abzufragen, ohne auf den Abschluss der Erstellung zu warten. Im Folgenden sind die Schritte aufgeführt:

  1. Der Prefer: respond-async Anforderung wird ein Header hinzugefügt, um anzugeben, dass es sich um einen Zeitintensiven Vorgang handelt.
  2. Die Antwort gibt einen Location Header zurück, um die URL zum Abrufen des Erstellungsvorgangs status anzugeben. Sie können den Vorgang status abrufen, indem Sie auf die angegebene URL zugreifen. Die status ist eine der folgenden: notStarted, running, succeededoder failed.
  3. Nach Abschluss des Vorgangs können Sie den status erneut anfordern, und die Antwort zeigt entweder succeeded oder failedan.

Diese API ist in den folgenden nationalen Cloudbereitstellungen verfügbar.

Globaler Dienst US Government L4 US Government L5 (DOD) China, betrieben von 21Vianet

Fehlerbehandlung

Bei dieser Anforderung tritt gelegentlich der 504 HTTP-Fehler auf. Sollte dieser Fehler auftreten, wiederholen Sie die Anforderung.

Berechtigungen

Wählen Sie für diese API die Als am wenigsten privilegierten Berechtigungen gekennzeichneten Berechtigungen aus. Verwenden Sie nur dann eine Berechtigung mit höheren Berechtigungen , wenn dies für Ihre App erforderlich ist. Ausführliche Informationen zu delegierten Berechtigungen und Anwendungsberechtigungen finden Sie unter Berechtigungstypen. Weitere Informationen zu diesen Berechtigungen finden Sie in der Berechtigungsreferenz.

Berechtigungstyp Berechtigungen mit den geringsten Berechtigungen Berechtigungen mit höheren Berechtigungen
Delegiert (Geschäfts-, Schul- oder Unikonto) Files.ReadWrite Nicht verfügbar.
Delegiert (persönliches Microsoft-Konto) Nicht unterstützt Nicht unterstützt
Anwendung Nicht unterstützt Nicht unterstützt

HTTP-Anforderung

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

Anforderungsheader

Name Beschreibung
Authorization Bearer {token}. Erforderlich. Erfahren Sie mehr über die Authentifizierung und Autorisierung.

Anforderungstext

Geben Sie im Anforderungstext eine JSON-Darstellung des workbookSessionInfo-Objekts an.

Antwort

Bei erfolgreicher Ausführung gibt die Methode den 201 Created Antwortcode und ein workbookSessionInfo-Objekt im Antworttext zurück. Bei einem zeitintensiven Vorgang werden der 202 Accepted Antwortcode und ein Location Header mit einem leeren Text in der Antwort zurückgegeben.

Beispiele

Beispiel 1: Sitzungserstellung mit zeitintensivem Vorgangsmuster

Anforderung

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

{
    "persistChanges": true
}

Antwort

Hinweis: Das hier gezeigte Antwortobjekt kann zur besseren Lesbarkeit gekürzt werden.

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

{
}

Informationen zum Abrufen des Vorgangs 202 Accepted status und zum Abrufen des Sitzungserstellungsergebnisses finden Sie in der Antwort unter Arbeiten mit APIs, die lange dauern.

Beispiel 2: Grundlegende Sitzungserstellung

Anforderung

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

{
  "persistChanges": true
}

Antwort

Hinweis: Das hier gezeigte Antwortobjekt kann zur besseren Lesbarkeit gekürzt werden.

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

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