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 ist für das Erstellen einer neuen Sitzung eine unbestimmte Zeit erforderlich. Microsoft Graph bietet auch ein lange ausgeführtes Betriebsmuster. Dieses Muster bietet eine Möglichkeit, Aktualisierungen des Erstellungsstatus abzufragen, ohne auf den Abschluss der Erstellung zu warten. Die folgenden Schritte sind ausgeführt:

1. Prefer: respond-asyncDer Anforderung wird ein Header hinzugefügt, um anzugeben, dass es sich um einen vorgang mit langer Ausführungsdauer handelt.
2. Die Antwort gibt einen Location Header zurück, um die URL zum Abrufen des Erstellungsvorgangsstatus anzugeben. Sie können den Vorgangsstatus abrufen, indem Sie auf die angegebene URL zugreifen. Der Status ist einer der folgenden: notStarted running , , oder succeeded failed .
3. Nach Abschluss des Vorgangs können Sie den Status erneut anfordern, und die Antwort wird entweder succeeded oder failed angezeigt.

Fehlerbehandlung

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

Berechtigungen

Eine der nachfolgenden Berechtigungen ist erforderlich, um diese API aufrufen zu können. Weitere Informationen, unter anderem zur Auswahl von Berechtigungen, finden Sie im Artikel zum Thema Berechtigungen.

Berechtigungstyp	Berechtigungen (von der Berechtigung mit den wenigsten Rechten zu der mit den meisten Rechten)
Delegiert (Geschäfts-, Schul- oder Unikonto)	Files.ReadWrite
Delegiert (persönliches Microsoft-Konto)	Nicht unterstützt
Anwendung	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.

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 vorgang mit langer Ausführungsdauer werden der 202 Accepted Antwortcode und ein Location Header mit einem leeren Textkörper in der Antwort zurückgegeben.

Beispiele

Beispiel 1: Grundlegende Sitzungserstellung

Anforderung

HTTP

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

{
  "persistChanges": true
}

C#

GraphServiceClient graphClient = new GraphServiceClient( authProvider );

var persistChanges = true;

await graphClient.Me.Drive.Items["{driveItem-id}"].Workbook
    .CreateSession(persistChanges)
    .Request()
    .PostAsync();

Ausführliche Informationen zum Hinzufügen des SDK zu Ihrem Projekt und zum Erstellen einer authProvider-Instanz finden Sie in der SDK-Dokumentation.

JavaScript

const options = {
    authProvider,
};

const client = Client.init(options);

const workbookSessionInfo = {
  persistChanges: true
};

await client.api('/me/drive/items/{id}/workbook/createSession')
    .post(workbookSessionInfo);

Ausführliche Informationen zum Hinzufügen des SDK zu Ihrem Projekt und zum Erstellen einer authProvider-Instanz finden Sie in der SDK-Dokumentation.

Objective-C

MSHTTPClient *httpClient = [MSClientFactory createHTTPClientWithAuthenticationProvider:authenticationProvider];

NSString *MSGraphBaseURL = @"https://graph.microsoft.com/v1.0/";
NSMutableURLRequest *urlRequest = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:[MSGraphBaseURL stringByAppendingString:@"/me/drive/items/{id}/workbook/createSession"]]];
[urlRequest setHTTPMethod:@"POST"];
[urlRequest setValue:@"application/json" forHTTPHeaderField:@"Content-Type"];

NSMutableDictionary *payloadDictionary = [[NSMutableDictionary alloc] init];

BOOL persistChanges = YES;
payloadDictionary[@"persistChanges"] = persistChanges;

NSData *data = [NSJSONSerialization dataWithJSONObject:payloadDictionary options:kNilOptions error:&error];
[urlRequest setHTTPBody:data];

MSURLSessionDataTask *meDataTask = [httpClient dataTaskWithRequest:urlRequest 
    completionHandler: ^(NSData *data, NSURLResponse *response, NSError *nserror) {

        //Request Completed

}];

[meDataTask execute];

Ausführliche Informationen zum Hinzufügen des SDK zu Ihrem Projekt und zum Erstellen einer authProvider-Instanz finden Sie in der SDK-Dokumentation.

Java

GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

Boolean persistChanges = true;

graphClient.me().drive().items("{id}").workbook()
    .createSession(WorkbookCreateSessionParameterSet
        .newBuilder()
        .withPersistChanges(persistChanges)
        .build())
    .buildRequest()
    .post();

Ausführliche Informationen zum Hinzufügen des SDK zu Ihrem Projekt und zum Erstellen einer authProvider-Instanz finden Sie in der SDK-Dokumentation.

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
}

Beispiel 2: Sitzungserstellung mit lange ausgeführtem Vorgangsmuster

Anforderung

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
}

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