次の方法で共有


ブック: 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. 操作が完了したら、状態をもう一度要求すると、応答に または failedsucceeded表示されます。

この API は、次の国内クラウド展開で使用できます。

グローバル サービス 米国政府機関 L4 米国政府機関 L5 (DOD) 21Vianet が運営する中国

エラー処理

この要求に対して、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
}