Senden und Empfangen von Dateien mithilfe von Bots

Es gibt zwei Möglichkeiten zum Senden von Dateien an und von einem Bot:

• Using the Microsoft Graph APIs. Diese Methode funktioniert für Bots in allen Bereichen in Teams:
  • personal
  • channel
  • groupchat
• mithilfe der Teams-APIs. Diese unterstützen nur Dateien in einem Kontext:
  • personal

Verwenden der Microsoft Graph-APIs

Sie können Nachrichten mit Kartenanlagen posten, die auf vorhandene SharePoint-Dateien verweisen, indem Sie die Microsoft Graph-APIs für OneDrive und SharePoint verwenden. Die Verwendung der Graph-APIs erfordert den Zugriff auf den OneDrive-Ordner eines Benutzers (für personal und groupchat Dateien) oder auf die Dateien in den Kanälen eines Teams (für channel Dateien) über den standardmäßigen OAuth 2.0-Autorisierungsfluss. Diese Methode funktioniert in allen Teams-Bereichen.

Verwenden der Teams Bot-APIs

Ihr Bot kann mithilfe von Teams-APIs Dateien direkt an Benutzer im Kontext senden und empfangen, auch personal als persönliche Chats bezeichnet. Auf diese Weise können Sie Spesenabrechnung, Bilderkennung, Dateiarchivierung, elektronische Signaturen und andere Szenarien mit direkter Manipulation von Dateiinhalten implementieren. In Teams freigegebene Files werden in der Regel als Karten angezeigt und ermöglichen eine umfangreiche In-App-Anzeige.

In den folgenden Abschnitten wird beschrieben, wie Sie dies tun können, um Dateiinhalte als Ergebnis einer direkten Benutzerinteraktion, z. B. dem Senden einer Nachricht, zu senden. Diese API wird als Teil der Microsoft Teams Bot-Plattform bereitgestellt.

Konfigurieren Sie Ihren Bot für die Unterstützung von Dateien

Um Dateien in Ihrem Bot zu senden und zu empfangen, müssen Sie die supportsFiles Eigenschaft im Manifest auf truesetzen. Diese Eigenschaft wird im Abschnitt [bots]/microsoft-365/extensibility/schema/root-bots#supportsfiles) der Manifestreferenz beschrieben.

Die Definition sieht wie folgt aus: "supportsFiles": true. Wenn Ihr Bot nicht aktiviert supportsFiles, funktionieren die folgenden Features nicht.

Empfangen von Dateien im persönlichen Chat

Wenn ein Benutzer eine Datei an Ihren Bot sendet, wird die Datei zuerst in den OneDrive for Business-Speicher des Benutzers hochgeladen. Ihr Bot empfängt dann eine Nachrichtenaktivität, die Sie über den Benutzerupload benachrichtigt. Die Aktivität enthält Dateimetadaten wie den Namen und die Inhalts-URL. Sie können direkt aus dieser URL lesen, um den binären Inhalt abzurufen.

Beispiel für 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:

Als bewährte Methode sollten Sie den Dateiupload bestätigen, indem Sie eine Nachricht an den Benutzer zurücksenden.

Hochladen von Dateien in den persönlichen Chat

Das Hochladen einer Datei für einen Benutzer umfasst die folgenden Schritte:

1. Senden Sie eine Nachricht an den Benutzer, in der Sie die Berechtigung zum Schreiben der Datei anfordern. Diese Nachricht muss eine FileConsentCard Anlage mit dem Namen der hochzuladenden Datei enthalten.
2. Wenn der Benutzer den Dateidownload akzeptiert, empfängt Ihr Bot eine Invoke-Aktivität mit einer Standort-URL.
3. Um die Datei zu übertragen, führt Ihr Bot eine HTTP POST direkt in die angegebene Standort-URL aus.
4. Optional können Sie die ursprüngliche Zustimmungs-Karte entfernen, wenn Sie dem Benutzer nicht erlauben möchten, weitere Uploads derselben Datei zu akzeptieren.

Nachricht, mit der die Berechtigung zum Hochladen angefordert wird

Diese Desktopnachricht enthält ein einfaches Anlageobjekt, das die Benutzerberechtigung zum Hochladen der Datei anfordert:

Diese 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:

Aktivität aufrufen, wenn der Benutzer die Datei akzeptiert

Eine Aufrufaktivität wird an Ihren Bot gesendet, wenn der Benutzer die Datei akzeptiert. Sie enthält die Platzhalter-URL für OneDrive for Business, in die Ihr Bot dann eine PUT Datei zum Übertragen des Dateiinhalts ausgeben kann. Informationen zum Hochladen auf die OneDrive-URL finden Sie in diesem Artikel: Hochladen von Bytes in die Uploadsitzung.

Das folgende Beispiel zeigt eine gekürzte Version der Aufrufaktivität, die Ihr 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, empfängt Ihr Bot das folgende Ereignis mit demselben Aktivitätsnamen:

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

Benachrichtigen des Benutzers über eine hochgeladene Datei

Nachdem Sie eine Datei auf das OneDrive des Benutzers hochgeladen haben, sollten Sie unabhängig davon, ob Sie den oben beschriebenen Mechanismus oder die vom OneDrive-Benutzer delegierten APIs verwenden, eine Bestätigungsnachricht an den Benutzer senden. Diese Nachricht sollte eine FileCard Anlage enthalten, die der Benutzer auswählen kann, um sie in der Vorschau anzuzeigen, in OneDrive zu öffnen oder lokal herunterzuladen.

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

Einfaches Beispiel in C

Das folgende Beispiel zeigt, wie Sie Dateiuploads behandeln und Dateizustimmungsanfragen im Dialogfeld Ihres Bots senden können:

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

Siehe auch

Arbeiten mit Dateien in Microsoft Graph