Использование Fluid с Teams

Статья
04/04/2023

К концу этого руководства вы сможете интегрировать любое приложение на платформе Fluid в Teams и сотрудничать с другими пользователями в режиме реального времени.

В этом разделе вы узнаете о следующих понятиях:

Интеграция клиента Fluid в приложение вкладки Teams.
Запустите приложение Teams и подключите его к службе Fluid Service (Azure Fluid Relay).
Создайте и получите гибкие контейнеры и передайте их в компонент React.

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

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

Для работы с этим руководством необходимо ознакомиться со следующими понятиями и ресурсами:

Необходимые условия для установки

Создание проекта

Откройте командную строку и перейдите в родительскую папку, в которой вы хотите создать проект, например /My Microsoft Teams Projects.
Создайте приложение вкладки Teams, выполнив следующую команду и создав вкладку канала:
```
yo teams
```
После создания перейдите к проекту с помощью следующей команды cd <your project name>.

В проекте используются следующие библиотеки:

Library	Описание
`fluid-framework`	Содержит IFluidContainer и другие распределенные структуры данных , которые синхронизируют данные между клиентами.
`@fluidframework/azure-client`	Определяет начальную схему для контейнера Fluid.
`@fluidframework/test-client-utils`	Определяет необходимый `InsecureTokenProvider` для создания подключения к fluid service.

Выполните следующую команду, чтобы установить библиотеки:

npm install @fluidframework/azure-client fluid-framework @fluidframework/test-client-utils

Код проекта

Откройте файл /src/client/<your tab name> в редакторе кода.

Создайте файл как Util.ts и добавьте следующие инструкции импорта:

//`Util.ts

import { IFluidContainer } from "fluid-framework";
import { AzureClient, AzureClientProps } from "@fluidframework/azure-client";
import { InsecureTokenProvider } from "@fluidframework/test-client-utils";

Определение функций и параметров Fluid

Это приложение предназначено для использования в контексте Microsoft Teams со всеми связанными с жидкостью импортами, инициализацией и функциями вместе. Это обеспечивает расширенный интерфейс и упрощает его использование в будущем. В инструкции import можно добавить следующий код:

// TODO 1: Define the parameter key(s).
// TODO 2: Define container schema.
// TODO 3: Define connectionConfig (AzureClientProps).
// TODO 4: Create Azure client.
// TODO 5: Define create container function.
// TODO 6: Define get container function.

Примечание.

Комментарии определяют все функции и константы, необходимые для взаимодействия со службой Fluid и контейнером.

Замените TODO 1: на приведенный ниже код.
```
export const containerIdQueryParamKey = "containerId";
```
Константа экспортируется по мере добавления contentUrl в в параметры Microsoft Teams, а затем для анализа идентификатора контейнера на странице содержимого. Обычно важно хранить ключи параметров запроса в виде констант, а не вводить необработанную строку каждый раз.

Прежде чем клиент сможет создать какие-либо контейнеры, ему нужен объект , определяющий containerSchema общие объекты, используемые в этом приложении. В этом примере в качестве initialObjectsиспользуется SharedMap, но можно использовать любой общий объект.

Примечание.

— map это идентификатор SharedMap объекта, который должен быть уникальным в контейнере, как и любые другие DDS.

Замените TODO: 2 на приведенный ниже код.

const containerSchema = {
    initialObjects: { map: SharedMap }
};

Замените TODO: 3 на приведенный ниже код.
```
const connectionConfig : AzureClientProps =
{
    connection: {
        type: "local",
        tokenProvider: new InsecureTokenProvider("foobar", { id: "user" }),
        endpoint: "http://localhost:7070"
    }
};
```
Прежде чем клиент можно будет использовать, ему нужен AzureClientProps объект , определяющий тип подключения, используемого клиентом. Свойство connectionConfig требуется для подключения к службе. Используется локальный режим клиента Azure. Чтобы обеспечить совместную работу между всеми клиентами, замените ее учетными данными службы Fluid Relay Service. Дополнительные сведения см. в статье Настройка службы Azure Fluid Relay.
Замените TODO: 4 на приведенный ниже код.
```
const client = new AzureClient(connectionConfig);
```
Замените TODO: 5 на приведенный ниже код.
```
export async function createContainer() : Promise<string> {
    const { container } = await client.createContainer(containerSchema);
    const containerId = await container.attach();
    return containerId;
};
```
При создании контейнера на странице конфигурации и добавлении contentUrl его в параметр в Teams необходимо вернуть идентификатор контейнера после присоединения контейнера.
Замените TODO: 6 на приведенный ниже код.
```
export async function getContainer(id : string) : Promise<IFluidContainer> {
    const { container } = await client.getContainer(id, containerSchema);
    return container;
};
```
При получении контейнера Fluid необходимо вернуть контейнер, так как приложение должно взаимодействовать с контейнером и DDS в нем на странице содержимого.

