Invia e ricevi file usando i bot

Esistono due modi per inviare file da e verso un bot:

• Uso delle API di Microsoft Graph. Questo metodo funziona per i bot in tutti gli ambiti in Teams:
  • personal
  • channel
  • groupchat
• Uso delle API di Teams. Questi supportano i file solo in un contesto:
  • personal

Uso delle API di Microsoft Graph

È possibile pubblicare messaggi con allegati che fanno riferimento a file di SharePoint esistenti usando le API di Microsoft Graph per OneDrive e SharePoint. L'uso delle API di Graph richiede l'accesso alla cartella OneDrive di un utente (per personalgroupchat e file) o ai file nei canali di un team (per channel i file) tramite il flusso di autorizzazione OAuth 2.0 standard. Questo metodo funziona in tutti gli ambiti di Teams.

Uso delle API bot di Teams

Il bot può inviare e ricevere direttamente file con gli utenti nel contesto, noto anche come chat personale, usando le personal API di Teams. In questo modo è possibile implementare la rendicontazione delle spese, il riconoscimento delle immagini, l'archiviazione dei file, le firme elettroniche e altri scenari che implicano la manipolazione diretta del contenuto dei file. I file condivisi in Teams vengono in genere visualizzati come schede e consentono una visualizzazione in-app avanzata.

Nelle sezioni seguenti viene descritto come eseguire questa operazione per inviare il contenuto dei file in seguito all'interazione diretta dell'utente, ad esempio l'invio di un messaggio. Questa API viene fornita come parte della piattaforma bot di Microsoft Teams.

Configurare il bot per supportare i file

Per inviare e ricevere file nel bot, è necessario impostare la supportsFiles proprietà nel manifesto su true. Questa proprietà è descritta nella sezione [bots]/microsoft-365/extensibility/schema/root-bots#supportsfiles) del riferimento al manifesto.

La definizione sarà simile alla seguente: "supportsFiles": true. Se il bot non abilita supportsFiles, le funzionalità seguenti non funzioneranno.

Ricezione di file nella chat personale

Quando un utente invia un file al bot, il file viene prima caricato nello spazio di archiviazione di OneDrive for Business dell'utente. Il bot riceverà quindi un messaggio che informa dell'utente del caricamento. L'attività contiene metadati di file, ad esempio il nome e l'URL del contenuto. È possibile leggere direttamente da questo URL per recuperarne il contenuto binario.

Esempio di attività messaggio con file allegato

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

Nella tabella seguente vengono descritte le proprietà del contenuto dell'allegato:

Come procedura consigliata, è consigliabile confermare il caricamento del file inviando un messaggio all'utente.

Caricamento di file nella chat personale

Il caricamento di un file per un utente prevede i passaggi seguenti:

1. Inviare un messaggio all'utente chiedendo l'autorizzazione per scrivere il file. Il messaggio deve contenere un FileConsentCard allegato con il nome del file da caricare.
2. Se l'utente accetta il download del file, il bot riceve un'attività Invoke con un URL di percorso.
3. Per trasferire il file, il bot esegue un HTTP POST operazione direttamente nell'URL della posizione fornito.
4. Facoltativamente, è possibile rimuovere la scheda di consenso originale se non si vuole consentire all'utente di accettare ulteriori caricamenti dello stesso file.

Messaggio che richiede l'autorizzazione per il caricamento

Questo messaggio desktop contiene un semplice oggetto allegato che richiede l'autorizzazione dell'utente per caricare il file:

Questo messaggio per dispositivi mobili contiene un oggetto allegato che richiede l'autorizzazione dell'utente per caricare il file:

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

Nella tabella seguente vengono descritte le proprietà del contenuto dell'allegato:

Richiama l'attività quando l'utente accetta il file

Un'attività di richiamo viene inviata al bot se e quando l'utente accetta il file. Contiene l'URL segnaposto di OneDrive for Business in cui il bot può quindi rilasciare un PUT per trasferire il contenuto del file. Per informazioni sul caricamento nell'URL di OneDrive, leggere questo articolo: Caricare byte nella sessione di caricamento.

L'esempio seguente mostra una versione abbreviata dell'attività di richiamo ricevuta dal bot:

{
  ...

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

Analogamente, se l'utente rifiuta il file, il bot riceve l'evento seguente, con lo stesso nome di attività complessivo:

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

Notifica all'utente di un file caricato

Dopo aver caricato un file in OneDrive dell'utente, indipendentemente dal fatto che si usi il meccanismo descritto in precedenza o le API delegate dall'utente di OneDrive, è necessario inviare un messaggio di conferma all'utente. Questo messaggio deve contenere un FileCard allegato che l'utente può selezionare per visualizzarlo, aprirlo in OneDrive o scaricarlo in locale.

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

Nella tabella seguente vengono descritte le proprietà del contenuto dell'allegato:

Esempio di base in C

L'esempio seguente mostra come gestire il caricamento di file e l'invio di richieste di consenso per i file nella finestra di dialogo del bot:

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

Vedere anche

Usare i file in Microsoft Graph