SharePoint webhook の概要Overview of SharePoint webhooks

開発者は SharePoint webhook を使用して、SharePoint で発生する特定のイベントの通知をサブスクライブして受け取るアプリケーションを作成できます。SharePoint webhooks enable developers to build applications that subscribe to receive notifications on specific events that occur in SharePoint. イベントがトリガーされると、SharePoint からサブスクライバーに HTTP POST ペイロードが送信されます。When an event is triggered, SharePoint sends an HTTP POST payload to the subscriber. webhook は標準の HTTP サービス (Web API) なので、SharePoint アドイン リモート イベント レシーバーで使用される Windows Communication Foundation (WCF) サービスに比べて、webhook の方が簡単に開発し、使用することができます。Webhooks are easier to develop and consume than Windows Communication Foundation (WCF) services used by SharePoint Add-in remote event receivers because webhooks are regular HTTP services (web API).

現在、webhook は SharePoint リスト アイテムに対してのみ有効です。Currently webhooks are only enabled for SharePoint list items. SharePoint リスト アイテムの webhook では、所定の SharePoint リストやドキュメント ライブラリのリスト アイテムの変更に対応するイベントを扱います。SharePoint list item webhooks cover the events corresponding to list item changes for a given SharePoint list or a document library. SharePoint webhook は単純な通知パイプラインを提供しているため、アプリケーションは、サービスをポーリングすることなく、SharePoint リストの変更内容に気付くことができます。SharePoint webhooks provide a simple notification pipeline so that your application can be aware of changes to a SharePoint list without polling the service. 詳細については、「SharePoint リストの webhook」を参照してください。For more information, see SharePoint list webhooks.

webhook を作成するCreating webhooks

新しい SharePoint webhook を作成するには、SharePoint リストなど、特定の SharePoint リソースへの新しいサブスクリプションを追加します。To create a new SharePoint webhook, you add a new subscription to the specific SharePoint resource, such as a SharePoint list.

新しいサブスクリプションを作成するには、次の情報が必要です。The following information is required for creating a new subscription:

  • リソース。サブスクリプションを作成するリソースのエンドポイント URL (例: SharePoint リスト API の URL)。Resource. The resource endpoint URL you are creating the subscription for. For example, a SharePoint List API URL.
  • サーバー通知 URLServer notification URL. サービス エンドポイントの URL。Your service endpoint URL. 指定されたリソースでイベントが発生すると、SharePoint は HTTP POST をこのエンドポイントに送信します。SharePoint sends an HTTP POST to this endpoint when events occur in the specified resource.
  • 有効期限Expiration date. サブスクリプションの有効期限。The expiration date for your subscription. 有効期限は 180 日を超えてはなりません。The expiration date should not be more than 180 days. 既定では、サブスクリプションは作成時から 180 日で期限切れになるよう設定されています。By default, subscriptions are set to expire 180 days from when they are created.

必要に応じて次の情報を含めることもできます。You can also include the following information if needed:

  • クライアントの状態Client State. すべての通知でクライアントに送り返される不透明文字列。An opaque string passed back to the client on all notifications. これは通知の検証、さまざまなサブスクリプションのタグ付け、またはその他の理由で使用できます。You can use this for validating notifications, tagging different subscriptions, or other reasons.

webhook 検証要求の処理Handling webhook validation requests

新しいサブスクリプションが作成されると、SharePoint は通知 URL が webhook 通知の受信をサポートしているかどうかを検証します。When a new subscription is created, SharePoint validates whether the notification URL supports receiving webhook notifications. この検証は、サブスクリプション作成の要求時に実行されます。This validation is performed during the subscription creation request. サブスクリプションが作成されるのは、サービスが検証トークンを伴ってタイムリーに応答した場合だけです。The subscription is only created if your service responds in a timely manner back with the validation token.

検証要求の例Example validation request

新しいサブスクリプションが作成されると、SharePoint は、登録されている URL に次の例のような形式で HTTP POST 要求を送信します。When a new subscription is created, SharePoint sends an HTTP POST request to the registered URL in a format similar to the following example:

