Condividi tramite

Abilitare la condivisione di file usando la libreria dell'interfaccia utente in Servizi di comunicazione di Azure Chat con Archiviazione BLOB di Azure

  • Articolo

Importante

Questa funzionalità di Servizi di comunicazione di Azure è attualmente in anteprima.

Le API di anteprima e gli SDK vengono forniti senza un contratto di servizio. È consigliabile non usarli per i carichi di lavoro di produzione. Alcune funzionalità potrebbero non essere supportate o potrebbero avere funzionalità limitate.

Per altre informazioni, vedere Condizioni per l'utilizzo supplementari per le anteprime di Microsoft Azure.

In una chat Servizi di comunicazione di Azure è possibile abilitare la condivisione di file tra gli utenti delle comunicazioni. Nota, Servizi di comunicazione di Azure Chat è diversa dalla chat di interoperabilità di Teams ("Chat di interoperabilità"). Per abilitare la condivisione di file in una chat di interoperabilità, vedere Aggiungere la condivisione di file con la libreria dell'interfaccia utente in Teams Interoperability Chat.

In questa esercitazione si sta configurando il composito della chat della libreria dell'interfaccia utente Servizi di comunicazione di Azure per abilitare la condivisione di file. Ui Library Chat Composite fornisce un set di componenti avanzati e controlli dell'interfaccia utente che possono essere usati per abilitare la condivisione di file. Si sta usando Archiviazione BLOB di Azure per abilitare l'archiviazione dei file condivisi tramite il thread di chat.

Importante

Servizi di comunicazione di Azure non fornisce un servizio di archiviazione file. È necessario usare il proprio servizio di archiviazione file per la condivisione dei file. Per i pupose di questa esercitazione, viene usato Archiviazione BLOB di Azure.**

Scaricare il codice

Accedere al codice completo per questa esercitazione su GitHub. Per usare la condivisione file con i componenti dell'interfaccia utente, fare riferimento a questo esempio.

Prerequisiti

Questa esercitazione presuppone che si sappia già come configurare ed eseguire una chat composita. È possibile seguire l'esercitazione su Chat Composite per informazioni su come configurare ed eseguire un composito di chat.

Panoramica

Ui Library Chat Composite supporta la condivisione di file consentendo agli sviluppatori di passare l'URL a un file ospitato inviato tramite il servizio chat Servizi di comunicazione di Azure. La libreria dell'interfaccia utente esegue il rendering del file allegato e supporta più estensioni per configurare l'aspetto del file inviato. In particolare, supporta le funzionalità seguenti:

  1. Pulsante Allega file per la selezione dei file tramite selezione file del sistema operativo
  2. Configurare le estensioni di file consentite.
  3. Abilitare/disabilitare più caricamenti.
  4. Icone di file per un'ampia gamma di tipi di file.
  5. Schede di caricamento/download di file con indicatori di stato.
  6. Possibilità di convalidare dinamicamente ogni caricamento e visualizzare errori nell'interfaccia utente.
  7. Possibilità di annullare un caricamento e rimuovere un file caricato prima dell'invio.
  8. Visualizzare i file caricati in MessageThread, scaricarli. Consente download asincroni.

Il diagramma mostra un flusso tipico di uno scenario di condivisione file per il caricamento e il download. La sezione contrassegnata come Client Managed mostra i blocchi predefiniti in cui gli sviluppatori devono implementarli.

Flusso tipico di condivisione file

Configurare l'archiviazione file con BLOB di Azure

È possibile seguire l'esercitazione Caricare il file in Archiviazione BLOB di Azure con una funzione di Azure per scrivere il codice back-end necessario per la condivisione di file.

Dopo l'implementazione, è possibile chiamare questa funzione di Azure all'interno della handleAttachmentSelection funzione per caricare i file in Archiviazione BLOB di Azure. Per il resto dell'esercitazione, si presuppone che sia stata generata la funzione usando l'esercitazione per Archiviazione BLOB di Azure collegata in precedenza.

Protezione del contenitore di archiviazione BLOB di Azure

Questa esercitazione presuppone che il contenitore di archiviazione BLOB di Azure consenta l'accesso pubblico ai file caricati. Rendere pubblici i contenitori di archiviazione di Azure non è consigliato per le applicazioni di produzione reali.

Per scaricare i file, caricare nell'archivio BLOB di Azure, è possibile usare firme di accesso condiviso . Una firma di accesso condiviso (SAS) fornisce accesso delegato sicuro alle risorse nell'account di archiviazione. Con una firma di accesso condiviso è possibile controllare in modo granulare il modo in cui un client può accedere ai dati.

L'esempio gitHub scaricabile illustra l'uso della firma di accesso condiviso per la creazione di URL di firma di accesso condiviso per Archiviazione di Azure contenuto. È anche possibile leggere altre informazioni sulla firma di accesso condiviso.

