SharePoint API への接続

  • [アーティクル]

SharePoint Framework ソリューションでは、SharePoint に保存されたデータの操作が必要になることがよくあります。 SharePoint は、さまざまな方法で利用可能な豊富な API のセットを提供しています。 この記事では、選択可能なオプションの種類、それらの動作内容および長所と短所の概要について説明します。

SPHttpClient を使用した SharePoint API への接続

SharePoint Framework では、SharePoint REST API への接続に使用できる SPHttpClient を提供しています。 SPHttpClient のすぐに使用できるインスタンスは、Web パーツ/拡張機能のコンテキストで利用できます。このインスタンスは、あらゆる種類の Web 要求を実行するために使用できます。 次のコード スニペットは、SPHttpClient を使用して現在のサイトのタイトルを取得する方法を示しています。

this.context.spHttpClient
  .get(`${this.context.pageContext.web.absoluteUrl}/_api/web?$select=Title`, SPHttpClient.configurations.v1)
  .then((res: SPHttpClientResponse): Promise<{ Title: string; }> => {
    return res.json();
  })
  .then((web: {Title: string}): void => {
    console.log(web.Title);
  });

SPHttpClient には、最も一般的な Web 要求を実行するための基本的な機能があります。 また、要求ヘッダーの指定などによって要求を構成することもできます。 たとえば、メタデータを取得することなく Web 要求を発行する場合は、次のコードを使用できます。

this.context.spHttpClient
  .get(`${this.context.pageContext.web.absoluteUrl}/_api/web?$select=Title`,
    SPHttpClient.configurations.v1,
    {
      headers: [
        ['accept', 'application/json;odata.metadata=none']
      ]
    })
  .then((res: SPHttpClientResponse): Promise<{ Title: string; }> => {
    return res.json();
  })
  .then((web: { Title: string }): void => {
    console.log(web.Title);
  });

SPHttpClient を使用する際の考慮事項

SPHttpClient を使用する際には、いくつかの事項について考慮する必要があります。

OData v4.0

既定では、SPHttpClient は OData v4 の仕様を使用します。この仕様では、応答メタデータを制御するために odata のみではなく odata.metadata を使用する必要があります。 OData v4 モードで odata ディレクティブを使用すると、「HTTP ヘッダー ACCEPT が見つからないか、その値が無効です。」のようなエラーが返されます。 要求ヘッダーを空の値に設定することで、SPHttpClient を OData v3.0 モードに設定 odata-version できます。

this.context.spHttpClient
  .get(`${this.context.pageContext.web.absoluteUrl}/_api/web?$select=Title`,
    SPHttpClient.configurations.v1,
    {
      headers: [
        ['accept', 'application/json;odata=nometadata'],
        ['odata-version', '']
      ]
    })
  .then((res: SPHttpClientResponse): Promise<{ Title: string; }> => {
    return res.json();
  })
  .then((web: { Title: string }): void => {
    console.log(web.Title);
  });

認証 Cookie

SharePoint Framework には、Web 要求を実行するためのクラスが複数あります。 それらの 2 つは、SPHttpClient と HttpClient です。 SPHttpClient と HttpClient の相違点の 1 として、SPHttpClient は Web 要求の発行時に認証 Cookie を含めます。 SharePoint API は匿名ではないため、認証情報を提供する必要があります。この情報を提供しないと、「401 Unauthorized」の応答が返されます。 HttpClient は要求内に認証 Cookie を含めないため、SharePoint REST API の呼び出しに使用すると、その要求は失敗して「401 Unauthorized」の応答が返されます。

SharePoint Framework の一部である

SPHttpClient は SharePoint Framework の一部であり、使用を開始するために追加の依存関係は不要です。 ページで利用できるようになっているため、これを使用することで実行時に追加のパフォーマンス オーバーヘッドは発生しません。

生の REST クエリではエラーが発生しやすくなる

SPHttpClient は、SharePoint REST API との通信のための基本的なサポートを提供しています。 アプリケーションで、より複雑な GET 要求または POST 要求が必要になる場合や、より高度な機能 (バッチ処理など) を使用する場合、SPHttpClient の使用は煩雑でエラーが発生しやすいことがすぐにわかります。 このような場合は、TypeScript で正確性の検証が可能な fluent API を提供する PnPjs ライブラリなどの代替手段の使用を検討してください。

PnPjs を使用した SharePoint への接続

PnPjs は、SharePoint および Microsoft 365 との通信に対応したオープン ソースの JavaScript ライブラリです。 これにより、タイプ セーフな方法で SharePoint および Microsoft 365 REST API を簡単に使用できる fluent API が公開されます。 PnPjs を使用して現在のサイトのタイトルを取得するには、次のコードを実行します。

const web = await sp.web
  .select('Title')
  .get<{Title: string;}>();
console.log(web.Title);

注:

PnPJS はオープン ソース ソリューションであり、アクティブなコミュニティでサポートが提供されています。 Microsoft からのオープン ソース ツールのサポート SLA はありません。

このコードは SharePoint Framework の SPHttpClient と比較すると、冗長性が低くなっている点と、取得するプロパティの名前を除く要求のすべての要素が厳密に型指定されているために実行時エラーの危険性が低くなっている点に注目してください。

SharePoint Framework での PnPjs の設定方法と使用方法の詳細については、「PnPjs のドキュメント (https://pnp.github.io/pnpjs/)」を参照してください。

PnPjs を使用する際の考慮事項

PnPjs を使用するかどうかを決定する際には、次に示すいくつかの事項を考慮する必要があります。

生の REST クエリではエラーが発生しやすくなる

SPHttpClient を使用して生の REST 要求を実行するとエラーが発生しやすくなります。 特に、アプリケーションで POST クエリの実行が必要になる場合や、要求のバッチ処理などのより高度な機能を使用する場合は、正しい要求の作成と応答の解析が煩雑になります。 当然のことですが、要求が正しいかどうかを確認する方法は、ブラウザーでコードを実行する以外にありません。 PnPjs により、タイプセーフな方法で SharePoint API と通信できるようになり、SharePoint API の高度な機能を簡単に使用できるようになるため、要求のテストではなくアプリケーションの作成に集中できます。

オープン ソース プロジェクト

PnPjs は、SharePoint コミュニティによって管理されているオープン ソース プロジェクトです。 ソリューションでの PnPjs の使用に関する SLA はありません。また、PnPjs によって発生する可能性のある問題について、Microsoft サポートでは支援できません。 ただし、PnPjs の開発は活発に行われていて、コミュニティは提出されたすべての問題や質問に迅速に対応しています。

追加の依存関係

PnPjs は、プロジェクトに追加して、長期にわたって管理する必要のある追加の依存関係です。 更新プログラムを常に追跡して、必要に応じてプロジェクトをアップグレードする必要があります。 PnPjs のコミュニティは、現在の作業の状態、今後のリリース、および新しいバージョンにアップグレードした場合の影響 (影響がある場合) について定期的に発表しています。

追加のペイロード

PnPjs は、SharePoint API との通信のための機能の豊富なセットを提供します。 ライブラリは選択的なインポートをサポートしていますので、カーフル キュレーションを使用すると、バンドル サイズに対する全体的な影響を軽減できます。 詳細については、https://pnp.github.io/pnpjs/ のドキュメントを参照してください。