Envío y recepción de archivos

Hay dos maneras de enviar y recibir archivos:

• Use las API de Microsoft Graph: Este método funciona en todos los ámbitos de Microsoft Teams (personal, channel, groupchat).

• Use las API de consentimiento de archivos del SDK de Teams: Solo admiten archivos en personal contexto.

Uso de graph API

Publique mensajes con datos adjuntos de tarjeta que hagan referencia a archivos de SharePoint ya existentes, mediante Graph API para OneDrive y SharePoint. Para usar graph API, obtenga acceso a cualquiera de las siguientes opciones a través del flujo de autorización estándar de OAuth 2.0:

• Carpeta de OneDrive de un usuario para archivos personal y groupchat.
• Los archivos del canal de un equipo para channel archivos.

Las API de Graph funcionan en todos los ámbitos de Teams. Para obtener más información, vea enviar datos adjuntos de archivos de mensajes de chat.

Como alternativa, puede enviar y recibir archivos desde un agente mediante las API de consentimiento de archivos del SDK de Teams.

Uso de las API del archivo de consentimiento del SDK de Teams

Las API de consentimiento de archivos del SDK de Teams solo funcionan en el personal contexto. No funcionan en el channel contexto o groupchat .

Con el SDK de Teams, el agente puede enviar y recibir archivos directamente con los usuarios en el personal contexto, también conocidos como chats personales. Implemente funcionalidades, como son informes de gastos, reconocimiento de imágenes, archivado de archivos y firmas electrónicas que implican la edición del contenido del archivo. Los archivos compartidos en Teams suelen aparecer como tarjetas y permiten una visualización enriquecida desde la aplicación.

En las secciones siguientes se describe cómo enviar contenido de archivo como interacción directa del usuario, como el envío de un mensaje. El SDK de Teams proporciona rutas de actividad para controlar flujos de trabajo de consentimiento de archivos, incluidos file.consent.accept y file.consent.decline.

Configuración del agente para admitir archivos

Para enviar y recibir archivos en el agente, establezca la supportsFiles propiedad del manifiesto trueen . Esta propiedad se describe en la sección bots de la referencia del manifiesto.

La definición tiene este aspecto, "supportsFiles": true. Si el agente no habilita supportsFiles, las características enumeradas en esta sección no funcionan.

Recibir archivos en un chat personal

Cuando un usuario envía un archivo al agente, el archivo se carga por primera vez en el almacenamiento de OneDrive para la Empresa del usuario. A continuación, el agente recibe una actividad de mensaje que notifica al usuario sobre la carga del usuario. La actividad contiene metadatos de archivo, como es su nombre y la dirección URL de contenido. El usuario puede leer directamente desde esta dirección URL para capturar su contenido binario.

Ejemplo de actividad de mensaje con datos adjuntos de archivo

El código siguiente muestra un ejemplo de actividad de mensaje con datos adjuntos de archivo:

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

En la tabla siguiente se describen las propiedades de contenido de los datos adjuntos:

Como procedimiento recomendado, confirme la carga del archivo mediante el envío de un mensaje al usuario.

Cargar archivos en un chat personal

Para cargar un archivo en un usuario:

1. Envíe un mensaje al usuario que solicita permiso para escribir el archivo. Este mensaje debe contener FileConsentCard datos adjuntos con el nombre del archivo que se va a cargar.
2. Si el usuario acepta la descarga de archivos, el agente recibe una actividad de invocación con una dirección URL de ubicación.
3. Para transferir el archivo, el agente realiza una HTTP POST operación directamente en la dirección URL de ubicación proporcionada.
4. Opcionalmente, quite la tarjeta de consentimiento original si no desea que el usuario acepte más cargas del mismo archivo.

Mensaje que solicita permiso para cargar

El siguiente mensaje de escritorio contiene un objeto de datos adjuntos simple que solicita permiso de usuario para cargar el archivo:

El siguiente mensaje móvil contiene un objeto de datos adjuntos que solicita permiso de usuario para cargar el archivo:

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

En la tabla siguiente se describen las propiedades de contenido de los datos adjuntos:

Invocación de la actividad cuando el usuario acepta el archivo

Una actividad de invocación se envía al agente cuando un usuario acepta el archivo. Contiene la dirección URL del marcador de posición OneDrive para la Empresa que el agente puede emitir PUT para transferir el contenido del archivo. Para obtener información sobre cómo cargar en la dirección URL de OneDrive, vea cargar bytes en la sesión de carga.

En el código siguiente se muestra un ejemplo de una versión concisa de la actividad de invocación que recibe el agente:

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

Del mismo modo, si el usuario rechaza el archivo, el agente recibe el siguiente evento con el mismo nombre de actividad general:

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

Notificar al usuario sobre un archivo cargado

Después de cargar un archivo en el OneDrive del usuario, envíe un mensaje de confirmación al usuario. El mensaje debe contener los siguientes datos adjuntos FileCard que el usuario puede seleccionar, ya sea para obtener una vista previa o para abrirlo en OneDrive, o descargarlo 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",
    }
  }]
}

En la tabla siguiente se describen las propiedades de contenido de los datos adjuntos:

Capturar imágenes alineadas del mensaje

Captura de imágenes insertadas que forman parte del mensaje mediante el OnMessage controlador . El SDK de Teams controla la autenticación automáticamente, por lo que puede acceder a las direcciones URL de contenido de datos adjuntos directamente desde el contexto de actividad.

En el código siguiente se muestra un ejemplo de captura de imágenes insertadas de un mensaje:

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.`
    );
  }
});

Ejemplo básico

En el ejemplo siguiente se muestra cómo controlar el flujo de trabajo de consentimiento de archivos completo, incluido el envío de tarjetas de consentimiento, el control de respuestas aceptadas y rechazadas y la carga de archivos en OneDrive.

Enviar tarjeta de consentimiento de archivo

El código siguiente envía una tarjeta de consentimiento de archivo al usuario, solicitando permiso para cargar el archivo recibido en su 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,
    )]))

Controlar la carga de archivos

El código siguiente realiza la carga real de archivos después de que el usuario acepte la tarjeta de consentimiento, cargue el contenido en OneDrive y envíe un mensaje de éxito con un archivo adjunto de información. En C#, esta lógica está insertada dentro del OnFileConsent controlador.

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

Ejemplo de código

En el ejemplo de código siguiente se muestra cómo obtener el consentimiento de archivos y cargar archivos en Teams desde un agente:

Consulte también

• Introducción al SDK de Teams
• Autenticación del usuario:
• Envío de mensajes
• Conceptos básicos de Teams