La libreria dell'interfaccia utente richiede la configurazione di un ambiente React. A questo punto lo facciamo. Se si dispone già di un'app React, è possibile ignorare questa sezione.

Configurare l'app React

Per questa guida introduttiva viene usato il modello create-react-app. Per altre informazioni, vedere: Introduzione a React


npx create-react-app ui-library-quickstart-composites --template typescript

cd ui-library-quickstart-composites

Al termine di questo processo, è necessario disporre di un'applicazione completa all'interno della cartella ui-library-quickstart-composites. Per questa guida introduttiva, verranno modificati i file all'interno della src cartella .

Installare il pacchetto

Usare il npm install comando per installare la libreria dell'interfaccia utente beta Servizi di comunicazione di Azure per JavaScript.


npm install @azure/communication-react@1.16.0-beta.1

@azure/communication-reactspecifica i Servizi di comunicazione di Azure di base in peerDependencies modo che sia possibile usare in modo più coerente l'API dalle librerie di base nell'applicazione. È necessario installare anche queste librerie:


npm install @azure/communication-calling@1.24.1-beta.2
npm install @azure/communication-chat@1.6.0-beta.1

Creare un'app React

Testare ora l'installazione di Create React App eseguendo:


npm run start

Configurazione di Chat Composite per abilitare la condivisione di file

È necessario sostituire i valori delle variabili per entrambe le variabili comuni necessarie per inizializzare il composito della chat.

App.tsx

import { initializeFileTypeIcons } from '@fluentui/react-file-type-icons';
import {
  ChatComposite,
  AttachmentUploadTask,
  AttachmentUploadOptions,
  AttachmentSelectionHandler,
  fromFlatCommunicationIdentifier,
  useAzureCommunicationChatAdapter
} from '@azure/communication-react';
import React, { useMemo } from 'react';

initializeFileTypeIcons();

function App(): JSX.Element {
  // Common variables
  const endpointUrl = 'INSERT_ENDPOINT_URL';
  const userId = ' INSERT_USER_ID';
  const displayName = 'INSERT_DISPLAY_NAME';
  const token = 'INSERT_ACCESS_TOKEN';
  const threadId = 'INSERT_THREAD_ID';

  // We can't even initialize the Chat and Call adapters without a well-formed token.
  const credential = useMemo(() => {
    try {
      return new AzureCommunicationTokenCredential(token);
    } catch {
      console.error('Failed to construct token credential');
      return undefined;
    }
  }, [token]);

  // Memoize arguments to `useAzureCommunicationChatAdapter` so that
  // a new adapter is only created when an argument changes.
  const chatAdapterArgs = useMemo(
    () => ({
      endpoint: endpointUrl,
      userId: fromFlatCommunicationIdentifier(userId) as CommunicationUserIdentifier,
      displayName,
      credential,
      threadId
    }),
    [userId, displayName, credential, threadId]
  );
  const chatAdapter = useAzureCommunicationChatAdapter(chatAdapterArgs);

  if (!!chatAdapter) {
    return (
      <>
        <div style={containerStyle}>
          <ChatComposite
            adapter={chatAdapter}
            options={{
              attachmentOptions: {
                uploadOptions: uploadOptions,
                downloadOptions: downloadOptions,
              }
            }} />
        </div>
      </>
    );
  }
  if (credential === undefined) {
    return <h3>Failed to construct credential. Provided token is malformed.</h3>;
  }
  return <h3>Initializing...</h3>;
}

const uploadOptions: AttachmentUploadOptions = {
  // default is false
  disableMultipleUploads: false,
  // define mime types
  supportedMediaTypes: ["image/jpg", "image/jpeg"]
  handleAttachmentSelection: attachmentSelectionHandler,
}

const attachmentSelectionHandler: AttachmentSelectionHandler = async (uploadTasks) => {
  for (const task of uploadTasks) {
    try {
      const uniqueFileName = `${v4()}-${task.file?.name}`;
      const url = await uploadFileToAzureBlob(task);
      task.notifyUploadCompleted(uniqueFileName, url);
    } catch (error) {
      if (error instanceof Error) {
        task.notifyUploadFailed(error.message);
      }
    }
  }
}

