SharePoint webhook の概要

[アーティクル]
04/08/2023

開発者は SharePoint webhook を使用して、SharePoint で発生する特定のイベントの通知をサブスクライブして受け取るアプリケーションを作成できます。イベントがトリガーされると、SharePoint からサブスクライバーに HTTP POST ペイロードが送信されます。 webhook は標準の HTTP サービス (Web API) なので、SharePoint アドインリモートイベントレシーバーで使用される Windows Communication Foundation (WCF) サービスに比べて、webhook の方が簡単に開発し、使用することができます。

現在、webhook は SharePoint リストアイテムに対してのみ有効です。 SharePoint リストアイテムの webhook では、所定の SharePoint リストやドキュメントライブラリのリストアイテムの変更に対応するイベントを扱います。 SharePoint webhook は単純な通知パイプラインを提供しているため、アプリケーションは、サービスをポーリングすることなく、SharePoint リストの変更内容に気付くことができます。詳細については、「SharePoint リストの webhook」を参照してください。

webhook を作成する

新しい SharePoint webhook を作成するには、SharePoint リストなど、特定の SharePoint リソースへの新しいサブスクリプションを追加します。

新しいサブスクリプションを作成するには、次の情報が必要です。

リソース。サブスクリプションを作成するリソースエンドポイント URL。たとえば、SharePoint List API URL などです。
サーバー通知 URL。サービスエンドポイントの URL。指定されたリソースでイベントが発生すると、SharePoint は HTTP POST をこのエンドポイントに送信します。
有効期限。サブスクリプションの有効期限。有効期限は 180 日を超えてはなりません。既定では、サブスクリプションは作成時から 180 日で期限切れになるよう設定されています。

必要に応じて次の情報を含めることもできます。

クライアントの状態。すべての通知でクライアントに送り返される不透明文字列。これは通知の検証、さまざまなサブスクリプションのタグ付け、またはその他の理由で使用できます。

webhook 検証要求の処理

新しいサブスクリプションが作成されると、SharePoint は通知 URL が webhook 通知の受信をサポートしているかどうかを検証します。この検証は、サブスクリプション作成の要求時に実行されます。サブスクリプションが作成されるのは、サービスが検証トークンを伴ってタイムリーに応答した場合だけです。

検証要求の例

新しいサブスクリプションが作成されると、SharePoint は、登録されている URL に次の例のような形式で HTTP POST 要求を送信します。

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

応答

サブスクリプションが正常に作成されるには、サービスが要求に応答して、validationtoken クエリ文字列パラメーターの値をプレーンテキスト応答として返す必要があります。

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

{randomString}

アプリケーションが 200 以外の状態コードを返す場合、または validationtoken パラメーターの値で応答できない場合、新しいサブスクリプションの作成要求は失敗します。

通知の受け取り

通知のペイロードは、所定のサブスクリプションの所定のリソースでイベントが発生したことをアプリケーションに通知します。あるリソースで同じ期間内に複数の変更が発生した場合、アプリケーションに対する複数の通知が 1 つの要求にまとめられることがあります。

サブスクリプションの作成時にクライアントの状態を使用した場合は、それも通知のペイロードの本文に含まれます。

webhook 通知リソース

通知リソースは、登録されている通知 URL に SharePoint webhook 通知要求が送信されるときにサービスに提供されるデータの形状を定義します。

JSON 表記

サービスによって生成されるそれぞれの通知は、webhookNotifiation インスタンスにシリアル化されます。

{
    "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 つのオブジェクトにまとめられます。

{
   "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"
      }
   ]
}

プロパティ

プロパティ名	種類	説明
resource	String	サブスクリプションの登録先リストの一意識別子。
subscriptionId	String	サブスクリプションリソースの一意識別子。
clientState	文字列 - 省略可	このサブスクリプションへの通知メッセージに入れて送り返されるオプションの文字列値。
expirationDateTime	DateTime	サブスクリプションが更新されなかった場合に期限切れになる日時。
tenantId	String	この通知を生成したテナントの一意識別子。
siteUrl	String	サブスクリプションの登録先サイトのサーバーの相対 URL。
webId	String	サブスクリプションの登録先 Web の一意識別子。

通知の例

サービス通知 URL への HTTP 要求の本文には、webhook 通知が含まれます。次の例では、1 つの通知を持つペイロードを示します。

{
   "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 を使用する必要があります。

イベントの種類

SharePoint webhooks では、非同期イベントのみをサポートしています。つまり、webhook が起動するのは変更が起こった後だけであり (-ed イベントと類似)、同期 (-ing イベント) は不可能です。

エラー処理

アプリケーションへの通知の送信中にエラーが発生すると、SharePoint は 5 回まで通知の配信を再試行します。 HTTP 状態コードが 200 から 299 の範囲にない応答や、タイムアウトした応答は、5 分後に再試行されます。 5 回実行しても要求が成功しない場合、通知は破棄されます。将来の通知はその後もアプリケーションに対して試行されます。

有効期限

expirationDateTime 値が指定されない場合、webhook サブスクリプションは既定で 180 日後に期限切れになるよう設定されます。

サブスクリプションを作成する場合は、有効期限を設定する必要があります。有効期限は 180 日未満にする必要があります。アプリケーションは、サブスクリプションを定期的に更新して、アプリケーションの必要に合わせて有効期限に対処しなければなりません。

再試行のメカニズム

SharePoint でイベントが発生し、(メンテナンスなどにより) サービスエンドポイントに到達できない場合、SharePoint は通知を送信し直します。 SharePoint は再試行を実行し、5 分間隔で 5 回試行します。何らかの理由でそれより長い時間に渡ってサービスが停止する場合、サービスが利用できなかった間に失われた変更は、次回、サービスが稼動中に SharePoint から呼び出されたとき、GetChanges() の呼び出しによって復元されます。

次の方法で共有