SharePoint でリモート イベント レシーバーを使用するUse remote event receivers in SharePoint

リモート イベント レシーバーは、SharePoint アドイン モデルでイベントを処理するために使用します。AppInstalled および AppUninstalling イベントを使用すると、アドインに必要な SharePoint オブジェクトとその他のイベント レシーバーをセットアップまたは削除できます。Use remote event receivers to handle events in the SharePoint add-in model. Use AppInstalled and AppUninstalling events to set up or remove SharePoint objects and other event receivers your add-in needs.

**適用対象: **SharePoint 用アドイン | SharePoint 2013 | SharePoint OnlineApplies to: add-ins for SharePoint | SharePoint 2013 | SharePoint Online

重要 2017 年 1 月時点で、SharePoint Online は、"-ed" リモート イベント レシーバーの代わりに使用できるリスト Webhook をサポートしています。Important As of January 2017 SharePoint Online does support list webhooks which you can use instead of "-ed" remote event receivers. Webhook の詳細については、「SharePoint Webhook の概要」をご確認ください。Checkout Overview of SharePoint webhooks to learn more about webhooks. また、sp-dev-samples GitHub リポジトリからいくつかの Webhook サンプルを入手することもできます。Also note that several webhook samples are available from the sp-dev-samples GitHub repository.

Core.EventReceivers サンプルでは、プロバイダー向けのホスト型アドインを使用してリモート イベント レシーバーで AppInstalled イベントおよび AppUninstalling イベントを処理する方法を紹介します。AppInstalled イベントおよび AppUninstalling イベントでは、アドインが実行時に使用する SharePoint オブジェクトをセットアップおよび削除します。さらに、AppInstalled イベント ハンドラーでは、ItemAdded イベント ハンドラーをリストに追加します。このソリューションは、以下の操作を行うために使用してください。The Core.EventReceivers sample shows how to use a provider-hosted add-in with a remote event receiver to handle the AppInstalled and AppUninstalling events. The AppInstalled and AppUninstalling events set up and remove SharePoint objects that the add-in uses when it runs. Additionally, the AppInstalled event handler adds the ItemAdded event handler to a list. Use this solution if you want to:

  • アドインの初めての実行時に AppInstalled イベントを使用して構成を行い、さまざまな SharePoint オブジェクトや、アドインで処理する追加のイベント レシーバーをセットアップします。Configure your add-in on first run using the AppInstalled event to set up various SharePoint objects or additional event receivers that your add-in works with.

  • 完全に信頼されたコード ソリューションを使用して実装したイベント レシーバーと置き換えます。完全に信頼されたコード ソリューションでは、SharePoint サーバー上でイベント レシーバーを実行できます。新しい SharePoint アドイン モデルでは、SharePoint サーバー上でイベント レシーバーを実行できないため、リモート イベント レシーバーは Web サーバー上に実装する必要があります。Replace event receivers implemented using fully trusted code solutions. In fully trusted code solutions, you can run event receivers on the SharePoint server. In the new SharePoint add-in model, because you cannot run the event receiver on the SharePoint server, you need to implement a remote event receiver on a web server.

  • SharePoint で発生する変更の通知を受信します。たとえば、新しいアイテムがリストに追加されたときタスクを実行する場合に利用できます。Receive notifications of changes occuring in SharePoint. For example, when a new item is added to a list, you want to perform a task.

  • 変更ログのソリューションを補完します。リモート イベント レシーバー パターンを変更ログ パターンと一緒に使用すると、SharePoint コンテンツ データベース、サイト コレクション、サイト、またリストに加えられたすべての変更を処理する、さらに信頼性の高いアーキテクチャが提供されます。リモート イベント レシーバーは即座に実行されますが、リモート サーバー上で実行されているため、通信エラーが発生する可能性があります。変更ログ パターンによりすべての変更が処理可能な状態に保持されますが、アプリケーションによる変更の処理は、通常、スケジュールに従って (たとえば、タイマー ジョブとして) 実行されます。これは、変更が即座には処理されないことを意味します。これら 2 つのパターンを一緒に使用すれば、同じ変更を 2 回処理する可能性を確実に回避するメカニズムを使用できます。詳細については、「ChangeQuery と ChangeToken で SharePoint の変更ログを照会する」を参照してください。Complement your change log solution. Using the remote event receiver pattern with a change log pattern provides a more reliable architecture for handling all changes made to SharePoint content databases, site collections, sites, or lists. Remote event receivers run immediately, but because they run on a remote server, you might encounter a communication failure. The change log pattern ensures that all changes are available for processing, but the application processing the changes usually runs on a schedule (for example, a timer job). This means that changes are not processed immediately. If you use these two patterns together, ensure you use a mechanism to prevent processing the same change twice. For more information, see Query SharePoint change log with ChangeQuery and ChangeToken.

