Senden und Empfangen von Dateien mithilfe eines Bots

Wichtig

• Dieser Artikel basiert auf dem Bot Framework SDK v4.
• Bots unterstützen das Senden und Empfangen von Dateien in Umgebungen in Governmernt Community Cloud High (GCC-High) und Department of Defense (DOD) nicht.

Es gibt zwei Möglichkeiten, Dateien an einen Bot zu senden und von einem Bot zu empfangen:

• Verwenden der Microsoft Graph-APIs: Diese Methode funktioniert für Bots in allen Microsoft Teams-Bereichen:

  • personal
  • channel
  • groupchat

• Verwenden der Teams-Bot-APIs: Diese unterstützen nur Dateien im personal-Kontext.

Das folgende Video zeigt, wie ein Bot das Senden und Empfangen von Dateien mit Leichtigkeit und Effizienz vereinfacht:

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 mithilfe der Teams-Bot-APIs an einen Bot senden und von diesem empfangen.

Verwenden der Teams-Bot-APIs

Teams Bot-APIs funktionieren nur im personal-Kontext. Sie funktionieren nicht im - oder groupchat -channelKontext.

Mit Teams-APIs kann der Bot Dateien an Benutzer im personal-Kontext, auch als persönliche Chats bezeichnet, senden und von diesen empfangen. 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. Diese API wird als Teil der Teams-Bot-Plattform bereitgestellt.

Konfigurieren des Bots zur Unterstützung von Dateien

Um Dateien im Bot zu senden und zu empfangen, legen Sie die supportsFilesEigenschaft im Manifest auf true fest. Diese Eigenschaft wird im Abschnitt bots des Manifestverweises beschrieben.

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

Empfangen von Dateien im persönlichen Chat

Wenn ein Benutzer eine Datei an den Bot sendet, wird die Datei zuerst in den OneDrive for Business-Speicher des Benutzers hochgeladen. Der Bot 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.

Eigenschaft	Zweck
downloadUrl	OneDrive-URL zum Abrufen des Dateiinhalts Der Benutzer kann eine HTTP GET direkt über diese URL ausgeben.
uniqueId	Eindeutige Datei-ID. Dies ist die OneDrive-Laufwerkelement-ID, falls der Benutzer eine Datei an den Bot sendet.
fileType	Dateityp, z. B. .pdf oder .docx.

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 Bot eine Aufrufaktivität mit einer Standort-URL.
3. Um die Datei zu übertragen, führt der Bot eine HTTP POST direkt in die angegebene Speicherort-URL aus.
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:

Eigenschaft	Zweck
description	Beschreibt den Zweck der Datei oder fasst deren Inhalt zusammen.
sizeInBytes	Bietet dem Benutzer eine Schätzung der Dateigröße und des Speicherplatzes, der in OneDrive benötigt wird.
acceptContext	Zusätzlicher Kontext, der automatisch an den Bot übertragen wird, wenn der Benutzer die Datei akzeptiert.
declineContext	Zusätzlicher Kontext, der automatisch an den Bot übertragen wird, wenn der Benutzer die Datei ablehnt.

Aufrufaktivität, wenn der Benutzer die Datei akzeptiert

Eine Aufrufaktivität wird an den Bot gesendet, wenn der Benutzer die Datei akzeptiert. Sie enthält die OneDrive for Business-Platzhalter-URL, damit der Bot dann eine PUT ausstellen 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 Bot 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, erhält der Bot entsprechend 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:

Eigenschaft	Zweck
uniqueId	OneDrive- oder SharePoint-Laufwerkelement-ID
fileType	Dateityp, z. B. .pdf oder .docx.

Abrufen von Inlinebildern aus einer Nachricht

Rufen Sie Inlinebilder, die Teil der Nachricht sind, mithilfe des Zugriffstokens des Bots ab.

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

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}​​​​​",
    }​​​​​;
}​​​​​

Einfaches Beispiel in C#

Der folgende Code zeigt ein Beispiel für die Behandlung von Dateiuploads und das Senden von Dateizustimmungsanforderungen im Dialogfeld des Bots:

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

Codebeispiel

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

Beispielname	Beschreibung	.NET	Node.js	Python	Manifest
File upload	In diesem Beispiel wird gezeigt, wie Sie die Dateizustimmung einholen und Dateien mithilfe eines Bots in Teams hochladen. Außerdem erfahren Sie, wie Sie eine an einen Bot gesendete Datei empfangen.	View	View	View	View

Schrittweise Anleitung

Befolgen Sie die schrittweise Anleitung zum Hochladen der Datei in Teams mithilfe eines Bots.

Nächster Schritt

Optimieren eines Bots mit Ratenbegrenzung in Teams

Siehe auch

• Erstellen von Bots für Teams
• Authentifizierungsfluss für Bots in Microsoft Teams
• Führen Sie eine persönliche (1:1) Unterhaltung mit einem Microsoft Teams-Bot
• Microsoft Teams-Kontext für Ihren Bot erhalten