chatMessage: delta

Статья
10/03/2024

Пространство имен: microsoft.graph

Получите список сообщений из всех чатов , участником которых является пользователь, включая чаты с одним на один, групповые чаты и чаты собраний. При использовании разностного запроса можно получать новые или обновленные сообщения.

Заметка: Delta возвращает сообщения только за последние восемь месяцев. Для получения старых сообщений можно использовать GET /users/{id | user-principal-name}/chats/getAllMessages . Разностный запрос поддерживает как полную синхронизацию, которая получает все сообщения из всех чатов, участником которых является пользователь, так и добавочную синхронизацию, которая получает сообщения, добавленные или измененные с момента последней синхронизации. Как правило, вы выполняете начальную полную синхронизацию, а затем периодически получаете добавочные изменения в этом представлении сообщений.

Чтобы получить ответы на сообщение, используйте список ответов на сообщения или операции получения ответа на сообщение .

Запрос GET с функцией delta возвращает одно из следующих данных:

Объект @odata.nextLink , содержащий URL-адрес с вызовом функции delta и skipToken.
Объект @odata.deltaLink , содержащий URL-адрес с вызовом функции delta и deltaToken.

Маркеры состояния непрозрачны для клиента. Чтобы продолжить цикл отслеживания изменений, скопируйте и примените URL-адрес @odata.nextLink или @odata.deltaLink , возвращенный из последнего запроса GET, к следующему вызову функции delta . Значение @odata.deltaLink , возвращаемое в ответе, означает, что текущий цикл отслеживания изменений завершен. Вы можете сохранить и использовать URL-адрес @odata.deltaLink , когда начинаете получать дополнительные изменения (сообщения, измененные или опубликованные после получения @odata.deltaLink).

Дополнительные сведения см. в документации по разностному запросу.

Этот API доступен в следующих национальных облачных развертываниях.

Глобальная служба	Правительство США L4	Правительство США L5 (DOD)	Китай управляется 21Vianet
✅	✅	✅	✅

Разрешения

Выберите разрешение или разрешения, помеченные как наименее привилегированные для этого API. Используйте более привилегированное разрешение или разрешения только в том случае, если это требуется приложению. Дополнительные сведения о делегированных разрешениях и разрешениях приложений см. в разделе Типы разрешений. Дополнительные сведения об этих разрешениях см. в справочнике по разрешениям.

Тип разрешения	Разрешения с наименьшими привилегиями	Более высокие привилегированные разрешения
Делегированные (рабочая или учебная учетная запись)	Не поддерживается.	Не поддерживается.
Делегированные (личная учетная запись Майкрософт)	Не поддерживается.	Не поддерживается.
Приложение	Chat.Read.All	Chat.ReadWrite.All

HTTP-запрос

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

Параметры запроса

При отслеживании изменений в сообщениях выполняется цикл из одного или нескольких вызовов разностной функции. Если вы используете параметры запроса, отличные от $deltatoken и $skiptoken, их необходимо указать в начальном запросе delta. Microsoft Graph автоматически кодирует все указанные параметры в часть маркера url-адреса @odata.nextLink или @odata.deltaLink , указанного в ответе.

Необходимо указать параметры запроса только один раз.

В последующих запросах скопируйте и примените URL-адрес @odata.nextLink или @odata.deltaLink из предыдущего ответа, так как этот URL-адрес уже содержит закодированные параметры.

Параметр запроса	Тип	Описание
`$deltatoken`	String	Маркер состояния, возвращенный в URL-адресе @odata.deltaLink предыдущего вызова функции delta, который указывает на завершение этого раунда отслеживания изменений. Сохраните и примените весь URL-адрес @odata.deltaLink , включая этот маркер, в первом запросе следующей итерации отслеживания изменений для этой коллекции.
`$skiptoken`	String	Маркер состояния, возвращенный в URL-адресе @odata.nextLink предыдущего вызова функции delta, который указывает, что доступны дальнейшие изменения для отслеживания.

Необязательные параметры запросов 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' извлекает любое сообщение, созданное или измененное после указанных даты и времени.

Заголовки запросов

Заголовок	Значение
Авторизация	Bearer {token}. Обязательно. Дополнительные сведения о проверке подлинности и авторизации.

Текст запроса

Не указывайте текст запроса для этого метода.

Отклик

В случае успешного выполнения этот метод возвращает код отклика 200 OK и коллекцию объектов chatMessage в тексте отклика. Ответ также содержит URL-адрес @odata.nextLink или URL-адрес @odata.deltaLink .

Примеры

Пример 1: Первоначальная синхронизация

В следующем примере показана серия из трех запросов для синхронизации сообщений. Ответ состоит из трех сообщений:

Шаг 1. Исходный запрос и отклик.
Шаг 2. Второй запрос и отклик.
Шаг 3. Третий запрос и последний отклик.

Для краткости в примерах ответов отображается только подмножество свойств сообщения. В фактическом вызове возвращается большинство свойств сообщения.

См. также, что можно сделать в следующем раунде, чтобы получить больше сообщений.

Исходный запрос

В этом примере сообщения чата синхронизируются в первый раз, а первоначальный запрос синхронизации не содержит маркер состояния.

Запрос задает необязательный $top параметр запроса, который возвращает два сообщения одновременно.

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

Ответ на исходный запрос

Ответ включает два сообщения и заголовок ответа @odata.nextLink с skipToken. URL-адрес @odata.nextLink указывает, что доступны дополнительные сообщения в чатах для получения.

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

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(microsoft.graph.chatMessage)",
  "@odata.nextLink": "https://graph.microsoft.com/v1.0/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": []
    }
  ]
}

Второй запрос

Второй запрос указывает URL-адрес @odata.nextLink , возвращенный из предыдущего ответа. Обратите внимание, что ему больше не нужно указывать тот же $top параметр, что и в первоначальном запросе, так как skipToken в URL-адресе @odata.nextLink кодируется и включает эти параметры.

GET https://graph.microsoft.com/v1.0/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

Ответ на второй запрос

Второй ответ возвращает следующие два сообщения и заголовок ответа @odata.nextLink с элементом , skipToken который указывает, что доступно больше сообщений для получения.

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

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(microsoft.graph.chatMessage)",
  "@odata.nextLink": "https://graph.microsoft.com/v1.0/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": []
    }
  ]
}

Третий запрос

Третий запрос продолжает использовать последнюю версию @odata.nextLink , возвращенную последним запросом синхронизации.

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

Ответ на третий запрос

Третий ответ возвращает только оставшиеся сообщения и заголовок ответа @odata.deltaLink с элементом , deltaToken который указывает, что возвращаются все сообщения. Сохраните и используйте URL-адрес @odata.deltaLink для запроса новых сообщений, добавленных или измененных с этого момента.

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

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(microsoft.graph.chatMessage)",
  "@odata.deltaLink": "https://graph.microsoft.com/v1.0/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/v1.0/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/v1.0/$metadata#Collection(chatMessage)",
  "@odata.deltaLink": "https://graph.microsoft.com/v1.0/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. Следующий раунд для получения дополнительных сообщений

Запрос

Отклик

Обратная связь

Дополнительные ресурсы