Dateien senden und erhalten

Wichtig

  • Agenten unterstützen nicht das Senden und Empfangen von Dateien in Government Community Cloud High (GCC High), Department of Defense (DoD) und Teams, die von 21Vianet-Umgebungen betrieben werden.

Es gibt zwei Methoden zum Senden und Empfangen von Dateien:

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 von einem Agent empfangen, indem Sie die Teams SDK-Dateizustimmungs-APIs verwenden.

Teams-SDK-Dateizustimmungs-APIs funktionieren nur im personal Kontext. Sie funktionieren nicht im channelgroupchat oder-Kontext.

Mithilfe des Teams SDK kann der Agent Dateien direkt mit Benutzern im Kontext senden und empfangen, auch personal bekannt als persönliche Chats. 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 Handhabung von Workflows zur Dateizustimmung bereit, einschließlich file.consent.accept und file.consent.decline.

Agent für Unterstützung von Dateien konfigurieren

Um Dateien im Agenten zu senden und zu empfangen, setzen Sie die supportsFiles Eigenschaft im Manifest auf true. Diese Eigenschaft wird im Abschnitt "bots " der Manifestreferenz beschrieben.

Die Definition sieht wie folgt aus: "supportsFiles": true. Wenn der Agent nicht aktiviert supportsFiles, funktionieren die in diesem Abschnitt aufgeführten Funktionen 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.

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-Laufwerkselement-ID für den Fall, dass der Benutzer eine Datei an den Agent 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 Agent eine Aufrufaktivität mit einer Standort-URL.
  3. Um die Datei zu übertragen, führt der Agent eine HTTP POST direkt an die angegebene Standort-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:

Zustimmungskarte für die Benutzerberechtigung zum Hochladen der Datei

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

Einwilligungs-Karte, mit der die Benutzerberechtigung zum Hochladen einer Datei auf ein Mobilgerät angefordert wird
{
  "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 im Hintergrund an den Agent übertragen wird, wenn der Benutzer die Datei akzeptiert.
declineContext Zusätzlicher Kontext, der im Hintergrund an den Agent übertragen wird, wenn der Benutzer die Datei ablehnt.

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 Platzhalter-URL für OneDrive for Business, die der Agent dann zum PUT Übertragen des Dateiinhalts ausgeben kann. 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 kurze 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 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 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

Abrufen von Inlinebildern, die Teil der Nachricht sind, mithilfe des Handlers OnMessage . Das Teams SDK verarbeitet die Authentifizierung automatisch, sodass Sie direkt aus dem Aktivitätskontext auf die Inhalts-URLs von Anlagen zugreifen können.

Inlinebild

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

using Microsoft.Teams.Api;
using Microsoft.Teams.Apps;

WebApplicationBuilder builder = WebApplication.CreateSlimBuilder(args);
builder.Services.AddTeamsBotApplication();

WebApplication app = builder.Build();
TeamsBotApplication teams = app.UseTeamsBotApplication();

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 MessageActivityInput().WithText(
            $"Attachment of {attachment.ContentType} type and size of {responseMessage.Content.Headers.ContentLength} bytes received.");
        reply.AddAttachment(TeamsAttachment.CreateBuilder()
            .WithContentType("image/png")
            .WithName("ImageFromUser.png")
            .WithContentUrl($"data:image/png;base64,{imageData}")
            .Build());
        await context.SendAsync(reply, cancellationToken);
    }
});

app.Run();

Einfaches Beispiel

Das folgende Beispiel zeigt, wie Sie den gesamten Workflow zur Dateizustimmung handhaben, einschließlich des Versendens von Zustimmungskarten, der Behandlung akzeptierter und abgelehnter Antworten und des Hochladens von Dateien auf OneDrive.

Der folgende Code sendet eine Dateieinwilligungs-Karte an den Benutzer mit der Bitte um Erlaubnis, die empfangene Datei auf sein OneDrive hochzuladen:

async Task SendFileConsentCard(Context<MessageActivity> context, string fileName, string fileId, int fileSize, CancellationToken cancellationToken)
{
    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 MessageActivityInput()
        .AddAttachment(TeamsAttachment.CreateBuilder()
            .WithContentType(ContentTypeFileConsent)
            .WithName(fileName)
            .WithContent(fileCard)
            .Build());
    await context.SendAsync(message, cancellationToken);
}

Dateiupload bearbeiten

Der folgende Code führt den eigentlichen Dateiupload durch, nachdem der Benutzer die Zustimmungs-Karte akzeptiert, den Inhalt auf OneDrive hochgeladen und eine Erfolgsmeldung mit einer Dateiinfoanlage gesendet hat. In C# ist diese Logik innerhalb des Handlers OnFileConsent inline.

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

Codebeispiel

Der folgende Codebeispiel zeigt, wie Sie die Dateizustimmung einholen und Dateien von einem Agenten in Teams hochladen:

Beispielname Beschreibung .NET Node.js Python
File upload Dieses Agentbeispiel für Teams veranschaulicht die Dateiuploadfunktionen mithilfe des Teams SDK-Frameworks, sodass Benutzer Dateien hochladen und Inlinebilder in Chats anzeigen können. View View Anzeigen

Siehe auch