chatMessage: delta

[アーティクル]
10/03/2024

名前空間: microsoft.graph

重要

Microsoft Graph の /beta バージョンの API は変更される可能性があります。実稼働アプリケーションでこれらの API を使用することは、サポートされていません。 v1.0 で API を使用できるかどうかを確認するには、Version セレクターを使用します。

1 対 1 のチャット、グループチャット、会議チャットなど、ユーザーが参加しているすべてのチャットからメッセージの一覧を取得します。デルタクエリを使用すると、新しいメッセージまたは更新されたメッセージを取得できます。

手記： Delta は、過去 8 か月以内にのみメッセージを返します。 GET /users/{id | user-principal-name}/chats/getAllMessages を使用して、古いメッセージを取得できます。デルタクエリでは、ユーザーが参加しているすべてのチャットからすべてのメッセージを取得する完全同期と、最後の同期以降に追加または変更されたメッセージを取得する増分同期の両方がサポートされています。通常、最初の完全同期を行い、そのメッセージビューに対する増分変更を定期的に取得します。

メッセージの応答を取得するには、リストメッセージ応答またはメッセージ応答の取得操作を使用します。

デルタ関数を持つ GET 要求は、次のいずれかを返します。

デルタ関数呼び出しとskipTokenを含む URL を含む @odata.nextLink。
デルタ関数呼び出しとdeltaTokenを含む URL を含む @odata.deltaLink。

状態トークンはクライアントに対して不透明です。変更追跡のラウンドを続行するには、最後の GET 要求から返された @odata.nextLink URL または @odata.deltaLink URL をコピーして次の デルタ 関数呼び出しに適用します。応答で返される @odata.deltaLink は、現在の変更追跡のラウンドが完了したことを示します。変更の取得を開始するときに 、@odata.deltaLink URL を保存して使用できます ( @odata.deltaLink を取得した後にメッセージが変更または投稿されます)。

詳細については、デルタクエリに関するドキュメントを参照してください。

この API は、次の国内クラウド展開で使用できます。

グローバルサービス	米国政府機関 L4	米国政府機関 L5 (DOD)	21Vianet が運営する中国
✅	✅	✅	✅

アクセス許可

この API の最小特権としてマークされているアクセス許可またはアクセス許可を選択します。アプリで必要な場合にのみ、より高い特権のアクセス許可またはアクセス許可を使用します。委任されたアクセス許可とアプリケーションのアクセス許可の詳細については、「アクセス許可の種類」を参照してください。これらのアクセス許可の詳細については、「アクセス許可のリファレンス」を参照してください。

アクセス許可の種類	最小特権アクセス許可	より高い特権のアクセス許可
委任 (職場または学校のアカウント)	サポートされていません。	サポートされていません。
委任 (個人用 Microsoft アカウント)	サポートされていません。	サポートされていません。
Application	Chat.Read.All	Chat.ReadWrite.All

HTTP 要求

GET /users/{id | user-principal-name}/chats/getAllMessages/delta

クエリパラメーター

メッセージの変更を追跡すると、1 つ以上の デルタ 関数呼び出しのラウンドが発生します。任意のクエリパラメーター ($deltatoken と$skiptoken以外) を使用する場合は、最初のデルタ要求でこれを指定する必要があります。 Microsoft Graph は、指定したパラメーターを応答で指定された @odata.nextLink または @odata.deltaLink URL のトークン部分に自動的にエンコードします。

クエリパラメーターは 1 回だけ指定する必要があります。

後続の要求では、前の応答 の @odata.nextLink URL または @odata.deltaLink URL をコピーして適用します。URL にはエンコードされたパラメーターが既に含まれています。

クエリパラメーター	種類	説明
`$deltatoken`	String	前のデルタ関数呼び出しの@odata.deltaLink URL で返された状態トークン。変更追跡のラウンドが完了したことを示します。このトークンを含む @odata.deltaLink URL 全体を保存し、そのコレクションの変更追跡の次のイテレーションの最初の要求に適用します。
`$skiptoken`	String	以前のデルタ関数呼び出しの@odata.nextLink URL で返された状態トークン。これは、追加の変更を追跡可能であることを示します。

オプションの OData クエリパラメーター

この API では、次の OData クエリパラメーターがサポートされています。

