ブック: createSession
名前空間: microsoft.graph
新しいブック セッションを作成します。
2 つのモードのいずれかで、Excel API を呼び出すことができます。
- 永続セッション - ブックに加えられたすべての変更は永続化 (保存) されます。 これは通常の操作モードです。
- 非永続セッション - API によって加えられた変更は元の場所に保存されません。 代わりに、その特定の API セッション中に加えられた変更を反映するファイルの一時コピーが Excel のバックエンド サーバーに保持されます。 Excel のセッションの有効期限が切れると、変更は失われます。 分析を行ったり、計算の結果やグラフのイメージを取得したりする必要があるものの、ドキュメントの状態には影響を与えないアプリには、このモードが便利です。
API でセッションを表すには、workbook-session-id: {session-id}
ヘッダーを使用します。
注: セッション ヘッダーは Excel API が機能するために必要ではありません。 しかし、パフォーマンスを向上させるためにセッション ヘッダーを使用することをお勧めします。 セッション ヘッダーを使用しない場合は、API の呼び出し時に行われた変更がファイルに永続化されます。
場合によっては、新しいセッションを作成するには、完了するまでに不確定な時間が必要です。 Microsoft Graph には、実行時間の長い操作パターンも用意されています。 このパターンでは、作成が完了するのを待たずに、作成状態の更新をポーリングする方法が提供されます。 次の手順を実行します。
Prefer: respond-async
ヘッダーが要求に追加され、実行時間の長い操作であることを示します。- 応答は、作成操作の状態を
Location
ポーリングするための URL を指定するヘッダーを返します。 指定した URL にアクセスすることで、操作の状態を取得できます。 状態は、、、running
succeeded
、またはfailed
のいずれかになりますnotStarted
。 - 操作が完了したら、状態をもう一度要求すると、応答に または
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: 実行時間の長い操作パターンを使用したセッションの作成
要求
POST https://graph.microsoft.com/v1.0/me/drive/items/{drive-item-id}/workbook/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
{
}
応答については、「操作の状態を 202 Accepted
取得してセッションの作成結果を取得する方法については、 完了に時間がかかる API の 操作」を参照してください。
例 2: 基本的なセッションの作成
要求
POST https://graph.microsoft.com/v1.0/me/drive/items/{id}/workbook/createSession
Content-type: application/json
{
"persistChanges": true
}
応答
注: ここに示す応答オブジェクトは、読みやすさのために短縮されている場合があります。
HTTP/1.1 201 Created
Content-type: application/json
{
"id": "id-value",
"persistChanges": true
}