Microsoft Learn Challenge

マイクロソフトグラフでのExcelの活用 – Microsoft Graph v1.0

Microsoft Graphを使用すると、OneDrive for BusinessやSharePointに保存されているExcelワークブックを読み書きできます。ワークブックリソースは他のExcelリソースへの関係を含み、Drive API経由でアクセス可能です。Excel REST APIはOffice Open XMLフォーマットのみをサポートし、商用プラットフォームのファイルのみが対象です。APIは認証が必要で、CRUD操作が可能です。また、セッションモードには持続的、非持続的、およびセッションなしの3種類があります。Excelオブジェクトへの一般的な操作も詳細に説明されています。

Microsoft Graphを使用したExcelワークブックの操作

Microsoft Graphを使用すると、WebおよびモバイルアプリケーションでOneDrive for Business、SharePointサイト、またはグループドライブに保存されているExcelワークブックを読み取り、変更することができます。Workbook（またはExcelファイル）リソースは、他のExcelリソースを関係性を通じて含んでいます。ワークブックにアクセスするには、URL内のファイルの場所を特定して、Drive APIを利用します。例としては以下のような形です。

https://graph.microsoft.com/v1.0/me/drive/items/{id}/workbook/
https://graph.microsoft.com/v1.0/me/drive/root:/{item-path}:/workbook/

Excelオブジェクト（テーブル、範囲、またはチャートなど）のセットにアクセスするには、標準のREST APIを使用して、ワークブックに対して作成、読み取り、更新、削除（CRUD）操作を行います。例えば、次のリクエストはワークシートオブジェクトのコレクションを取得します。

GET https://graph.microsoft.com/v1.0/me/drive/items/{id}/workbook/worksheets

認証とスコープ

Excel APIを認証するために、Microsoft Identity Platformを使用します。すべてのAPIには、HTTPヘッダーにAuthorization: Bearer {access-token}が必要です。

Excelリソースを使用するには、次のいずれかのパーミッションスコープが必要です。

  • Files.Read（読み取り操作用）
  • Files.ReadWrite（読み書き操作用）

セッションと持続性

Excel APIは、次の3つのモードのいずれかで呼び出すことができます。

  1. 持続セッション – ワークブックに加えたすべての変更が永続的に保存されます。このモードが最も効率的でパフォーマンスが高いです。
  2. 非持続セッション – APIによって行われた変更は元の場所に保存されません。その代わりに、Excelバックエンドサーバーは、その特定のAPIセッション中に加えられた変更を反映する一時コピーを保持します。Excelセッションが期限切れになると、変更は失われます。
  3. セッションなし – セッション情報なしでAPI呼び出しが行われます。Excelサーバーは操作を実行するたびにワークブックのコピーを見つけなければならないため、これは効率的な方法ではありません。

APIでセッションを示すには、次のヘッダーを使用します。

workbook-session-id: {session-id}

注: セッションヘッダーはExcel APIが動作するために必須ではありませんが、パフォーマンス向上のために利用することをお勧めします。

Excelの一般的なシナリオ

以下の章では、Excelオブジェクトに対して使用できる一般的な操作の例を紹介します。

ワークシート操作

ワークブックの一部であるワークシートをリストするには、次のリクエストを行います。

GET https://graph.microsoft.com/v1.0/me/drive/items/{id}/workbook/worksheets

新しいワークシートを追加するには：

POST /{version}/me/drive/root:/workbook/worksheets
チャート操作

ワークシートのチャートをリストするには：

GET https://graph.microsoft.com/v1.0/me/drive/items/{item-id}/workbook/worksheets('{worksheet-id')/charts

新しいチャートを追加するには：

POST https://graph.microsoft.com/v1.0/me/drive/items/{item-id}/workbook/worksheets('{worksheet-id}')/charts/Add
テーブル操作

テーブルのリストを取得する場合：

GET https://graph.microsoft.com/v1.0/me/drive/items/{item-id}/workbook/worksheets('{worksheet-id}')/tables

新しいテーブルを追加するには：

POST https://graph.microsoft.com/v1.0/me/drive/items/{item-id}/workbook/tables/{table-id}/add
範囲操作

範囲を取得するには：

GET https://graph.microsoft.com/v1.0/me/drive/items/{item-id}/workbook/worksheets('{worksheet-id}')/range(address="A1:B2")

範囲を更新するには：

PATCH https://graph.microsoft.com/v1.0/me/drive/items/{item-id}/workbook/worksheets('{worksheet-id}')/range(address="test!A1:B2")

これらのAPIを使用することで、Microsoft Graphを通じてExcelの操作が大幅に簡素化されます。Microsoft Graphを利用することで、データの管理がこれまで以上に効率的かつ柔軟に行えるようになります。

————-

Working with Excel in Microsoft Graph – Microsoft Graph v1.0

Source link

The article explains how to use Microsoft Graph API for interacting with Excel workbooks stored in OneDrive for Business, SharePoint, or Group drives. It details the various Excel resources accessible through the API, which supports operations like Create, Read, Update, and Delete (CRUD) for elements such as worksheets, tables, ranges, and charts.

Key Points:

  1. API Access:

    • To access a workbook, the API uses specific URLs formatted with the drive items’ IDs.
    • Only Office Open XML file formats (.xlsx) are supported; older .xls files are not.

  2. Authentication:

    • Microsoft identity platform is required for API access, specifically using the Bearer token in the HTTP header with necessary permissions, such as Files.Read and Files.ReadWrite.

  3. Sessions:

    • The API supports three session modes: persistent (changes saved), non-persistent (temporary changes), and sessionless (inefficient for repeated calls).
    • It is recommended to use a session when executing API calls for performance benefits.

  4. Common Operations:

    • The article provides detailed API requests for common Excel operations, including listing, adding, and retrieving worksheets, as well as updating and deleting properties.

  5. Handling Data Objects:

    • Procedures for managing tables and ranges are outlined, including creating, updating, sorting, and filtering data.

  6. Excel Functions:

    • The Graph API allows access to workbook functions, enabling calculations directly through API calls.

  7. Error Management:

    • Understanding error codes and structures in response to invalid requests is vital. An error object is returned upon failures, detailing the issue.

  8. Null Handling:

    • The article also discusses how nulls are managed within API calls, emphasizing how null input can either ignore elements or lead to errors when incorrectly applied.

  9. Large Data Sizes:

    • For operations involving large ranges, the article advises breaking requests into smaller chunks to avoid resource utilization errors.
  10. Updates:
    • Guidance is provided for updating Excel ranges, charts, and tables along with the expected responses.

Overall, the article serves as a comprehensive guide for developers seeking to manipulate Excel files programmatically using Microsoft Graph API within business environments.

お知らせ：DX実践手引書の改訂版を公開いたしました 前の記事 オンプレミスデータゲートウェイ 2024年11月リリース | Microsoft Power BI ブログ 次の記事

関連記事

コメント

この記事へのコメントはありません。