Enviar e receber arquivos por meio do botSend and receive files through the bot

Importante

Os artigos neste documento são baseados no SDK da Estrutura de Bots v4.The articles in this document are based on the v4 Bot Framework SDK.

Há duas maneiras de enviar arquivos para e receber arquivos de um bot:There are two ways to send files to and receive files from a bot:

Usar as APIs do GraphUse the Graph APIs

Poste mensagens com anexos de cartão que se referem a arquivos existentes do SharePoint, usando as APIs do Graph para OneDrive e SharePoint.Post messages with card attachments that refer to existing SharePoint files, using the Graph APIs for OneDrive and SharePoint. Para usar as APIs do Graph, obtenha acesso a qualquer um dos seguintes por meio do fluxo de autorização OAuth 2.0 padrão:To use the Graph APIs, obtain access to either of the following through the standard OAuth 2.0 authorization flow:

  • Pasta do OneDrive de um usuário e personal groupchat arquivos.A user's OneDrive folder for personal and groupchat files.
  • Os arquivos no canal de uma equipe para channel arquivos.The files in a team's channel for channel files.

As APIs gráficas funcionam em todos os escopos do Teams.Graph APIs work in all Teams scopes. Para obter mais informações, consulte send chat message file attachments.For more information, see send chat message file attachments.

Como alternativa, você pode enviar arquivos para e receber arquivos de um bot usando as APIs de bot do Teams.Alternately, you can send files to and receive files from a bot using the Teams bot APIs.

Usar as APIs de bot do TeamsUse the Teams bot APIs

Observação

As APIs de bot do Teams funcionam somente no personal contexto.Teams bot APIs work only in the personal context. Eles não funcionam no channel contexto groupchat ou.They do not work in the channel or groupchat context.

Usando APIs do Teams, o bot pode enviar e receber arquivos diretamente com usuários no contexto, também personal conhecidos como chats pessoais.Using Teams APIs, the bot can directly send and receive files with users in the personal context, also known as personal chats. Implemente recursos, como relatórios de despesas, reconhecimento de imagem, arquivamento de arquivos e assinaturas eletrônicas envolvendo a edição de conteúdo de arquivo.Implement features, such as expense reporting, image recognition, file archival, and e-signatures involving the editing of file content. Os arquivos compartilhados no Teams normalmente aparecem como cartões e permitem a exibição rica no aplicativo.Files shared in Teams typically appear as cards and allow rich in-app viewing.

As próximas seções descrevem como enviar conteúdo de arquivo como interação direta do usuário, como o envio de uma mensagem.The next sections describe how to send file content as direct user interaction, like sending a message. Essa API é fornecida como parte da plataforma de bot do Teams.This API is provided as part of the Teams bot platform.

Configurar o bot para dar suporte a arquivosConfigure the bot to support files

Para enviar e receber arquivos no bot, de definir a supportsFiles propriedade no manifesto como true .To send and receive files in the bot, set the supportsFiles property in the manifest to true. Essa propriedade é descrita na seção bots da referência manifesto.This property is described in the bots section of the Manifest reference.

A definição tem esta aparência, "supportsFiles": true .The definition looks like this, "supportsFiles": true. Se o bot não supportsFiles habilitar , os recursos listados nesta seção não funcionarão.If the bot does not enable supportsFiles, the features listed in this section do not work.

Receber arquivos no chat pessoalReceive files in personal chat

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.When a user sends a file to the bot, the file is first uploaded to the user's OneDrive for business storage. Em seguida, o bot recebe uma atividade de mensagem notificando o usuário sobre o carregamento do usuário.The bot then receives a message activity notifying the user about the user upload. A atividade contém metadados de arquivo, como seu nome e a URL de conteúdo.The activity contains file metadata, such as its name and the content URL. O usuário pode ler diretamente a partir dessa URL para buscar seu conteúdo binário.The user can directly read from this URL to fetch its binary content.

Atividade de mensagem com exemplo de anexo de arquivoMessage activity with file attachment example

O código a seguir mostra um exemplo de atividade de mensagem com anexo de arquivo:The following code shows an example of message activity with file attachment:

