Поделиться через

команда: sendActivityNotification

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

Отправка уведомления о веб-канале действий в область команды. Дополнительные сведения об отправке уведомлений и требованиях для этого см. в статье Отправка уведомлений о действиях Teams.

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

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

Разрешения

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

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

Примечание.

Разрешение TeamsActivity.Send.Group использует согласие для конкретного ресурса.

HTTP-запрос

POST /teams/{teamId}/sendActivityNotification

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

Имя Описание
Авторизация Bearer {token}. Обязательно. Дополнительные сведения о проверке подлинности и авторизации.
Content-Type application/json. Обязательно.

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

В тело запроса добавьте параметры в формате JSON.

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

Параметр Тип Описание
activityType String Тип действия должен быть объявлен в манифесте приложения Teams, за systemDefault исключением типа зарезервированного действия, который предоставляет текст в свободной форме в строке Actor+Reason уведомления.
chainId Int64 Необязательный параметр. Идентификатор цепочки для уведомления. Используется для переопределения предыдущего уведомления. Используйте то же chainId самое в последующих запросах, чтобы переопределить предыдущее уведомление.
iconId String Необязательный параметр. Уникальный идентификатор значка, позволяющий приложениям отправлять настраиваемые значки для каждого типа действия. Идентификаторы значков должны присутствовать в схеме манифеста приложения Teams. Если идентификатор значка указан в манифесте, но отсутствует в тексте запроса API, значок возвращается к значку по умолчанию для приложения.
previewText itemBody Текст предварительного просмотра для уведомления. В Microsoft Teams отображаются первые 150 символов.
получатель; teamworkNotificationRecipient Получатель уведомления. Дополнительные сведения см. в разделах aadUserNotificationRecipient, channelMembersNotificationRecipient и teamMembersNotificationRecipient.
teamsAppId String Необязательный параметр. Идентификатор приложения Teams, связанного с уведомлением. Используется для устранения неоднозначности установленных приложений, когда для одного и того же пользователя-получателя установлено несколько приложений с одинаковым Microsoft Entra ID идентификатором приложения. Избегайте совместного использования идентификаторов приложений Microsoft Entra ID между приложениями Teams.
templateParameters Коллекция keyValuePair Значения переменных шаблона, определенных в записи веб-канала действий, activityType соответствующей в манифесте приложения Teams.
topic teamworkActivityTopic Раздел уведомления. Указывает ресурс, о котором идет речь.

Следующие ресурсы поддерживаются при установке source значения свойства раздела в entityUrl:

Заметка: URL-адрес сущности должен быть таким же или дочерним ресурсом команды в URL-адресе. Кроме того, приложение Teams должно быть установлено в команде.

Отклик

В случае успешного выполнения это действие возвращает код отклика 204 No Content.

Примеры

Пример 1. Уведомление пользователя об ожидающих запросах на утверждение финансов

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

Запрос

POST https://graph.microsoft.com/v1.0/teams/{teamId}/sendActivityNotification
Content-Type: application/json

{
    "topic": {
        "source": "entityUrl",
        "value": "https://graph.microsoft.com/v1.0/teams/{teamId}"
    },
    "activityType": "pendingFinanceApprovalRequests",
    "previewText": {
        "content": "Internal spending team has a pending finance approval requests"
    },
    "recipient": {
        "@odata.type": "microsoft.graph.aadUserNotificationRecipient",
        "userId": "569363e2-4e49-4661-87f2-16f245c5d66a"
    },
    "templateParameters": [
        {
            "name": "pendingRequestCount",
            "value": "5"
        }
    ] 
}

Отклик

HTTP/1.1 204 No Content

Пример 2. Уведомление пользователя о вкладке канала

Как и в предыдущем примере, в этом примере используется entityUrl для topic. Однако этот пример ссылается на вкладку в канале. На вкладке отображается страница, показывающая пользователю состояние резервирования в отеле. При выборе уведомления пользователь перейдет на вкладку, где он может проверка резервирование.

Запрос

POST https://graph.microsoft.com/v1.0/teams/{teamId}/sendActivityNotification
Content-Type: application/json

