Обновление карточек Teams: руководство по ID бесед и сообщений

Как обновить карточку в Microsoft Teams после публикации

Чтобы обновить карточку в Microsoft Teams после публикации в канале, необходимо использовать REST API с идентификатором беседы и идентификатором сообщения, а не полагаться на стандартную функциональность обновления. Ключевой момент — выполнить PUT-запрос к конечной точке /v3/conversations/{conversationId}/activities/{messageId} с обновленным содержимым карточки в вложениях сообщения.

Содержание

• [Основы обновления карточек в Microsoft Teams](#основы-обновления-карточек в-microsoft-teams)
• Использование REST API с идентификатором беседы и идентификатором сообщения
• Различные подходы для разных сценариев
• Примеры кода и реализация
• Устранение распространенных проблем

Основы обновления карточек в Microsoft Teams

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

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

Использование REST API с идентификатором беседы и идентификатором сообщения

Основной метод обновления карточек включает использование REST API Bot Framework с идентификатором беседы и идентификатором сообщения. Вот процесс:

Требуемая информация

• Идентификатор беседы (Conversation ID): Идентификатор канала или чата, где была опубликована карточка
• Идентификатор сообщения (Message ID): Идентификатор конкретного сообщения, содержащего карточку
• Токен доступа (Access Token): Токен аутентификации с соответствующими разрешениями
• URL-адрес службы (Service URL): URL-адрес конечной точки вашего бота

Конечная точка API

Конечная точка для обновления сообщения:

PUT /v3/conversations/{conversationId}/activities/{messageId}

Структура запроса

Как показано в решении на Stack Overflow, вам нужно построить полный объект сообщения:

const updatedMessage = {
  id: messageId,
  type: "message",
  from: { ... },
  conversation: { ... },
  recipient: { ... },
  attachments: [
    {
      contentType: "application/vnd.microsoft.card.adaptive",
      content: messageWithUpdatedURL,
    },
  ],
};

Документация Microsoft Teams подтверждает, что “для обновления существующей активности в беседе включите conversationId и activityId в конечную точку запроса”.

Различные подходы для разных сценариев

Подход с использованием Bot Framework

При использовании Bot Framework необходимо:

1. Кэшировать идентификатор сообщения, возвращенный из первоначальной публикации
2. Сохранить идентификатор беседы для будущего использования
3. Использовать URL-адрес службы из контекста бота

Microsoft Graph API предоставляет альтернативу с конечной точкой:

PATCH /teams/{team-id}/channels/{channel-id}/messages/{message-id}

Подход с использованием Power Automate

Для пользователей Power Automate ситуация иная. Как упоминается в обсуждении на Reddit, “в отличие от публикации обычного сообщения Teams, проблема в том, что ваша адаптивная карточка не создает идентификатор сообщения”. Однако вы можете использовать действие “Ожидать ответа” и настроить область “Обновить сообщение” для замены карточки после отправки.

Использование Microsoft Graph API

Microsoft Graph API предоставляет еще один вариант для обновления сообщений в каналах Teams с разрешениями приложения.

Примеры кода и реализация

Пример на JavaScript/Node.js

Вот полный пример с использованием REST API Bot Framework:

async function updateAdaptiveCard(conversationId, messageId, updatedCardContent, serviceUrl, accessToken) {
  const updatedMessage = {
    id: messageId,
    type: "message",
    conversation: { id: conversationId },
    attachments: [
      {
        contentType: "application/vnd.microsoft.card.adaptive",
        content: updatedCardContent,
      },
    ],
  };

  const response = await fetch(
    `${serviceUrl}/v3/conversations/${conversationId}/activities/${messageId}`,
    {
      method: "PUT",
      headers: {
        "Authorization": `Bearer ${accessToken}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify(updatedMessage),
    }
  );

  if (!response.ok) {
    throw new Error(`Не удалось обновить карточку: ${response.statusText}`);
  }

  return await response.json();
}

Пример на PowerShell

Для предпочитающих PowerShell можно использовать Microsoft Graph API:

# Обновить сообщение Teams с адаптивной карточкой
$teamId = "идентификатор-вашей-команды"
$channelId = "идентификатор-вашего-канала"
$messageId = "идентификатор-вашего-сообщения"
$updatedCardContent = Get-Content -Path "updated-card.json" -Raw

$params = @{
  body = @{
    attachments = @(
      @{
        contentType = "application/vnd.microsoft.card.adaptive"
        content = $updatedCardContent | ConvertFrom-Json
      }
    )
  }
}

Invoke-RestMethod -Uri "https://graph.microsoft.com/v1.0/teams/$teamId/channels/$channelId/messages/$messageId" `
  -Method PATCH `
  -Headers @{Authorization = "Bearer $accessToken"; "Content-Type" = "application/json" } `
  -Body ($params | ConvertTo-Json -Depth 10)

Устранение распространенных проблем

Отсутствие идентификатора сообщения

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

Проблемы с разрешениями

Убедитесь, что ваш токен доступа имеет правильные разрешения. Документация Microsoft предупреждает, что “разрешения приложения поддерживаются только для миграции” и будущие изменения могут потребовать дополнительных платежей.

Проблемы с URL-адресом службы

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

Замена карточки вместо обновления

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

Источники

1. Stack Overflow - Teams Bot - Как обновить существующую адаптивную карточку, отправленную в канал?
2. Microsoft Learn - Беседы с ботом
3. Microsoft Learn - Обновить chatMessage (Graph API)
4. Reddit - Обновить существующую адаптивную карточку Teams, которая не ожидает ответа
5. Microsoft Learn - Типы карточек и их использование
6. Microsoft Learn - Работа с API обмена сообщениями Microsoft Teams в Microsoft Graph

Заключение

Обновление карточек в Microsoft Teams требует понимания базового API сообщений, а не reliance на встроенную функциональность обновления карточек. Ключевые выводы:

1. Всегда захватывайте и сохраняйте как идентификатор беседы, так и идентификатор сообщения при первоначальной публикации карточек
2. Используйте конечную точку REST API /v3/conversations/{conversationId}/activities/{messageId} для обновлений
3. Стройте полный объект сообщения с обновленным содержимым карточки в массиве вложений
4. Для Power Automate используйте действие “Ожидать ответа” с настроенной областью “Обновить сообщение”
5. Обеспечьте правильную аутентификацию и разрешения для операций обновления

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