Dateien senden und erhalten

Es gibt zwei Möglichkeiten zum Senden und Empfangen von Dateien:

• Verwenden Sie die Microsoft Graph-APIs: Diese Methode funktioniert in allen Microsoft Teams-Bereichen (personal, channel, groupchat).

• Verwenden Sie die Teams SDK-Datei-Zustimmungs-APIs: Diese unterstützen nur Dateien im personal Kontext.

Verwenden der Graph-APIs

Posten Sie Nachrichten mit Kartenanlagen, die auf vorhandene SharePoint-Dateien verweisen, mithilfe der Graph-APIs für OneDrive und SharePoint. Um die Graph-APIs zu verwenden, erhalten Sie über den standardmäßigen OAuth 2.0-Autorisierungsfluss Zugriff auf eine der folgenden Methoden:

• OneDrive-Ordner eines Benutzers für personal- und groupchat-Dateien.
• Dateien im Kanal eines Teams für channel-Dateien.

Graph-APIs funktionieren in allen Teams-Bereichen. Weitere Informationen finden Sie unter Senden der Dateianlagen einer Chatnachricht.

Alternativ können Sie Dateien an einen Agent senden und dateien von diesem empfangen, indem Sie die Teams SDK-APIs für die Dateizustimmung verwenden.

Verwenden der APIs der Teams SDK-Datei-Zustimmungsdatei

Teams SDK-Datei-Zustimmungs-APIs funktionieren nur im personal Kontext. Sie funktionieren nicht im - oder groupchat -channelKontext.

Mithilfe des Teams SDK kann der Agent Dateien direkt mit Benutzern im Kontext senden und empfangen, die personal auch als persönliche Chats bezeichnet werden. Implementieren Sie Features wie Spesenabrechnung, Bilderkennung, Dateiarchivierung und E-Signaturen, die die Bearbeitung von Dateiinhalten einbeziehen. In Teams freigegebene Dateien werden in der Regel als Karten angezeigt und ermöglichen eine umfassende Anzeige in der App.

In den nächsten Abschnitten wird beschrieben, wie Sie Dateiinhalte als direkte Benutzerinteraktion, wie beim Versenden einer Nachricht, senden. Das Teams SDK stellt Aktivitätsrouten für die Verarbeitung von Dateizustimmungsworkflows bereit, einschließlich file.consent.accept und file.consent.decline.

Konfigurieren des Agents zur Unterstützung von Dateien

Legen Sie zum Senden und Empfangen von Dateien im Agent die supportsFiles -Eigenschaft im Manifest auf fest true. Diese Eigenschaft wird im Abschnitt bots des Manifestverweises beschrieben.

Die Definition sieht wie folgt aus: "supportsFiles": true. Wenn der Agent nicht aktiviert supportsFiles, funktionieren die in diesem Abschnitt aufgeführten Features nicht.

Empfangen von Dateien im persönlichen Chat

Wenn ein Benutzer eine Datei an den Agent sendet, wird die Datei zuerst in den OneDrive for Business-Speicher des Benutzers hochgeladen. Der Agent empfängt dann eine Nachrichtenaktivität, die den Benutzer über den Benutzerupload benachrichtigt. Die Aktivität enthält Dateimetadaten, z. B. den Namen und die Inhalts-URL. Der Benutzer kann direkt von aus URL lesen, um seinen binären Inhalt abzurufen.

Beispiel für Nachrichtenaktivität mit Dateianlage

Der folgende Code zeigt ein Beispiel für eine Nachrichtenaktivität mit Dateianlage:

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

In der folgenden Tabelle werden die Inhaltseigenschaften der Anlage beschrieben.

In der Regel bestätigen Sie den Dateiupload, indem Sie eine Nachricht an den Benutzer senden.

Hochladen von Dateien in einen persönlichen Chat

So laden Sie eine Datei für einen Benutzer hoch:

