通知リストの購読

  • [アーティクル]

SharePoint Framework v1.7.0 で導入された SharePoint ドキュメント ライブラリに保存されているファイルの変更をサブスクライブできます。 これにより、ライブラリのコンテンツを定期的にポーリングすることなく、変更があったときに対応できるようになります。

前提条件

SharePoint Framework リスト サブスクリプション機能を使用するには、まず 、@microsoft/sp-list-subscription npm パッケージをインストールする必要があります。 これは、次のコード スニペットを使用して実行できます。

npm install @microsoft/sp-list-subscription --save --save-exact

SharePoint ドキュメント ライブラリに保存されたドキュメントへの変更の通知を受け取る

SharePoint ドキュメント ライブラリに保存されたファイルへの変更について購読するには、ListSubscriptionFactory クラスのインスタンスを作成します。 その後で、購読するドキュメント ライブラリの ID を渡して createSubscription() メソッドを呼び出します。 ドキュメント ライブラリが現在のサイト内にある場合は、ライブラリ ID を指定するだけでかまいません。 別のサイトまたはサイト コレクション内にある場合は、ID も指定する必要があります。

次に、現在のサイトにドキュメント ライブラリがある場合のリスト サブスクリプションの例を示します。

import { ListSubscriptionFactory, IListSubscription } from '@microsoft/sp-list-subscription';
import { Guid } from '@microsoft/sp-core-library';

export default class LatestDocumentsWebPart extends BaseClientSideWebPart<ILatestDocumentsWebPartProps> {
  private _listSubscriptionFactory: ListSubscriptionFactory;
  private _listSubscription: IListSubscription;

  private async createListSubscription(): Promise<void> {
    this._listSubscriptionFactory = new ListSubscriptionFactory(this);
    this._listSubscription = await this._listSubscriptionFactory.createSubscription({
      listId: Guid.parse(this.properties.listId),
      callbacks: {
        notification: this._loadDocuments.bind(this)
      }
    });
  }

  private _loadDocuments(): void {
    // load documents here
  }

  // omitted for brevity
}

リスト サブスクリプションを作成するときに、callbacks.notification プロパティを使用する場合は、変更が発生したときに呼び出されるメソッドを指定する必要があります。 このメソッドには引数がなく、実際の変更内容についてはセキュリティ上の理由から通知されません。 ドキュメント ライブラリの最新のコンテンツを取得する場合は、構成済みのアクセス許可に準拠する SharePoint REST API または Microsoft Graph のどちらかを使用できます。

追加の構成

ソリューションによっては、リスト通知の購読時に追加の構成の指定が必要になることがあります。

複数地域テナントのサイト コレクションに接続する

複数地域テナントで SharePoint を使用する場合は、特定のサイト コレクションが存在するドメインを指定する必要があります。 これは、domain プロパティを使用することで可能になります。次に例を示します。

this._listSubscriptionFactory.createSubscription({
  domain: this.properties.siteDomain,
  siteId: Guid.parse(this.properties.siteId),
  webId: Guid.parse(this.properties.webId),
  listId: Guid.parse(this.properties.listId),
  callbacks: {
    notification: this._loadDocuments.bind(this)
  }
});

サブスクリプションが確立またはキャンセルされたときに通知を受け取る

場合によっては、作成中のコンポーネントがリスト通知の購読に成功したとき、または接続が切れた場合に通知の受け取りが必要になることがあります。 これにより、UI を通じてユーザーに接続を通知できるようになります。

リスト サブスクリプション API では、サブスクリプションの状態に応答するために実装できる 2 つの追加コールバックが公開されます。 次のコードは、サブスクリプションの成立時と切断時にコンポーネントに通知する事例を示しています。

private createListSubscription(): void {
  this._listSubscriptionFactory.createSubscription({
    domain: this.properties.siteDomain,
    siteId: Guid.parse(this.properties.siteId),
    webId: Guid.parse(this.properties.webId),
    listId: Guid.parse(this.properties.listId),
    callbacks: {
      notification: this._loadDocuments.bind(this),
      connect: this._subscriptionConnected.bind(this),
      disconnect: this._subscriptionDisconnected.bind(this)
    }
  });
}

private _subscriptionConnected(): void {
  // code to execute when the subscription to the list has been established
}

private _subscriptionDisconnected(reason: string): void {
  // code to execute when the connection to the list has been disconnected
}

callbacks.disconnect コールバックのメソッドでは、接続が切断された理由を引数として渡します。 有効な値は、クライアントによって接続が切断された場合の io server disconnect、またはサーバーが接続を閉じた場合の io client disconnect です。

考慮事項

  • すべてのSharePoint Framework コンポーネントでリスト サブスクリプション機能を使用できます
  • ライブラリとリストからイベントをサブスクライブできます
  • 変更とコンポーネントによって受信される通知の間に数秒の遅延があります
  • コンポーネントは、複数のドキュメント ライブラリの変更をサブスクライブできます
  • 変更の通知は、追加または変更されたドキュメントに関する一切の情報を渡しません。 変更内容を確認するには、SharePoint REST API または Microsoft Graph を使用します。

関連項目