REST API を使用して SharePoint リストを操作する方法

Microsoft 365 で提供されているサービスである SharePoint は、情報共有や共同作業のためのポータルサイトを作成する機能があります。
標準でも豊富な種類のWebパーツが用意されていますが、利用者が求める機能を標準機能だけでは実現できない場合があります。標準機能にはない外観や機能を実現するには、「SharePoint Framework」を利用してWebパーツを開発する必要があります。Webパーツ開発のための基幹技術として「REST API」というものがあり、SharePoint の REST API を使いこなすことができればサイトやリストの操作が可能になります。
弊社が開発した「ez ポータルパーツ」も、SharePoint が提供する REST API を利用することで SharePoint から様々な情報の取得やサイトの操作を行っています。
本記事では、Webパーツの開発に使用している REST API についての説明と、SharePoint の REST エンドポイントの紹介、SharePoint リストへのCRUD操作について解説します。また、弊社の ez ポータルパーツ開発の際には事前に REST API の調査を行っていますが、その際によく利用する REST API や調査の際に利用しているツールについても紹介します。

REST とは？

そもそも REST とは

REST (REpresentational State Transfer)は、HTTPプロトコル作成者の一人であるロイ・フィールディング（Roy Fielding）氏によって2000年頃に提唱されたもので、分散システムにおいて複数のソフトウェアを連携させるのに適したWebサービスの設計思想のことです。
REST なWebサービスは、そのサービスのURIにHTTPメソッドでアクセスすることでデータの送受信を行います。

REST の4原則

RESTには設計の原則として以下の４原則があります。これらの原則を満たすものを「RESTfulなシステム」といい、これらの原則に則った API のことを REST API といいます。

統一インターフェース

あらかじめ定義された方法でデータのやり取りを行うことです。Webでは「GET、POST、PUT、DELETEなどのHTTPメソッドでやりとりする」というインターフェースの統一が図られているため、サービスが利用しやすくなっています。

アドレス可能性

サーバーの全てのリソースが一意なURI（識別子）を持っていること、提供する情報をURIで表現することができることです。
URI（Uniformed Resource Identifier）はWebの場合は通常URLで与えられます。

ステートレス性

REST では、「やり取りが１回ごとに完結する」ということです。
システムが現在の状態を表すデータなどを保持せず、入力の内容によってのみ出力が決定されます。同じ入力に対する出力は常に同じになります（べき等性）。ステートレスの反意語として「ステートフル」があります。

接続性

やり取りされる情報には別の情報への参照（ハイパーリンク）を含めることができます。

SharePoint REST エンドポイント

SharePoint リソースにアクセスするための REST URLの作成

SharePoint で提供される Representational State Transfer (REST) を使用すると、基本的な作成、読み取り、更新、削除 (CRUD) の操作を実行できます。SharePoint リソースにアクセスするには、ODataプロトコルを利用して REST 対応のHTTPリクエストを作成する必要があります。

SharePoint REST エンドポイントの例

SharePoint の REST エンドポイントの例には以下のようなものがあります。
※ REST URL を作成するには、表に示される URL エンドポイントの先頭に 【SharePoint サイトURL】/_api/をつける

REST を使用して SharePoint リストを操作する方法

前項で記載した SharePoint REST エンドポイントを使用してリストの操作をします。
本記事では、弊社がWebパーツを開発する際、実際に使用しているWebパーツである「SharePoint Framework API Tester」を使用して SharePoint リストへの操作を行います。このWebパーツはGitHubで公開されています。

※引用元： GitHub

このページから「estruyf-rest-api-tester.sppkg」のパッケージをダウンロードしてサイトに展開すると使用できるようになります。
Webパーツをサイトに展開する手順については以下をご参照ください。

※参考元：Microsoft 公式｜ Web パーツの SharePoint ページへの展開

SharePoint リストのアイテムを作成する（Create）

作成したばかりの SharePoint リストに任意の列を追加し、REST API によりアイテムを作成してみます。
（ここでは「Content」と「Memo」の列を１行テキストで追加しました。）

対象のリスト名は「REST API Test」、新規アイテムの作成なのでPOSTメソッドを使用します。

