通知リストの購読Subscribe to list notifications

SharePoint Framework v1.7.0 以降では、SharePoint ドキュメント ライブラリに保存されているファイルへの変更についての購読が可能です。Starting from SharePoint Framework v1.7.0, you can subscribe to changes to files stored in a SharePoint Document Library. これにより、ライブラリのコンテンツを定期的にポーリングすることなく、変更があったときに対応できるようになります。This allows you to respond to changes when they happen, without having to regularly poll the contents of the library.

重要

この機能は現在プレビュー段階であり、変更される可能性があります。This feature is currently in preview and is subject to change. 運用環境での使用は、現在サポートされていません。It is not currently supported for use in production environments. SharePoint 開発ドキュメントの問題リストを使用して、この機能に関するフィードバックやご意見をお寄せください。Your feedback and input around this capability is welcome using the SharePoint Dev Docs issue list.

前提条件Prerequisites

SharePoint Framework のリスト サブスクリプション機能を使用するには、まず、@microsoft/sp-list-subscription npm パッケージをインストールする必要があります。To use the SharePoint Framework list subscription capability, you first need to install the @microsoft/sp-list-subscription npm package. これは、次のコード スニペットを使用して実行できます。You can do it using the following code snippet:

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

SharePoint ドキュメント ライブラリに保存されたドキュメントへの変更の通知を受け取るGet notified of changes to documents stored in a SharePoint Document Library

SharePoint ドキュメント ライブラリに保存されたファイルへの変更について購読するには、ListSubscriptionFactory クラスのインスタンスを作成します。To subscribe to changes to files stored in a SharePoint Document Library, create an instance of the ListSubscriptionFactory class. その後で、購読するドキュメント ライブラリの ID を渡して createSubscription メソッドを呼び出します。Next, call the createSubscription method passing the ID of the Document Library to which you want to subscribe. ドキュメント ライブラリが現在のサイト内にある場合は、ライブラリ ID を指定するだけでかまいません。If the Document Library is located in the current site, it's sufficient to specify just the library ID. 別のサイトやサイト コレクション内にある場合は、そのサイトの ID も指定する必要があります。If it's located in a different site or site collection, then you need to specify their ID's as well.

次に、現在のサイトにドキュメント ライブラリがある場合のリスト サブスクリプションの例を示します。Following, is an example of a list subscription for a Document Library located in the current site:

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 createListSubscription(): void {
    this._listSubscriptionFactory = new ListSubscriptionFactory(this);
    this._listSubscription = this._listSubscriptionFactory.createSubscription({
      listId: Guid.parse(this.properties.listId),
      callbacks: {
        notification: this._loadDocuments.bind(this)
      }
    });
  }

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

  // omitted for brevity
}

重要

現時点では、SharePoint ドキュメント ライブラリでの変更のみを購読できます。At this moment, you can subscribe only to changes in SharePoint Document Libraries. SharePoint リストでの変更を購読しようとすると、エラーが発生します。If you try to subscribe to changes in SharePoint List, you will get an error.

リスト サブスクリプションを作成するときに、callbacks.notification プロパティを使用する場合は、変更が発生したときに呼び出されるメソッドを指定する必要があります。When creating a list subscription, using the callbacks.notification property, you have to specify the method that should be called, when a change has been detected. このメソッドには引数がなく、実際の変更内容についてはセキュリティ上の理由から通知されません。The method doesn't have any arguments, and for security reasons, you don't get notified what has been changed exactly. ドキュメント ライブラリの最新のコンテンツを取得する場合は、構成済みのアクセス許可に準拠する SharePoint REST API または Microsoft Graph のどちらかを使用できます。To get the latest contents of the Document Library, adhering to the configured permissions, you can use either the SharePoint REST APIs or the Microsoft Graph.

追加の構成Additional configuration

ソリューションによっては、リスト通知の購読時に追加の構成の指定が必要になることがあります。Depending on your solution, you might need to provide additional configuration when subscribing to list notifications.

複数地域テナントのサイト コレクションに接続するConnect to a site collection in a multi-geography tenancy

複数地域テナントで SharePoint を使用する場合は、特定のサイト コレクションが存在するドメインを指定する必要があります。If you use SharePoint in a multi-geography tenancy, you need to provide the domain where the particular site collection lives in. これは、domain プロパティを使用することで可能になります。次に例を示します。You can do it, using the domain property, for example:

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)
  }
});

サブスクリプションの成立時またはキャンセル時に通知を受け取るGet notified when the subscription has been established or cancelled

場合によっては、作成中のコンポーネントがリスト通知の購読に成功したとき、または接続が切れた場合に通知の受け取りが必要になることがあります。In some cases, you might want to get notified when the component that you're building successfully subscribed to list notifications or if the connection has been broken. これにより、UI を通じてユーザーに接続を通知できるようになります。This would allow you to communicate the connection to the user through the UI.

リスト サブスクリプション API は、サブスクリプションの状態に対応するために実装できる 2 つの追加のコールバックを公開しています。The list subscription API, exposes two additional callbacks which you can implement to respond to the subscription status. 次のコードは、サブスクリプションの成立時と切断時にコンポーネントに通知する事例を示しています。The following code illustrates the case, where the component will be notified when the subscription has been established and when it was disconnected.

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 コールバックのメソッドでは、接続が切断された理由を引数として渡します。The method for the callbacks.disconnect callback passes as an argument the reason why the connection has been disconnected. 有効な値は、クライアントによって接続が切断された場合の io server disconnect、またはサーバーが接続を閉じた場合の io client disconnect です。The possible values are io server disconnect, when the connection has been broken by the client or io client disconnect when the server closed the connection.

考慮事項Considerations

  • Web パーツと拡張機能の両方でリスト サブスクリプション機能を使用できます。both web parts and extensions can use the list subscription capabilities
  • SharePoint ドキュメント ライブラリの通知についての購読のみが可能です。it is only possible to subscribe to notifications in SharePoint Document Libraries. SharePoint リストは、この機能を現時点でサポートしていません。SharePoint Lists don't support this capability at the moment
  • 変更があってからコンポーネントに通知されるまでに数秒間の遅延があります。there is a few seconds delay between the change and the notification being received by the component
  • コンポーネントは複数のドキュメント ライブラリの変更についての購読が可能です。components can be subscribe to changes in multiple Document Libraries
  • 変更の通知は、追加または変更されたドキュメントに関する一切の情報を渡しません。the change notification doesn't pass any information about the added or changed document. 変更内容を確認するには、SharePoint REST API または Microsoft Graph を使用します。To see what has changed, use the SharePoint REST API or Microsoft Graph

関連項目See also