workbook：createSession

命名空间：microsoft.graph

创建新的工作簿会话。

可以在以下任一模式下调用 Excel API：

1. 永久会话 - 保持（保存）对工作簿所做的全部更改。这是常用的操作模式。
2. 非永久会话 - 不会将 API 所做的更改保存到源位置。相反，Excel 后端服务器保留文件的临时副本，体现在特定 API 会话期间所做的更改。Excel 会话过期时，这些更改将丢失。此模式可用于需要进行分析或获得计算结果或图表图像的应用，但不会影响文档状态。

若要表示 API 中的会话，请使用 workbook-session-id: {session-id} 标头。

注意： Excel API 不需要会话标头也能起作用。但是，建议你使用会话标头来提高性能。如果不使用会话标头，API 调用过程中进行的更改 仅 保持在该文件中。

在某些情况下，创建新会话需要不确定的时间才能完成。 Microsoft Graph 还提供长时间运行的操作模式。 此模式提供了一种轮询创建状态更新的方法，而无需等待创建完成。 步骤如下：

1. 标头 Prefer: respond-async 将添加到请求中，以指示这是长时间运行的操作。
2. 响应返回标头 Location 以指定轮询创建操作状态的 URL。 可以通过访问指定的 URL 获取操作状态。 状态将为以下项之一 notStarted running ：、、或 succeeded failed 。
3. 操作完成后，可以再次请求状态，响应将显示 或 succeeded failed 。

错误处理

此请求有时可能会收到 504 HTTP 错误。 此错误的适当响应做法是重复发出请求。

Permissions

要调用此 API，需要以下权限之一。要了解详细信息，包括如何选择权限的信息，请参阅权限。

权限类型	权限（从最低特权到最高特权）
委派（工作或学校帐户）	Files.ReadWrite
委派（个人 Microsoft 帐户）	不支持。
应用程序	不支持。

HTTP 请求

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

请求标头

名称	说明
Authorization	Bearer {token}。必需。

请求正文

在请求正文中，提供 workbookSessionInfo 对象的 JSON 表示形式。

响应

如果成功，此方法在响应正文中返回 响应代码和 201 Created workbookSessionInfo 对象。 对于长时间运行的操作，它将在响应中返回 响应代码和包含空正文 202 Accepted Location 的标头。

示例

示例 1：基本会话创建

请求

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();

有关如何将 SDK 添加 到项目并 创建 authProvider 实例的 详细信息，请参阅 SDK 文档。

JavaScript

const options = {
    authProvider,
};

const client = Client.init(options);

const workbookSessionInfo = {
  persistChanges: true
};

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

有关如何将 SDK 添加 到项目并 创建 authProvider 实例的 详细信息，请参阅 SDK 文档。

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

有关如何将 SDK 添加 到项目并 创建 authProvider 实例的 详细信息，请参阅 SDK 文档。

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();

有关如何将 SDK 添加 到项目并 创建 authProvider 实例的 详细信息，请参阅 SDK 文档。

响应

注意： 为了提高可读性，可能缩短了此处显示的响应对象。

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

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

示例 2：使用长时间运行的操作模式创建会话

请求

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
}

响应

注意： 为了提高可读性，可能缩短了此处显示的响应对象。

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