1. Senden Sie eine Nachricht an den Benutzer, in der Sie um die Berechtigung zum Schreiben der Datei bitten. Diese Nachricht muss eine FileConsentCard-Anlage mit dem Namen der hochzuladenden Datei enthalten.
2. Wenn der Benutzer den Dateidownload akzeptiert, empfängt der Agent eine Aufrufaktivität mit einer Standort-URL.
3. Um die Datei zu übertragen, führt der Agent eine direkt in die angegebene Speicherort-URL aus HTTP POST .
4. Entfernen Sie optional die ursprüngliche Zustimmungskarte, wenn Sie nicht möchten, dass der Benutzer weitere Uploads derselben Datei akzeptiert.

Nachricht für die Anforderung der Berechtigung zum Hochladen

Die folgende Desktopnachricht enthält ein einfaches Anlageobjekt, in dem der Benutzer um die Berechtigung zum Hochladen der Datei gebeten wird:

Die folgende mobile Nachricht enthält ein Anlageobjekt, das die Benutzerberechtigung zum Hochladen der Datei anfordert:

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

In der folgenden Tabelle werden die Inhaltseigenschaften der Anlage beschrieben:

Aufrufaktivität, wenn der Benutzer die Datei akzeptiert

Eine Aufrufaktivität wird an den Agent gesendet, wenn ein Benutzer die Datei akzeptiert. Sie enthält die OneDrive for Business Platzhalter-URL, die der Agent dann ausstellen PUT kann, um den Dateiinhalt zu übertragen. Informationen zum Hochladen in die OneDrive-URL finden Sie unter Hochladen von Bytes in die Uploadsitzung.

Der folgende Code zeigt ein Beispiel für eine präzise Version der Aufrufaktivität, die der Agent empfängt:

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

Wenn der Benutzer die Datei ablehnt, empfängt der Agent auf ähnliche Weise das folgende Ereignis mit demselben Allgemeinen Aktivitätsnamen:

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

Benachrichtigen des Benutzers über eine hochgeladene Datei

Nachdem Sie eine Datei in das OneDrive des Benutzers hochgeladen haben, senden Sie eine Bestätigungsmeldung an den Benutzer. Die Nachricht muss die folgende FileCard-Anlage enthalten, die der Benutzer in der Vorschau anzeigen, in OneDrive öffnen oder lokal herunterladen kann:

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

In der folgenden Tabelle werden die Inhaltseigenschaften der Anlage beschrieben:

Abrufen von Inlinebildern aus einer Nachricht

Rufen Sie Mithilfe des Handlers Inlinebilder ab, die OnMessage Teil der Nachricht sind. Das Teams SDK übernimmt die Authentifizierung automatisch, sodass Sie direkt aus dem Aktivitätskontext auf Die UrLs für Anlageninhalte zugreifen können.

Der folgende Code zeigt ein Beispiel für das Abrufen von Inlinebildern aus einer Nachricht:

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

Einfaches Beispiel

Das folgende Beispiel zeigt, wie Sie den gesamten Dateizustimmungsworkflow verarbeiten, einschließlich des Sendens von Zustimmungskarten, der Verarbeitung akzeptierter und abgelehnter Antworten und des Hochladens von Dateien auf OneDrive.

Send File Consent Card

Der folgende Code sendet eine Dateizustimmung Karte an den Benutzer und fordert die Berechtigung an, die empfangene Datei auf sein OneDrive hochzuladen:

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,
    )]))

Verarbeiten des Dateiuploads

Der folgende Code führt den tatsächlichen Dateiupload durch, nachdem der Benutzer die Zustimmung Karte akzeptiert hat, lädt den Inhalt auf OneDrive hoch und sendet eine Erfolgsmeldung mit einer Dateiinformationsanlage. In C# wird diese Logik innerhalb des Handlers OnFileConsent inline ausgeführt.

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

Codebeispiel

Im folgenden Codebeispiel wird veranschaulicht, wie Sie die Dateizustimmung einholen und Dateien von einem Agent in Teams hochladen:

Siehe auch

• Übersicht über das Teams SDK
• Benutzerauthentifizierung
• Senden von Nachrichten
• Kernkonzepte von Teams