{
    "topic": {
        "source": "entityUrl",
        "value": "https://graph.microsoft.com/v1.0/teams/{teamId}/channels/{channelId}/tabs/{tabId}"
    },
    "activityType": "reservationUpdated",
    "previewText": {
        "content": "You have moved up the queue"
    },
    "recipient": {
        "@odata.type": "microsoft.graph.aadUserNotificationRecipient",
        "userId": "569363e2-4e49-4661-87f2-16f245c5d66a"
    },
    "templateParameters": [
        {
            "name": "reservationId",
            "value": "TREEE433"
        },
        {
            "name": "currentSlot",
            "value": "23"
        }
    ]
}

Отклик

HTTP/1.1 204 No Content

Пример 3. Уведомление пользователя о вкладке канала с помощью имени участника-пользователя

Как и в предыдущем примере, в этом примере используется entityUrl для topic. Однако этот пример ссылается на вкладку в канале. На вкладке отображается страница, показывающая пользователю состояние резервирования в отеле. При выборе уведомления пользователь перейдет на вкладку, где он может проверка резервирование.

Запрос

POST https://graph.microsoft.com/v1.0/teams/{teamId}/sendActivityNotification
Content-Type: application/json

{
    "topic": {
        "source": "entityUrl",
        "value": "https://graph.microsoft.com/v1.0/teams/{teamId}/channels/{channelId}/tabs/{tabId}"
    },
    "activityType": "reservationUpdated",
    "previewText": {
        "content": "You have moved up the queue"
    },
    "recipient": {
        "@odata.type": "microsoft.graph.aadUserNotificationRecipient",
        "userId": "[email protected]"
    },
    "templateParameters": [
        {
            "name": "reservationId",
            "value": "TREEE433"
        },
        {
            "name": "currentSlot",
            "value": "23"
        }
    ]
}

Отклик

HTTP/1.1 204 No Content

Пример 4. Уведомление пользователя о событии с помощью пользовательского раздела

Как показано в предыдущих примерах, можно связать с различными аспектами команды. Однако если вы хотите связать с аспектом, который не является частью команды или не представлен Microsoft Graph, или вы хотите настроить имя, можно задать источник topictext объекта в и передать для него настраиваемое значение. webUrl является обязательным, если для параметра topic источника задано значение text.

Запрос

POST https://graph.microsoft.com/v1.0/teams/{teamId}/sendActivityNotification
Content-Type: application/json

{
    "topic": {
        "source": "text",
        "value": "Deployment Approvals Channel",
        "webUrl": "https://teams.microsoft.com/l/message/19:[email protected]/1605223780000?tenantId=c8b1bf45-3834-4ecf-971a-b4c755ee677d&groupId=d4c2a937-f097-435a-bc91-5c1683ca7245&parentMessageId=1605223771864&teamName=Approvals&channelName=Azure%20DevOps&createdTime=1605223780000"
    },
    "activityType": "deploymentApprovalRequired",
    "previewText": {
        "content": "New deployment requires your approval"
    },
    "recipient": {
        "@odata.type": "microsoft.graph.aadUserNotificationRecipient",
        "userId": "569363e2-4e49-4661-87f2-16f245c5d66a"
    },
    "templateParameters": [
        {
            "name": "deploymentId",
            "value": "6788662"
        }
    ]
}

Отклик

HTTP/1.1 204 No Content

Пример 5. Уведомление участников команды о ожидающих запросах на утверждение финансирования

В следующем примере показано, как отправить уведомление о веб-канале действий всем участникам команды. Этот пример аналогичен предыдущим примерам. Однако в этом случае получателем является teamMembersNotificationRecipient. TeamId, указанный в получателе, должен соответствовать teamId, указанному в URL-адресе запроса.

Заметка: Возможность отправки уведомлений всем участникам команды ограничена командами с 10 000 участниками или меньше. Если число участников команды превышает 10 000 человек, ни один из участников команды не получит уведомление.

Запрос

Ниже показан пример запроса.

POST https://graph.microsoft.com/v1.0/teams/e8bece96-d393-4b9b-b8da-69cedef1a7e7/sendActivityNotification
Content-Type: application/json

{
    "topic": {
        "source": "entityUrl",
        "value": "https://graph.microsoft.com/v1.0/teams/e8bece96-d393-4b9b-b8da-69cedef1a7e7"
    },
    "activityType": "pendingFinanceApprovalRequests",
    "previewText": {
        "content": "Internal spending team has a pending finance approval requests"
    },
    "recipient": {
        "@odata.type": "microsoft.graph.teamMembersNotificationRecipient",
        "teamId": "e8bece96-d393-4b9b-b8da-69cedef1a7e7"
    },
    "templateParameters": [
        {
            "name": "pendingRequestCount",
            "value": "5"
        }
    ] 
}

