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

Внимание

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

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

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

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

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

Внимание

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

Скачать код

Доступ к полному коду этого руководства на сайте GitHub. Если вы хотите использовать общий доступ к файлам с помощью компонентов пользовательского интерфейса, обратитесь к этому примеру.

Необходимые компоненты

• Учетная запись Azure с активной подпиской. Дополнительные сведения см. на странице Создайте бесплатную учетную запись Azure уже сегодня.
• Visual Studio Code на одной из поддерживаемых платформ.
• Node.js, активная версия LTS и версия Maintenance LTS (рекомендуется 10.14.1). Используйте команду node --version, чтобы проверить установленную версию.
• Активный ресурс Служб коммуникации и строка подключения. Создайте ресурс Служб коммуникации.

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

Обзор

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

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

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

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

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

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

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

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

Для скачивания файлов вы отправляете в хранилище BLOB-объектов Azure, вы можете использовать подписанные URL-адреса (SAS). Подписанный URL-адрес (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/communication-react@1.16.0-beta.1

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

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

Создание приложения 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

Чтобы включить отправку Хранилище BLOB-объектов Azure, мы изменим метод, объявленный 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 progess.
      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.

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

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

Полезные ссылки

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