Enviar e receber arquivos usando bots

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

• Usando as APIs do Microsoft Graph. Este 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 card que façam referência a 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 personal e groupchat arquivos) ou aos arquivos nos canais de uma equipe (para channel arquivos) 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

Seu bot pode enviar e receber diretamente arquivos com usuários no personal contexto, também conhecidos 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. Files compartilhados no Teams normalmente aparecem como cartões e permitem uma visualizaçã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 bots do Microsoft Teams.

Configurar seu bot para dar suporte a arquivos

Para enviar e receber arquivos em seu bot, você precisa definir a supportsFiles propriedade no manifesto como true. Essa propriedade é descrita na seção [bots]/microsoft-365/extensibility/schema/root-bots#supportsfiles) da referência do manifesto.

A definição ficará assim: "supportsFiles": true. Se o bot não habilitar supportsFiles, os recursos a seguir não funcionarão.

Receber arquivos no chat pessoal

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

Atividade de mensagem com exemplo de 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:

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

Carregando arquivos no chat pessoal

O upload de um arquivo para um usuário envolve as seguintes etapas:

1. Envie uma mensagem ao usuário solicitando permissão para gravar o arquivo. Esta mensagem deve conter um FileConsentCard anexo com o nome do arquivo a ser carregado.
2. Se o usuário aceitar o download do arquivo, seu bot receberá uma atividade Invoke com uma URL de local.
3. Para transferir o arquivo, o bot executa um HTTP POST diretamente na URL de local fornecida.
4. Opcionalmente, você poderá remover o card de consentimento original se não quiser permitir que o usuário aceite mais uploads do mesmo arquivo.

Mensagem solicitando permissão para carregar

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

Esta mensagem móvel contém um objeto anexo solicitando permissão do 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:

Invocar atividade quando o usuário aceitar o arquivo

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

O exemplo a seguir mostra uma versão resumida 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 usuário recusar o arquivo, seu bot receberá o seguinte evento, com o mesmo nome geral da atividade:

{
  "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, independentemente de você usar o mecanismo descrito acima ou as APIs delegadas pelo usuário do OneDrive, você deve enviar uma mensagem de confirmação ao usuário. Esta mensagem deve conter um FileCard anexo no qual o usuário possa selecionar, seja para visualizá-lo, abri-lo no OneDrive ou baixá-lo 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:

Exemplo básico em C

O exemplo a seguir mostra como você pode lidar com carregamentos de arquivos e enviar solicitações de consentimento de arquivos na caixa de diálogo do seu 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