Enviar e receber arquivos

Há duas maneiras de enviar e receber arquivos:

• Use as APIs do Microsoft Graph: Este método funciona em todos os escopos dopersonalchannelgroupchat Microsoft Teams.

• Use as APIs de consentimento de arquivo do SDK do Teams: Eles dão suporte apenas a arquivos no personal contexto.

Usar as APIs do Graph

Poste mensagens com anexos de cartão que se referem a arquivos existentes do SharePoint usando as APIs do Graph para OneDrive e SharePoint. Para usar as APIs do Graph, obtenha acesso a qualquer um dos seguintes por meio do fluxo de autorização padrão do OAuth 2.0:

• A pasta do OneDrive de um usuário para arquivos personal e groupchat.
• Os arquivos no canal de uma equipe para channel arquivos.

As APIs do Graph funcionam em todos os escopos do Teams. Para obter mais informações, consulte enviar anexos de arquivo de mensagem de chat.

Como alternativa, você pode enviar e receber arquivos de um agente usando as APIs de consentimento de arquivo do SDK do Teams.

Usar as APIs de arquivo de consentimento do arquivo SDK do Teams

As APIs de consentimento de arquivo do SDK do personal Teams funcionam somente no contexto. Eles não funcionam no channel contexto ou groupchat .

Usando o SDK do Teams, o agente pode enviar e receber diretamente arquivos com usuários no personal contexto, também conhecidos como chats pessoais. Implemente recursos, como relatórios de despesas, reconhecimento de imagem, arquivamento de arquivos e assinaturas eletrônicas que envolvem a edição 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 próximas seções descrevem como enviar conteúdo de arquivo como interação direta do usuário, como enviar uma mensagem. O SDK do Teams fornece rotas de atividade para lidar com fluxos de trabalho de consentimento de arquivos, incluindo file.consent.accept e file.consent.decline.

Configurar o agente para dar suporte a arquivos

Para enviar e receber arquivos no agente, defina a supportsFiles propriedade no manifesto como true. Essa propriedade é descrita na seção bots da referência de manifesto.

A definição tem esta aparência: "supportsFiles": true. Se o agente não habilitar supportsFiles, os recursos listados nesta seção não funcionarão.

Receber arquivos no chat pessoal

Quando um usuário envia um arquivo para o agente, o arquivo é carregado primeiro no armazenamento do OneDrive for Business do usuário. Em seguida, o agente recebe uma atividade de mensagem notificando o usuário 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

O código a seguir mostra um 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:

Como prática recomendada, confirme o upload do arquivo enviando uma mensagem de volta ao usuário.

Carregar arquivos no chat pessoal

Para carregar um arquivo para um usuário:

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 usuário aceitar o download do arquivo, o agente receberá uma atividade de invocação com uma URL de local.
3. Para transferir o arquivo, o agente executa um HTTP POST diretamente na URL de localização fornecida.
4. Opcionalmente, você pode remover o cartão de consentimento original se não quiser permitir que o usuário aceite uploads adicionais 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 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:

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

Uma atividade de invocação é enviada ao agente quando um usuário aceita o arquivo. Ele contém a URL de espaço reservado do OneDrive for Business que o agente pode emitir PUT para transferir o conteúdo do arquivo. Para obter informações sobre como carregar para a URL do OneDrive, consulteCarregar bytes para a sessão de upload.

O código a seguir mostra um exemplo de uma versão concisa da atividade de invocação que o agente 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, o agente 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, envie uma mensagem de confirmação para o usuário. A mensagem deve conter o seguinte anexo FileCard que o usuário pode selecionar, visualizar ou abri-lo no OneDrive ou baixar 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:

Buscar imagens embutidas da mensagem

Busque imagens embutidas que fazem parte da mensagem usando o OnMessage manipulador. O SDK do Teams lida com a autenticação automaticamente, para que você possa acessar URLs de conteúdo de anexo diretamente do contexto da atividade.