注意

SharePoint ホスト型アドインは、リモート イベント レシーバーをサポートしていません。SharePoint-hosted add-ins do not support remote event receivers. リモート イベント レシーバーを使用するには、プロバイダー向けのホスト型アドインを使用する必要があります。To use remote event receivers, you need to use a provider-hosted add-in. リモート イベント レシーバーは、同期のシナリオや、長時間実行するプロセスのために使用するべきではありません。You should not use remote event receivers for synchronization scenarios, or for long running processes. 詳細については、アドイン イベント レシーバーの作成方法に関する記事をご覧ください。For more information, see How to: Create an add-in event receiver.

はじめにBefore you begin

まず GitHub の Office 365 Developer Patterns and Practices プロジェクトから、Core.EventReceivers サンプル アドインをダウンロードします。To get started, download the Core.EventReceivers sample add-in from the Office 365 Developer patterns and practices project on GitHub.

このアドインを実行する前に、次の手順を実行します。Before you run this add-in, do the following:

  1. Core.EventReceivers プロジェクトのプロパティで、[アプリのハンドルがインストールされました] および [アプリのハンドルをアンインストール中]True に設定されていることを確認します。[アプリのハンドルがインストールされました] および [アプリのハンドルをアンインストール中]True に設定すると、AppInstalled および AppUninstalling の各イベントに対するイベント ハンドラーを定義する WCF サービスが作成されます。Core.EventReceivers で、AppManifest.xml のショートカット メニューを開き (右クリック)、[プロパティ] を選択します。InstalledEventEndpoint および UninstallingEventEndpointAppInstalled および AppUninstalling の各イベントを処理するリモート イベント レシーバーをポイントします。In the properties on the Core.EventReceivers project, verify that Handle App Installed and Handle App Uninstalling is set to True. Setting Handle App Installed and Handle App Uninstalling to True creates a WCF service that defines the event handler for the AppInstalled and AppUninstalling event. In Core.EventReceivers, open the shortcut menu (right-click) on AppManifest.xml, and choose Properties. The InstalledEventEndpoint and UninstallingEventEndpoint point to the remote event receiver that handles the AppInstalled and AppUninstalling events.

  2. リモート イベント レシーバーをホスト Web 内のオブジェクトにアタッチするには、通常、そのオブジェクトに対してのみ [管理] アクセス許可が必要です。たとえば、イベント レシーバーを既存のリストにアタッチする場合、アドインにはその [リスト] に対してのみ [管理] アクセス許可が必要です。このコード サンプルでは、リストを追加し、ホスト Web 上の機能をアクティブ化するため、[Web] に対する [管理] アクセス許可が必要です。Web に対して管理アクセス許可を設定するには、次のようにします。Attaching a remote event receiver to an object in the host web usually requires Manage permission for that object only. For example, when attaching an event receiver to an existing list, the add-in requires Manage permission on the List only. This code sample requires Manage permissions on the Web because it adds a list and activates a feature on the host web. To set manage permissions on the web:

    1. Core.EventReceivers\AppManifest.xml をダブルクリックします。Double click Core.EventReceivers\AppManifest.xml.

    2. [アクセス許可] を選択します。Choose Permissions.

    3. [スコープ][Web] に設定され、[アクセス許可][管理] に設定されていることを確認します。Verify that Scope is set to Web, and Permission is set to Manage.

  3. このコード例を実行するには、Azure サブスクリプションが必要です。試用をサインアップするには、1 か月間の無料評価版をご利用ください。To run this code sample, you need an Azure subscription. To sign up for a trial, see Free one-month trial.

  4. Azure Service Bus の名前空間を作成します。Create an Azure Service Bus Namespace.

    1. サービス バス名前空間を作成する」の手順を実行します。Carry out the instructions in Create a Service Bus namespace.

    2. プライマリ接続文字列を、作成したばかりのサービス バス名前空間からコピーします。Copy Primary Connection String from the just created Service Bus Namespace

    3. Visual Studio に戻ります。Return to Visual Studio.

    4. Core.EventReceivers を右クリックし、[プロパティ] > [SharePoint] とクリックします。Right-click Core.EventReceivers > Properties > SharePoint.

    5. [Microsoft Azure Service Bus 経由でのデバッグを有効にする] を選択します。Select Enable debugging via Microsoft Azure Service Bus.

    6. [Microsoft Azure Service Bus 接続文字列] に接続文字列を貼り付けます。In Microsoft Azure Service Bus connection string, paste the Connection String.

    7. [保存] を選択します。Choose Save.

  5. コード サンプルを実行し、次の追加の手順を実行します。Run the code sample, and perform the following additional steps:

    • [アプリへのアクセス許可の付与] ウィンドウの [信頼する] をクリックします。Click Trust It in the Grant permissions to the app window.

    • [アプリへのアクセス許可の付与] ウィンドウを閉じます。Close the Grant permissions to the app window.

    • アドインと WCF サービスのインストールが完了すると、ブラウザーが開きます。When installation of the add-in and WCF service is completed, your browser will open.

    • Office 365 サイトにサインインします。Core.EventReceivers アドインのスタート ページが表示されます。Sign in to your Office 365 site. The start page of the Core.EventReceivers add-in is displayed.