$top は、呼び出しでフェッチするメッセージの最大数を表します。上限は 50。
$skip は、リストの先頭でスキップするメッセージの数を表します。
$filter は、特定の条件を満たすメッセージを返します。フィルターをサポートする唯一のプロパティは lastModifiedDateTime, and only the gtoperator is supported. For example,.です。/messages/delta?$filter=lastModifiedDateTime gt 2024-08-27T07:13:28.000z' は、指定した日時以降に作成または変更されたすべてのメッセージをフェッチします。

要求ヘッダー

ヘッダー	値
Authorization	ベアラー {token}。必須です。認証と認可についての詳細をご覧ください。

要求本文

このメソッドには、要求本文を指定しません。

応答

このメソッドは、成功すると 200 OK 応答コードと chatMessage オブジェクトのコレクションを応答本文で返します。応答には、 @odata.nextLink URL または @odata.deltaLink URL も含まれます。

例

例 1: 初期同期

次の例は、メッセージを同期するための一連の 3 つの要求を示しています。応答は、次の 3 つのメッセージで構成されます。

手順 1: 最初の要求と応答。
手順 2: 2 番目の要求と応答。
手順 3: 3 番目の要求と最後の応答。

簡潔にするために、サンプル応答にはメッセージのプロパティのサブセットのみが表示されます。実際の呼び出しでは、ほとんどのメッセージプロパティが返されます。

さらに多くのメッセージを取得するには、次のラウンドでできることも参照してください。

最初の要求

この例では、チャットメッセージが初めて同期され、初期同期要求に状態トークンは含まれません。

要求では、一度に 2 つのメッセージを返す省略可能な $top クエリパラメーターを指定します。

GET https://graph.microsoft.com/beta/users/5ed12dd6-24f8-4777-be3d-0d234e06cefa/chats/getAllMessages/delta?$top=2

最初の要求の応答

応答には、2 つのメッセージと、skipTokenを含む @odata.nextLink 応答ヘッダーが含まれます。 @odata.nextLink URL は、チャット内のより多くのメッセージを取得可能であることを示します。

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

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#Collection(microsoft.graph.chatMessage)",
  "@odata.nextLink": "https://graph.microsoft.com/beta/users/5ed12dd6-24f8-4777-be3d-0d234e06cefa/chats/getAllMessages/delta?$skiptoken=a-5fqdzHFr_L_cc7C0q1F-HCB8Z9SjwOsMN37XV5yfSnYgK4jVGVGEl25GFlxKWq0Wv6quL-5qcNg4nUnxzof6namZ_DM5no-hcL515cSrRGDoRLn38fZE1AXoDugSTOohOq3YRCYLqJbFGIoovMPTar32oLuoltHixme-Bf1lZtscv1wv5uu-MtkpYZIT0uDw-umQUK7mLNjMcyhNaifDrdemGUDMaQ25_QuHukNbkXcxsKMJdJ288p9IkaSeEyJHX5a6T_kEdAmuffsdzOGY8mLbLc7VEsUL75rGdt2aiKkywaPHsT9bDGV7MBo7WM2g_kdPeLdRPSdSxxhkGpNA.y_WMscy7negz0HZPhgjH-YyzsdeXzr2UDSfNrdzC78A",
  "value": [
    {
      "replyToId": null,
      "etag": "1727366299993",
      "messageType": "message",
      "createdDateTime": "2024-09-26T15:58:19.993Z",
      "lastModifiedDateTime": "2024-09-26T15:58:19.993Z",
      "lastEditedDateTime": null,
      "deletedDateTime": null,
      "subject": "",
      "summary": null,
      "chatId": "19:65a44130a0f249359d77858287ed39f0@thread.v2",
      "importance": "normal",
      "locale": "en-us",
      "webUrl": null,
      "channelIdentity": null,
      "policyViolation": null,
      "eventDetail": null,
      "id": "1727366299993",
      "from": {
        "application": null,
        "device": null,
        "user": {
          "@odata.type": "#microsoft.graph.teamworkUserIdentity",
          "id": "43383bf2-f7ab-4ba3-bf5e-12d071db189b",
          "displayName": "CFCC5",
          "userIdentityType": "aadUser",
          "tenantId": "f54e6700-e876-410b-8996-d6447d64098a"
        }
      },
      "body": {
        "contentType": "html",
        "content": "<div>\n<div itemprop=\"copy-paste-block\">reply 9&nbsp;to new conv</div>\n</div>"
      },
      "attachments": [],
      "mentions": [],
      "reactions": []
    },
    {
      "replyToId": null,
      "etag": "1727216579286",
      "messageType": "message",
      "createdDateTime": "2024-09-24T22:22:59.286Z",
      "lastModifiedDateTime": "2024-09-24T22:22:59.286Z",
      "lastEditedDateTime": null,
      "deletedDateTime": null,
      "subject": "",
      "summary": null,
      "chatId": "19:2a247d5dadc24f408d009e4ae84502cf@thread.v2",
      "importance": "normal",
      "locale": "en-us",
      "webUrl": null,
      "channelIdentity": null,
      "policyViolation": null,
      "eventDetail": null,
      "id": "1727216579286",
      "from": {
        "application": null,
        "device": null,
        "user": {
          "@odata.type": "#microsoft.graph.teamworkUserIdentity",
          "id": "43383bf2-f7ab-4ba3-bf5e-12d071db189b",
          "displayName": "CFCC5",
          "userIdentityType": "aadUser",
          "tenantId": "f54e6700-e876-410b-8996-d6447d64098a"
        }
      },
      "body": {
        "contentType": "html",
        "content": "<div>\n<div itemprop=\"copy-paste-block\">reply 10 to new conv</div>\n</div>"
      },
      "attachments": [],
      "mentions": [],
      "reactions": []
    }
  ]
}