const uploadFileToAzureBlob = async (uploadTask: AttachmentUploadTask) => {
  // You need to handle the file upload here and upload it to Azure Blob Storage.
  // This is how you can configure the upload
  // Optionally, you can also update the file upload progress.
  uploadTask.notifyUploadProgressChanged(0.2);
  return {
    url: 'https://sample.com/sample.jpg', // Download URL of the file.
  };

Configurare il metodo di caricamento per l'uso dell'archiviazione BLOB di Azure

Per abilitare Archiviazione BLOB di Azure caricamento, si modifica il uploadFileToAzureBlob metodo dichiarato in precedenza con il codice seguente. Per caricare i file, è necessario sostituire le informazioni sulla funzione di Azure.

App.tsx

const uploadFileToAzureBlob = async (uploadTask: AttachmentUploadTask) => {
  const file = uploadTask.file;
  if (!file) {
    throw new Error("uploadTask.file is undefined");
  }

  const filename = file.name;
  const fileExtension = file.name.split(".").pop();

  // Following is an example of calling an Azure Function to handle file upload
  // The https://learn.microsoft.com/azure/developer/javascript/how-to/with-web-app/azure-function-file-upload
  // tutorial uses 'username' parameter to specify the storage container name.
  // the container in the tutorial is private by default. To get default downloads working in
  // this sample, you need to change the container's access level to Public via Azure Portal.
  const username = "ui-library";

  // You can get function url from the Azure Portal:
  const azFunctionBaseUri = "<YOUR_AZURE_FUNCTION_URL>";
  const uri = `${azFunctionBaseUri}&username=${username}&filename=${filename}`;

  const formData = new FormData();
  formData.append(file.name, file);

  const response = await axios.request({
    method: "post",
    url: uri,
    data: formData,
    onUploadProgress: (p) => {
      // Optionally, you can update the file upload progess.
      uploadTask.notifyUploadProgressChanged(p.loaded / p.total);
    },
  });

  const storageBaseUrl = "https://<YOUR_STORAGE_ACCOUNT>.blob.core.windows.net";

  return {
    url: `${storageBaseUrl}/${username}/${filename}`,
  };
};

Gestione errori

Quando un caricamento ha esito negativo, il composito della libreria dell'interfaccia utente visualizza un messaggio di errore.

Barra degli errori caricamento file

Di seguito è riportato un codice di esempio che illustra come è possibile eseguire un caricamento a causa di un errore di convalida delle dimensioni:

App.tsx

import { AttachmentSelectionHandler } from from '@azure/communication-react';

const attachmentSelectionHandler: AttachmentSelectionHandler = async (uploadTasks) => {
  for (const task of uploadTasks) {
    if (task.file && task.file.size > 99 * 1024 * 1024) {
      // Notify ChatComposite about upload failure.
      // Allows you to provide a custom error message.
      task.notifyUploadFailed('File too big. Select a file under 99 MB.');
    }
  }
}

export const attachmentUploadOptions: AttachmentUploadOptions = {
  handleAttachmentSelection: attachmentSelectionHandler
};

Download di file - Utilizzo avanzato

Per impostazione predefinita, la libreria dell'interfaccia utente aprirà una nuova scheda che punta all'URL impostato quando si è notifyUploadCompleted. In alternativa, è possibile avere una logica personalizzata per gestire i download degli allegati tramite actionsForAttachment. Di seguito viene illustrato un esempio.

App.tsx

import { AttachmentDownloadOptions } from "communication-react";

const downloadOptions: AttachmentDownloadOptions = {
  actionsForAttachment: handler
}

const handler = async (attachment: AttachmentMetadata, message?: ChatMessage) => {
   // here we are returning a static action for all attachments and all messages
   // alternately, you can provide custom menu actions based on properties in `attachment` or `message` 
   return [defaultAttachmentMenuAction];
};

const customHandler = = async (attachment: AttachmentMetadata, message?: ChatMessage) => {
   if (attachment.extension === "pdf") {
    return [
      {
        title: "Custom button",
        icon: (<i className="custom-icon"></i>),
        onClick: () => {
          return new Promise((resolve, reject) => {
              // custom logic here
              window.alert("custom button clicked");
              resolve();
              // or to reject("xxxxx") with a custom message
          })
        }
      },
      defaultAttachmentMenuAction
    ];
  } else if (message?.senderId === "user1") {
    return [
      {
        title: "Custom button 2",
        icon: (<i className="custom-icon-2"></i>),
        onClick: () => {
          return new Promise((resolve, reject) => {
            window.alert("custom button 2 clicked");
            resolve();
          })
        }
      },
      // you can also override the default action partially
      {
        ...defaultAttachmentMenuAction,
        onClick: () => {
          return new Promise((resolve, reject) => {
            window.alert("default button clicked");
            resolve();
          })
        }
      }
    ];
  }
}

Se si sono verificati problemi durante il download e l'utente deve ricevere una notifica, è sufficiente throw un errore con un messaggio nella onClick funzione, il messaggio verrà visualizzato nella barra degli errori sopra il composito chat.

Errore di download del file

Pulire le risorse

Se si vuole pulire e rimuovere una sottoscrizione a Servizi di comunicazione, è possibile eliminare la risorsa o il gruppo di risorse. L'eliminazione del gruppo di risorse comporta anche l'eliminazione di tutte le altre risorse associate. Altre informazioni sulla pulizia delle risorse Servizi di comunicazione di Azure e sulla pulizia delle risorse delle funzioni di Azure.

Passaggi successivi

Controllare il resto della libreria dell'interfaccia utente

Può essere utile vedere anche gli articoli seguenti: