Поделиться через

Добавление общего доступа к файлам в чате с помощью библиотеки пользовательского интерфейса и хранилища BLOB-объектов Azure

  • Статья

Внимание

Эта функция Службы коммуникации Azure сейчас доступна в предварительной версии. Функции в предварительной версии общедоступны и могут использоваться всеми новыми и существующими клиентами Майкрософт.

Предварительные версии API и пакеты SDK предоставляются без соглашения об уровне обслуживания. Мы рекомендуем не использовать их для задач в условиях эксплуатации. Некоторые функции могут не поддерживаться или могут быть ограничены.

Дополнительные сведения см. в дополнительных условиях использования для предварительных версий Microsoft Azure.

В Службы коммуникации Azure чате мы можем включить общий доступ к файлам между пользователями связи. Чат служб коммуникации Azure отличается от чата взаимодействия Teams или Interop Chat. Если вы хотите включить общий доступ к файлам в чате взаимодействия, см. статью "Добавление общего доступа к файлам с библиотекой пользовательского интерфейса" в чате взаимодействия Teams.

В этой статье описывается, как настроить композит чата библиотеки пользовательского интерфейса Служб коммуникации Azure для разрешения обмена файлами. Библиотека UI: Композитный чат предоставляет набор расширенных компонентов и элементов управления пользовательским интерфейсом, которые можно использовать для обеспечения обмена файлами. Мы используем Хранилище BLOB-объектов Azure, чтобы обеспечить хранение файлов, которые передаются через переписку в чате.

Внимание

Службы коммуникации Azure не предоставляет службу хранилища файлов. Для общего доступа к файлам необходимо использовать собственную службу хранилища файлов. В этом руководстве описывается использование хранилища BLOB-объектов Azure.

Скачать код

Доступ к полному коду этого учебника можно получить на странице Пример библиотеки пользовательского интерфейса — обмен файлами с использованием UI Chat Composite. Если вы хотите использовать общий доступ к файлам с помощью компонентов пользовательского интерфейса, см. пример библиотеки пользовательского интерфейса . Общий доступ к файлам с помощью компонентов пользовательского интерфейса.

Предварительные условия

Чтобы использовать эту статью, необходимо знать, как настроить и запустить составной чат. Дополнительные сведения о настройке и запуске составного чата см. в руководстве по ChatComposite.

Обзор

Составной чат библиотеки пользовательского интерфейса поддерживает общий доступ к файлам, позволяя разработчикам передавать URL-адрес размещенного файла, который отправляется через службу чата Службы коммуникации Azure. Библиотека пользовательского интерфейса отрисовывает вложенный файл и поддерживает различные расширения, чтобы настроить внешний вид отправленного файла. В частности, он поддерживает следующие функции:

  1. Кнопка "Присоединить файл" для выбора файлов с помощью средства выбора файлов операционной системы.
  2. Настройка разрешенных расширений файлов.
  3. Включить/отключить возможность нескольких загрузок.
  4. Значки файлов для различных типов файлов.
  5. Карточки отправки и скачивания файлов с индикаторами хода выполнения.
  6. Возможность динамической проверки каждой отправки и отображения ошибок в пользовательском интерфейсе.
  7. Возможность отмены отправки и удаления отправленного файла перед отправкой.
  8. Просмотрите загруженные файлы в MessageThread, скачайте их. Разрешает асинхронные загрузки.

На следующей схеме показан типичный поток сценария общего доступа к файлам для отправки и скачивания. Раздел, отмеченный как Client Managed, показывает строительные блоки, которые разработчикам нужно реализовать.

Типичная схема потока файлов

Настройка хранилища файлов с помощью Azure Blob

Вы можете следовать руководству по отправке файла в хранилище BLOB-объектов Azure с помощью функции Azure , чтобы записать внутренний код, необходимый для общего доступа к файлам.