Создание контейнера Fluid на странице конфигурации

Откройте файл src/client/<your tab name>/<your tab name>Config.tsx в редакторе кода.

Стандартный поток приложения вкладки Teams переходит от конфигурации к странице содержимого. Чтобы обеспечить совместную работу, сохранение контейнера при загрузке на страницу содержимого имеет решающее значение. Лучшее решение для сохранения контейнера — добавить идентификатор контейнера в contentUrl и websiteUrl, URL-адреса страницы содержимого в качестве параметра запроса. Кнопка "Сохранить" на странице конфигурации Teams — это шлюз между страницей конфигурации и страницей содержимого. Это место для создания контейнера и добавления идентификатора контейнера в параметры.

Добавьте следующий оператор импорта:

import { createContainer, containerIdQueryParamKey } from "./Util";

Замените метод onSaveHandler следующим кодом. Единственные строки, добавленные здесь, вызывает метод create container, определенный ранее в , Utils.ts а затем добавляет возвращенный идентификатор контейнера в contentUrl и websiteUrl в качестве параметра запроса.
```
const onSaveHandler = async (saveEvent: microsoftTeams.settings.SaveEvent) => {
    const host = "https://" + window.location.host;
    const containerId = await createContainer();
    microsoftTeams.settings.setSettings({
        contentUrl: host + "/<your tab name>/?" + containerIdQueryParamKey + "=" + containerId + "&name={loginHint}&tenant={tid}&group={groupId}&theme={theme}",
        websiteUrl: host + "/<your tab name>/?" + containerIdQueryParamKey + "=" + containerId + "&name={loginHint}&tenant={tid}&group={groupId}&theme={theme}",
        suggestedDisplayName: "<your tab name>",
        removeUrl: host + "/<your tab name>/remove.html?theme={theme}",
        entityId: entityId.current
    });
    saveEvent.notifySuccess();
};
```
Обязательно замените <your tab name> именем вкладки из проекта.

Предупреждение

Так как URL-адрес страницы содержимого используется для хранения идентификатора контейнера, эта запись удаляется при удалении вкладки Teams. Кроме того, каждая страница содержимого может поддерживать только один идентификатор контейнера.

Рефакторинг страницы содержимого в соответствии с приложением Fluid

Откройте файл src/client/<your tab name>/<your tab name>.tsx в редакторе кода. Типичное приложение на основе fluid-power состоит из представления и структуры данных Fluid. Сосредоточьтесь на получении или загрузке контейнера Fluid и оставьте все взаимодействия, связанные с жидкостью, в компоненте React.

Добавьте следующие инструкции импорта на страницу содержимого:

import { IFluidContainer } from "fluid-framework";
import { getContainer, containerIdQueryParamKey } from "./Util";

Удалите весь код под операторами импорта на странице содержимого и замените его следующим кодом:

export const <your tab name> = () => {
  // TODO 1: Initialize Microsoft Teams.
  // TODO 2: Initialize inTeams boolean.
  // TODO 3: Define container as a React state.
  // TODO 4: Define a method that gets the Fluid container
  // TODO 5: Get Fluid container on content page startup.
  // TODO 6: Pass the container to the React component as argument.
}

Обязательно замените <your tab name> именем вкладки, определяемой для проекта.

Замените TODO 1 на приведенный ниже код.
```
microsoftTeams.initialize();
```
Чтобы отобразить страницу содержимого в Teams, необходимо включить клиентскую библиотеку JavaScript Microsoft Teams и включить вызов для ее инициализации после загрузки страницы.
Замените TODO 2 на приведенный ниже код.
```
const [{ inTeams }] = useTeams();
```
Так как приложение Teams является всего лишь внедрением IFrame веб-страницы, необходимо инициализировать inTeams логическую константу, чтобы узнать, находится ли приложение в Teams или нет, а также доступны ли ресурсы Teams, такие как contentUrl, .
Замените TODO 3 на приведенный ниже код.
```
const [fluidContainer, setFluidContainer] = useState<IFluidContainer | undefined>(undefined);
```
Используйте состояние React для контейнера, так как оно предоставляет возможность динамического обновления контейнера и объектов данных в нем.
Замените TODO 4 на приведенный ниже код.
```
const getFluidContainer = async (url : URLSearchParams) => {
    const containerId = url.get(containerIdQueryParamKey);
    if (!containerId) {
        throw Error("containerId not found in the URL");
    }
    const container = await getContainer(containerId);
    setFluidContainer(container);
};
```
Проанализируйте URL-адрес, чтобы получить строку параметра запроса, определенную в containerIdQueryParamKey, и получить идентификатор контейнера. С помощью идентификатора контейнера можно загрузить контейнер. После создания контейнера задайте fluidContainer состояние React, см. предыдущий шаг.
Замените TODO 5 на приведенный ниже код.
```
useEffect(() => {
    if (inTeams === true) {
        microsoftTeams.settings.getSettings(async (instanceSettings) => {
            const url = new URL(instanceSettings.contentUrl);
            getFluidContainer(url.searchParams);
        });
        microsoftTeams.appInitialization.notifySuccess();
    }
}, [inTeams]);
```
Определив способ получения контейнера Fluid, необходимо сообщить, React вызывать getFluidContainer при загрузке, а затем сохранить результат в состоянии на основе того, находится ли приложение в Teams. Обработчик useState React предоставляет требуемое хранилище, а useEffect позволяет вызывать getFluidContainer при отрисовке, передав возвращаемое значение в setFluidContainer.

