Share via

webhook を使用してサービス間の通知を受信する

  • [アーティクル]

OneDrive では、webhook によりサービス間の通知が可能です。 webhook は、単純な通知パイプラインを提供することで、アプリがサービスをポーリングすることなく、ユーザーのドライブに対する変更を認識できるようにします。

アプリがアクセスするユーザーのドライブ内の項目に変更が行われると、指定の URL に変更の発生を通知する要求が送信されます。

一般的なタスク

タスク HTTP メソッド
新しいサブスクリプションを作成する POST /subscriptions
サブスクリプションの削除 DELETE /subscriptions/{id}
サブスクリプションを更新する PATCH /subscriptions/{id}

登録する

webhook を登録する場合は、変更について受信するスコープの最上位を表す項目に新しいサブスクリプションを追加します。

通知のための URL を登録する方法の詳細については、「新しいサブスクリプションを追加する」を参照してください。

通知のスコープ

webhook 通知は、次に示す条件を満たす変更に関してのみアプリに送信されます。

  • ユーザーが、アプリに OneDrive コンテンツへのアクセスを承認している。
  • アプリが、通知を生成する項目にアクセスできる。
  • サブスクリプションが失効していない。

アプリは、ユーザーのドライブ内のサインインしているユーザーと共有されている項目またはリモート項目に対する通知を受け取りません。ただし、それらの元の項目に対して個別のサブスクリプションが作成されている場合を除きます。

通知の受け取り

サブスクリプションが作成されると、OneDrive は、通知スコープに含まれる項目が変更されたときに、登録された URL に POST 要求を送信するようになります。 同じ期間内に複数のユーザーによる変更があった場合は、サービスへの複数の通知が 1 つの要求にまとめられることがあります。

通知の例

通知 URL に送信される HTTP 要求の本文には、次に示すような、Webhook 通知リソースが含まれます。

{
  "value": [
    {
      "subscriptionId": "A640DFF3-0429-44FC-AF7E-30523A476864",
      "expirationDateTime": "2017-02-22T16:00:00Z",
      "resource": "/me/drive/root",
      "clientState": "client-specific string"
    }
  ]
}

この通知には、通知をトリガーした変更に関する情報が一切含まれていない点に注目してください。 アプリには、delta 動詞を使用して OneDrive 内の項目の状態に対する変更を検出することと、次回送信される通知のために syncToken 値を保管することが求められます。

エラー処理

サービスへの通知の送信中にエラーが発生した場合、OneDrive は指数バックオフ ロジックに従います。 HTTP 状態コードが 200-299 の範囲にない応答、またはタイムアウトした応答は、直後の数分間でもう一度試みられます。 15 分経過しても要求が成功しない場合、通知は破棄されます。

その後もサービスへの通知が試行されますが、失敗の検出数が十分な数に達した場合、サービスはサブスクリプションを削除する権利を保有します。

有効期限

新しいサブスクリプションには、有効期限が自動的に指定されます (サブスクリプションの作成時に指定しなかった場合)。 既定では、サブスクリプションは作成時から 6 か月で期限切れになるよう設定されています。

ベスト プラクティス

webhook を使用する際には、いくつかの重要な考慮事項があります。

サービス間

webhook を使用してクライアント デバイスに直接通知しようとしないでください。 各アプリは、すべてのユーザーに対して呼び出される 1 つの webhook URL を持ちます。 この URL は、制御するサービスを指している必要があります。 サービスでは、通知メッセージを解析して、適切なプッシュ通知を必要に応じてクライアント アプリに転送できます。

迅速な応答

アプリが要求に応答するまでの時間には制限があります。 通知の更新に関する情報をキューに入れてから、それらの要求を個別のスレッドで処理する必要があります。 webhook 要求に応答する前に、OneDrive サービスから変更を取得しようとしないでください。

同時通知の予期

多くの状況で、同じユーザーについての通知を立て続けに複数回受信することがあります。 たとえば、ユーザーが大量のコンテンツを新規作成またはアップロードすると、最初の通知を処理する前に、同じユーザーについての複数の通知を受信する可能性があります。 webhook 通知への応答アクションは、この事例を適切に処理するようにしてください。