Excel API を使用するためのベスト プラクティス

この記事では、Microsoft Graph で Excel API を 操作するための推奨事項について説明します。

最も効率的な方法でセッションを管理する

一定期間内に複数の呼び出しを行う場合は、セッションを作成し、各要求でセッション ID を渡することをお勧めします。 API でセッションを表すには、workbook-session-id: {session-id} ヘッダーを使用します。 これにより、最も効率的な方法で Excel API を使用できます。

次の例では、テーブルに新しい番号を追加し、この方法を使用してブック内の 1 つのレコードを検索する方法を示します。

手順 1: セッションを作成する

要求

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
}

手順 2: テーブルに新しい行を追加する

要求

HTTP

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]]
}

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

const workbookTableRow = {
  values: [[“east”, “pear”, 4]]
};

await client.api('/me/drive/items/{id}/workbook/tables/Table1/rows/add')
	.post(workbookTableRow);

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

Java

Snippet not available

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

応答

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

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

手順 3: 更新されたテーブルの値を検索する

要求

HTTP

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
}

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

const workbookFunctionResult = {
    lookupValue: 'pear',
    tableArray: {Address: 'Sheet1!B2:C7'},
    colIndexNum: 2,
    rangeLookup: false
};

await client.api('/me/drive/items/{id}/workbook/functions/vlookup')
	.post(workbookFunctionResult);

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

Java

Snippet not available

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

応答

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

{
    "value": 5
}

手順 4: すべての要求が完了した後にセッションを閉じる

要求

HTTP

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

{
}

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

const closeSession = {
};

await client.api('/me/drive/items/{id}/workbook/closeSession')
	.post(closeSession);

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

Java

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

LinkedList<Option> requestOptions = new LinkedList<Option>();
requestOptions.add(new HeaderOption("workbook-session-id", "{session-id}"));

graphClient.me().drive().items("{id}").workbook()
	.closeSession()
	.buildRequest( requestOptions )
	.post();

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

応答

HTTP/1.1 204 No Content

詳細については、「セッションの 作成 」および「セッションを 閉じる」を参照してください。

完了するまでに長い時間がかかる API の操作

一部の操作の完了には不確定な時間がかかる場合があります。たとえば、大きなブックを開きます。 これらの要求への応答を待っている間にタイムアウトに達するのは簡単です。 この問題を解決するために、実行時間の長い操作パターンを提供します。 このパターンを使用する場合、要求のタイムアウトについて心配する必要はありません。

現在、Microsoft Graph でのセッション作成 Excel API では、実行時間の長い操作パターンが有効になっています。 このパターンには、次の手順が含まれます。

1. セッションを Prefer: respond-async クレートするときに実行時間の長い操作であることを示すヘッダーを要求に追加します。
2. 実行時間の長い操作では、Location ヘッダーと共に 202 Accepted 応答が返され、操作の状態が取得されます。 セッションの作成が数秒で完了すると、実行時間の長い操作パターンを使用するのではなく、通常の作成セッション応答が返されます。
3. 応答を 202 Accepted 使用すると、指定した場所で操作の状態を取得できます。 操作の状態の値には、、、succeeded、および がfailed含まれますnotStarted。 running
4. 操作が完了すると、成功した応答で指定された URL を使用してセッション作成結果を取得できます。

次の例では、実行時間の長い操作パターンを使用してセッションを作成します。

セッションを作成するための最初の要求

要求

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

応答

実行時間の長い操作パターンは、次のような応答を返 202 Accepted します。

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 返します。

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

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

次の例は、要求が失敗したときの応答を示しています。

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

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."
      }
    }
  }
}

実行時間の長い作成セッションのポーリング状態

実行時間の長い操作パターンでは、次の要求を使用して、指定した場所で作成状態を取得できます。 状態をポーリングするための推奨される間隔は約 30 秒です。 最大間隔は 4 分以下にする必要があります。

要求

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

応答

操作の状態が である場合の応答を次に running示します。

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

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

操作の状態が の場合の応答を次に 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示します。

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."
      }
    }
  }
}

エラーの詳細については、「 エラー コードとメッセージ」を参照してください。

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

要求

の succeeded状態では、次のような要求を使用して resourceLocation 、作成されたセッション情報を取得できます。

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

応答

応答は次のようになります。

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

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

注:

セッション情報の取得は、最初の要求によって異なります。 最初の要求が応答本文を返さない場合は、結果を取得する必要はありません。

調整エラーを減らす

Microsoft Graph の Excel API は、複数の依存関係サービスのリソース使用量に影響します。 影響は要求によって異なる場合があります。たとえば、小さなブックの 1 つのセル内の短い文字列を更新すると、大きなブックに複雑な数式を含む大きなテーブルを追加するよりも、リソースの消費が少なくなると予想される場合があります。

同じ API を使用しても、パラメーターとターゲット ブックでは大きな違いが生じる可能性があります。 そのため、Excel API の調整は、制限が厳しくなるため、単純な制限番号とユニバーサル制限番号では定義されません。 次のベスト プラクティスは、調整エラーが少ないタスクをより迅速に完了するのに役立ちます。

Retry-After ヘッダー

多くの場合、調整応答にはヘッダーが Retry-After 含まれます。 ヘッダーの値を尊重し、同様の要求を遅延すると、クライアントが調整から回復するのに役立ちます。 Microsoft Graph での Excel API からのエラー応答の処理の詳細については、「Microsoft Graph での Excel API のエラー処理」を参照してください。

調整とコンカレンシー

調整に関連するもう 1 つの要因は、要求のコンカレンシーです。 特に書き込み要求に対して、Excel API を使用する場合 (たとえば、同じブックへの要求の並列化など) は、コンカレンシーを増やすことはお勧めしません。 代わりに、要求の実行時間が非常に短い場合に比べてネットワークのオーバーヘッドが大幅に増加するなど、特定の懸念がある場合を除き、最も一般的なケースでは順次使用することをお勧めします。ブックごとに、現在の要求に対する応答が成功した後にのみ次の要求を送信します。

同じブックへの同時書き込み要求は、通常は並列で実行されません (ただし、場合によっては実行される場合があります)。多くの場合、調整、タイムアウト (サーバーで要求がキューに入れられている場合)、マージ競合 (同時セッションが関係する場合)、その他の種類のエラーの原因になります。 また、エラー処理も複雑になります。たとえば、エラー応答を受け取った場合、他の保留中の要求の状態を確認する方法がないため、ブックの状態の特定や回復が困難になります。

関連項目

• Excel REST API を使用する