Отправка и получение файлов с помощью ботов

Статья
04/04/2023

Важно!

Эта статья основана на пакете SDK Bot Framework версии 3. Если вы ищете текущую документацию по пакету SDK версии 4.6 или более поздней, см. раздел Боты для бесед.

Существует два способа отправки файлов в бот и из бота:

Использование API Microsoft Graph. Этот метод поддерживается для ботов во всех областях Teams:
- personal
- channel
- groupchat
Использование API-интерфейсов Teams. Они поддерживают файлы только в одном контексте:
- personal

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

Вы можете публиковать сообщения с вложенными карточками, ссылаясь на существующие файлы SharePoint с помощью API Microsoft Graph для OneDrive и SharePoint. Для использования API Graph требуется получить доступ к папке OneDrive пользователя (для файлов personal и groupchat) или файлам в каналах команды (для файлов channel) через стандартный поток авторизации OAuth 2.0. Этот метод поддерживается во всех областях Teams.

Использование API бота Teams

Примечание.

Этот метод поддерживается только в контексте personal. Он не поддерживается в контексте channel или groupchat.

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

В следующих разделах описано, как отправить содержимое файла в результате прямого взаимодействия с пользователем, например при отправке сообщения. Этот API предоставляется в составе Microsoft Teams Bot Platform.

Настройка бота для поддержки файлов

Чтобы отправлять и получать файлы в боте, настройте для свойства supportsFiles в манифесте значение true. Это свойство описано в разделе ботов в справочнике по манифесту.

Определение будет выглядеть следующим образом: "supportsFiles": true. Если бот не включает supportsFiles, следующие функции не будут работать.

Получение файлов в личном чате

Когда пользователь отправляет файл вашему боту, файл сначала отправляется в хранилище OneDrive для бизнеса пользователя. Затем бот получает сообщение с уведомлением об отправке пользователем. Оно содержит метаданные файла, например его имя и URL-адрес содержимого. Вы можете напрямую считать данные из этого URL-адреса, чтобы получить его двоичное содержимое.

Пример сообщения с вложенным файлом

{
  "attachments": [{
    "contentType": "application/vnd.microsoft.teams.file.download.info",
    "contentUrl": "https://contoso.sharepoint.com/personal/johnadams_contoso_com/Documents/Applications/file_example.txt",
    "name": "file_example.txt",
    "content": {
      "downloadUrl" : "https://download.link",
      "uniqueId": "1150D938-8870-4044-9F2C-5BBDEBA70C9D",
      "fileType": "txt",
      "etag": "123"
    }
  }]
}

В следующей таблице описаны свойства содержимого вложения.

Свойство	Назначение
`downloadUrl`	URL-адрес OneDrive для получения содержимого файла. Вы можете выполнить запрос `HTTP GET` непосредственно из этого URL-адреса.
`uniqueId`	Уникальный идентификатор файла. Это идентификатор элемента диска OneDrive, если пользователь отправляет файл вашему боту.
`fileType`	Тип расширения файла, например PDF или DOCX.

Рекомендуется подтвердить отправку файла, отправив обратное сообщение пользователю.

Отправка файлов в личный чат

Отправка файла пользователю включает в себя следующие действия.

Отправка сообщения пользователю с запросом разрешения на запись файла. Это сообщение должно содержать вложение FileConsentCard с именем файла для отправки.
Если пользователь принимает скачивание файла, бот получает действие Invoke с URL-адресом расположения.
Чтобы передать файл, ваш бот выполняет запрос HTTP POST непосредственно в указанном URL-адресе расположения.
При необходимости можно удалить исходную карточку согласия, если вы не хотите разрешать пользователю принимать дальнейшие отправки того же файла.

Сообщение с запросом разрешения на отправку

Это сообщение в классическом интерфейсе содержит простой объект вложения с запросом разрешения пользователя на отправку файла:

Снимок экрана: карточка согласия с запросом разрешения пользователя на отправку файла

Это сообщение в мобильном интерфейсе содержит объект вложения с запросом разрешения пользователя на отправку файла:

Снимок экрана: карточка согласия с запросом разрешения пользователя на отправку файла на мобильном устройстве

{
  "attachments": [{
    "contentType": "application/vnd.microsoft.teams.card.file.consent",
    "name": "file_example.txt",
    "content": {
      "description": "<Purpose of the file, such as: this is your monthly expense report>",
      "sizeInBytes": 1029393,
      "acceptContext": {
      },
      "declineContext": {
      }
    }
  }]
}

В следующей таблице описаны свойства содержимого вложения.

