Отправка уведомлений веб-канала действий пользователям в Microsoft Teams

  • Статья

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

Основные сведения об уведомлении веб-канала действий

На следующем рисунке показано, что уведомления веб-канала действий в Microsoft Teams содержат несколько бит информации, отображаемой вместе.

Изображение, показывающее компоненты уведомления веб-канала действий

К компонентам относятся:

  • Субъект, инициировавший действие
  • Значок, представляющий тип действия
  • Причина, по которой субъект выполнил действие
  • Предварительный просмотр текста
  • Метка времени
  • Место действия

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

Пример уведомления о действии Yammer

Требования к использованию API уведомлений канала действий

API веб-канала действий работают с приложением Teams. Ниже приведены требования к отправке уведомлений веб-канала действий.

  • Манифест приложения Teams должен содержать Microsoft Entra идентификатор приложения, добавленный в webApplicationInfo раздел. Дополнительные сведения см. в разделе Схема манифеста.
  • Уведомления об активности можно отправлять с типами действий, объявленными в манифесте приложения, или без нее.
    • По умолчанию можно использовать API-интерфейсы уведомлений о действиях, не объявляя activities раздел в манифесте. Тип systemDefault действия зарезервирован, что позволяет предоставлять текст в свободной форме в строке Actor+Reason уведомления веб-канала действий. Дополнительные сведения см. в разделе Отправка уведомлений настраиваемого веб-канала действий.

      Примечание.

      Тип systemDefault действия доступен только в общедоступной предварительной версии.

    • Если вы хотите отправить шаблонное уведомление в традиционном режиме, типы действий должны быть объявлены в разделе Действия . Дополнительные сведения см. в разделе Схема манифеста.
  • Приложение Teams должно быть установлено для получателя лично, в команде или чате , в котором он участвует. Дополнительные сведения см. в разделе Установка приложения Teams.

Разрешения

Для отправки уведомлений о действиях можно использовать делегированные разрешения или разрешения приложений. При использовании разрешений приложения рекомендуется использовать согласие для конкретных ресурсов (RSC), так как TeamsActivity.Send.User разрешение позволяет пользователю давать согласие на отправку уведомлений о действиях. Необходимо объявить разрешения RSC в схеме манифеста приложения Teams.

Изменения манифеста приложения Teams

В этом разделе описаны изменения, которые необходимо добавить в манифест приложения Teams. Необходимо использовать версию манифеста приложения Teams или более позднюю.1.7

"$schema": "https://developer.microsoft.com/json-schemas/teams/v1.7/MicrosoftTeams.schema.json",
"manifestVersion": "1.7",

Изменения раздела webApplicationInfo

"webApplicationInfo":
{
    "id": "a3111f15-658e-457c-9689-fd20fe907330",
    "resource": "https://contosoapp.com"
}
Параметр Тип Описание
id string Microsoft Entra (идентификатор клиента).
resource string Ресурс, связанный с приложением Azure AD. Он также называется URI ответа или перенаправления в обзоре регистрации приложений Центр администрирования Microsoft Entra.

Примечание.

Если несколько приложений Teams в одной область (команда, чат или пользователь) используют одно и то же приложение Microsoft Entra, может возникнуть ошибка. Убедитесь, что вы используете уникальные приложения Microsoft Entra.

изменения раздела действий

"activities":
{
  "activityTypes": [
    {
      "type": "taskCreated",
      "description": "Task Created Activity",
      "templateText": "{actor} created task {taskId} for you"
    },
    {
      "type": "approvalRequired",
      "description": "Deployment requires your approval",
      "templateText": "{actor} created a new deployment {deploymentId}"
    }
  ]
}
Параметр Тип Описание
type string Тип должен быть уникальным в определенном манифесте.
description string Понятное краткое описание. Описание отображается в клиенте Microsoft Teams.
templateText string Текст шаблона для уведомления о действии. Параметры можно объявить, инкапсулировав параметры в {}.

