この記事では、Microsoft Graph で Excel API を 操作するための推奨事項について説明します。
最も効率的な方法でセッションを管理する
一定期間内に複数の呼び出しを行う場合は、セッションを作成し、各要求でセッション ID を渡することをお勧めします。 API でセッションを表すには、workbook-session-id: {session-id}
ヘッダーを使用します。 これにより、最も効率的な方法で Excel API を使用できます。
次の例では、テーブルに新しい番号を追加し、この方法を使用してブック内の 1 つのレコードを検索する方法を示します。
手順 1: セッションを作成する
要求
POST https://graph.microsoft.com/v1.0/me/drive/items/{id}/workbook/createSession
Content-type: application/json
{
"persistChanges": true
}
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Drives.Item.Items.Item.Workbook.CreateSession;
var requestBody = new CreateSessionPostRequestBody
{
PersistChanges = true,
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Drives["{drive-id}"].Items["{driveItem-id}"].Workbook.CreateSession.PostAsync(requestBody);
プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。
mgc drives items workbook create-session post --drive-id {drive-id} --drive-item-id {driveItem-id} --body '{\
"persistChanges": true\
}\
'
プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。
// Code snippets are only available for the latest major version. Current major version is $v1.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphdrives "github.com/microsoftgraph/msgraph-sdk-go/drives"
//other-imports
)
requestBody := graphdrives.NewCreateSessionPostRequestBody()
persistChanges := true
requestBody.SetPersistChanges(&persistChanges)
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
createSession, err := graphClient.Drives().ByDriveId("drive-id").Items().ByDriveItemId("driveItem-id").Workbook().CreateSession().Post(context.Background(), requestBody, nil)
プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
com.microsoft.graph.drives.item.items.item.workbook.createsession.CreateSessionPostRequestBody createSessionPostRequestBody = new com.microsoft.graph.drives.item.items.item.workbook.createsession.CreateSessionPostRequestBody();
createSessionPostRequestBody.setPersistChanges(true);
var result = graphClient.drives().byDriveId("{drive-id}").items().byDriveItemId("{driveItem-id}").workbook().createSession().post(createSessionPostRequestBody);
プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。
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 のドキュメントを参照してください。
<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Drives\Item\Items\Item\Workbook\CreateSession\CreateSessionPostRequestBody;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestBody = new CreateSessionPostRequestBody();
$requestBody->setPersistChanges(true);
$result = $graphServiceClient->drives()->byDriveId('drive-id')->items()->byDriveItemId('driveItem-id')->workbook()->createSession()->post($requestBody)->wait();
プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.drives.item.items.item.workbook.create_session.create_session_post_request_body import CreateSessionPostRequestBody
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = CreateSessionPostRequestBody(
persist_changes = True,
)
result = await graph_client.drives.by_drive_id('drive-id').items.by_drive_item_id('driveItem-id').workbook.create_session.post(request_body)
プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。
応答
成功した応答を次に示します。
HTTP/1.1 201 Created
Content-type: application/json
{
"id": "id-value",
"persistChanges": true
}
手順 2: テーブルに新しい行を追加する
要求
POST https://graph.microsoft.com/v1.0/me/drive/items/{id}/workbook/tables/{id|name}/rows/add
Content-type: application/json
workbook-session-id: {session-id}
{
"values": [[“east”, “pear”, 4]]
}
mgc drives items workbook tables rows add post --drive-id {drive-id} --drive-item-id {driveItem-id} --workbook-table-id {workbookTable-id} --body '{\
"values": [[“east”, “pear”, 4]]\
}\
'
プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。
const options = {
authProvider,
};
const client = Client.init(options);
const workbookTableRow = {
values: [[“east”, “pear”, 4]]
};
await client.api('/me/drive/items/{id}/workbook/tables/{id|name}/rows/add')
.post(workbookTableRow);
プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。
応答
HTTP/1.1 200 OK
Content-type: application/json
{
"index": 6,
"values": [[“east”, “pear”, 4]]
}
手順 3: 更新されたテーブルの値を検索する
要求
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
}
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Drives.Item.Items.Item.Workbook.Functions.Vlookup;
using Microsoft.Kiota.Abstractions.Serialization;
var requestBody = new VlookupPostRequestBody
{
LookupValue = new UntypedString("pear"),
TableArray = new UntypedObject(new Dictionary<string, UntypedNode>
{
{
"Address", new UntypedString("Sheet1!B2:C7")
},
}),
ColIndexNum = new UntypedDouble(2),
RangeLookup = new UntypedBoolean(false),
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Drives["{drive-id}"].Items["{driveItem-id}"].Workbook.Functions.Vlookup.PostAsync(requestBody, (requestConfiguration) =>
{
requestConfiguration.Headers.Add("workbook-session-id", "{session-id}");
});
プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。
mgc drives items workbook functions vlookup post --drive-id {drive-id} --drive-item-id {driveItem-id} --body '{\
"lookupValue":"pear",\
"tableArray":{"Address":"Sheet1!B2:C7"},\
"colIndexNum":2,\
"rangeLookup":false\
}\
'
プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。
// Code snippets are only available for the latest major version. Current major version is $v1.*
// Dependencies
import (
"context"
abstractions "github.com/microsoft/kiota-abstractions-go"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphdrives "github.com/microsoftgraph/msgraph-sdk-go/drives"
//other-imports
)
headers := abstractions.NewRequestHeaders()
headers.Add("workbook-session-id", "{session-id}")
configuration := &graphdrives.ItemItemsItemWorkbookFunctionsVlookupRequestBuilderPostRequestConfiguration{
Headers: headers,
}
requestBody := graphdrives.NewVlookupPostRequestBody()
lookupValue := "pear"
requestBody.SetLookupValue(&lookupValue)
tableArray := graph.NewUntypedNode()
address := "Sheet1!B2:C7"
tableArray.SetAddress(&address)
requestBody.SetTableArray(tableArray)
colIndexNum := float64(2)
requestBody.SetColIndexNum(&colIndexNum)
rangeLookup := false
requestBody.SetRangeLookup(&rangeLookup)
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
vlookup, err := graphClient.Drives().ByDriveId("drive-id").Items().ByDriveItemId("driveItem-id").Workbook().Functions().Vlookup().Post(context.Background(), requestBody, configuration)
プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
com.microsoft.graph.drives.item.items.item.workbook.functions.vlookup.VlookupPostRequestBody vlookupPostRequestBody = new com.microsoft.graph.drives.item.items.item.workbook.functions.vlookup.VlookupPostRequestBody();
vlookupPostRequestBody.setLookupValue("pear");
UntypedNode tableArray = new UntypedNode();
tableArray.setAddress("Sheet1!B2:C7");
vlookupPostRequestBody.setTableArray(tableArray);
vlookupPostRequestBody.setColIndexNum(2d);
vlookupPostRequestBody.setRangeLookup(false);
var result = graphClient.drives().byDriveId("{drive-id}").items().byDriveItemId("{driveItem-id}").workbook().functions().vlookup().post(vlookupPostRequestBody, requestConfiguration -> {
requestConfiguration.headers.add("workbook-session-id", "{session-id}");
});
プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。
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 のドキュメントを参照してください。
<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Drives\Item\Items\Item\Workbook\Functions\Vlookup\VlookupRequestBuilderPostRequestConfiguration;
use Microsoft\Graph\Generated\Drives\Item\Items\Item\Workbook\Functions\Vlookup\VlookupPostRequestBody;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestBody = new VlookupPostRequestBody();
$requestBody->setLookupValue('pear');
$tableArray = new UntypedNode();
$tableArray->setAddress('Sheet1!B2:C7');
$requestBody->setTableArray($tableArray);
$requestBody->setColIndexNum(2);
$requestBody->setRangeLookup(false);
$requestConfiguration = new VlookupRequestBuilderPostRequestConfiguration();
$headers = [
'workbook-session-id' => '{session-id}',
];
$requestConfiguration->headers = $headers;
$result = $graphServiceClient->drives()->byDriveId('drive-id')->items()->byDriveItemId('driveItem-id')->workbook()->functions()->vlookup()->post($requestBody, $requestConfiguration)->wait();
プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.drives.item.items.item.workbook.functions.vlookup.vlookup_request_builder import VlookupRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
from msgraph.generated.drives.item.items.item.workbook.functions.vlookup.vlookup_post_request_body import VlookupPostRequestBody
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = VlookupPostRequestBody(
lookup_value = "pear",
table_array = UntypedNode(
address = "Sheet1!B2:C7",
),
col_index_num = 2,
range_lookup = False,
)
request_configuration = RequestConfiguration()
request_configuration.headers.add("workbook-session-id", "{session-id}")
result = await graph_client.drives.by_drive_id('drive-id').items.by_drive_item_id('driveItem-id').workbook.functions.vlookup.post(request_body, request_configuration = request_configuration)
プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。
応答
HTTP code: 200 OK
content-type: application/json
{
"value": 5
}
手順 4: すべての要求が完了した後にセッションを閉じる
要求
POST https://graph.microsoft.com/v1.0/me/drive/items/{id}/workbook/closeSession
Content-type: application/json
workbook-session-id: {session-id}
{
}
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Drives.Item.Items.Item.Workbook.CloseSession;
var requestBody = new CloseSessionPostRequestBody
{
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
await graphClient.Drives["{drive-id}"].Items["{driveItem-id}"].Workbook.CloseSession.PostAsync(requestBody, (requestConfiguration) =>
{
requestConfiguration.Headers.Add("workbook-session-id", "{session-id}");
});
プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。
// Code snippets are only available for the latest major version. Current major version is $v1.*
// Dependencies
import (
"context"
abstractions "github.com/microsoft/kiota-abstractions-go"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphdrives "github.com/microsoftgraph/msgraph-sdk-go/drives"
//other-imports
)
headers := abstractions.NewRequestHeaders()
headers.Add("workbook-session-id", "{session-id}")
configuration := &graphdrives.ItemItemsItemWorkbookCloseSessionRequestBuilderPostRequestConfiguration{
Headers: headers,
}
requestBody := graphdrives.NewCloseSessionPostRequestBody()
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
graphClient.Drives().ByDriveId("drive-id").Items().ByDriveItemId("driveItem-id").Workbook().CloseSession().Post(context.Background(), requestBody, configuration)
プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
com.microsoft.graph.drives.item.items.item.workbook.closesession.CloseSessionPostRequestBody closeSessionPostRequestBody = new com.microsoft.graph.drives.item.items.item.workbook.closesession.CloseSessionPostRequestBody();
graphClient.drives().byDriveId("{drive-id}").items().byDriveItemId("{driveItem-id}").workbook().closeSession().post(closeSessionPostRequestBody, requestConfiguration -> {
requestConfiguration.headers.add("workbook-session-id", "{session-id}");
});
プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。
const options = {
authProvider,
};
const client = Client.init(options);
const closeSession = {
};
await client.api('/me/drive/items/{id}/workbook/closeSession')
.post(closeSession);
プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。
<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Drives\Item\Items\Item\Workbook\CloseSession\CloseSessionRequestBuilderPostRequestConfiguration;
use Microsoft\Graph\Generated\Drives\Item\Items\Item\Workbook\CloseSession\CloseSessionPostRequestBody;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestBody = new CloseSessionPostRequestBody();
$requestConfiguration = new CloseSessionRequestBuilderPostRequestConfiguration();
$headers = [
'workbook-session-id' => '{session-id}',
];
$requestConfiguration->headers = $headers;
$graphServiceClient->drives()->byDriveId('drive-id')->items()->byDriveItemId('driveItem-id')->workbook()->closeSession()->post($requestBody, $requestConfiguration)->wait();
プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.drives.item.items.item.workbook.close_session.close_session_request_builder import CloseSessionRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
from msgraph.generated.drives.item.items.item.workbook.close_session.close_session_post_request_body import CloseSessionPostRequestBody
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = CloseSessionPostRequestBody(
)
request_configuration = RequestConfiguration()
request_configuration.headers.add("workbook-session-id", "{session-id}")
await graph_client.drives.by_drive_id('drive-id').items.by_drive_item_id('driveItem-id').workbook.close_session.post(request_body, request_configuration = request_configuration)
プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。
応答
HTTP/1.1 204 No Content
詳細については、「セッションの 作成 」と「セッションを 閉じる」を参照してください。
完了するまでに長い時間がかかる API を操作する
一部の操作の完了には不確定な時間がかかる場合があります。たとえば、大きなブックを開きます。 これらの要求への応答を待っている間にタイムアウトに達するのは簡単です。 この問題を解決するために、実行時間の長い操作パターンを提供します。 このパターンを使用する場合、要求のタイムアウトについて心配する必要はありません。
現在、Microsoft Graph でのセッション作成 Excel API では、実行時間の長い操作パターンが有効になっています。 このパターンには、次の手順が含まれます。
- セッションの
Prefer: respond-async
作成時に実行時間の長い操作であることを示すヘッダーを要求に追加します。
- 実行時間の長い操作では、Location ヘッダーと共に
202 Accepted
応答が返され、操作の状態が取得されます。 セッションの作成が数秒で完了すると、実行時間の長い操作パターンを使用するのではなく、通常の作成セッション応答が返されます。
- 応答を
202 Accepted
使用すると、指定した場所で操作の状態を取得できます。 操作の状態の値には、、、succeeded
、および がfailed
含まれますnotStarted
。 running
- 操作が完了すると、成功した応答で指定された URL を使用してセッション作成結果を取得できます。
次の例では、実行時間の長い操作パターンを使用してセッションを作成します。
セッションを作成するための最初の要求
要求
POST https://graph.microsoft.com/v1.0/me/drive/items/{drive-item-id}/workbook/createSession
Prefer: respond-async
Content-type: application/json
{
"persistChanges": true
}
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Drives.Item.Items.Item.Workbook.CreateSession;
var requestBody = new CreateSessionPostRequestBody
{
PersistChanges = true,
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Drives["{drive-id}"].Items["{driveItem-id}"].Workbook.CreateSession.PostAsync(requestBody, (requestConfiguration) =>
{
requestConfiguration.Headers.Add("Prefer", "respond-async");
});
プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。
mgc drives items workbook create-session post --drive-id {drive-id} --drive-item-id {driveItem-id} --body '{\
"persistChanges": true\
}\
'
プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。
// Code snippets are only available for the latest major version. Current major version is $v1.*
// Dependencies
import (
"context"
abstractions "github.com/microsoft/kiota-abstractions-go"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphdrives "github.com/microsoftgraph/msgraph-sdk-go/drives"
//other-imports
)
headers := abstractions.NewRequestHeaders()
headers.Add("Prefer", "respond-async")
configuration := &graphdrives.ItemItemsItemWorkbookCreateSessionRequestBuilderPostRequestConfiguration{
Headers: headers,
}
requestBody := graphdrives.NewCreateSessionPostRequestBody()
persistChanges := true
requestBody.SetPersistChanges(&persistChanges)
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
createSession, err := graphClient.Drives().ByDriveId("drive-id").Items().ByDriveItemId("driveItem-id").Workbook().CreateSession().Post(context.Background(), requestBody, configuration)
プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
com.microsoft.graph.drives.item.items.item.workbook.createsession.CreateSessionPostRequestBody createSessionPostRequestBody = new com.microsoft.graph.drives.item.items.item.workbook.createsession.CreateSessionPostRequestBody();
createSessionPostRequestBody.setPersistChanges(true);
var result = graphClient.drives().byDriveId("{drive-id}").items().byDriveItemId("{driveItem-id}").workbook().createSession().post(createSessionPostRequestBody, requestConfiguration -> {
requestConfiguration.headers.add("Prefer", "respond-async");
});
プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。
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 のドキュメントを参照してください。
<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Drives\Item\Items\Item\Workbook\CreateSession\CreateSessionRequestBuilderPostRequestConfiguration;
use Microsoft\Graph\Generated\Drives\Item\Items\Item\Workbook\CreateSession\CreateSessionPostRequestBody;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestBody = new CreateSessionPostRequestBody();
$requestBody->setPersistChanges(true);
$requestConfiguration = new CreateSessionRequestBuilderPostRequestConfiguration();
$headers = [
'Prefer' => 'respond-async',
];
$requestConfiguration->headers = $headers;
$result = $graphServiceClient->drives()->byDriveId('drive-id')->items()->byDriveItemId('driveItem-id')->workbook()->createSession()->post($requestBody, $requestConfiguration)->wait();
プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.drives.item.items.item.workbook.create_session.create_session_request_builder import CreateSessionRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
from msgraph.generated.drives.item.items.item.workbook.create_session.create_session_post_request_body import CreateSessionPostRequestBody
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = CreateSessionPostRequestBody(
persist_changes = True,
)
request_configuration = RequestConfiguration()
request_configuration.headers.add("Prefer", "respond-async")
result = await graph_client.drives.by_drive_id('drive-id').items.by_drive_item_id('driveItem-id').workbook.create_session.post(request_body, request_configuration = request_configuration)
プロジェクトに 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 は、複数の依存関係サービスのリソース使用量に影響します。 影響は要求によって異なる場合があります。たとえば、小さなブックの単一セル内の短い文字列を更新すると、大きなブックに複雑な数式を含む大きなテーブルを追加するよりも、リソースの消費が少なくなると予想される場合があります。
同じ API を使用しても、パラメーターとターゲット ブックでは大きな違いが生じる可能性があります。 そのため、Excel API の調整は、制限が厳しくなるため、単純な制限番号とユニバーサル制限番号では定義されません。 次のベスト プラクティスは、調整エラーを減らしながらタスクをより迅速に完了するのに役立ちます。
多くの場合、調整応答にはヘッダーが Retry-After
含まれます。 ヘッダーの値を尊重し、同様の要求を遅延すると、クライアントが調整から回復するのに役立ちます。 Microsoft Graph での Excel API からのエラー応答の処理の詳細については、「Microsoft Graph での Excel API のエラー処理」を参照してください。
調整とコンカレンシー
調整に関連するもう 1 つの要因は、要求のコンカレンシーです。 特に書き込み要求に対して、Excel API を使用する場合 (たとえば、同じブックに要求を並列化する) 場合は、コンカレンシーを増やすことはお勧めしません。 代わりに、要求の実行時間が非常に短い場合に比べてネットワークのオーバーヘッドが大きいなど、特定の懸念がある場合を除き、最も一般的なケースでは順次使用することをお勧めします。ブックごとに、現在の要求に対する応答が成功した後にのみ次の要求を送信します。
同じブックに対する同時書き込み要求は、通常は並列で実行されません (ただし、場合によっては実行される場合があります)。多くの場合、調整、タイムアウト (要求がサーバー上でキューに入れられている場合)、マージの競合 (同時セッションが関係する場合)、その他の種類のエラーの原因になります。 また、エラー処理も複雑になります。たとえば、エラー応答を受け取った場合、他の保留中の要求の状態を確認する方法がないため、ブックの状態の特定や回復が困難になります。
関連コンテンツ