2 番目の要求

2 番目の要求では、前の応答から返された @odata.nextLink URL を指定します。 @odata.nextLink URL のskipTokenがエンコードして含まれているので、最初の要求と同じ $top パラメーターを指定する必要がなくなりました。

GET https://graph.microsoft.com/beta/users/5ed12dd6-24f8-4777-be3d-0d234e06cefa/chats/getAllMessages/delta?&%24skiptoken=a-5fqdzHFr_L_cc7C0q1F-HCB8Z9SjwOsMN37XV5yfSnYgK4jVGVGEl25GFlxKWq0Wv6quL-5qcNg4nUnxzof6namZ_DM5no-hcL515cSrRGDoRLn38fZE1AXoDugSTOohOq3YRCYLqJbFGIoovMPTar32oLuoltHixme-Bf1lZtscv1wv5uu-MtkpYZIT0uDw-umQUK7mLNjMcyhNaifMIVTT-htmEOClLVwgcyWLR-sl9Qb73uTTtPXdFdMK6FDE4gpwvvKxvo2ChsW2c4eo77LDh6ZL_WQ8Luq00koQ6vHIrLBHPMUdOAxDxu-U7N7H4hsFn9aRDRdwRky7067A.V2a-J-86yXTd9SJMA4CHP6enI-Ab-bQzRgYujwsIwDo

2 番目の要求の応答

2 番目の応答は、次の 2 つのメッセージと @odata.nextLink 応答ヘッダーを返し、さらに多くのメッセージを取得可能であることを示す skipToken を返します。

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

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#Collection(microsoft.graph.chatMessage)",
  "@odata.nextLink": "https://graph.microsoft.com/beta/users/5ed12dd6-24f8-4777-be3d-0d234e06cefa/chats/getAllMessages/delta?$skiptoken=yJQeoV00BlfhYsCMsrn1GnNz7v5S39NShp1U4rzLZnPsraIATwnnsvbdv52hvKp7AAG-Bcwdu7dA7UweXHvGYQ2M5eysh-cNz6EZICZp7kM9HtmQHu7JU-_sX5S1edvEQxyAgm1R2HXk4R9_TWn9ZAu1BRQ-elS9hg0f8BlwKLCIluuSPS2ZuNVnQTOOYMMpmzKGX4wVVQUv0UlrIFZIPWTeriNpg5sJFd91n2GHSMnS7WaRTh3NSmvJE08ww-2CjGml2RjPyHfLHSqywuNt5BGNVj_vqsLbjetdDIYZFa_yaQqV_Bp5DaWM_nXD8RjVULH7H4ATXoUiG3Etsd_Nhd_GIYoxV6x2_rmbh928WPGSsenCOa352tyFxmuyTH0ozDmU4onVbGnOBQEYJDKZjuIeNVW-E19VHthjZ9GvYGE.NHJkfAbRu3Qoozl699AinriiHvWofLVnWkB5wEJmZlk",
  "value": [
    {
      "replyToId": null,
      "etag": "1726706286844",
      "messageType": "message",
      "createdDateTime": "2024-09-19T00:38:06.844Z",
      "lastModifiedDateTime": "2024-09-19T00:38:06.844Z",
      "lastEditedDateTime": null,
      "deletedDateTime": null,
      "subject": "",
      "summary": null,
      "chatId": "19:65a44130a0f249359d77858287ed39f0@thread.v2",
      "importance": "normal",
      "locale": "en-us",
      "webUrl": null,
      "channelIdentity": null,
      "policyViolation": null,
      "eventDetail": null,
      "id": "1726706286844",
      "from": {
        "application": null,
        "device": null,
        "user": {
          "@odata.type": "#microsoft.graph.teamworkUserIdentity",
          "id": "43383bf2-f7ab-4ba3-bf5e-12d071db189b",
          "displayName": "CFCC5",
          "userIdentityType": "aadUser",
          "tenantId": "f54e6700-e876-410b-8996-d6447d64098a"
        }
      },
      "body": {
        "contentType": "html",
        "content": "<p>Not one message, but several combined together to give you the full picture</p>"
      },
      "attachments": [],
      "mentions": [],
      "reactions": []
    },
    {
      "replyToId": null,
      "etag": "1726706276201",
      "messageType": "message",
      "createdDateTime": "2024-09-19T00:37:56.201Z",
      "lastModifiedDateTime": "2024-09-19T00:37:56.201Z",
      "lastEditedDateTime": null,
      "deletedDateTime": null,
      "subject": "",
      "summary": null,
      "chatId": "19:65a44130a0f249359d77858287ed39f0@thread.v2",
      "importance": "normal",
      "locale": "en-us",
      "webUrl": null,
      "channelIdentity": null,
      "policyViolation": null,
      "eventDetail": null,
      "id": "1726706276201",
      "from": {
        "application": null,
        "device": null,
        "user": {
          "@odata.type": "#microsoft.graph.teamworkUserIdentity",
          "id": "43383bf2-f7ab-4ba3-bf5e-12d071db189b",
          "displayName": "CFCC5",
          "userIdentityType": "aadUser",
          "tenantId": "f54e6700-e876-410b-8996-d6447d64098a"
        }
      },
      "body": {
        "contentType": "html",
        "content": "<p>Dive into the possibilities of incorporating context into ML evaluations by looking at entire conversations</p>"
      },
      "attachments": [],
      "mentions": [],
      "reactions": []
    }
  ]
}

