Практическое руководство. Подключение к службе Azure Fluid Relay

Статья
01/04/2024

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

Важно!

Прежде чем подключить приложение к серверу Azure Fluid Relay, необходимо подготовить ресурс сервера Azure Fluid Relay в учетной записи Azure.

Служба Azure Fluid Relay — это облачная служба "Жидкость". Вы можете подключить приложение Fluid к экземпляру Ретранслятора Azure с помощью AzureClient в пакете @fluidframework/azure-client . AzureClient обрабатывает логику подключения контейнера "Жидкость" к службе при сохранении объекта контейнера, не зависящем от службы. Для управления несколькими контейнерами можно использовать один экземпляр этого клиента.

В следующих разделах описано, как использовать AzureClient в собственном приложении.

Подключение в службу

Чтобы подключиться к экземпляру Ретранслятора Azure, сначала необходимо создать экземпляр AzureClient. Необходимо указать некоторые параметры конфигурации, включая идентификатор клиента, URL-адрес службы и поставщик маркеров для создания веб-маркера JSON (JWT), который будет использоваться для авторизации текущего пользователя в службе. Пакет @fluidframework/test-client-utils предоставляет insecureTokenProvider, который можно использовать для целей разработки.

Внимание

Следует InsecureTokenProvider использовать только для целей разработки, так как он предоставляет секрет ключа клиента в пакете кода на стороне клиента. Это необходимо заменить реализацией ITokenProvider, которая извлекает маркер из собственной серверной службы, ответственной за подписывание с помощью ключа клиента. Примером реализации является AzureFunctionTokenProvider. Дополнительные сведения см. в статье "Практическое руководство. Запись tokenProvider с помощью функции Azure". Обратите внимание, что id поля name являются произвольными.

const user = { id: "userId", name: "userName" };

const config = {
  tenantId: "myTenantId",
  tokenProvider: new InsecureTokenProvider("myTenantKey", user),
  endpoint: "https://myServiceEndpointUrl",
  type: "remote",
};

const clientProps = {
  connection: config,
};

const client = new AzureClient(clientProps);

Теперь, когда у вас есть экземпляр AzureClient, вы можете начать использовать его для создания или загрузки контейнеров Жидкости!

Поставщики токенов

AzureFunctionTokenProvider — это реализация ITokenProvider , которая гарантирует, что секрет ключа клиента не предоставляется в коде пакета на стороне клиента. Принимает AzureFunctionTokenProvider URL-адрес функции Azure, добавленный /api/GetAzureToken вместе с текущим объектом пользователя. Позже он отправляет GET запрос в функцию Azure путем передачи идентификатора клиента, documentId и userId/userName в качестве необязательных параметров.

const config = {
  tenantId: "myTenantId",
  tokenProvider: new AzureFunctionTokenProvider(
    "myAzureFunctionUrl" + "/api/GetAzureToken",
    { userId: "userId", userName: "Test User" }
  ),
  endpoint: "https://myServiceEndpointUrl",
  type: "remote",
};

const clientProps = {
  connection: config,
};

const client = new AzureClient(clientProps);

Добавление пользовательских данных в маркеры

Объект пользователя также может содержать дополнительные сведения о пользователе. Например:

const userDetails = {
  email: "xyz@outlook.com",
  address: "Redmond",
};

const config = {
  tenantId: "myTenantId",
  tokenProvider: new AzureFunctionTokenProvider(
    "myAzureFunctionUrl" + "/api/GetAzureToken",
    { userId: "UserId", userName: "Test User", additionalDetails: userDetails }
  ),
  endpoint: "https://myServiceEndpointUrl",
  type: "remote",
};

Функция Azure создаст маркер для данного пользователя, подписанного с помощью секретного ключа клиента, и вернет его клиенту без предоставления секрета.

Управление контейнерами

AzureClient API предоставляет функции createContainer и getContainer для создания и получения контейнеров соответственно. Обе функции выполняются в схеме контейнера, которая определяет модель данных контейнера. getContainer Для функции существует дополнительный параметр для контейнера id контейнера, который требуется получить.

В сценарии создания контейнера можно использовать следующий шаблон:

const schema = {
  initialObjects: {
    /* ... */
  },
  dynamicObjectTypes: [
    /*...*/
  ],
};
const azureClient = new AzureClient(clientProps);
const { container, services } = await azureClient.createContainer(
  schema
);
const id = await container.attach();

