Enviar e receber ficheiros com bots

Importante

Este artigo baseia-se no SDK v3 do Bot Framework. Se estiver à procura da versão atual da documentação 4.6 ou posterior do SDK, consulte a secção bots de conversação .

Há duas maneiras de enviar arquivos de e para um bot:

• Usando as APIs do Microsoft Graph. Esse método funciona para bots em todos os escopos no Teams:
  • personal
  • channel
  • groupchat
• Usando as APIs do Teams. Eles só dão suporte a arquivos em um contexto:
  • personal

Usando as APIs do Microsoft Graph

Você pode postar mensagens com anexos de cartão referenciando arquivos existentes do SharePoint usando as APIs do Microsoft Graph para OneDrive e SharePoint. O uso das APIs do Graph requer a obtenção de acesso à pasta do OneDrive de um usuário (para arquivos personal e groupchat) ou os arquivos nos canais de uma equipe (para arquivos channel) por meio do fluxo de autorização OAuth 2.0 padrão. Esse método funciona em todos os escopos do Teams.

Usando as APIs de Bot do Teams

Observação

Esse método funciona somente no contexto personal. Ele não funciona no contexto channel ou groupchat.

Seu bot pode enviar e receber arquivos diretamente com usuários no contexto personal, também conhecido como chats pessoais, usando APIs do Teams. Isso permite implementar relatórios de despesas, reconhecimento de imagem, arquivamento de arquivos, assinaturas eletrônicas e outros cenários que envolvem manipulação direta do conteúdo do arquivo. Os arquivos compartilhados no Teams normalmente aparecem como cartões e permitem a exibição avançada no aplicativo.

As seções a seguir descrevem como fazer isso para enviar conteúdo de arquivo como resultado da interação direta do usuário, como enviar uma mensagem. Essa API é fornecida como parte da Plataforma de Bot do Microsoft Teams.

Configurar seu bot para dar suporte a arquivos

Para enviar e receber arquivos em seu bot, você precisa definir a propriedade supportsFiles no manifesto como true. Essa propriedade é descrita na seção bots da referência de manifesto.

A definição terá esta aparência: "supportsFiles": true. Se o bot não ativar supportsFiles, as seguintes funcionalidades não funcionarão.

Recebendo arquivos no chat pessoal

Quando um usuário envia um arquivo para o bot, o arquivo é carregado pela primeira vez no armazenamento do OneDrive for Business do usuário. Em seguida, seu bot receberá uma atividade de mensagem notificando sobre o upload do usuário. A atividade conterá metadados de arquivo, como seu nome e a URL de conteúdo. Você pode ler diretamente dessa URL para buscar seu conteúdo binário.

Exemplo de atividade de mensagem com anexo de arquivo

{
  "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"
    }
  }]
}

A tabela a seguir descreve as propriedades de conteúdo do anexo:

Propriedade	Objetivo
downloadUrl	URL do OneDrive para buscar o conteúdo do arquivo. Você pode emitir um HTTP GET diretamente dessa URL.
uniqueId	ID de arquivo exclusiva. Essa será a ID do item de unidade do OneDrive, no caso do usuário enviar um arquivo para o bot.
fileType	Tipo de extensão de arquivo, como pdf ou docx.

Como prática recomendada, você deve reconhecer o upload do arquivo enviando uma mensagem de volta para o usuário.

Carregando arquivos no chat pessoal

Carregar um arquivo para um usuário envolve as seguintes etapas:

1. Envie uma mensagem para o usuário solicitando permissão para gravar o arquivo. Esta mensagem deve conter um anexo FileConsentCard com o nome do arquivo a ser carregado.
2. Se o utilizador aceitar a transferência do ficheiro, o bot recebe uma atividade Invocar com um URL de localização.
3. Para transferir o arquivo, o bot executa um HTTP POST diretamente na URL de local fornecida.
4. Opcionalmente, pode remover o cartão de consentimento original se não quiser permitir que o utilizador aceite mais carregamentos do mesmo ficheiro.

Mensagem solicitando permissão para carregar

Esta mensagem da área de trabalho contém um objeto de anexo simples solicitando permissão de usuário para carregar o arquivo:

Esta mensagem móvel contém um objeto de anexo solicitando permissão de usuário para carregar o arquivo:

{
  "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": {
      }
    }
  }]
}

A tabela a seguir descreve as propriedades de conteúdo do anexo:

Propriedade	Objetivo
description	Descrição do recurso. Pode ser mostrado ao usuário para descrever sua finalidade ou resumir seu conteúdo.
sizeInBytes	Fornece ao usuário uma estimativa do tamanho do arquivo e da quantidade de espaço que ele levará no OneDrive.
acceptContext	Contexto adicional que será transmitido silenciosamente para o bot quando o usuário aceitar o arquivo.
declineContext	Contexto adicional que será transmitido silenciosamente para o bot quando o usuário recusar o arquivo.

Atividade de invocação quando o usuário aceitar o arquivo

Uma atividade de invocação é enviada ao bot se e quando o usuário aceita o arquivo. Ele contém OneDrive for Business URL de espaço reservado para a qual o bot pode emitir um PUT para transferir o conteúdo do arquivo. Para obter informações sobre como carregar para o URL do OneDrive, leia este artigo: Carregar bytes para a sessão de carregamento.

O exemplo seguinte mostra uma versão abreviada da atividade de invocação que o bot recebe:

{
  ...

  "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"
    }
  }
}

Da mesma forma, se o utilizador recusar o ficheiro, o bot recebe o seguinte evento, com o mesmo nome de atividade geral:

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

Notificando o usuário sobre um arquivo carregado

Depois de carregar um arquivo no OneDrive do usuário, se você usar o mecanismo descrito acima ou as APIs delegadas pelo usuário do OneDrive, deverá enviar uma mensagem de confirmação ao usuário. Esta mensagem deve conter um FileCard anexo que o utilizador pode selecionar para pré-visualizar, abri-lo no OneDrive ou transferir localmente.

{
  "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",
    }
  }]
}

A tabela a seguir descreve as propriedades de conteúdo do anexo:

Propriedade	Objetivo
uniqueId	ID do item da unidade do OneDrive/SharePoint.
fileType	Tipo de arquivo, como pdf ou docx.

Exemplo básico em C

O exemplo a seguir mostra como você pode lidar com uploads de arquivos e enviar solicitações de consentimento de arquivo na caixa de diálogo do bot:

// 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;
}

Confira também

Trabalhando com arquivos no Microsoft Graph