Dodaj udostępnianie plików w czacie przy użyciu biblioteki UI i usługi Azure Blob Storage

W czacie usług Azure Communication Services możemy włączyć udostępnianie plików między użytkownikami komunikacji. Czat usługi Azure Communication Services różni się od czatu interoperacyjnego usługi Teams lub czatu Interop. Jeśli chcesz włączyć udostępnianie plików w czacie międzyopowym, zobacz Dodawanie udostępniania plików za pomocą biblioteki interfejsu użytkownika w aplikacji Teams Interoperability Chat.

W tym artykule opisano sposób konfigurowania złożonej biblioteki interfejsu użytkownika usług Azure Communication Services w celu włączenia udostępniania plików. Biblioteka interfejsu użytkownika Chat Composite udostępnia zestaw zaawansowanych składników i kontrolek interfejsu użytkownika, których możemy użyć do włączenia udostępniania plików. Używamy usługi Azure Blob Storage, aby umożliwić przechowywanie plików udostępnianych za pośrednictwem wątku czatu.

Pobierz kod

Uzyskaj dostęp do pełnego kodu na potrzeby tego samouczka na stronie Przykład biblioteki interfejsu użytkownika — udostępnianie plików przy użyciu interfejsu użytkownika Chat Composite. Jeśli chcesz używać udostępniania plików przy użyciu składników interfejsu użytkownika, zobacz Przykład biblioteki interfejsu użytkownika — udostępnianie plików przy użyciu składników interfejsu użytkownika.

Prerequisites

• Konto platformy Azure z aktywną subskrypcją. Aby uzyskać szczegółowe informacje, zobacz Tworzenie bezpłatnego konta.
• Program Visual Studio Code na jednej z obsługiwanych platform.
• Node.js, active LTS i maintenance LTS (zalecane wersje 10.14.1). Użyj polecenia node --version, aby sprawdzić wersję.
• Aktywny zasób usług komunikacyjnych i parametry połączenia. Utwórz zasób usług komunikacyjnych.

Aby użyć tego artykułu, musisz wiedzieć, jak skonfigurować i uruchomić aplikację Chat Composite. Aby uzyskać więcej informacji na temat konfigurowania i uruchamiania aplikacji Chat Composite, zobacz samouczek ChatComposite.

Overview

Biblioteka interfejsu użytkownika Chat Composite obsługuje udostępnianie plików, umożliwiając deweloperom przekazywanie adresu URL do pliku hostowanego, który jest wysyłany za pośrednictwem usługi czatu usług Azure Communication Services. Biblioteka interfejsu użytkownika renderuje dołączony plik i obsługuje wiele rozszerzeń w celu skonfigurowania wyglądu i działania wysyłanego pliku. W szczególności obsługuje następujące funkcje:

1. Przycisk "Dołącz plik" do wybierania plików za pomocą selektora plików systemu operacyjnego.
2. Konfigurowanie dozwolonych rozszerzeń plików.
3. Włączanie/wyłączanie wielu przesyłań.
4. Ikony plików dla różnych typów plików.
5. Karty przekazywania/pobierania plików ze wskaźnikami postępu.
6. Możliwość dynamicznego sprawdzania każdego przesyłania plików i wyświetlania błędów w interfejsie użytkownika.
7. Możliwość anulowania przekazywania i usuwania przekazanego pliku przed wysłaniem.
8. Wyświetl przesłane pliki w wątku wiadomości, pobierz je. Umożliwia pobieranie asynchroniczne.

Na poniższym diagramie przedstawiono typowy przepływ scenariusza udostępniania plików zarówno w przypadku przekazywania, jak i pobierania. Sekcja oznaczona jako Client Managed pokazuje bloki konstrukcyjne, w których deweloperzy muszą je zaimplementować.

Konfigurowanie magazynu plików przy użyciu usługi Azure Blob

Możesz wykonać czynności opisane w samouczku Przekazywanie pliku do usługi Azure Blob Storage za pomocą funkcji platformy Azure , aby napisać kod zaplecza wymagany do udostępniania plików.

Po zaimplementowaniu można wywołać tę funkcję platformy Azure wewnątrz handleAttachmentSelection funkcji w celu przekazania plików do usługi Azure Blob Storage. W pozostałej części samouczka przyjęto założenie, że funkcja została wygenerowana przy użyciu samouczka dotyczącego połączonej wcześniej usługi Azure Blob Storage.

Zabezpieczanie kontenera usługi Azure Blob Storage

W tym artykule założono, że kontener usługi Azure Blob Storage umożliwia publiczny dostęp do przekazanych plików. Publiczne udostępnianie kontenerów usługi Azure Storage nie jest zalecane w przypadku rzeczywistych aplikacji produkcyjnych.

