Envoyer et recevoir des fichiers à l’aide d’un bot

Il y a deux façons d'envoyer des fichiers à un robot et de recevoir des fichiers de celui-ci :

• Utilisez les API graphiques de Microsoft : Cette méthode fonctionne pour les robots dans toutes les portées de Microsoft Teams :

  • personal
  • channel
  • groupchat

• Utilisez les API des robots Teams :Celles-ci ne prennent en charge que les fichiers enpersonal contexte.

La vidéo suivante montre comment un bot simplifie le processus d’envoi et de réception de fichiers avec facilité et efficacité :

Utiliser les API graphiques

Publier des messages avec des cartes jointes qui font référence à des fichiers SharePoint existants, en utilisant les API graphiques pour OneDrive et SharePoint. Pour utiliser les API graphiques, obtenez l'accès à l'un des éléments suivants par le biais du flux d'autorisation OAuth 2.0 standard :

• Le dossier OneDrive d'un utilisateur pour personal et groupchat fichiers.
• Les fichiers dans le canal d'une équipe pour channel les fichiers.

Les API graphiques fonctionnent dans toutes les portées de Teams. Pour plus d'informations, voir la section Envoyer des pièces jointes aux messages de conversation.

Vous pouvez également envoyer des fichiers à un robot et en recevoir de celui-ci à l'aide des API de robots Teams.

Utiliser les API des robots Teams

Les API des robots de l'équipe ne fonctionnent que dans le personalcontexte. Ils ne fonctionnent pas dans le channel contexte ou groupchat .

Grâce aux API de Teams, le robot peut envoyer et recevoir directement des fichiers avec les utilisateurs dans le contexte, également connu sous le nom de personal conversations personnelles . Mettre en œuvre des fonctionnalités, telles que le rapport de dépenses, la reconnaissance d'images, l'archivage de fichiers et les signatures électroniques impliquant l'édition du contenu des fichiers. Les fichiers partagés dans Teams apparaissent généralement sous forme de cartes et permettent une visualisation riche dans l'application.

Les sections suivantes décrivent comment envoyer le contenu d'un fichier en tant qu'interaction directe avec l'utilisateur, comme l'envoi d'un message. Cette API est fournie dans le cadre de la plateforme de robots Teams.

Configurer le robot pour qu'il prenne en charge les fichiers

Pour envoyer et recevoir des fichiers dans le robot, définissez la supportsFilespropriété dans le manifeste àtrue. Cette propriété est décrite dans la section bots de la référence du manifeste.

La définition ressemble à ceci, "supportsFiles": true. Si le robot n'est pas activé, supportsFilesles fonctions énumérées dans cette section ne fonctionnent pas.

Recevoir des fichiers en conversation personnelle

Lorsqu'un utilisateur envoie un fichier au robot, celui-ci est d'abord téléchargé vers le stockage OneDrive for business de l'utilisateur. Le robot reçoit alors un message d'activité notifiant l'utilisateur du téléchargement de l'utilisateur. L'activité contient les métadonnées du fichier, telles que son nom et l'URL du contenu. L'utilisateur peut lire directement cette URL pour récupérer son contenu binaire.

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

Le code suivant montre un 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 du contenu de la pièce jointe :

En guise de meilleure pratique, accusez réception du téléchargement du fichier en envoyant un message à l'utilisateur.

Télécharger fichiers à une conversation personnelle

Pour télécharger un fichier vers un utilisateur :

1. Envoyer un message à l'utilisateur pour lui demander la permission d'écrire dans le fichier. Ce message doit contenir une FileConsentCardpièce jointe avec le nom du fichier à télécharger.
2. Si l'utilisateur accepte le téléchargement du fichier, le robot reçoit une activité d'invocation avec une URL de localisation.
3. Pour transférer le fichier, le robot exécute un HTTP POSTdirectement dans l'URL de l'emplacement fourni.
4. Si vous le souhaitez, vous pouvez supprimer la carte de consentement initiale si vous ne voulez pas que l'utilisateur accepte d'autres téléchargements du même fichier.

Message demandant l'autorisation de télécharger

Le message de bureau suivant contient un objet de pièce jointe simple demandant à l'utilisateur l'autorisation de télécharger le fichier :

Le message mobile suivant contient un objet attaché demandant à l'utilisateur l'autorisation de télé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 du contenu de la pièce jointe :

Invoquer l'activité lorsque l'utilisateur accepte le fichier

Une activité d'invocation est envoyée au robot si et quand l'utilisateur accepte le fichier. Il contient l'URL de remplacement de OneDrive pour entreprises que le robot peut ensuite émettre pour PUT transférer le contenu du fichier. Pour plus d'informations sur le téléchargement vers l'URL OneDrive, voir Télécharger des octets vers la session de téléchargement.

Le code suivant montre un exemple d'une version concise de l'activité invoquer que le robot 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, le robot reçoit l'événement suivant avec le même nom d'activité globale :

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

Notifier l'utilisateur d'un fichier téléchargé

Après avoir téléchargé un fichier sur le OneDrive de l'utilisateur, envoyez un message de confirmation à l'utilisateur. Le message doit contenir la pièce jointe suivante FileCardque l'utilisateur peut sélectionner, soit pour la prévisualiser ou l'ouvrir dans OneDrive, soit pour la 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 du contenu de la pièce jointe :

Récupérer les images en ligne du message

Récupérer les images en ligne qui font partie du message en utilisant le jeton d'accès du robot.

Le code suivant montre un exemple de récupération d'images en ligne à partir d'un 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}​​​​​",
    }​​​​​;
}​​​​​

Exemple de base en C#

Le code suivant montre un exemple de la façon de gérer les téléchargements de fichiers et d'envoyer des demandes de consentement de fichiers dans le dialogue du robot :

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

Exemple de code

L'exemple de code suivant montre comment obtenir le consentement de fichiers et télécharger des fichiers vers Teams à partir d'un robot :

Guide pas à pas

Suivez le guide étape par étape pour télécharger un fichier dans Teams à l'aide d'un robot.

Étape suivante

Voir aussi

• Créer des bots pour Teams
• Flux d’authentification pour les bots dans Microsoft Teams
• Avoir une conversation personnelle (en tête-à-tête) avec un bot Microsoft Teams
• Obtenir le contexte spécifique à Teams pour votre bot