O código a seguir mostra um exemplo de busca de imagens embutidas de uma mensagem:

using Microsoft.Teams.Api;
using Microsoft.Teams.Apps;
using Microsoft.Teams.Plugins.AspNetCore.Extensions;

var builder = WebApplication.CreateBuilder(args);
builder.AddTeams();
var app = builder.Build();
var teams = app.UseTeams();

teams.OnMessage(async (context, cancellationToken) =>
{
    var attachment = context.Activity.Attachments?[0];
    if (attachment != null && attachment.ContentType.Contains("image"))
    {
        // Download the inline image from the content URL.
        var client = new HttpClient();
        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 the received image.
        var imageData = Convert.ToBase64String(File.ReadAllBytes(filePath));
        var reply = new MessageActivity(
            $"Attachment of {attachment.ContentType} type and size of {responseMessage.Content.Headers.ContentLength} bytes received.");
        reply.AddAttachment(new Attachment
        {
            Name = "ImageFromUser.png",
            ContentType = "image/png",
            ContentUrl = $"data:image/png;base64,{imageData}",
        });
        await context.SendAsync(reply, cancellationToken);
    }
});

app.Run();

import httpx
from microsoft_teams.api import Attachment, MessageActivity, MessageActivityInput
from microsoft_teams.apps import ActivityContext, App

app = App()

@app.on_message
async def on_message(context: ActivityContext[MessageActivity]):
    attachment = context.activity.attachments[0] if context.activity.attachments else None
    if attachment and "image" in attachment.content_type:
        # Download the inline image from the content URL.
        async with httpx.AsyncClient() as client:
            response = await client.get(attachment.content_url)
            file_path = "files/ImageFromUser.png"
            with open(file_path, "wb") as f:
                f.write(response.content)

        await context.send(
            f"Attachment of {attachment.content_type} type and size of "
            f"{len(response.content)} bytes received."
        )

import { App } from '@microsoft/teams.apps';
import { MessageActivity } from '@microsoft/teams.api';
import * as fs from 'fs';

const app = new App();

app.on('message', async ({ activity, send }) => {
  const attachment = activity.attachments?.[0];
  if (attachment && attachment.contentType?.includes('image')) {
    // Download the inline image from the content URL.
    const response = await fetch(attachment.contentUrl!);
    const buffer = Buffer.from(await response.arrayBuffer());

    // Save the inline image to Files directory.
    fs.writeFileSync('files/ImageFromUser.png', buffer);

    await send(
      `Attachment of ${attachment.contentType} type and size of ${buffer.length} bytes received.`
    );
  }
});

Exemplo básico

O exemplo a seguir mostra como lidar com todo o fluxo de trabalho de consentimento de arquivo, incluindo o envio de cartões de consentimento, o tratamento de respostas aceitas e recusadas e o upload de arquivos para o OneDrive.

Enviar Cartão de Consentimento do Arquivo

O código a seguir envia um card de consentimento de arquivo para o usuário, solicitando permissão para carregar o arquivo recebido no OneDrive:

async Task SendFileConsentCard<T>(IContext<T> context, string fileName, string fileId, int fileSize)
    where T : IActivity
{
    var consentContext = new { filename = fileName, file_id = fileId };

    var fileCard = new FileConsentCard
    {
        Description = "This is the file I want to send you",
        SizeInBytes = fileSize,
        AcceptContext = consentContext,
        DeclineContext = consentContext
    };

    var message = new MessageActivity
    {
        Attachments =
        [
            new Attachment
            {
                Content = fileCard,
                ContentType = new ContentType(ContentTypeFileConsent),
                Name = fileName
            }
        ]
    };
    await context.Send(message);
}

