Envoyer et recevoir des fichiers

Il existe deux façons d’envoyer et de recevoir des fichiers :

• Utilisez les API Microsoft Graph : Cette méthode fonctionne dans toutes les étendues Microsoft Teams (personal, channel, groupchat) .

• Utilisez les API de consentement du fichier sdk Teams : Ceux-ci prennent uniquement en charge les fichiers en personal contexte.

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 et recevoir des fichiers à un agent à l’aide des API de consentement de fichier du SDK Teams.

Utiliser les API de fichier de consentement du sdk Teams

Les API de consentement de fichier du SDK Teams fonctionnent uniquement dans le personal contexte. Ils ne fonctionnent pas dans le channel contexte ou groupchat .

À l’aide du Kit de développement logiciel (SDK) Teams, l’agent peut envoyer et recevoir directement des fichiers avec des utilisateurs dans le personal contexte, également appelé 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. Le Kit de développement logiciel (SDK) Teams fournit des itinéraires d’activité pour la gestion des flux de travail de consentement de fichier, notamment file.consent.accept et file.consent.decline.

Configurer l’agent pour prendre en charge les fichiers

Pour envoyer et recevoir des fichiers dans l’agent, définissez la supportsFiles propriété dans le manifeste sur 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 l’agent n’active supportsFilespas , les fonctionnalités répertoriées dans cette section ne fonctionnent pas.

Recevoir des fichiers en conversation personnelle

Lorsqu’un utilisateur envoie un fichier à l’agent, le fichier est d’abord chargé dans le stockage OneDrive Entreprise de l’utilisateur. L’agent reçoit ensuite une activité de message informant l’utilisateur du 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, l’agent reçoit une activité d’appel avec une URL d’emplacement.
3. Pour transférer le fichier, l’agent effectue une HTTP POST opération directement 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’appel est envoyée à l’agent lorsqu’un utilisateur accepte le fichier. Il contient l’URL OneDrive Entreprise d’espace réservé que l’agent peut ensuite émettre PUT pour 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 de version concise de l’activité d’appel que l’agent 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, l’agent reçoit l’événement suivant avec le même nom d’activité global :

{
  "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érez les images inline qui font partie du message à l’aide du OnMessage gestionnaire. Le Kit de développement logiciel (SDK) Teams gère automatiquement l’authentification, ce qui vous permet d’accéder aux URL de contenu des pièces jointes directement à partir du contexte d’activité.

Le code suivant montre un exemple d’extraction d’images inline à partir d’un message :

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

Exemple de base

L’exemple suivant montre comment gérer le flux de travail de consentement de fichier complet, notamment l’envoi de cartes de consentement, la gestion des réponses acceptées et refusées et le chargement de fichiers sur OneDrive.

Envoyer une carte de consentement de fichier

Le code suivant envoie un carte de consentement de fichier à l’utilisateur, demandant l’autorisation de charger le fichier reçu sur son 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,
    )]))

Gérer le chargement de fichiers

Le code suivant effectue le chargement réel du fichier après que l’utilisateur a accepté le consentement carte, charge le contenu sur OneDrive et envoie un message de réussite avec une pièce jointe d’informations de fichier. En C#, cette logique est inline dans le OnFileConsent gestionnaire.

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

Exemple de code

L’exemple de code suivant montre comment obtenir le consentement d’un fichier et charger des fichiers dans Teams à partir d’un agent :

Voir aussi

• Vue d’ensemble du Kit de développement logiciel (SDK
• Authentification d’utilisateur
• Envoi de messages
• Concepts de base de Teams