ブック: createSession

名前空間: microsoft.graph

新しいブック セッションを作成します。

2 つのモードのいずれかで、Excel API を呼び出すことができます。

1. 永続セッション - ブックに加えられたすべての変更は永続化 (保存) されます。これは通常の操作モードです。
2. 非永続セッション - API によって加えられた変更は元の場所に保存されません。代わりに、その特定の API セッション中に加えられた変更を反映するファイルの一時コピーが Excel のバックエンド サーバーに保持されます。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 エラーが表示されることがあります。 このエラーに対する適切な対応は、要求を繰り返すことです。

アクセス許可

この API を呼び出すには、次のいずれかのアクセス許可が必要です。アクセス許可の選択方法などの詳細については、「アクセス許可」を参照してください。

アクセス許可の種類	アクセス許可 (特権の小さいものから大きいものへ)
委任 (職場または学校のアカウント)	Files.ReadWrite
委任 (個人用 Microsoft アカウント)	サポートされていません。
アプリケーション	サポートされていません。

HTTP 要求

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

要求ヘッダー

名前	説明
Authorization	ベアラー {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
{
}