Core.EventReceivers アドインを使用するUse the Core.EventReceivers add-in

Core.EventReceivers コード サンプルのデモを見るには、次の手順を実行します。To see a demo of the Core.EventReceivers code sample:

  1. サンプルを実行し、スタート ページで [サイトに戻る] を選択します。Run the sample, and on the start page, choose Back to Site.

  2. [サイト コンテンツ] を選択します。Choose Site Contents.

  3. [Remote Event Receiver Jobs] (リモート イベント レシーバーのジョブ) を選択します。Choose Remote Event Receiver Jobs.

  4. [new item] (新しいアイテム) を選択します。Choose new item.

  5. [Title] (タイトル) に「Contoso」と入力し、[Description] (説明) に「Contoso test」と入力します。In Title, enter Contoso, and in Description enter Contoso test.

  6. リストに戻り、ページを更新します。Return to the list and refresh the page.

  7. 新しく追加されたアイテムの説明が「Contoso test Updated by ReR 192336」に更新されたことを確認します (192336 はタイムスタンプ)。Verify that the description of the newly added item was updated to Contoso test Updated by ReR 192336, where 192336 is a timestamp.

Services/AppEventReceiver.cs では、AppEventReceiverIRemoteEventService インターフェイスを実装します。このコード サンプルでは、同期イベントを使用するため、 ProcessEvent メソッドの実装を提供しています。非同期イベントを使用する場合は、 ProcessOneWayEvent メソッドの実装を提供する必要があります。In Services/AppEventReceiver.cs, AppEventReceiver implements the IRemoteEventService interface. This code sample provides an implementation for the ProcessEvent method because it uses synchronous events. If you use asynchronous events, you need to provide an implementation for the ProcessOneWayEvent method.

ProcessEvent は、次の SPRemoteEventType リモート イベントを処理します。The ProcessEvent handles the following SPRemoteEventType remote events:

  • アドインをインストールするときの AppInstalled イベント。AppInstalled イベントが発生すると、ProcessEventHandleAppInstalled を呼び出します。AppInstalled events when installing the add-in. When an AppInstalled event occurs, ProcessEvent calls HandleAppInstalled.

  • アドインをアンインストールするときの AppUninstalling イベント。AppUninstalling イベントが発生すると、ProcessEventHandleAppUninstalling を呼び出します。AppUninstalling イベントが実行されるのは、ユーザーがアドインを完全に削除した時点のみです。エンドユーザーの場合はサイトのごみ箱からアドインを削除した時、開発者の場合は [テスト中アプリ] の一覧からアドインを削除した時です。AppUninstalling events when uninstalling the add-in. When an AppUninstalling event occurs, ProcessEvent calls HandleAppUninstalling. The AppUninstalling event only runs when a user completely removes the add-in either by deleting the add-in from the site recycle bin (for end users) or by removing the add-in from the Apps in testing list (for developers).

  • リストにアイテムが追加された時の ItemAdded イベント。ItemAdded イベントが発生すると、ProcessEventHandleItemAdded を呼び出します。ItemAdded events when an item is added to a list. When an ItemAdded event occurs, ProcessEvent calls HandleItemAdded.