3 番目の要求

3 番目の要求では、最後の同期要求から返された最新 の@odata.nextLink が引き続き使用されます。

GET  https://graph.microsoft.com/beta/users/5ed12dd6-24f8-4777-be3d-0d234e06cefa/chats/getAllMessages/delta?$skiptoken=8UusBixEHS9UUau6uGcryrA6FpnWwMJbuTYILM1PArHxnZzDVcsHQrijNzCyIVeEauMQsKUfMhNjLWFs1o4sBS_LofJ7xMftZUfec_pijuT6cAk5ugcWCca9RCjK7iVj.DKZ9w4bX9vCR7Sj9P0_qxjLAAPiEZgxlOxxmCLMzHJ4

3 番目の要求の応答

3 番目の応答は、残りのメッセージと、すべてのメッセージが返されることを示すdeltaTokenを持つ @odata.deltaLink 応答ヘッダーを返します。 @odata.deltaLink URL を保存して使用して、この時点以降に追加または変更された新しいメッセージを照会します。

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

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#Collection(microsoft.graph.chatMessage)",
  "@odata.deltaLink": "https://graph.microsoft.com/beta/users/5ed12dd6-24f8-4777-be3d-0d234e06cefa/chats/getAllMessages/delta?$deltatoken=aQdvS1VwGCSRxVmZJqykmDik_JIC44iCZpv-GLiA2VnFuE5yG-kCEBROb2iaPT_y_eMWVQtBO_ejzzyIxl00ji-tQ3HzAbW4liZAVG88lO3nG_6-MBFoHY1n8y21YUzjocG-Cn1tCNeeLPLTzIe5Dw.EP9gLiCoF2CE_e6l_m1bTk2aokD9KcgfgfcLGqd1r_4",
  "value": [
    {
      "replyToId": null,
      "etag": "1726706340932",
      "messageType": "message",
      "createdDateTime": "2024-09-19T00:39:00.932Z",
      "lastModifiedDateTime": "2024-09-19T00:39:00.932Z",
      "lastEditedDateTime": null,
      "deletedDateTime": null,
      "subject": "",
      "summary": null,
      "chatId": "19:65a44130a0f249359d77858287ed39f0@thread.v2",
      "importance": "normal",
      "locale": "en-us",
      "webUrl": null,
      "channelIdentity": null,
      "policyViolation": null,
      "eventDetail": null,
      "id": "1726706340932",
      "from": {
        "application": null,
        "device": null,
        "user": {
          "@odata.type": "#microsoft.graph.teamworkUserIdentity",
          "id": "43383bf2-f7ab-4ba3-bf5e-12d071db189b",
          "displayName": "CFCC5",
          "userIdentityType": "aadUser",
          "tenantId": "f54e6700-e876-410b-8996-d6447d64098a"
        }
      },
      "body": {
        "contentType": "html",
        "content": "<p>let's get started!</p>"
      },
      "attachments": [],
      "mentions": [],
      "reactions": []
    }
  ]
}

