Envoyer et recevoir des fichiers à l’aide de bots

Il existe deux façons d’envoyer des fichiers vers et depuis un bot :

• Utilisation des API Microsoft Graph. Cette méthode fonctionne pour les bots dans toutes les étendues dans Teams :
  • personal
  • channel
  • groupchat
• Utilisation des API Teams. Ceux-ci ne prennent en charge les fichiers que dans un contexte :
  • personal

Utilisation des API Microsoft Graph

Vous pouvez publier des messages avec des pièces jointes de carte faisant référence à des fichiers SharePoint existants à l’aide des API Microsoft Graph pour OneDrive et SharePoint. L’utilisation des API Graph nécessite l’accès au dossier OneDrive d’un utilisateur (pour personal les fichiers et groupchat ) ou aux fichiers des canaux d’une équipe (pour channel les fichiers) via le flux d’autorisation OAuth 2.0 standard. Cette méthode fonctionne dans toutes les étendues Teams.

Utilisation des API bot Teams

Votre bot peut envoyer et recevoir directement des fichiers avec les utilisateurs dans le personal contexte, également appelés conversations personnelles, à l’aide des API Teams. Cela vous permet d’implémenter des notes de frais, la reconnaissance d’images, l’archivage de fichiers, les signatures électroniques et d’autres scénarios impliquant la manipulation directe du contenu des fichiers. Les Files partagés dans Teams apparaissent généralement sous forme de cartes et permettent un affichage enrichi dans l’application.

Les sections suivantes décrivent la procédure à suivre pour envoyer du contenu de fichier suite à une interaction directe de l’utilisateur, comme l’envoi d’un message. Cette API est fournie dans le cadre de la plateforme de bot Microsoft Teams.

Configurer votre bot pour qu’il prenne en charge les fichiers

Pour envoyer et recevoir des fichiers dans votre bot, vous devez définir la supportsFiles propriété dans le manifeste sur true. Cette propriété est décrite dans la section [bots]/microsoft-365/extensibility/schema/root-bots#supportsfiles) de la référence du manifeste.

La définition ressemblera à ceci : "supportsFiles": true. Si votre bot n’active supportsFilespas , les fonctionnalités suivantes ne fonctionneront pas.

Réception de fichiers dans la conversation personnelle

Lorsqu’un utilisateur envoie un fichier à votre bot, le fichier est d’abord chargé dans le stockage OneDrive Entreprise de l’utilisateur. Votre bot recevra ensuite une activité de message vous informant du chargement par l’utilisateur. L’activité contient des métadonnées de fichier, telles que son nom et l’URL de contenu. Vous pouvez lire directement à partir de cette URL pour récupérer son contenu binaire.

Exemple d’activité de message avec pièce jointe

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

Le tableau suivant décrit les propriétés de contenu de la pièce jointe :

Il est préférable d’accepter le chargement du fichier en renvoyant un message à l’utilisateur.

Chargement de fichiers dans une conversation personnelle

Le téléchargement d’un fichier vers un utilisateur implique les étapes suivantes :

1. Envoyez un message à l’utilisateur pour lui demander l’autorisation d’écrire le fichier. Ce message doit contenir une FileConsentCard pièce jointe portant le nom du fichier à télécharger.
2. Si l’utilisateur accepte le téléchargement du fichier, votre bot reçoit une activité Invoke avec une URL d’emplacement.
3. Pour transférer le fichier, votre bot effectue un HTTP POST directement dans l’URL d’emplacement fournie.
4. Si vous le souhaitez, vous pouvez supprimer la carte de consentement d’origine si vous ne souhaitez pas autoriser l’utilisateur à accepter d’autres chargements du même fichier.

Message demandant l’autorisation de téléchargement

Ce message de bureau contient une pièce jointe simple demandant à l’utilisateur l’autorisation de télécharger le fichier :

Ce message mobile contient une pièce jointe demandant à l’utilisateur l’autorisation de charger le fichier :

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

Le tableau suivant décrit les propriétés de contenu de la pièce jointe :

Appeler l’activité lorsque l’utilisateur accepte le fichier

Une activité d’appel est envoyée à votre bot si et quand l’utilisateur accepte le fichier. Il contient l’URL de l’espace réservé OneDrive Entreprise dans laquelle votre bot peut ensuite émettre un PUT pour transférer le contenu du fichier. Pour plus d’informations sur le chargement vers l’URL OneDrive, lisez cet article : Charger des octets vers la session de téléchargement.

L’exemple suivant montre une version abrégée de l’activité d’appel que votre bot reçoit :

{
  ...

  "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 même, si l’utilisateur refuse le fichier, votre bot reçoit l’événement suivant, avec le même nom d’activité globale :

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

Notification à l’utilisateur d’un fichier téléchargé

Après avoir téléchargé un fichier sur le OneDrive de l’utilisateur, que vous utilisiez le mécanisme décrit ci-dessus ou les API OneDrive déléguées par l’utilisateur, vous devez envoyer un message de confirmation à l’utilisateur. Ce message doit contenir une FileCard pièce jointe sur laquelle l’utilisateur peut sélectionner pour l’afficher en aperçu, l’ouvrir dans OneDrive ou le télécharger localement.

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

Le tableau suivant décrit les propriétés de contenu de la pièce jointe :

Exemple de base en C

L’exemple suivant montre comment gérer les téléchargements de fichiers et envoyer des demandes de consentement pour un fichier dans la boîte de dialogue de votre 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;
}

Voir aussi

Utilisation de fichiers dans Microsoft Graph