После реализации эту функцию Azure можно вызвать внутри handleAttachmentSelection функции для отправки файлов в Хранилище BLOB-объектов Azure. В оставшейся части руководства мы предполагаем, что вы создали функцию, используя ранее связанное руководство по хранилищу объектов Blob Azure.

Защита контейнера хранилища блоб-объектов Azure

В этой статье предполагается, что контейнер хранилища BLOB-объектов Azure разрешает общедоступный доступ к отправленным файлам. Предоставление общедоступных контейнеров хранилища Azure не рекомендуется для реальных рабочих приложений.

Для скачивания файлов сначала загружайте их в хранилище BLOB-объектов Azure. Затем можно использовать подписи для общего доступа (SAS). Подпись общего доступа (SAS) предоставляет защищенный делегированный доступ к ресурсам в учетной записи хранения. С помощью SAS вы можете детально контролировать процесс получения клиентом доступа к данным.

Скачиваемый пример GitHub демонстрирует использование SAS для создания URL-адресов SAS к содержимому хранилища Azure. Кроме того, вы можете ознакомиться с дополнительными сведениями о SAS.

Библиотека пользовательского интерфейса требует настройки среды React. Далее мы делаем это. Если у вас уже есть приложение React, вы можете пропустить этот раздел.

Настройка приложения React

Мы используем шаблон create-react-app для этого быстрого старта. Дополнительные сведения см. в статье "Начало работы с React"


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

cd ui-library-quickstart-composites

Завершив этот процесс, вы должны увидеть полностью развернутое приложение в папке ui-library-quickstart-composites. В этом кратком руководстве мы изменяем файлы в папке src.

Установка пакета

npm install Используйте команду, чтобы установить бета-версию библиотеки пользовательского интерфейса Службы коммуникации Azure для JavaScript.


npm install @azure/[email protected]

@azure/communication-reactуказывает основные Службы коммуникации Azure, peerDependencies чтобы обеспечить наиболее согласованное использование API из основных библиотек в приложении. Эти библиотеки также необходимо установить:


npm install @azure/[email protected]
npm install @azure/[email protected]

Создание приложения React

Проверим установку "Создание приложения React", выполнив следующую команду:


npm run start

Настройка составного чата для включения общего доступа к файлам

Для инициализации составного компонента чата необходимо заменить значения для обеих общих переменных.

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

Настройка метода отправки для использования хранилища BLOB-объектов Azure

Чтобы включить загрузку в Azure Blob Storage, мы изменим ранее объявленный метод uploadFileToAzureBlob следующим кодом. Для отправки файлов необходимо заменить сведения о функции 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}`,
  };
};

Обработка ошибок

При сбое загрузки в чатовой компоненте библиотеки пользовательского интерфейса отображается сообщение об ошибке.

Снимок экрана панели ошибок отправки файлов

Ниже приведен пример кода, показывающий, как загрузка может завершиться неудачей из-за ошибки проверки размера файла.

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

Скачивание файлов — расширенное использование

По умолчанию библиотека пользовательского интерфейса открывает новую вкладку, указывающую на URL-адрес, заданный при выполнении notifyUploadCompleted. Кроме того, можно использовать пользовательскую логику для обработки загрузки вложений с помощью actionsForAttachment. Рассмотрим пример.

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();
          })
        }
      }
    ];
  }
}

Если во время скачивания возникли какие-либо проблемы, и пользователя нужно уведомить, вы можете throw вызвать ошибку с сообщением в onClick функции. Затем сообщение отображается в строке ошибок в верхней части составного чата.

Ошибка загрузки файла

Очистка ресурсов

Если вы хотите отменить и удалить подписку на Службы коммуникации, можно удалить ресурс или группу ресурсов. При удалении группы ресурсов также удаляются все связанные с ней ресурсы. Дополнительные сведения о очистке ресурсов Служб коммуникации Azure и очистке ресурсов функций Azure.

Следующие шаги

Проверьте остальную часть библиотеки пользовательского интерфейса