Примечание.

  • actor — это специальный параметр, который всегда принимает имя вызывающего объекта. В делегированных вызовах actor — имя пользователя. В вызовах только для приложений оно принимает имя приложения Teams.

  • Зарезервированный systemDefault тип действия не должен быть указан в activities разделе манифеста. Зарезервированный тип действия может предоставлять текст в свободной форме в строке Actor+Reason уведомления веб-канала действий. Дополнительные сведения см. в разделе Отправка уведомлений настраиваемого веб-канала действий.

Изменения раздела авторизации

"authorization": 
{ 
  "permissions": { 
    "resourceSpecific": [ 
      {
        "type": "Application", 
         "name": "TeamsActivity.Send.User" 
      }, 
      { 
        "type": "Application",
        "name": "TeamsActivity.Send.Group"
      }, 
      { 
        "type": "Application", 
        "name": "TeamsActivity.Send.Chat" 
      } 
    ] 
  }
}
Параметр Тип Описание
type string Тип разрешений для конкретного ресурса (RSC).
name string Имя разрешения RSC. Дополнительные сведения см. в разделе Поддерживаемые разрешения RSC.

Установка приложения Teams

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

Вы также можете использовать API установки приложений Teams для управления установкой приложений Teams.

Отправка уведомлений о веб-канале действий пользователям

Примечание.

Приложение должно быть включено в список разрешений для отображения уведомлений веб-канала действий на клиентах iOS и Android. Поддерживаются только сторонние приложения.

Так как приложение Teams можно установить для пользователя, в команде или чате, уведомления также можно отправлять в следующих трех контекстах:

Кроме того, уведомления могут отправляться массово до 100 пользователей одновременно:

Дополнительные сведения о том, какие разделы поддерживаются для каждого сценария, см. в конкретных API. Пользовательские текстовые разделы поддерживаются во всех сценариях.

Примечание.

Значок действия основан на контексте, в котором выполняется запрос. Если запрос выполняется с делегированными разрешениями, фотография пользователя отображается в качестве аватара, а значок приложения Teams — в качестве значка действия. В контексте только приложения в качестве аватара используется значок приложения Teams, а значок действия опущен.

Пример 1. Уведомление пользователя о задаче, созданной в чате

В этом примере показано, как отправить уведомление веб-канала действий для новой задачи, созданной в чате. В этом случае приложение Teams должно быть установлено в чате с идентификатором chatId , а пользователь 569363e2-4e49-4661-87f2-16f245c5d66a также должен быть частью чата.

Запрос

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

{
    "topic": {
        "source": "entityUrl",
        "value": "https://graph.microsoft.com/v1.0/chats/{chatId}"
    },
    "activityType": "taskCreated",
    "previewText": {
        "content": "New Task Created"
    },
    "recipient": {
        "@odata.type": "microsoft.graph.aadUserNotificationRecipient",
        "userId": "569363e2-4e49-4661-87f2-16f245c5d66a"
    },
    "templateParameters": [
        {
            "name": "taskId",
            "value": "12322"
        }
    ]
}

Отклик

HTTP/1.1 204 No Content

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

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

Запрос

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": "taskCreated",
    "previewText": {
        "content": "New Task Created"
    },
    "recipient": {
        "@odata.type": "microsoft.graph.aadUserNotificationRecipient",
        "userId": "569363e2-4e49-4661-87f2-16f245c5d66a"
    },
    "templateParameters": [
        {
            "name": "taskId",
            "value": "12322"
        }
    ]
}

Отклик

HTTP/1.1 204 No Content

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

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

В приведенном выше примере уведомления Yammer используется пользовательский раздел, так как Microsoft Graph не поддерживает ресурсы Yammer.

Примечание.

webUrl должен начинаться с домена Microsoft Teams (например, teams.microsoft.com).

Запрос

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:448cfd2ac2a7490a9084a9ed14cttr78c@thread.skype/1605223780000?tenantId=c8b1bf45-3834-4ecf-971a-b4c755ee677d&groupId=d4c2a937-f097-435a-bc91-5c1683ca7245&parentMessageId=1605223771864&teamName=Approvals&channelName=Azure%20DevOps&createdTime=1605223780000"
    },
    "activityType": "approvalRequired",
    "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

Пример 4. Уведомление участников команды о событии

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

Запрос

