Instrukcje: Połączenie do usługi Azure Fluid Relay

Artykuł
10/24/2023

W tym artykule przedstawiono procedurę aprowizowania i gotowości usługi Azure Fluid Relay do użycia.

Ważne

Aby można było połączyć aplikację z serwerem usługi Azure Fluid Relay, musisz aprowizować zasób serwera usługi Azure Fluid Relay na koncie platformy Azure.

Usługa Azure Fluid Relay to hostowana w chmurze usługa Fluid Service. Aplikację Fluid można połączyć z wystąpieniem usługi Azure Fluid Relay przy użyciu elementu AzureClient w pakiecie @fluidframework/azure-client . AzureClient obsługuje logikę łączenia kontenera Fluid z usługą przy jednoczesnym zachowaniu niezależnego od usługi obiektu kontenera. Do zarządzania wieloma kontenerami można użyć jednego wystąpienia tego klienta.

W poniższych sekcjach wyjaśniono, jak używać AzureClient jej we własnej aplikacji.

Połączenie do usługi

Aby nawiązać połączenie z wystąpieniem usługi Azure Fluid Relay, należy najpierw utworzyć element AzureClient. Należy podać niektóre parametry konfiguracji, w tym identyfikator dzierżawy, adres URL usługi i dostawcę tokenu, aby wygenerować token internetowy JSON (JWT), który będzie używany do autoryzowania bieżącego użytkownika względem usługi. Pakiet @fluidframework/test-client-utils udostępnia insecureTokenProvider, który może być używany do celów programistycznych.

Uwaga

Element InsecureTokenProvider powinien być używany tylko do celów programistycznych, ponieważ użycie go uwidacznia klucz tajny klucza dzierżawy w pakiecie kodu po stronie klienta. Należy go zastąpić implementacją elementu ITokenProvider, która pobiera token z własnej usługi zaplecza, która jest odpowiedzialna za podpisywanie go za pomocą klucza dzierżawy. Przykładowa implementacja to AzureFunctionTokenProvider. Aby uzyskać więcej informacji, zobacz Jak napisać tokenProvider za pomocą funkcji platformy Azure. Należy pamiętać, że id pola i name są dowolne.

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

Teraz, gdy masz wystąpienie AzureClientprogramu , możesz zacząć używać go do tworzenia lub ładowania kontenerów fluidu.

Dostawcy tokenów

AzureFunctionTokenProvider to implementacja ITokenProvider , która zapewnia, że klucz tajny klucza dzierżawy nie jest uwidaczniany w kodzie pakietu po stronie klienta. Element AzureFunctionTokenProvider pobiera adres URL funkcji platformy Azure dołączony /api/GetAzureToken wraz z bieżącym obiektem użytkownika. Później wysyła GET żądanie do funkcji platformy Azure, przekazując wartości tenantId, documentId i userId/userName jako parametry opcjonalne.

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

Dodawanie danych niestandardowych do tokenów

Obiekt użytkownika może również przechowywać opcjonalne dodatkowe szczegóły użytkownika. Na przykład:

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

Funkcja platformy Azure wygeneruje token dla danego użytkownika podpisanego przy użyciu klucza tajnego dzierżawy i zwróci go do klienta bez ujawnienia samego wpisu tajnego.

Zarządzanie kontenerami

Interfejs AzureClient API uwidacznia funkcje createContainer i getContainer, aby odpowiednio tworzyć i pobierać kontenery. Obie funkcje przyjmują schemat kontenera, który definiuje model danych kontenera. W przypadku getContainer funkcji istnieje dodatkowy parametr dla kontenera id kontenera, który chcesz pobrać.

W scenariuszu tworzenia kontenera można użyć następującego wzorca:

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

Wywołanie container.attach() jest wtedy, gdy kontener rzeczywiście staje się połączony z usługą i jest rejestrowany w magazynie obiektów blob. Zwraca wartość, która jest unikatowym identyfikatorem id tego wystąpienia kontenera.