Отклик

Ниже показан пример отклика.

HTTP/1.1 204 No Content

Пример 6. Уведомление участников канала о ожидающих запросах на утверждение финансирования

В следующем примере показано, как отправить уведомление о веб-канале действий всем участникам канала. Этот пример аналогичен предыдущему примеру. Однако в этом случае получателем является channelMembersNotificationRecipient. TeamId, указанный в получателе, должен соответствовать teamId, указанному в URL-адресе запроса.

Запрос

Ниже показан пример запроса.

POST https://graph.microsoft.com/v1.0/teams/e8bece96-d393-4b9b-b8da-69cedef1a7e7/sendActivityNotification
Content-Type: application/json

{
    "topic": {
        "source": "entityUrl",
        "value": "https://graph.microsoft.com/v1.0/teams/e8bece96-d393-4b9b-b8da-69cedef1a7e7"
    },
    "activityType": "pendingFinanceApprovalRequests",
    "previewText": {
        "content": "Internal spending team has a pending finance approval requests"
    },
    "recipient": {
        "@odata.type": "microsoft.graph.channelMembersNotificationRecipient",
        "teamId": "e8bece96-d393-4b9b-b8da-69cedef1a7e7",
        "channelId": "19:[email protected]"
    },
    "templateParameters": [
        {
            "name": "pendingRequestCount",
            "value": "5"
        }
    ] 
}

Отклик

Ниже показан пример отклика.

HTTP/1.1 204 No Content

Пример 7. Уведомление об ожидающих запросах на утверждение финансирования в расположении ответа на сообщения канала

Как и в предыдущем примере, в этом примере используется entityUrl для topic. Однако этот пример ссылается на ответ на сообщение канала. В ответе на сообщение канала отображается состояние резервирования отеля пользователя. При выборе уведомления пользователь перейдет в ответное сообщение в канале, где он может проверка состояние резервирования.

Запрос

Ниже показан пример запроса.

POST https://graph.microsoft.com/v1.0/teams/e8bece96-d393-4b9b-b8da-69cedef1a7e7/sendActivityNotification
Content-Type: application/json

{
    "topic": {
        "source": "entityUrl",
        "value": "https://graph.microsoft.com/beta/teams/{teamId}/channels/{channelId}/messages/{messageId}/replies/{replyId}"
    },
    "activityType": "reservationStatusUpdated",
    "previewText": {
        "content": "You have moved up the queue"
    },
    "recipient": {
        "@odata.type": "microsoft.graph.aadUserNotificationRecipient",
        "userId": "[email protected]"
    },
    "templateParameters": [
        {
            "name": "reservationId",
            "value": "TREEE433"
        },
        {
            "name": "currentSlot",
            "value": "23"
        }
    ]
}

Отклик

Ниже показан пример отклика.

HTTP/1.1 204 No Content

Пример 8. Уведомление пользователя в команде о событии с помощью пользовательского значка

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

Заметка: Для activityType использования этого параметра в манифесте должен содержаться список разрешенных идентификаторов значков. Проверка запроса завершается ошибкой, если в манифесте приложения отсутствует настраиваемый список значков. Дополнительные сведения см. в разделе Общедоступная предварительная версия манифеста приложения для разработчиков.

Запрос

Ниже показан пример запроса.

POST https://graph.microsoft.com/v1.0/teams/e8bece96-d393-4b9b-b8da-69cedef1a7e7/sendActivityNotification
Content-Type: application/json

{
  "topic": {
    "source": "entityUrl",
    "value": "https://graph.microsoft.com/v1.0/teams/{teamId}/channels/{channelId}/messages/{messageId}/replies/{replyId}"
  },
  "activityType": "announcementPosted",
  "previewText": {
    "content": "new announcemnet posted"
  },
  "iconId": "announcementCreated",
  "recipient": {
    "@odata.type": "microsoft.graph.aadUserNotificationRecipient",
    "userId": "[email protected]"
  },
  "templateParameters": [
    {
      "name": "reservationId",
      "value": "TREEE433"
    },
    {
      "name": "currentSlot",
      "value": "23"
    }
  ]
}

Отклик

Ниже показан пример отклика.

HTTP/1.1 204 No Content

Связанные материалы