Добавляя inTeams в массив зависимостей в конце useEffect, приложение гарантирует, что эта функция вызывается только при загрузке страницы содержимого.
Замените TODO 6 на приведенный ниже код.
```
if (inTeams === false) {
  return (
      <div>This application only works in the context of Microsoft Teams</div>
  );
}

if (fluidContainer !== undefined) {
  return (
      <FluidComponent fluidContainer={fluidContainer} />
  );
}

return (
  <div>Loading FluidComponent...</div>
);
```
Примечание.

Важно убедиться, что страница содержимого загружена в Teams и что контейнер Fluid определен перед передачей в компонент React (определяется как FluidComponent, см. ниже).

Создание компонента React для представления и данных Fluid

Вы интегрировали базовый поток создания Teams и Fluid. Теперь можно создать собственный компонент React, обрабатывающий взаимодействие между представлением приложения и гибкими данными. С этого момента логика и поток ведут себя так же, как и другие приложения с гибким питанием. Настроив базовую структуру, вы можете создать любой из примеров Fluid в качестве приложения Teams, изменив ContainerSchema взаимодействие представления приложения с объектами DDS/data на странице содержимого.

Запустите сервер Fluid и запустите приложение

Если вы запускаете приложение Teams локально в локальном режиме клиента Azure, выполните в командной строке следующую команду, чтобы запустить службу Fluid:

npx @fluidframework/azure-local-service@latest

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

Предупреждение

Имена узлов со ngrokсвободными туннелями не сохраняются. При каждом выполнении создается другой URL-адрес. При создании нового ngrok туннеля старый контейнер больше не будет доступен. Сведения о рабочих сценариях см. в статье Использование AzureClient с Azure Fluid Relay.

Примечание.

Установите дополнительную зависимость, чтобы сделать эту демонстрацию совместимой с Webpack 5. Если появляется ошибка компиляции, связанная с "буферным" пакетом, запустите npm install -D buffer и повторите попытку. Это будет решено в будущем выпуске Fluid Framework.

Дальнейшие действия

Использование AzureClient с Azure Fluid Relay

Так как это приложение вкладки Teams, совместная работа и взаимодействие являются main фокусом. Замените локальный режим AzureClientProps , предоставленный ранее, не локальными учетными данными из экземпляра службы Azure, чтобы другие пользователи могли присоединиться к вам и взаимодействовать с вами в приложении. Узнайте , как подготовить службу Azure Fluid Relay.

Важно!

Важно скрыть учетные данные, которые вы передаете, AzureClientProps от случайной фиксации в системе управления версиями. Проект Teams поставляется с файлом, в котором .env учетные данные можно хранить как переменные среды, а сам файл уже включен в .gitignore. Сведения об использовании переменных среды в Teams см. в статье Установка и получение переменных среды.

Предупреждение

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

Установка и получение переменной среды

Чтобы задать переменную среды и получить ее в Teams, можно воспользоваться встроенным .env файлом. Следующий код используется для задания переменной среды в .env:

# .env

TENANT_KEY=foobar

Чтобы передать содержимое .env файла в клиентское приложение, необходимо настроить его webpack.config.js таким образом, webpack чтобы обеспечить доступ к ним во время выполнения. Используйте следующий код, чтобы добавить переменную среды из .env:

// webpack,config.js

webpack.EnvironmentPlugin({
    PUBLIC_HOSTNAME: undefined,
    TAB_APP_ID: null,
    TAB_APP_URI: null,
    REACT_APP_TENANT_KEY: JSON.stringify(process.env.TENANT_KEY) // Add environment variable here
}),

Вы можете получить доступ к переменной среды в Util.ts

// Util.ts

tokenProvider: new InsecureTokenProvider(JSON.parse(process.env.REACT_APP_TENANT_KEY!), { id: "user" }),

Совет

При внесении изменений в код проект автоматически перестраивается, а сервер приложений перезагружается. Однако при внесении изменений в схему контейнера они вступают в силу только при закрытии и перезапуске сервера приложений. Для этого перейдите в командную строку и дважды нажмите клавиши CTRL+C. Затем запустите gulp serve или gulp ngrok-serve еще раз.