Enviar y recibir archivos mediante bots

Hay dos maneras de enviar archivos a y desde un bot:

• Uso de las API de Microsoft Graph. Este método funciona con bots en todos los ámbitos de Teams:
  • personal
  • channel
  • groupchat
• Usar las API de Teams. Estos solo admiten archivos en un contexto:
  • personal

Uso de las API de Microsoft Graph

Puede publicar mensajes con datos adjuntos de tarjeta que hagan referencia a archivos SharePoint existentes mediante las API de Microsoft Graph para OneDrive y SharePoint. El uso de las API de Graph requiere obtener acceso a la carpeta de OneDrive de un usuario (para personal y groupchat archivos) o a los archivos de los canales de un equipo (para channel archivos) a través del flujo de autorización estándar de OAuth 2.0. Este método funciona en todos los ámbitos de Teams.

Usar las API de bot de Teams

El bot puede enviar y recibir archivos directamente con los usuarios en el contexto, también conocido como chats personales, mediante las API de personal Teams. Esto le permite implementar informes de gastos, reconocimiento de imágenes, archivado de archivos, firmas electrónicas y otros escenarios que implican la manipulación directa del contenido de los archivos. Los Files compartidos en Teams suelen aparecer como tarjetas y permiten una visualización completa en la aplicación.

En las secciones siguientes se describe cómo hacerlo para enviar contenido de archivo como resultado de la interacción directa del usuario, como enviar un mensaje. Esta API se proporciona como parte de la plataforma de bots de Microsoft Teams.

Configurar el bot para admitir archivos

Para enviar y recibir archivos en el bot, debe establecer la supportsFiles propiedad del manifiesto en true. Esta propiedad se describe en la sección [bots]/microsoft-365/extensibility/schema/root-bots#supportsfiles) de la referencia del manifiesto.

La definición se verá así: "supportsFiles": true. Si el bot no lo habilita supportsFiles, las siguientes características no funcionarán.

Recibir archivos en el chat personal

Cuando un usuario envía un archivo al bot, el archivo se carga primero en el almacenamiento de OneDrive para la Empresa del usuario. El bot recibirá una actividad de mensaje notificándole la carga del usuario. La actividad contiene metadatos de archivo, como su nombre y la dirección URL del contenido. Puede leer directamente desde esta dirección URL para capturar su contenido binario.

Ejemplo de actividad de mensajes 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 práctica recomendada, debe confirmar la carga de archivos enviando un mensaje al usuario.

Cargar archivos en el chat personal

La carga de un archivo a un usuario implica los siguientes pasos:

1. Envíe un mensaje al usuario solicitando permiso para escribir el archivo. Este mensaje debe contener un FileConsentCard archivo adjunto con el nombre del archivo que se va a cargar.
2. Si el usuario acepta la descarga del archivo, el bot recibe una actividad Invocar con una dirección URL de ubicación.
3. Para transferir el archivo, el bot realiza un HTTP POST directamente en la dirección URL de ubicación proporcionada.
4. Opcionalmente, puedes quitar la tarjeta de consentimiento original si no quieres permitir que el usuario acepte más cargas del mismo archivo.

Mensaje en el que se solicita permiso para cargar

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

Este mensaje móvil contiene un objeto de datos adjuntos que solicita el permiso del 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:

Invocar actividad cuando el usuario acepta el archivo

Se envía una actividad de invocación al bot siempre y cuando el usuario acepte el archivo. Contiene la dirección URL del marcador de posición de OneDrive para la Empresa en la que el bot puede emitir un PUT para transferir el contenido del archivo. Para obtener información sobre cómo cargar en la dirección URL de OneDrive, lea este artículo: Cargar bytes en la sesión de carga.

En el ejemplo siguiente se muestra una versión abreviada de la actividad de invocación que recibe el bot:

{
  ...

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

De forma similar, si el usuario rechaza el archivo, el bot recibe el siguiente evento, con el mismo nombre de actividad general:

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

Notificación al usuario acerca de un archivo cargado

Después de cargar un archivo en OneDrive del usuario, tanto si usa el mecanismo descrito anteriormente como las API delegadas por el usuario de OneDrive, debe enviar un mensaje de confirmación al usuario. Este mensaje debe contener datos adjuntos en los que el usuario pueda seleccionar, ya sea para obtener una FileCard vista previa, abrirlos en OneDrive o descargarlos 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:

Ejemplo básico en C

En el ejemplo siguiente se muestra cómo puede controlar las cargas de archivos y enviar solicitudes de consentimiento de archivos en el cuadro de diálogo del 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;
}

Vea también

Trabajar con archivos en Microsoft Graph