例 2: より多くのメッセージを取得する次のラウンド

最後のラウンドの最後の要求から @odata.deltaLink を使用すると、 @odata.deltaLink が取得されてから変更 (追加または更新) されたメッセージのみを取得できます。応答で同じ最大ページサイズを維持すると仮定すると、要求は次のようになります。

要求

次の例は要求を示しています。

GET https://graph.microsoft.com/beta/users/5ed12dd6-24f8-4777-be3d-0d234e06cefa/chats/getAllMessages/delta?$deltatoken=aQdvS1VwGCSRxVmZJqykmDik_JIC44iCZpv-GLiA2VnFuE5yG-kCEBROb2iaPT_y_eMWVQtBO_ejzzyIxl00ji-tQ3HzAbW4liZAVG88lO3nG_6-MBFoHY1n8y21YUzjocG-Cn1tCNeeLPLTzIe5Dw.EP9gLiCoF2CE_e6l_m1bTk2aokD9KcgfgfcLGqd1r_4

応答

次の例は応答を示しています。

注: ここに示す応答オブジェクトは、読みやすさのために短縮されている場合があります。

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

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#Collection(chatMessage)",
  "@odata.deltaLink": "https://graph.microsoft.com/beta/users/5ed12dd6-24f8-4777-be3d-0d234e06cefa/chats/getAllMessages/delta?$deltatoken=aQdvS1VwGCSRxVmZJqykmDik_JIC44iCZpv-GLiA2VnFuE5yG-kCEBROb2iaPT_yjz2nsMoh1gXNtXii7s78HapCi5woifXqwXlVNxICh8wUUnvE2gExsa8eZ2Vy_ch5rVIhm067_1mUPML3iYUVyg.3o0rhgaBUduuxOr98An5pjBDP5JjKUiVWku3flSiOsk",
  "value": [
    {
      "replyToId": null,
      "etag": "1727366299999",
      "messageType": "message",
      "createdDateTime": "2024-09-26T15:58:19.993Z",
      "lastModifiedDateTime": "2024-09-26T17:58:19.993Z",
      "lastEditedDateTime": null,
      "deletedDateTime": null,
      "subject": "",
      "summary": null,
      "chatId": "19:65a44130a0f249359d77858287ed39f0@thread.v2",
      "importance": "normal",
      "locale": "en-us",
      "webUrl": null,
      "channelIdentity": null,
      "policyViolation": null,
      "eventDetail": null,
      "id": "1727366299999",
      "from": {
        "application": null,
        "device": null,
        "user": {
          "@odata.type": "#microsoft.graph.teamworkUserIdentity",
          "id": "43383bf2-f7ab-4ba3-bf5e-12d071db189b",
          "displayName": "CFCC5",
          "userIdentityType": "aadUser",
          "tenantId": "f54e6700-e876-410b-8996-d6447d64098a"
        }
      },
      "body": {
        "contentType": "html",
        "content": "newly added content"
      },
      "attachments": [],
      "mentions": [],
      "reactions": []
    }
  ]
}

次の方法で共有

chatMessage: delta

アクセス許可

HTTP 要求

クエリパラメーター

オプションの OData クエリパラメーター

要求ヘッダー

要求本文

応答

例

例 1: 初期同期

最初の要求

最初の要求の応答

2 番目の要求

2 番目の要求の応答

3 番目の要求

3 番目の要求の応答

例 2: より多くのメッセージを取得する次のラウンド

要求

応答

フィードバック

その他のリソース

次の方法で共有

chatMessage: delta

アクセス許可

HTTP 要求

クエリ パラメーター

オプションの OData クエリ パラメーター

要求ヘッダー

要求本文

応答

例

例 1: 初期同期

最初の要求

最初の要求の応答

2 番目の要求

2 番目の要求の応答

3 番目の要求

3 番目の要求の応答

例 2: より多くのメッセージを取得する次のラウンド

要求

応答

フィードバック

その他のリソース

クエリパラメーター

オプションの OData クエリパラメーター