Aby pobrać pliki, należy przekazać je do usługi Azure Blob Storage. Następnie możesz użyć sygnatur dostępu współdzielonego (SAS). Sygnatura dostępu współdzielonego (SAS) zapewnia bezpieczny delegowany dostęp do zasobów na koncie magazynowania. Dzięki sygnaturze dostępu współdzielonego masz szczegółową kontrolę nad tym, w jaki sposób użytkownik może uzyskać dostęp do Twoich danych.

Przykład z GitHub do pobrania przedstawia użycie SAS do tworzenia adresów URL SAS do zawartości usługi Azure Storage. Ponadto możesz przeczytać więcej o SAS.

Biblioteka interfejsu użytkownika wymaga skonfigurowania środowiska React. Następnie to zrobimy. Jeśli masz już aplikację React, możesz pominąć tę sekcję.

Konfigurowanie aplikacji react

Na potrzeby szybkiego startu używamy szablonu create-react-app. Aby uzyskać więcej informacji, zobacz: Rozpoczynanie pracy z platformą React

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

cd ui-library-quickstart-composites

Na końcu tego procesu należy mieć pełną aplikację w folderze ui-library-quickstart-composites. W tym przewodniku szybkiego startu modyfikujemy pliki wewnątrz folderu src.

Instalowanie pakietu

Użyj polecenia , npm install aby zainstalować najnowszą wersję beta biblioteki interfejsu użytkownika usług Azure Communication Services dla języka JavaScript.

npm install @azure/communication-react@1.28.0-beta.2

@azure/communication-react Określa główne usługi Azure Communication Services, peerDependencies aby można było spójnie używać API z bibliotek podstawowych w aplikacji. Należy również zainstalować te biblioteki:

npm install @azure/communication-calling@1.36.1-beta.1
npm install @azure/communication-chat@1.6.0-beta.7

Tworzenie aplikacji React

Przetestujmy instalację Create React App, uruchamiając:

npm run start

Konfigurowanie aplikacji Chat Composite w celu włączenia udostępniania plików

Należy zastąpić wartości zmiennych dla obu wspólnych zmiennych wymaganych do zainicjowania złożonego czatu.

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';

function App(): JSX.Element {
  initializeFileTypeIcons();

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

Konfigurowanie metody przekazywania do korzystania z usługi Azure Blob Storage

Aby włączyć przesyłanie do Azure Blob Storage, zmodyfikujemy wcześniej zadeklarowaną metodę uploadFileToAzureBlob za pomocą następującego kodu. Aby przekazać pliki, musisz zastąpić informacje o funkcji platformy 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 progress.
      uploadTask.notifyUploadProgressChanged(p.loaded / p.total);
    },
  });

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

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

Obsługa błędów

Gdy przekazywanie zakończy się niepowodzeniem, biblioteka interfejsu użytkownika Chat Composite wyświetla komunikat o błędzie.

Oto przykładowy kod pokazujący, jak może dojść do niepowodzenia przesyłania z powodu błędu walidacji rozmiaru.

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

Pobieranie plików — zaawansowane użycie

Domyślnie biblioteka interfejsu użytkownika otwiera nową kartę wskazującą adres URL ustawiony podczas wykonywania notifyUploadCompleted polecenia. Alternatywnie możesz użyć niestandardowej logiki do obsługi pobierania załączników za pośrednictwem programu actionsForAttachment. Przyjrzyjmy się przykładowi.

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) => {
  const extension = attachment.name.split(".").pop() || "";
   if (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();
          })
        }
      }
    ];
  }
}

Jeśli podczas pobierania wystąpiły jakiekolwiek problemy i użytkownik musi zostać powiadomiony, możesz throw zgłosić błąd z komunikatem w funkcji onClick. Następnie komunikat zostanie wyświetlony na pasku błędu w górnej części aplikacji Chat Composite.

Czyszczenie zasobów

Jeśli chcesz wyczyścić i usunąć subskrypcję usług Komunikacyjnych, możesz usunąć zasób lub grupę zasobów. Usunięcie grupy zasobów powoduje również usunięcie wszelkich innych skojarzonych z nią zasobów. Możesz dowiedzieć się więcej na temat czyszczenia zasobów usług Azure Communication Services i czyszczenia zasobów funkcji platformy Azure.

Dalsze kroki

Powiązane artykuły

• Dodawanie czatu do aplikacji
• Tworzenie tokenów dostępu użytkowników
• Dowiedz się więcej o architekturze klienta i serwera
• Dowiedz się więcej o uwierzytelnianiu
• Dodawanie udostępniania plików za pomocą biblioteki interfejsu użytkownika w czacie współdziałania usługi Teams
• Dodawanie udostępniania plików za pomocą biblioteki UI w czacie usług Azure Communication Services
• Dodawanie wbudowanego obrazu z biblioteką interfejsu użytkownika w aplikacji Teams Interoperability Chat