message: deltamessage: delta

指定したフォルダーで追加、削除、更新されたメッセージのセットを取得します。Get a set of messages that have been added, deleted, or updated in a specified folder.

フォルダー内のメッセージに対するデルタ関数呼び出しと GET 要求とは似ていますが、状態トークンをこれらの 1 つ以上の呼び出しに適切に適用することにより、そのフォルダーのメッセージの増分の変更をクエリできる点が異なります。これにより、ユーザーのメッセージのローカル ストアの保守と同期を行う際に、メッセージのセット全体を毎回サーバーからフェッチする必要がなくなります。A delta function call for messages in a folder is similar to a GET request, except that by appropriately applying state tokens in one or more of these calls, you can query for incremental changes in the messages in that folder. This allows you to maintain and synchronize a local store of a user's messages without having to fetch the entire set of messages from the server every time.

アクセス許可Permissions

この API を呼び出すには、次のいずれかのアクセス許可が必要です。アクセス許可の選択方法などの詳細については、「アクセス許可」を参照してください。One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Permissions.

アクセス許可の種類Permission type アクセス許可 (特権の小さいものから大きいものへ)Permissions (from least to most privileged)
委任 (職場または学校のアカウント)Delegated (work or school account) Mail.Read、Mail.ReadWriteMail.Read, Mail.ReadWrite
委任 (個人用 Microsoft アカウント)Delegated (personal Microsoft account) Mail.Read、Mail.ReadWriteMail.Read, Mail.ReadWrite
アプリケーションApplication Mail.Read、Mail.ReadWriteMail.Read, Mail.ReadWrite

HTTP 要求HTTP request

GET /me/mailFolders/{id}/messages/delta
GET /users/{id}/mailFolders/{id}/messages/delta

クエリ パラメーターQuery parameters

メッセージの変更を追跡すると、1 つ以上のデルタ関数呼び出しのラウンドが発生します。任意のクエリ パラメーター ($deltatoken$skiptoken 以外) を使用する場合は、最初のデルタ要求でこれを指定する必要があります。Microsoft Graph は、応答で提供される nextLinkdeltaLink の URL のトークン部分に指定したパラメーターを自動的にエンコードします。必要なクエリ パラメーターを前もって指定しておくだけで済みます。それ以降の要求では、前の応答で nextLinkdeltaLink の URL に必要なパラメーターが既にエンコードされ、含まれているため、この URL をコピーして適用するだけです。Tracking changes in messages incurs a round of one or more delta function calls. If you use any query parameter (other than $deltatoken and $skiptoken), you must specify it in the initial delta request. Microsoft Graph automatically encodes any specified parameters into the token portion of the nextLink or deltaLink URL provided in the response. You only need to specify any desired query parameters once upfront. In subsequent requests, simply copy and apply the nextLink or deltaLink URL from the previous response, as that URL already includes the encoded, desired parameters.

クエリ パラメーターQuery parameter 種類Type 説明Description
$deltatoken$deltatoken stringstring 同じメッセージ コレクションの前のデルタ関数呼び出しの deltaLink URL で状態トークンが返され、その変更追跡のラウンドが完了したことを示します。このコレクションについて、このトークンを含む、deltaLink URL 全体を次の変更追跡のラウンドの最初の要求に保存し、適用します。A state token returned in the deltaLink URL of the previous delta function call for the same message collection, indicating the completion of that round of change tracking. Save and apply the entire deltaLink URL including this token in the first request of the next round of change tracking for that collection.
$skiptoken$skiptoken stringstring 前のデルタ関数呼び出しの nextLink URL で状態トークンが返され、同じメッセージ コレクションに追跡すべき変更が他にもあることを示します。A state token returned in the nextLink URL of the previous delta function call, indicating there are further changes to be tracked in the same message collection.