POST https://contoso.azurewebsites.net/your/webhook/service?validationtoken={randomString}
Content-Length: 0

応答Response

サブスクリプションが正常に作成されるには、サービスが要求に応答して、validationtoken クエリ文字列パラメーターの値をプレーンテキスト応答として返す必要があります。For the subscription to be created successfully, your service must respond to the request by returning the value of the validationtoken query string parameter as a plain-text response.

HTTP/1.1 200 OK
Content-Type: text/plain

{randomString}

アプリケーションが 200 以外の状態コードを返す場合、または validationtoken パラメーターの値で応答できない場合、新しいサブスクリプションの作成要求は失敗します。If your application returns a status code other than 200, or fails to respond with the value of the validationtoken parameter, the request to create a new subscription fails.

通知の受け取りReceiving notifications

通知のペイロードは、所定のサブスクリプションの所定のリソースでイベントが発生したことをアプリケーションに通知します。The notification payload informs your application that an event occurred in a given resource for a given subscription. あるリソースで同じ期間内に複数の変更が発生した場合、アプリケーションに対する複数の通知が 1 つの要求にまとめられることがあります。Multiple notifications to your application may be batched together into a single request if multiple changes occurred in the resource within the same time period.

サブスクリプションの作成時にクライアントの状態を使用した場合は、それも通知のペイロードの本文に含まれます。The notification payload body also contains your client state if you used it when creating the subscription.

webhook 通知リソースWebhook notification resource

通知リソースは、登録されている通知 URL に SharePoint webhook 通知要求が送信されるときにサービスに提供されるデータの形状を定義します。The notification resource defines the shape of the data provided to your service when a SharePoint webhook notification request is submitted to your registered notification URL.

JSON 表記JSON representation

サービスによって生成されるそれぞれの通知は、webhookNotifiation インスタンスにシリアル化されます。Each notification generated by the service is serialized into a webhookNotification instance:

{
    "subscriptionId":"91779246-afe9-4525-b122-6c199ae89211",
    "clientState":"00000000-0000-0000-0000-000000000000",
    "expirationDateTime":"2016-04-30T17:27:00.0000000Z",
    "resource":"b9f6f714-9df8-470b-b22e-653855e1c181",
    "tenantId":"00000000-0000-0000-0000-000000000000",
    "siteUrl":"/",
    "webId":"dbc5a806-e4d4-46e5-951c-6344d70b62fa"
}

複数の通知が 1 つの要求としてサービスに送信されることがあるため、複数の通知は 1 つの配列を持つ 1 つのオブジェクトにまとめられます。Because multiple notifications may be submitted to your service in a single request, these are combined together in an object with a single array value:

{
   "value":[
      {
         "subscriptionId":"91779246-afe9-4525-b122-6c199ae89211",
         "clientState":"00000000-0000-0000-0000-000000000000",
         "expirationDateTime":"2016-04-30T17:27:00.0000000Z",
         "resource":"b9f6f714-9df8-470b-b22e-653855e1c181",
         "tenantId":"00000000-0000-0000-0000-000000000000",
         "siteUrl":"/",
         "webId":"dbc5a806-e4d4-46e5-951c-6344d70b62fa"
      }
   ]
}

プロパティProperties

プロパティ名Property name 種類Type 説明Description
resourceresource String
String サブスクリプションの登録先リストの一意識別子。Unique identifier of the list where the subscription is registered.
subscriptionIdsubscriptionId StringString サブスクリプション リソースの一意識別子。The unique identifier for the subscription resource.
clientStateclientState 文字列 - 省略可String - optional このサブスクリプションへの通知メッセージに入れて送り返されるAn optional string value that is passed back in the notification. オプションの文字列値。message for this subscription.
expirationDateTimeexpirationDateTime DateTime
DateTime サブスクリプションが更新されなかった場合に期限切れになる日時。The date and time when the subscription expires if not updated or renewed.
tenantIdtenantId String
String この通知を生成したテナントの一意識別子。Unique identifier for the tenant that generated this notification.
siteUrlsiteUrl String
String サブスクリプションの登録先サイトのサーバーの相対 URL。Server relative URL of the site where the subscription is registered.
webIdwebId String
String サブスクリプションの登録先 Web の一意識別子。Unique identifier of the web where the subscription is registered.