注意

Core.EventReceiver プロジェクトのプロパティでは、[アプリのハンドルがインストールされました] プロパティと [アプリのハンドルをアンインストール中] プロパティのみを使用できます。In the Core.EventReceiver project properties, only Handle App Installed and Handle App Uninstalling properties are available. このコード サンプルでは、アドインのインストール中に AppInstalled イベントを使用してホスト Web 上のリストに ItemAdded イベント ハンドラーを追加する方法を示しています。This code sample shows how you can add the ItemAdded event handler to a list on the host web by using the AppInstalled event during add-in installation.

注意

この記事で提供されるコードは、明示または黙示のいかなる種類の保証なしに現状のまま提供されるものであり、特定目的への適合性、商品性、権利侵害の不存在についての暗黙的な保証は一切ありません。The code in this article is provided as-is, without warranty of any kind, either express or implied, including any implied warranties of fitness for a particular purpose, merchantability, or non-infringement.

public SPRemoteEventResult ProcessEvent(SPRemoteEventProperties properties)
        {

            SPRemoteEventResult result = new SPRemoteEventResult();

            switch (properties.EventType)
            {
                case SPRemoteEventType.AppInstalled:
                    HandleAppInstalled(properties);
                    break;
                case SPRemoteEventType.AppUninstalling:
                    HandleAppUninstalling(properties);
                    break;
                case SPRemoteEventType.ItemAdded:
                    HandleItemAdded(properties);
                    break;
            }


            return result;
        }

HandleAppInstalled は、RemoteEventReceiverManager.cs 内の RemoteEventReceiverManager.AssociateRemoteEventsToHostWeb を呼び出します。HandleAppInstalled calls RemoteEventReceiverManager.AssociateRemoteEventsToHostWeb in RemoteEventReceiverManager.cs.

 private void HandleAppInstalled(SPRemoteEventProperties properties)
        {
            using (ClientContext clientContext =
                TokenHelper.CreateAppEventClientContext(properties, false))
            {
                if (clientContext != null)
                {
                    new RemoteEventReceiverManager().AssociateRemoteEventsToHostWeb(clientContext);
                }
            }
        }

AssociateRemoteEventsToHostWeb は、Core.EventReceivers アドインが使用するさまざまな SharePoint オブジェクトを作成または有効にします。要件によっては、異なる動作が必要になります。AssociateRemoteEventsToHostWeb は次の処理を実行します。AssociateRemoteEventsToHostWeb creates or enables various SharePoint objects that the Core.EventReceivers add-in uses. Your requirements might differ. AssociateRemoteEventsToHostWeb does the following:

  • Web.Features.Add を使用することにより、プッシュ通知機能を有効にします。Enables the Push Notification feature by using Web.Features.Add.

  • clientContext オブジェクトを使用してリストを検索します。リストが存在しない場合は、 CreateJobsList でリストを作成します。リストが存在する場合は、List.EventReceivers を使用して、ItemAddedEvent という名前の既存のイベント レシーバーを検索します。Uses the clientContext object to search for a list. If the list does not exist, CreateJobsList creates the list. If the list exists, List.EventReceivers is used to search for an existing event receiver whose name is ItemAddedEvent.

  • ItemAddedEvent イベント レシーバーが存在しない場合は、次の処理を実行します。If the ItemAddedEvent event receiver does not exist:

    • EventReceiverDefinitionCreationInformation オブジェクトの新しいインスタンスを作成して、新しいリモート イベント レシーバーを作成します。ItemAdded イベント レシーバー タイプを EventReceiverDefinitionCreationInformation.EventType に追加します。Instantiates a new EventReceiverDefinitionCreationInformation object to create the new remote event receiver. The ItemAdded event receiver type is added to EventReceiverDefinitionCreationInformation.EventType.

    • EventReceiverDefinitionCreationInformation.ReceiverURLAppInstalled リモート イベント レシーバーの URL を設定します。Sets the EventReceiverDefinitionCreationInformation.ReceiverURL to the URL of the AppInstalled remote event receiver.

    • List.EventReceivers.Add を使用して、新しいイベント レシーバーをリストに追加します。Adds a new event receiver to the list using List.EventReceivers.Add.

