Webhook の使用

SharePoint Embedded を使用して Webhook を設定する

Webhook は、トリガーがアクティブ化されたときにアプリケーションによって送信される自動メッセージです。 SPE で使用すると、ワークフローの自動化、システムの統合、リアルタイムでのイベントへの応答を実現できます。

Webhook を使用して、既存のファイルが更新されたとき、または新しいファイルがアップロードされるたびに、アプリケーションから Azure Cognitive Services APIsを呼び出します。

現在の SharePoint Embedded アプリケーションで Webhook を設定するには、次の手順を実行する必要があります。

1. Webhook エンドポイントを作成して登録し、コンテナーに変更がある場合は常に通知を受け取ります。 これは REST API を使用して行われます。
2. Graph に接続し、変更をサブスクライブします。 アプリケーションをインターネットに公開するには、ローカルで実行するか、クラウドにデプロイします。 このチュートリアルでは、ngrok を利用し、POST 呼び出しを行って変更をサブスクライブすることで、前者を採用します。
3. Webhook データを処理して、必要なアクションを実行します。 このようなユース ケースの 1 つは、「 Azure Cognitive Services でのドキュメント処理の有効化」チュートリアルで説明されています。

ヒント

このチュートリアルで使用される Microsoft Graph API の詳細については、「 サブスクリプションの作成」を参照してください。

Webhook を作成して登録する

index.ts ファイルを開き、エンドポイント onReceiptAddedを追加します。

server.post('/api/onReceiptAdded', async (req, res, next) => {
  try {
    const response = await onReceiptAdded(req, res);
    res.send(200, response)
  } catch (error: any) {
    res.send(500, { message: `Error in API server: ${error.message}` });
  }
  next();
});

また、サーバーの起動時に実行されるように、このファイルの先頭にクエリ パーサー プラグインを追加する必要があります。

server.use(restify.plugins.bodyParser(), restify.plugins.queryParser());

onReceiptAdded.tsを作成し、メソッド onReceiptAddedを実装してvalidationTokenとdriveIdを読み取る。 validationToken は、Webhook サブスクリプションの作成時にエンドポイントを確認するために Microsoft Graph が 1 回限りの呼び出しを行う場合に必要です。 driveId は、サブスクリプションが作成されるコンテナー ID です。

require('isomorphic-fetch');

export const onReceiptAdded = async (req: Request, res: Response) => {

  const validationToken = req.query['validationToken'];
  if (validationToken) {
    res.send(200, validationToken, {"Content-Type":"text/plain"});
    return;
  }

  const driveId = req.query['driveId'];
  if (!driveId) {
    res.send(200, "Notification received without driveId, ignoring", {"Content-Type":"text/plain"});
    return;
  }

  console.log(`Received driveId: ${driveId}`);

  res.send(200, "");
  return;
}

Graph に接続して変更をサブスクライブする

ドキュメントに従って、ngrok を使用してバックエンド サーバーのトンネルを作成します。

アプリを起動したら、ターミナルで次のコマンドを実行します。

ngrok http 3001

正常に完了すると、次の出力が表示されます。 アプリのパブリック向けエンドポイントは、赤い四角形で強調表示されています。

トンネリングがアクティブになると、webhook URL を追加することで、コンテナー内の差分変更をサブスクライブできます。 これを行うには、Postman を開き、適切なグラフ アクセス トークンを使用して次のPOST要求を行い、driveIdをクエリ パラメーターとして追加してnotificationUrlして、目的のコンテナーでのみ変更の通知を受け取るようにします。

POST  https://graph.microsoft.com/v1.0/subscriptions
{
  "changeType": "updated",
  "notificationUrl":"https://5ac2-2404-f801-8028-3-691a-87b2-d309-545b.ngrok-free.app/api/onReceiptAdded?driveId={{ContainerId}}",
  "resource": "drives/{{ContainerId}}/root",
  "expirationDateTime": "2024-01-20T03:58:34.088Z",
  "clientState": ""
}

次のコード スニペットを使用して、現在の時刻から可能な最大有効期限を 4230 分に設定するには、これを [事前要求スクリプト] セクションに追加します。 要求本文で使用できる環境変数が設定されます。

var now = new Date()
var duration = 1000 * 60 * 4230; // max lifespan of driveItem subscription is 4230 minutes
var expiry = new Date(now.getTime() + duration);
var expiryDateTime = expiry.toISOString();

pm.environment.set("ContainerSubscriptionExpiry", expiryDateTime);

この時点で、コンテナー内のファイルを追加または更新すると、以前に追加したエンドポイント (/api/onReceiptAdded) に通知が表示され、コンソールにログ メッセージが表示されます。 Received driveId: <containerId>