POST https://graph.microsoft.com/v1.0/teams/7155e3c8-175e-4311-97ef-572edc3aa3db/sendActivityNotification
Content-Type: application/json

{
    "topic": {
        "source": "text",
        "value": "Weekly Virtual Social",
        "webUrl": "https://teams.microsoft.com/l/message/19:448cfd2ac2a7490a9084a9ed14cttr78c@thread.skype/1605223780000?tenantId=c8b1bf45-3834-4ecf-971a-b4c755ee677d&groupId=d4c2a937-f097-435a-bc91-5c1683ca7245&parentMessageId=1605223771864&teamName=Approvals&channelName=Azure%20DevOps&createdTime=1605223780000"
    },
    "previewText": {
        "content": "It will be fun!"
    },
    "activityType": "eventCreated",
    "recipient": {
        "@odata.type": "microsoft.graph.teamMembersNotificationRecipient",
        "teamId": "7155e3c8-175e-4311-97ef-572edc3aa3db"
    }
}

Отклик

HTTP/1.1 204 No Content

Пример 5. Уведомление участников канала о событии

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

Запрос

POST https://graph.microsoft.com/v1.0/teams/7155e3c8-175e-4311-97ef-572edc3aa3db/sendActivityNotification
Content-Type: application/json

{
    "topic": {
        "source": "text",
        "value": "Weekly Virtual Social",
        "webUrl": "https://teams.microsoft.com/l/message/19:448cfd2ac2a7490a9084a9ed14cttr78c@thread.skype/1605223780000?tenantId=c8b1bf45-3834-4ecf-971a-b4c755ee677d&groupId=d4c2a937-f097-435a-bc91-5c1683ca7245&parentMessageId=1605223771864&teamName=Approvals&channelName=Azure%20DevOps&createdTime=1605223780000"
    },
    "previewText": {
        "content": "It will be fun!"
    },
    "activityType": "eventCreated",
    "recipient": {
        "@odata.type": "microsoft.graph.channelMembersNotificationRecipient",
        "teamId": "7155e3c8-175e-4311-97ef-572edc3aa3db",
        "channelId": "19:0ea5de04de4743bcb4cd20cb99235d99@thread.tacv2"
    }
}

Отклик

HTTP/1.1 204 No Content

Пример 6. Уведомление участников чата о событии

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

Запрос

POST https://graph.microsoft.com/v1.0/chats/19:d65713bc498c4a428c71ef9353e6ce20@thread.v2/sendActivityNotification
Content-Type: application/json

{
    "topic": {
        "source": "text",
        "value": "Weekly Virtual Social",
        "webUrl": "https://teams.microsoft.com/l/message/19:448cfd2ac2a7490a9084a9ed14cttr78c@thread.skype/1605223780000?tenantId=c8b1bf45-3834-4ecf-971a-b4c755ee677d&groupId=d4c2a937-f097-435a-bc91-5c1683ca7245&parentMessageId=1605223771864&teamName=Approvals&channelName=Azure%20DevOps&createdTime=1605223780000"
    },
    "previewText": {
        "content": "It will be fun!"
    },
    "activityType": "eventCreated",
    "recipient": {
        "@odata.type": "microsoft.graph.chatMembersNotificationRecipient",
        "chatId": "19:d65713bc498c4a428c71ef9353e6ce20@thread.v2"
    }
}

Отклик

HTTP/1.1 204 No Content

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

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

Запрос

POST https://graph.microsoft.com/v1.0/teamwork/sendActivityNotificationToRecipients
Content-Type: application/json

{
    "topic": {
        "source": "entityUrl",
        "value": "https://graph.microsoft.com/v1.0/appCatalogs/teamsApps/{teamsAppId}"
    },
    "activityType": "pendingFinanceApprovalRequests",
    "previewText": {
        "content": "Internal spending team has a pending finance approval requests"
    },
    "recipients": [
        {
            "@odata.type": "microsoft.graph.aadUserNotificationRecipient",
            "userId": "569363e2-4e49-4661-87f2-16f245c5d66a"
        },
        {
            "@odata.type": "microsoft.graph.aadUserNotificationRecipient",
            "userId": "ab88234e-0874-477c-9638-d144296ed04f"
        },
        {
            "@odata.type": "microsoft.graph.aadUserNotificationRecipient",
            "userId": "01c64f53-69aa-42c7-9b7f-9f75195d6bfc"
        }
    ],
    "templateParameters": [
        {
            "name": "pendingRequestCount",
            "value": "5"
        }
    ] 
}