Вызов container.attach() происходит, когда контейнер фактически подключается к службе и записывается в его хранилище BLOB-объектов. Он возвращает id уникальный идентификатор для этого экземпляра контейнера.

Любой клиент, который хочет присоединиться к одному сеансу совместной работы, должен вызываться getContainer с тем же контейнером id.

const { container, services } = await azureClient.getContainer(
  id,
  schema
);

Дополнительные сведения о том, как начать запись журналов, создаваемых Жидкостью, см. в разделе "Ведение журналов и телеметрия".

Контейнер, извлекаемый обратно, будет содержать initialObjects как определено в схеме контейнера. Дополнительные сведения о том, как установить схему и использовать container объект, см. в разделе "Моделирование данных" в fluidframework.com.

Получение сведений о аудитории

createContainer Вызовы и возврат двух значений: как container описано выше, так и getContainer объект служб.

Содержит container модель динамических данных и не зависит от обслуживания. Любой код, который вы пишете против этого объекта контейнера, AzureClient возвращаемого повторно, можно использовать с клиентом для другой службы. Например, если вы прототипировали сценарий с помощью TinyliciousClient, то при переходе на использование AzureClientможно повторно использовать весь код, взаимодействующий с общими объектами в контейнере Fluid.

Объект services содержит данные, относящиеся к службе Azure Fluid Relay. Этот объект содержит значение аудитории, которое можно использовать для управления списком пользователей, которые в настоящее время подключены к контейнеру.

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

const { audience } = containerServices;
const audienceDiv = document.createElement("div");

const onAudienceChanged = () => {
  const members = audience.getMembers();
  const self = audience.getMyself();
  const memberStrings = [];
  const useAzure = process.env.FLUID_CLIENT === "azure";

  members.forEach((member) => {
    if (member.userId !== (self ? self.userId : "")) {
      if (useAzure) {
        const memberString = `${member.userName}: {Email: ${member.additionalDetails ? member.additionalDetails.email : ""},
                        Address: ${member.additionalDetails ? member.additionalDetails.address : ""}}`;
        memberStrings.push(memberString);
      } else {
        memberStrings.push(member.userName);
      }
    }
  });
  audienceDiv.innerHTML = `
            Current User: ${self ? self.userName : ""} <br />
            Other Users: ${memberStrings.join(", ")}
        `;
};

onAudienceChanged();
audience.on("membersChanged", onAudienceChanged);

audience предоставляет две функции, которые возвращают объекты AzureMember с идентификатором пользователя и именем пользователя:

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

audience также выдает события при изменении списка членов. membersChanged будет запускаться для любых изменений списка, в то время как memberAdded и memberRemoved будет запускаться для их соответствующих изменений с clientId member измененными значениями и значениями. После какого-либо из этих событий вызов getMembers возвращает обновленный список участников.

Пример AzureMember объекта выглядит следующим образом:

{
  "userId": "0e662aca-9d7d-4ff0-8faf-9f8672b70f15",
  "userName": "Test User",
  "connections": [
    {
      "id": "c699c3d1-a4a0-4e9e-aeb4-b33b00544a71",
      "mode": "write"
    },
    {
      "id": "0e662aca-9d7d-4ff0-8faf-9f8672b70f15",
      "mode": "write"
    }
  ],
  "additionalDetails": {
    "email": "xyz@outlook.com",
    "address": "Redmond"
  }
}

Помимо идентификатора пользователя, имени и дополнительных сведений, AzureMember объекты также содержат массив соединений. Если пользователь вошел в сеанс только с одним клиентом, connections в нем будет только одно значение с идентификатором клиента и находится ли в режиме чтения и записи. Однако если один и тот же пользователь вошел из нескольких клиентов (то есть они вошли с разных устройств или имеют несколько вкладок браузера, открытых с одинаковым контейнером), connections здесь будут храниться несколько значений для каждого клиента. В приведенном выше примере данных видно, что пользователь с именем "Тестовый пользователь" и идентификатор "0e662aca-9d7d-4ff0-8faf-9f8672b70f15" в настоящее время имеет контейнер, открытый из двух разных клиентов. Значения в поле дополнительныхDetails соответствуют значениям, указанным в AzureFunctionTokenProvider создании токенов.

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

Поздравляем! Теперь вы успешно подключили контейнер "Жидкость" к службе Ретранслятора Azure и получили подробные сведения о пользователях в сеансе совместной работы!

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