public void AssociateRemoteEventsToHostWeb(ClientContext clientContext)
        {
            // Add Push Notification feature to host web.
            // Not required but it is included here to show you
            // how to activate features.
            clientContext.Web.Features.Add(
                     new Guid("41e1d4bf-b1a2-47f7-ab80-d5d6cbba3092"),
                     true, FeatureDefinitionScope.None);


            // Get the Title and EventReceivers lists.
            clientContext.Load(clientContext.Web.Lists,
                lists => lists.Include(
                    list => list.Title,
                    list => list.EventReceivers).Where
                        (list => list.Title == LIST_TITLE));

            clientContext.ExecuteQuery();

            List jobsList = clientContext.Web.Lists.FirstOrDefault();

            bool rerExists = false;
            if (null == jobsList)
            {
                // List does not exist, create it. 
                jobsList = CreateJobsList(clientContext);

            }
            else
            {
                foreach (var rer in jobsList.EventReceivers)
                {
                    if (rer.ReceiverName == RECEIVER_NAME)
                    {
                        rerExists = true;
                        System.Diagnostics.Trace.WriteLine("Found existing ItemAdded receiver at "
                            + rer.ReceiverUrl);
                    }
                }
            }

            if (!rerExists)
            {
                EventReceiverDefinitionCreationInformation receiver =
                    new EventReceiverDefinitionCreationInformation();
                receiver.EventType = EventReceiverType.ItemAdded;

                // Get WCF URL where this message was handled.
                OperationContext op = OperationContext.Current;
                Message msg = op.RequestContext.RequestMessage;
                receiver.ReceiverUrl = msg.Headers.To.ToString();

                receiver.ReceiverName = RECEIVER_NAME;
                receiver.Synchronization = EventReceiverSynchronization.Synchronous;

                // Add the new event receiver to a list in the host web.
                jobsList.EventReceivers.Add(receiver);
                clientContext.ExecuteQuery();

                System.Diagnostics.Trace.WriteLine("Added ItemAdded receiver at " + receiver.ReceiverUrl);
            }
        }

アイテムが Remote Event Receiver Jobs リストに追加されると、AppEventReceiver.svc.cs 内の ProcessEventItemAdded イベントを処理し、HandleItemAdded を呼び出します。HandleItemAdded は、RemoteEventReceiverManager.ItemAddedToListEventHandler を呼び出します。ItemAddedToListEventHandler は、追加されたリスト アイテムをフェッチし、リスト アイテムの説明に「Updated by ReR」という文字列を追加します。When an item is added to the Remote Event Receiver Jobs list, ProcessEvent in AppEventReceiver.svc.cs handles the ItemAdded event, and then calls HandleItemAdded. HandleItemAdded calls RemoteEventReceiverManager.ItemAddedToListEventHandler. ItemAddedToListEventHandler fetches the list item that was added, and adds the string Updated by ReR to the list item's description.

 public void ItemAddedToListEventHandler(ClientContext clientContext, Guid listId, int listItemId)
        {
            try
            {
                List photos = clientContext.Web.Lists.GetById(listId);
                ListItem item = photos.GetItemById(listItemId);
                clientContext.Load(item);
                clientContext.ExecuteQuery();

                item["Description"] += "\nUpdated by RER " +
                    System.DateTime.Now.ToLongTimeString();
                item.Update();
                clientContext.ExecuteQuery();
            }
            catch (Exception oops)
            {
                System.Diagnostics.Trace.WriteLine(oops.Message);
            }

        }

関連項目See also