Свойство	Назначение
`description`	Описание файла. Может отображаться пользователю для описания назначения или обобщения содержимого.
`sizeInBytes`	Предоставляет пользователю оценку размера файла и объема пространства, которое он занимает в OneDrive.
`acceptContext`	Дополнительный контекст, который будет автоматически передан боту, когда пользователь примет файл.
`declineContext`	Дополнительный контекст, который будет автоматически передан боту, когда пользователь отклонит файл.

Действие вызова, когда пользователь принимает файл

Действие вызова отправляется боту, если и когда пользователь принимает файл. Оно содержит URL-адрес заполнителя OneDrive для бизнеса, для которого ваш бот может выпустить запрос PUT, чтобы передать содержимое файла. Сведения о передаче по URL-адресу OneDrive см. в статье Отправка байтов в сеанс отправки.

В следующем примере показана сокращенная версия действия вызова, получаемого ботом:

{
  ...

  "name": "fileConsent/invoke",
  "value": {
    "type": "fileUpload",
    "action": "accept",
    "context": {
    },
    "uploadInfo": {
      "contentUrl": "https://contoso.sharepoint.com/personal/johnadams_contoso_com/Documents/Applications/file_example.txt",
      "name": "file_example.txt",
      "uploadUrl": "https://upload.link",
      "uniqueId": "1150D938-8870-4044-9F2C-5BBDEBA70C8C",
      "fileType": "txt",
      "etag": "123"
    }
  }
}

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

{
  "name": "fileConsent/invoke",
  "value": {
    "type": "fileUpload",
    "action": "decline",
    "context": {
    }
  }
}

Уведомление пользователя об отправленном файле

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

{
  "attachments": [{
    "contentType": "application/vnd.microsoft.teams.card.file.info",
    "contentUrl": "https://contoso.sharepoint.com/personal/johnadams_contoso_com/Documents/Applications/file_example.txt",
    "name": "file_example.txt",
    "content": {
      "uniqueId": "1150D938-8870-4044-9F2C-5BBDEBA70C8C",
      "fileType": "txt",
    }
  }]
}

В следующей таблице описаны свойства содержимого вложения.

Свойство	Назначение
`uniqueId`	Идентификатор элемента диска OneDrive/SharePoint
`fileType`	Тип файла, например PDF или DOCX.

Базовый пример на C

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


// This sample dialog shows two simple flows:
// 1) A silly example of receiving a file from the user, processing the key elements,
//    and then constructing the attachment and sending it back.
// 2) Creating a new file consent card requesting user permission to upload a file.
private async Task MessageReceivedAsync(IDialogContext context, IAwaitable<object> result)
{
    var replyMessage = context.MakeMessage();
    Attachment returnCard;

    var message = await result as Activity;

    // Check to see if the user is sending the bot a file.
    if (message.Attachments != null && message.Attachments.Any())
    {
        var attachment = message.Attachments.First();

        if (attachment.ContentType == FileDownloadInfo.ContentType)
        {
            FileDownloadInfo downloadInfo = (attachment.Content as JObject).ToObject<FileDownloadInfo>();
            if (downloadInfo != null)
            {
                returnCard = CreateFileInfoAttachment(downloadInfo, attachment.Name, attachment.ContentUrl);
                replyMessage.Attachments.Add(returnCard);
            }
        }
    }
    else
    {
        // Illustrates creating a file consent card.
        returnCard = CreateFileConsentAttachment();
        replyMessage.Attachments.Add(returnCard);
    }
    await context.PostAsync(replyMessage);
}


private static Attachment CreateFileInfoAttachment(FileDownloadInfo downloadInfo, string name, string contentUrl)
{
    FileInfoCard card = new FileInfoCard()
    {
        FileType = downloadInfo.FileType,
        UniqueId = downloadInfo.UniqueId
    };

    Attachment att = card.ToAttachment();
    att.ContentUrl = contentUrl;
    att.Name = name;

    return att;
}

private static Attachment CreateFileConsentAttachment()
{
    JObject acceptContext = new JObject();
    // Fill in any additional context to be sent back when the user accepts the file.

    JObject declineContext = new JObject();
    // Fill in any additional context to be sent back when the user declines the file.

    FileConsentCard card = new FileConsentCard()
    {
        AcceptContext = acceptContext,
        DeclineContext = declineContext,
        SizeInBytes = 102635,
        Description = "File description"
    };

    Attachment att = card.ToAttachment();
    att.Name = "Example file";

    return att;
}

См. также

Работа с файлами в Microsoft Graph

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

Отправка и получение файлов с помощью ботов

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

Использование API бота Teams

Настройка бота для поддержки файлов

Получение файлов в личном чате

Пример сообщения с вложенным файлом

Отправка файлов в личный чат

Сообщение с запросом разрешения на отправку

Действие вызова, когда пользователь принимает файл

Уведомление пользователя об отправленном файле

Базовый пример на C

См. также

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