Отклик

HTTP/1.1 202 Accepted

Пример 8. Отправка уведомления пользователю с помощью типа действия systemDefault

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

Примечание.

Тип systemDefault действия доступен только в общедоступной предварительной версии.

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

Запрос

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": "systemDefault",
    "previewText": {
        "content": "Take a break"
    },
    "recipient": {
        "@odata.type": "microsoft.graph.aadUserNotificationRecipient",
        "userId": "569363e2-4e49-4661-87f2-16f245c5d66a"
    },
    "templateParameters": [
        {
            "name": "systemDefaultText",
            "value": "You need to take a short break"
        }
    ]
}

Отклик

HTTP/1.1 204 No Content

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

  • Тип systemDefault действия зарезервирован и не может использоваться в манифесте при объявлении действий.
  • Тип действия можно использовать systemDefault для:
    • Легко тестируйте новые сценарии и (или) быстро пробуйте API-интерфейсы уведомлений веб-канала действий, не определяя типы действий в манифесте приложения.
    • Для приложений Магазина это экономит время и упрощает процесс, так как вам не нужно постоянно изменять типы действий в манифесте приложения. Тип systemDefault действия готов к использованию из get-go.
  • Имейте в виду, что с типом systemDefault действия вы не можете:
    • Используйте встроенные функции локализации, предоставляемые манифестами.
    • Полагайтесь на отправку настраиваемых уведомлений с типом systemDefault действия. Пользователи могут отключить все уведомления из приложения с помощью переключателя в параметрах клиента Microsoft Teams, что может помешать обмену данными между приложением и его пользователями.
  • Мы по-прежнему рекомендуем использовать шаблонные уведомления для повторяющихся и больших пакетов уведомлений, так как для них в манифесте требуются шаблоны действий.
  • Зарезервированный systemDefault тип действия остается доступным независимо от типов действий, перечисленных в манифесте приложения.

Настройка оповещений о том, как уведомления оповещают вас

Пользователи Microsoft Teams могут настраивать уведомления, которые они видят в веб-канале, в виде баннера и т. д. Уведомления, созданные с помощью API веб-канала действий, также можно настроить. Пользователи могут выбирать способ уведомления с помощью параметров в Microsoft Teams. Приложения Teams отображаются в списке для выбора пользователем, как показано на следующем снимке экрана.

Снимок экрана: параметры уведомлений в Teams с выделенным параметром Custom

Пользователи могут нажать кнопку Изменить рядом с приложением и настроить уведомления, как показано в следующем примере. Отображается description поле в манифесте приложения Teams.

Снимок экрана: уведомления, настроенные для баннера и веб-канала для приложения Teams

Вопросы и ответы

Кому нужно установить приложение Teams?

У целевого пользователя должно быть установлено приложение Teams, которое отправляет уведомления.

Может ли пользователь отправлять уведомления себе?

``

Нет, пользователь не может отправлять уведомления себе. В этом сценарии используйте разрешения приложения.

Может ли приложение Teams управлять отображением уведомлений для пользователя?

Нет, изменять параметры уведомлений могут только пользователи.

Я установил свое приложение; Почему в учетной записи пользователя не отображаются параметры уведомлений?

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

Я начал получать ошибку 409 (конфликт); как ее устранить?

ConflictОшибки в основном возникают, если несколько приложений Teams, установленных в одном область (команда, чат, пользователь и т. д.), имеют одинаковый Microsoft Entra appId в webApplicationInfo разделе манифеста. В этом случае появляется сообщение об ошибке, например Found multiple applications with the same Microsoft Entra App ID 'Your Microsoft Entra AppId'.. Убедитесь, что вы используете уникальные приложения Microsoft Entra для уникальных приложений Teams. Одно и то же приложение Teams можно установить в нескольких областях (например, команда и пользователь).

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