{
  "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:The following table describes the content properties of the attachment:

PropriedadeProperty ObjetivoPurpose
downloadUrl URL do OneDrive para buscar o conteúdo do arquivo.OneDrive URL for fetching the content of the file. O usuário pode emitir um HTTP GET diretamente a partir dessa URL.The user can issue an HTTP GET directly from this URL.
uniqueId ID de arquivo exclusivo.Unique file ID. Esta é a ID do item de unidade do OneDrive, caso o usuário envie um arquivo para o bot.This is the OneDrive drive item ID, in case the user sends a file to the bot.
fileType Tipo de arquivo, como .pdf ou .docx.Type of file, such as .pdf or .docx.

Como prática prática, confirme o carregamento de arquivo enviando uma mensagem de volta para o usuário.As a best practice, acknowledge the file upload by sending a message back to the user.

Carregar arquivos no chat pessoalUpload files to personal chat

Para carregar um arquivo em um usuárioTo upload a file to a user

  1. Envie uma mensagem para o usuário solicitando permissão para gravar o arquivo.Send a message to the user requesting permission to write the file. Esta mensagem deve conter FileConsentCard um anexo com o nome do arquivo a ser carregado.This message must contain a FileConsentCard attachment with the name of the file to be uploaded.
  2. Se o usuário aceitar o download do arquivo, o bot receberá uma atividade de invocação com uma URL de local.If the user accepts the file download, the bot receives an invoke activity with a location URL.
  3. Para transferir o arquivo, o bot executa um diretamente para a HTTP POST URL de local fornecida.To transfer the file, the bot performs an HTTP POST directly into the provided location URL.
  4. Opcionalmente, remova o cartão de consentimento original se você não quiser que o usuário aceite mais carregamentos do mesmo arquivo.Optionally, remove the original consent card if you do not want the user to accept further uploads of the same file.

Mensagem solicitando permissão para carregarMessage requesting permission to upload

A seguinte mensagem da área de trabalho contém um objeto de anexo simples solicitando permissão do usuário para carregar o arquivo:The following desktop message contains a simple attachment object requesting user permission to upload the file:

Cartão de consentimento solicitando permissão do usuário para carregar arquivo

A seguinte mensagem móvel contém um objeto de anexo solicitando permissão do usuário para carregar o arquivo:The following mobile message contains an attachment object requesting user permission to upload the file:

Consent card requesting user permission to upload file on mobile
{
  "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:The following table describes the content properties of the attachment:

PropriedadeProperty ObjetivoPurpose
description Descreve a finalidade do arquivo ou resume seu conteúdo.Describes the purpose of the file or summarizes its content.
sizeInBytes Fornece ao usuário uma estimativa do tamanho do arquivo e da quantidade de espaço necessário no OneDrive.Provides the user an estimate of the file size and the amount of space it takes in OneDrive.
acceptContext Contexto adicional que é transmitido silenciosamente para o bot quando o usuário aceita o arquivo.Additional context that is silently transmitted to the bot when the user accepts the file.
declineContext Contexto adicional que é transmitido silenciosamente para o bot quando o usuário recusa o arquivo.Additional context that is silently transmitted to the bot when the user declines the file.

Invocar atividade quando o usuário aceitar o arquivoInvoke activity when the user accepts the file

Uma atividade de invocação é enviada ao bot se e quando o usuário aceitar o arquivo.An invoke activity is sent to the bot if and when the user accepts the file. Ele contém a URL de espaço reservado do OneDrive for Business que o bot pode emitir para PUT transferir o conteúdo do arquivo.It contains the OneDrive for Business placeholder URL that the bot can then issue a PUT to transfer the file contents. Para obter informações sobre como carregar para a URL do OneDrive, consulte upload bytes para a sessão de carregamento.For information on uploading to the OneDrive URL, see upload bytes to the upload session.

O código a seguir mostra um exemplo de uma versão concisa da atividade de invocação que o bot recebe:The following code shows an example of a concise version of the invoke activity that the bot receives:

{
  "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, o bot receberá o seguinte evento com o mesmo nome de atividade geral:Similarly, if the user declines the file, the bot receives the following event with the same overall activity name:

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

Notificar o usuário sobre um arquivo carregadoNotifying the user about an uploaded file

Depois de carregar um arquivo no OneDrive do usuário, envie uma mensagem de confirmação para o usuário.After uploading a file to the user's OneDrive, send a confirmation message to the user. A mensagem deve conter o seguinte anexo que o usuário pode selecionar, para visualizar ou FileCard abri-la no OneDrive, ou baixar localmente:The message must contain the following FileCard attachment that the user can select, either to preview or open it in OneDrive, or download locally:

{
  "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:The following table describes the content properties of the attachment:

PropriedadeProperty ObjetivoPurpose
uniqueId ID do item de unidade do OneDrive ou sharePoint.OneDrive or SharePoint drive item ID.
fileType Tipo de arquivo, como .pdf ou .docx.Type of file, such as .pdf or .docx.

Buscar imagens em linha da mensagemFetch inline images from message

Buscar imagens em linha que fazem parte da mensagem usando o token de acesso do Bot.Fetch inline images that are part of the message using the Bot's access token.

Imagem em linha

O código a seguir mostra um exemplo de busca de imagens em linha da mensagem:The following code shows an example of fetching inline images from message:

private async Task ProcessInlineImage(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
    var attachment = turnContext.Activity.Attachments[0];
    var client = _clientFactory.CreateClient();
    // Get Bot's access token to fetch inline image. 
    var token = await new MicrosoftAppCredentials(microsoftAppId, microsoftAppPassword).GetTokenAsync();
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);
    var responseMessage = await client.GetAsync(attachment.ContentUrl);
    // Save the inline image to Files directory.
    var filePath = Path.Combine("Files", "ImageFromUser.png");
    using (var fileStream = new FileStream(filePath, FileMode.Create, FileAccess.Write, FileShare.None))
    {
        await responseMessage.Content.CopyToAsync(fileStream);
    }
    // Create reply with image.
    var reply = MessageFactory.Text($"Attachment of {attachment.ContentType} type and size of {responseMessage.Content.Headers.ContentLength} bytes received.");
    reply.Attachments = new List<Attachment>() { 
        GetInlineAttachment() 
    };
    await turnContext.SendActivityAsync(reply, cancellationToken);
}
private static Attachment GetInlineAttachment()
{
    var imagePath = Path.Combine("Files", "ImageFromUser.png");
    var imageData = Convert.ToBase64String(File.ReadAllBytes(imagePath));
    return new Attachment
    {
        Name = @"ImageFromUser.png",
        ContentType = "image/png",
        ContentUrl = $"data:image/png;base64,{imageData}",
    };
}

Exemplo básico em C #Basic example in C#

O código a seguir mostra um exemplo de como lidar com carregamentos de arquivo e enviar solicitações de consentimento de arquivo na caixa de diálogo do bot:The following code shows an example of how to handle file uploads and send file consent requests in the bot's dialog:


protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
    if (turnContext.Activity.Attachments?[0].ContentType.Contains("image/*") == true)
    {
        // Inline image.
        await ProcessInlineImage(turnContext, cancellationToken);
    }
    else
    {
        string filename = "teams-logo.png";
        string filePath = Path.Combine("Files", filename);
        long fileSize = new FileInfo(filePath).Length;
        await SendFileCardAsync(turnContext, filename, fileSize, cancellationToken);
    }
}
private async Task ProcessInlineImage(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
    var attachment = turnContext.Activity.Attachments[0];
    var client = _clientFactory.CreateClient();
    // Get Bot's access token to fetch inline image. 
    var token = await new MicrosoftAppCredentials(microsoftAppId, microsoftAppPassword).GetTokenAsync();
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);
    var responseMessage = await client.GetAsync(attachment.ContentUrl);
    // Save the inline image to Files directory.
    var filePath = Path.Combine("Files", "ImageFromUser.png");
    using (var fileStream = new FileStream(filePath, FileMode.Create, FileAccess.Write, FileShare.None))
    {
        await responseMessage.Content.CopyToAsync(fileStream);
    }
    // Create reply with image.
    var reply = MessageFactory.Text($"Attachment of {attachment.ContentType} type and size of {responseMessage.Content.Headers.ContentLength} bytes received.");
    reply.Attachments = new List<Attachment>() { GetInlineAttachment() };
    await turnContext.SendActivityAsync(reply, cancellationToken);
}
private static Attachment GetInlineAttachment()
{
    var imagePath = Path.Combine("Files", "ImageFromUser.png");
    var imageData = Convert.ToBase64String(File.ReadAllBytes(imagePath));
    return new Attachment
    {
        Name = @"ImageFromUser.png",
        ContentType = "image/png",
        ContentUrl = $"data:image/png;base64,{imageData}",
    };
}
private async Task SendFileCardAsync(ITurnContext turnContext, string filename, long filesize, CancellationToken cancellationToken)
{
    var consentContext = new Dictionary<string, string>
    {
        { 
            "filename", filename 
        },
    };
    var fileCard = new FileConsentCard
    {
        Description = "This is the file I want to send you",
        SizeInBytes = filesize,
        AcceptContext = consentContext,
        DeclineContext = consentContext,
    };
    var asAttachment = new Attachment
    {
        Content = fileCard,
        ContentType = FileConsentCard.ContentType,
        Name = filename,
    };
    var replyActivity = turnContext.Activity.CreateReply();
    replyActivity.Attachments = new List<Attachment>() { asAttachment };
    await turnContext.SendActivityAsync(replyActivity, cancellationToken);
}

Exemplo de códigoCode sample

O exemplo de código a seguir demonstra como obter o consentimento do arquivo e carregar arquivos para o Teams a partir de um bot:The following code sample demonstrates how to obtain file consent and upload files to Teams from a bot:

Exemplo de nomeSample name DescriçãoDescription .NET.NET JavascriptJavascript PythonPython
Upload de arquivosFile upload Demonstra como obter o consentimento do arquivo e carregar arquivos no Teams de um bot.Demonstrates how to obtain file consent and upload files to Teams from a bot. Além disso, como receber um arquivo enviado para um bot.Also, how to receive a file sent to a bot. ViewView ViewView ViewView

Próxima etapaNext step