OData クエリ パラメーターOData query parameters

  • 任意の GET リクエストと同様に $select クエリ パラメーターを使用して、最善のパフォーマンスを得るために必要なプロパティのみを指定することができます。Id プロパティは常に返されます。You can use a $select query parameter as in any GET request to specify only the properties your need for best performance. The id property is always returned.
  • デルタ クエリは、メッセージの $select$top、および $expand をサポートします。Delta query support $select, $top, and $expand for messages.
  • $filter$orderby に対するサポートには制限があります。There is limited support for $filter and $orderby:
    • サポートされている唯一の $filter 式は、$filter=receivedDateTime+ge+{value} または $filter=receivedDateTime+gt+{value} です。The only supported $filter expresssions are $filter=receivedDateTime+ge+{value} or $filter=receivedDateTime+gt+{value}.
    • サポートされている唯一の $orderby 式は、$orderby=receivedDateTime+desc です。$orderby 式を含めない場合、戻り値の順序は保証されません。The only supported $orderby expression is $orderby=receivedDateTime+desc. If you do not include an $orderby expression, the return order is not guaranteed.
  • $search はサポートされていません。There is no support for $search.

要求ヘッダーRequest headers

名前Name Type 説明Description
AuthorizationAuthorization stringstring ベアラー {トークン}。必須。Bearer {token}. Required.
Content-TypeContent-Type stringstring application/json. Required.application/json. Required.
PreferPrefer stringstring odata.maxpagesize={x}.省略可能。odata.maxpagesize={x}. Optional.

応答Response

成功した場合、このメソッドは 200 OK 応答コードと、応答本文で message コレクション オブジェクトを返します。If successful, this method returns a 200 OK response code and message collection object in the response body.

Example

要求Request

次の例に、デルタ関数呼び出しを 1 つ作成し、応答本文に含まれるメッセージの最大数を 2 に制限する方法を示します。The following example shows how to make a single delta function call, and limit the maximum number of messages in the response body to 2.

フォルダー内のメッセージの変更を追跡するには、1 つ以上のデルタ関数呼び出しを作成し、前回のデルタ クエリ以降になされた一連の増分の変更を取得します。デルタ クエリ呼び出しのラウンドを示す例については、「フォルダー内のメッセージへの増分の変更を取得する」をご覧ください。To track changes in the messages in a folder, you would make one or more delta function calls to get the set of incremental changes since the last delta query. For an example that shows a round of delta query calls, see Get incremental changes to messages in a folder.

GET https://graph.microsoft.com/v1.0/me/mailFolders/{id}/messages/delta
Prefer: odata.maxpagesize=2
応答Response

要求が成功すると、応答には状態トークンが含まれます。これは、skipTokenIf the request is successful, the response would include a state token, which is either a skipToken
(@odata.nextLink_ 応答ヘッダーに含まれる) か、deltaToken (@odata.deltaLink_ 応答ヘッダーに含まれる) のいずれかになります。前者はその回を続行する必要があることを示し、後者はその回のすべての変更の取得が完了したことを示します。(in an _@odata.nextLink_ response header) or a deltaToken (in an _@odata.deltaLink_ response header). Respectively, they indicate whether you should continue with the round or you have completed getting all the changes for that round.

以下の応答は、_@odata.nextLink_ 応答ヘッダーに含まれる skipToken を示しています。The response below shows a skipToken in an _@odata.nextLink_ response header.

注:簡潔にするために、ここに示す応答オブジェクトは切り詰められている場合があります。すべてのプロパティは実際の呼び出しから返されます。Note: The response object shown here may be truncated for brevity. All of the properties will be returned from an actual call.

HTTP/1.1 200 OK
Content-type: application/json
Content-length: 337

{
  "@odata.nextLink":"https://graph.microsoft.com/v1.0/me/mailfolders('{id}')/messages/delta?$skiptoken={_skipToken_}",
  "value": [
    {
      "receivedDateTime": "datetime-value",
      "sentDateTime": "datetime-value",
      "hasAttachments": true,
      "internetMessageId": "internetMessageId-value",
      "subject": "subject-value",
      "body": {
        "contentType": "contentType-value",
        "content": "content-value"
      }
    }
  ]
}

関連項目See also