通知の例Example notification

サービス通知 URL への HTTP 要求の本文には、webhook 通知が含まれます。The body of the HTTP request to your service notification URL contains a webhook notification. 次の例では、1 つの通知を持つペイロードを示します。The following example shows a payload with one notification:

{
   "value":[
      {
         "subscriptionId":"91779246-afe9-4525-b122-6c199ae89211",
         "clientState":"00000000-0000-0000-0000-000000000000",
         "expirationDateTime":"2016-04-30T17:27:00.0000000Z",
         "resource":"b9f6f714-9df8-470b-b22e-653855e1c181",
         "tenantId":"00000000-0000-0000-0000-000000000000",
         "siteUrl":"/",
         "webId":"dbc5a806-e4d4-46e5-951c-6344d70b62fa"
      }
   ]
}

これをトリガーした変更に関する情報は通知に含まれていません。アプリケーションが通知を受けたとき、変更ログから変更のコレクションのクエリを実行し、後続の呼び出し用に変更トークン値を保存するため、アプリケーションはリストに対して GetChanges API を使用する必要があります。The notification doesn't include any information about the changes that triggered it. Your application is expected to use the GetChanges API on the list to query the collection of changes from the change log and store the change token value for any subsequent calls when the application is notified.

イベントの種類Event types

SharePoint webhooks では、非同期イベントのみをサポートしています。つまり、webhook が起動するのは変更が起こった後だけであり (-ed イベントと類似)、同期 (-ing イベント) は不可能です。SharePoint webhooks only support asynchronous events. This means that webhooks are only fired after a change happened (similar to -ed events), and thus synchronous (-ing events) are not possible.

エラー処理Error handling

アプリケーションへの通知の送信中にエラーが発生すると、SharePoint は 5 回まで通知の配信を再試行します。If an error occurs while sending the notification to your application, SharePoint retries up to 5 times to deliver the notification. HTTP 状態コードが 200 から 299 の範囲にない応答や、タイムアウトした応答は、5 分後に再試行されます。Any response with an HTTP status code outside of the 200-299 range, or that times out, is attempted again 5 minutes later. 5 回実行しても要求が成功しない場合、通知は破棄されます。If the request is not successful after 5 attempts, the notification is dropped. 将来の通知はその後もアプリケーションに対して試行されます。Future notifications will still be attempted to your application.

有効期限Expiration

expirationDateTime 値が指定されない場合、webhook サブスクリプションは既定で 180 日後に期限切れになるよう設定されます。Webhook subscriptions are set to expire after 180 days by default if an expirationDateTime value is not specified.

サブスクリプションを作成する場合は、有効期限を設定する必要があります。有効期限は 180 日未満にする必要があります。アプリケーションは、サブスクリプションを定期的に更新して、アプリケーションの必要に合わせて有効期限に対処しなければなりません。You need to set an expiration date when creating the subscription. The expiration date should be less than 180 days. Your application is expected to handle the expiration date according to your application's needs by updating the subscription periodically.

再試行のメカニズムRetry mechanism

SharePoint でイベントが発生し、(メンテナンスなどにより) サービス エンドポイントに到達できない場合、SharePoint は通知を送信し直します。If an event occurs in SharePoint and your service endpoint is not reachable (for example, due to maintenance) SharePoint retries sending the notification. SharePoint は再試行を実行し、5 分間隔で 5 回試行します。SharePoint performs a retry of 5 times with a 5-minute wait time between the attempts. 何らかの理由でそれより長い時間に渡ってサービスが停止する場合、サービスが利用できなかった間に失われた変更は、次回、サービスが稼動中に SharePoint から呼び出されたとき、GetChanges() の呼び出しによって復元されます。If for some reason your service is down for a longer time, the next time it's up and gets called by SharePoint, the call to the GetChanges() recovers the changes that were missed when your service was not available.