Każdy klient, który chce dołączyć do tej samej sesji współpracy, musi wywołać getContainer z tym samym kontenerem id.

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

Aby uzyskać więcej informacji na temat uruchamiania rejestrowania dzienników emitowanych przez płyn, zobacz Rejestrowanie i telemetria.

Pobrany z powrotem kontener będzie przechowywać initialObjects wartość zdefiniowaną w schemacie kontenera. Zobacz Modelowanie danych w fluidframework.com, aby dowiedzieć się więcej na temat sposobu ustanawiania schematu i używania container obiektu.

Pobieranie szczegółów odbiorców

Wywołuje i createContainergetContainer zwraca dwie wartości: container - opisane powyżej - i obiekt usług.

Element container zawiera model danych płynu i jest niezależny od usługi. Każdy kod zapisywany względem tego obiektu kontenera zwrócony przez AzureClient obiekt jest wielokrotnego użytku z klientem dla innej usługi. Przykładem może być utworzenie prototypu scenariusza przy użyciu programu TinyliciousClient, wówczas cały kod współdziałający z obiektami udostępnionymi w kontenerze Fluid może zostać ponownie użyty podczas przechodzenia do metody .AzureClient

Obiekt services zawiera dane specyficzne dla usługi Azure Fluid Relay. Ten obiekt zawiera wartość odbiorców, która może służyć do zarządzania składem użytkowników, którzy są obecnie połączeni z kontenerem.

Poniższy kod pokazuje, jak za pomocą audience obiektu zachować zaktualizowany widok wszystkich elementów członkowskich znajdujących się obecnie w kontenerze.

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 Udostępnia dwie funkcje, które będą zwracać obiekty AzureMember, które mają identyfikator użytkownika i nazwę użytkownika:

getMembers Zwraca mapę wszystkich użytkowników połączonych z kontenerem. Te wartości zmienią się za każdym razem, gdy element członkowski zostanie sprzężenia lub opuści kontener.
getMyself Zwraca bieżącego użytkownika na tym kliencie.

audience Emituje również zdarzenia, gdy zmienia się skład członków. membersChanged zostanie wyzwolony dla wszystkich zmian listy, podczas gdy memberAdded i memberRemoved zostanie wyzwolony dla odpowiednich zmian z wartościami clientId i member , które zostały zmodyfikowane. Po uruchomieniu któregokolwiek z tych zdarzeń nowe wywołanie getMembers zwróci zaktualizowany skład członka.

Przykładowy AzureMember obiekt wygląda następująco:

{
  "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"
  }
}

Oprócz identyfikatora użytkownika, nazwy i dodatkowych szczegółów AzureMember obiekty przechowują również tablicę połączeń. Jeśli użytkownik jest zalogowany do sesji tylko z jednym klientem, connections będzie miał tylko jedną wartość z identyfikatorem klienta i czy jest w trybie odczytu/zapisu. Jeśli jednak ten sam użytkownik jest zalogowany z wielu klientów (czyli loguje się z różnych urządzeń lub ma otwarte wiele kart przeglądarki przy użyciu tego samego kontenera), connections w tym miejscu będzie przechowywać wiele wartości dla każdego klienta. W powyższych przykładowych danych widać, że użytkownik o nazwie "Użytkownik testowy" i identyfikator "0e662aca-9d7d-4ff0-8faf-9f8672b70f15" obecnie ma otwarty kontener z dwóch różnych klientów. Wartości w polu additionalDetails są zgodne z wartościami podanymi w generowaniu tokenu AzureFunctionTokenProvider .

Te funkcje i zdarzenia można połączyć, aby przedstawić widok użytkowników w czasie rzeczywistym w bieżącej sesji.

Gratulacje! Teraz pomyślnie połączono kontener Fluid z usługą Azure Fluid Relay i pobrano szczegóły użytkownika z powrotem dla członków w sesji współpracy.

Share via