Microsoft Graph で Excel API を操作するためのベストプラクティスBest practices for working with the Excel API in Microsoft Graph

この記事では、Microsoft Graph での Excel Api の使用に関する推奨事項について説明します。This article provides recommendations for working with the Excel APIs in Microsoft Graph.

最も効率的な方法でセッションを管理するManage sessions in the most efficient way

一定の期間内に複数の通話を行う場合は、セッションを作成して、要求ごとにセッション ID を渡すことをお勧めします。If you have more than one call to make within a certain period of time, we recommend that you create a session and pass the session ID with each request. API でセッションを表すには、workbook-session-id: {session-id} ヘッダーを使用します。To represent the session in the API, use the workbook-session-id: {session-id} header. これにより、Excel Api を最も効率的な方法で使用できます。By doing so, you can use the Excel APIs in the most efficient way.

次の例は、新しい番号をテーブルに追加し、この方法を使用してブック内のレコードを検索する方法を示しています。The following example shows you how to add a new number to a table and then find one record in a workbook using this approach.

手順 1: セッションを作成するStep 1: Create a session

要求Request

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

{
  "persistChanges": true
}

応答Response

正常な応答を次に示します。The following is a successful response.

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

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

手順 2: テーブルに新しい行を追加するStep 2: Add a new row to the table

要求Request

POST https://graph.microsoft.com/v1.0/me/drive/items/{id}/workbook/tables/Table1/rows/add
Content-type: application/json
workbook-session-id: {session-id}

{
  "values": [[“east”, “pear”, 4]]
}

応答Response

HTTP/1.1 200 OK
Content-type: application/json
Content-length: 42

{
  "index": 6,
  "values": [[“east”, “pear”, 4]]
}

手順 3: 更新されたテーブルの値を参照するStep 3: Look up a value in the updated table

要求Request

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

{
    "lookupValue":"pear",
    "tableArray":{"Address":"Sheet1!B2:C7"},
    "colIndexNum":2,
    "rangeLookup":false
}

応答Response

HTTP code: 200 OK
content-type: application/json

{
    "value": 5
}

手順 4: すべての要求が完了した後にセッションを閉じるStep 4: Close the session after all the requests are completed

要求Request

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

{
}

応答Response

HTTP/1.1 204 No Content

詳細については、「 セッションを作成 し、 セッションを閉じる」を参照してください。For more details, see Create session and Close session.

完了までに時間がかかる Api を使用するWorking with APIs that take a long time to complete

一部の操作は、完了するまでに中間時間がかかる場合があることがわかります。たとえば、大きなブックを開くとします。You might notice that some operations take an indeterminate amount time to complete; for example, opening a large workbook. これらの要求への応答を待機している間に、タイムアウトを簡単に実行できます。It is easy to hit timeout while waiting for the response to these requests. この問題を解決するには、長時間実行の操作パターンを提供します。To resolve this issue, we provide the long-running operation pattern. このパターンを使用する場合、要求のタイムアウトについて心配する必要はありません。When you use this pattern, you don't need to worry about the timeout for the request.

現時点では、Microsoft Graph のセッション作成 Excel API で、長時間実行処理パターンが有効になっています。Currently, the session creation Excel API in Microsoft Graph has the long-running operation pattern enabled. このパターンには、次の手順が含まれます。This pattern involves the following steps:

  1. セッションを Prefer: respond-async 作成するときに、長時間実行される操作であることを示すために、要求にヘッダーを追加します。Add a Prefer: respond-async header to the request to indicate that it is a long-running operation when you crate a session.
  2. 長時間実行処理では、操作の 202 Accepted 状態を取得するために、Location ヘッダーと共に応答が返されます。A long-running operation will return a 202 Accepted response along with a Location header to retrieve the operation status. セッション作成が数秒間で完了すると、長時間実行の処理パターンを使用するのではなく、通常のセッション応答の作成が返されます。If the session creation completes in several seconds, it will return a regular create session response instead of using the long-running operation pattern.
  3. 応答を使用 202 Accepted すると、指定した場所にある操作の状態を取得できます。With the 202 Accepted response, you can retrieve the operation status at the specified location. 操作の状態の値には、、、、、があり notStarted running succeeded failed ます。Operation status values include notStarted, running, succeeded, and failed.
  4. 操作が完了したら、指定した URL を使用して、成功した応答でセッションの作成結果を取得できます。After the operation completes, you can get the session creation result through the specified URL in the succeeded response.