async function sendFileConsentCard(context: any, filename: string, fileId: string): Promise<void> {
  const consentContext = { filename: filename, file_id: fileId };
  await context.send({
    type: 'message',
    attachments: [{
      content: {
        description: 'This is the file I want to send you',
        sizeInBytes: pendingUploads.get(fileId)!.length,
        acceptContext: consentContext,
        declineContext: consentContext
      },
      contentType: CONTENT_TYPE_FILE_CONSENT,
      name: filename
    }]
  });
}

async def _send_file_consent_card(ctx: ActivityContext, filename: str, file_id: str) -> None:
    consent_context = {"filename": filename, "file_id": file_id}
    await ctx.send(MessageActivityInput(attachments=[Attachment(
        content=FileConsentCard(
            description="This is the file I want to send you",
            size_in_bytes=len(pending_uploads[file_id]),
            accept_context=consent_context,
            decline_context=consent_context,
        ),
        content_type=CONTENT_TYPE_FILE_CONSENT,
        name=filename,
    )]))

Lidar com upload de arquivo

O código a seguir executa o upload do arquivo real depois que o usuário aceita o card de consentimento, carrega o conteúdo no OneDrive e envia uma mensagem de sucesso com um anexo de informações de arquivo. Em C#, essa lógica está embutida no OnFileConsent manipulador.

async function handleFileUpload(context: any, uploadInfo: FileUploadInfo, fileId: string): Promise<void> {
  try {
    const content = pendingUploads.get(fileId)!;
    pendingUploads.delete(fileId);
    await uploadToOnedrive(uploadInfo.uploadUrl!, content);
    await context.send({
      type: 'message',
      text: `<b>${uploadInfo.name}</b> has been successfully uploaded.`,
      attachments: [{
        content: {
          uniqueId: uploadInfo.uniqueId,
          fileType: uploadInfo.fileType
        },
        contentType: CONTENT_TYPE_FILE_INFO,
        name: uploadInfo.name,
        contentUrl: uploadInfo.contentUrl
      }]
    });
  } catch (e: any) {
    pendingUploads.delete(fileId);
    console.log(`File upload failed: ${e}`);
  }
}

async function uploadToOnedrive(url: string, content: Buffer): Promise<void> {
  const fileSize = content.length;
  const response = await axios.put(url, content, {
    headers: {
      'Content-Type': 'application/octet-stream',
      'Content-Length': fileSize.toString(),
      'Content-Range': `bytes 0-${fileSize - 1}/${fileSize}`
    }
  });
  if (![200, 201].includes(response.status)) {
    throw new Error(`Upload failed with status ${response.status}`);
  }
}

async def _handle_file_upload(ctx: ActivityContext, upload_info: FileUploadInfo, file_id: str) -> None:
    try:
        content = pending_uploads.pop(file_id)
        await _upload_to_onedrive(upload_info.upload_url, content)
        await ctx.send(MessageActivityInput(
            text=f"<b>{upload_info.name}</b> has been successfully uploaded.",
            attachments=[Attachment(
                content=FileInfoCard(
                    unique_id=upload_info.unique_id,
                    file_type=upload_info.file_type,
                ),
                content_type=CONTENT_TYPE_FILE_INFO,
                name=upload_info.name,
                content_url=upload_info.content_url,
            )],
        ))
    except Exception as e:
        pending_uploads.pop(file_id, None)
        print(f"File upload failed: {e}")

async def _upload_to_onedrive(url: str, content: bytes) -> None:
    file_size = len(content)
    client = Client(ClientOptions(headers={
        "Content-Type": "application/octet-stream",
        "Content-Length": str(file_size),
        "Content-Range": f"bytes 0-{file_size - 1}/{file_size}",
    }))
    response = await client.put(url, content=content)
    if response.status_code not in [200, 201]:
        raise Exception(f"Upload failed with status {response.status_code}")

Exemplo de código

A amostra de código a seguir demonstra como obter consentimento de arquivo e carregar arquivos no Teams de um agente:

Confira também

• Visão geral do SDK do Teams
• Autenticação de usuário
• Enviar mensagens
• Principais conceitos do Teams