ブック: 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 にアクセスすることで、操作の状態を取得できます。 状態は、、、runningsucceeded、または failedのいずれかになりますnotStarted。
3. 操作が完了したら、状態をもう一度要求すると、応答に または failedがsucceeded表示されます。

エラー処理

この要求に対して、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 オブジェクトを返します。 実行時間の長い操作では、応答コードと、応答に空の本文をLocation持つヘッダーが返202 Accepted されます。

例

例 1: 実行時間の長い操作パターンを使用したセッションの作成

要求

HTTP

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

{
    "persistChanges": true
}

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

const workbookSessionInfo = {
    persistChanges: true
};

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

SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。

Java

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

LinkedList<Option> requestOptions = new LinkedList<Option>();
requestOptions.add(new HeaderOption("Prefer", "respond-async"));

Boolean persistChanges = true;

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

SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。

応答

注: ここに示す応答オブジェクトは、読みやすさのために短縮されている場合があります。

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

{
}

応答については、「操作の状態を 202 Accepted 取得してセッションの作成結果を取得する方法については、 完了に時間がかかる API の 操作」を参照してください。

例 2: 基本的なセッションの作成

要求

HTTP

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

{
  "persistChanges": true
}

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 のドキュメントを参照してください。

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
}