次の例では、実行時間の長い操作パターンを使用してセッションを作成します。The following example creates a session using the long-running operation pattern.

セッションを作成するための最初の要求Initial request to create session

要求Request

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
}

応答Response

長時間実行処理パターンは、 202 Accepted 次のような応答を返します。The long-running operation pattern will return a 202 Accepted response similar to the following.

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

{
}

場合によっては、作成が数秒以内に成功すると、長時間実行される操作パターンには入りません。代わりに、通常の作成セッションとして返され、成功した要求は応答を返し 201 Created ます。In some cases, if the creation succeeds within seconds, it won't enter the long-running operation pattern; instead, it returns as a regular create session and the successful request will return a 201 Created response.

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

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

次の例は、要求が失敗した場合の応答を示しています。The following example shows the response when the request fails.

注: ここに示す応答オブジェクトは、読みやすさのために短縮されている場合があります。Note: The response object shown here might be shortened for readability.

HTTP/1.1 500 Internal Server Error
Content-type: application/json

{
  "error":{
    "code": "internalServerError",
    "message": "An internal server error occurred while processing the request.",
    "innerError": {
      "code": "internalServerErrorUncategorized",
      "message": "An unspecified error has occurred.",
      "innerError": {
        "code": "GenericFileOpenError",
        "message": "The workbook cannot be opened."
      }
    }
  }
}

長時間実行されている作成セッションのポーリングの状態Poll status of the long-running create session

長時間実行処理パターンを使用すると、次の要求を使用して、指定した場所で作成の状態を取得できます。With the long-running operation pattern, you can get the creation status at specified location by using the following request. 推奨されるポーリング状態の間隔は、約30秒です。The suggested interval to poll status is around 30 seconds. 最大間隔は4分以内にする必要があります。The maximum interval should be no more than 4 minutes.

要求Request

GET https://graph.microsoft.com/v1.0/me/drive/items/{drive-item-id}/workbook/operations/{operation-id}
{
}

応答Response

操作の状態がの場合の応答を次に示し running ます。The following is the response when the operation has a status of running.

HTTP/1.1 200 OK
Content-type: application/json

{
    "id": {operation-id},
    "status": "running"
}

操作の状態がである場合の応答を次に示し succeeded ます。The following is the response when the operation status is succeeded.

HTTP/1.1 200 OK
Content-type: application/json

{
    "id": {operation-id},
    "status": "succeeded",
    "resourceLocation": "https://graph.microsoft.com/v1.0/me/drive/items/{drive-item-id}/workbook/sessionInfoResource(key='{key}')
}

操作の状態がである場合の応答を次に示し failed ます。The following is the response when the operation status is failed.

HTTP/1.1 200 OK
Content-type: application/json

{
  "id": {operation-id},
  "status": "failed",
  "error":{
    "code": "internalServerError",
    "message": "An internal server error occurred while processing the request.",
    "innerError": {
      "code": ""internalServerErrorUncategorized",
      "message": "An unspecified error has occurred.",
      "innerError": {
        "code": "GenericFileOpenError",
        "message": "The workbook cannot be opened."
      }
    }
  }
}

エラーの詳細については、「エラーコード」を参照してください。For more details about errors, see Error codes

セッション情報を取得するAcquire session information

要求Request

の状態で succeededresourceLocation 次のような要求を使用して、作成されたセッション情報を取得できます。With a status of succeeded, you can get the created session information through resourceLocation with a request similar to the following.

GET https://graph.microsoft.com/v1.0/me/drive/items/{drive-item-id}/workbook/sessionInfoResource(key='{key}')
{
}

応答Response

応答は次のようになります。The following is the response.

HTTP/1.1 200 OK
Content-type: application/json

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

注: セッション情報の取得は、最初の要求によって異なります。Note: Acquire session information depends on the initial request. 最初の要求が応答本文を返さない場合、結果を取得する必要はありません。You don't need to acquire the result if the initial request doesn't return a response body.