REST URLは次のようになります。
【SharePoint サイトのURL】/_api/web/lists/getByTitle(‘REST API Test’)/items

また、新規アイテムの内容を「Request body」にオブジェクト形式で入力します。
この例では次のように入力します。

{
“Title”: “新規アイテム１”,
“Content”: “Create”,
“Memo”: “新規作成しました”
}

「Run query」を選択します。

作成が成功すると以下の画面が表示されます。
対象のリストを参照して、新しいアイテムが作成されていることを確認します。

SharePoint リストのアイテムを取得する（Read）

SharePoint リストのアイテムを取得します。アイテムの取得なのでGETメソッドを使用します。

REST URLは次のようになります。
【SharePoint サイトのURL】/_api/web/lists/getByTitle(‘REST API Test’)/items

アイテムの取得が成功すると以下の画面が表示されます。

クエリオプションを使用することで取得するアイテムの内容を加工するが可能です。

（例）
※取得する列をタイトル列のみに絞り込む場合のURL
　　【SharePoint サイトのURL】/_api/web/lists/getByTitle(‘REST API Test’)/items?$select=Title

※タイトル列が「新規アイテム１」であるアイテムを取得したい場合のURL
　　【SharePoint サイトのURL】/_api/web/lists/getByTitle(‘REST API Test’)/items?$filter=Title eq ‘新規アイテム１’

※Id列で昇順にアイテムを取得したい場合のURL
【SharePoint サイトのURL】/_api/web/lists/getByTitle(‘REST API Test’)/items?$orderby=Id asc

SharePoint リストのアイテムを更新する（Update）

SharePoint リストのアイテムを更新します。更新前のリストは以下とします。

アイテムの更新なので REST の設計に従うならPUTメソッドを使用したいのですが、SharePoint リストは PUT メソッドをサポートしていないため、POST メソッドを使用します。SharePoint リストはID列でオブジェクトの一意性を確保しているので、アイテムの指定にIDを利用します。この例では、ID列が１であるアイテムを更新するのでURLの末尾を「items(1)」とします。

REST URLは次のようになります。
【SharePoint サイトのURL】/_api/web/lists/getByTitle(‘REST API Test’)/items(1)

次に更新の内容を「Request body」にオブジェクト形式で入力します。

{
“Title”: “新規アイテム１を更新”,
“Content”: “Update”,
“Memo”: “更新しました”
}

続いて、「Request headers」を選択して「Request headers」に値を入力します。
「X-HTTP-Method」の値に「MERGE」、「If-Match」の値に「*」を入力します。
「X-HTTP-Method」は、POSTメソッドを指定しますがサーバー側の処理としては「MERGE」メソッドとして実行してもらうために使用します。
「If-Match」はアイテムを複数のユーザーが同時に操作しようとした場合に、不整合が起こらないように管理するための値です。
今回は同時操作を考慮しないのでこの値に「*」を入力します。これでアイテムを更新できるようになります。

以下の画面のようになったら「Run query」を選択します。

対象のリストを参照して正しく更新されていることを確認します。

SharePoint リストのアイテムを削除する（Delete）

SharePoint リストのアイテムを削除します。削除前のリストは以下とします。

アイテムの削除なのでDELETEメソッドを使用します。この例では、「Id」列が3であるアイテムを削除するのでURLの末尾を「items(3)」とします。

REST URLは次のようになります。
【SharePoint サイトのURL】/_api/web/lists/getByTitle(‘REST API Test’)/items(3)

続いて、「Request headers」を選択して「Request headers」に値を入力します。
「If-Match」の値に「*」を入力します。
以下の画面のようになったら「Run query」を選択します。

対象のリストを参照して正しく削除されていることを確認します。

まとめ

本記事では、基本的な REST の概念と SharePoint REST サービスを使用してリストを操作する方法について解説しました。弊社が開発した「ez ポータルパーツ」も、今回のように SharePoint が提供する REST API を利用することで、SharePoint から様々な情報の取得やサイトの操作を行っています。また、REST API は、Webやアプリケーション開発において欠かせない概念です。興味を持った方はその概念が生まれた経緯についても調べてみてください。