Herstellen einer Verbindung mit einem Azure Fluid Relay-Dienst

Artikel
01/04/2024

In diesem Artikel werden die Schritte erläutert, mit denen Sie Ihren Azure Fluid Relay-Dienst bereitstellen und verwenden können.

Wichtig

Bevor Sie Ihre App mit einem Azure Fluid Relay-Server verbinden können, müssen Sie eine Azure Fluid Relay-Serverressource in Ihrem Azure-Konto bereitstellen.

Der Azure Fluid Relay-Dienst ist ein in der Cloud gehosteter Fluid-Dienst. Sie können Ihre Fluid-Anwendung mit einer Azure Fluid Relay-Instanz verbinden, indem Sie den AzureClient im @fluidframework/azure-client-Paket verwenden. AzureClient übernimmt die Logik beim Herstellen der Verbindung Ihres Fluid-Containers mit dem Dienst, während das Containerobjekt selbst dienstunabhängig bleibt. Sie können eine Instanz dieses Clients für die Verwaltung mehrerer Container verwenden.

In den folgenden Abschnitten wird erläutert, wie Sie AzureClient in Ihrer eigenen Anwendung verwenden.

Herstellen einer Verbindung mit dem Dienst

Zum Herstellen einer Verbindung mit einer Azure Fluid Relay-Instanz müssen Sie zunächst ein AzureClient erstellen. Sie müssen einige Konfigurationsparameter bereitstellen, darunter die ID des Mandanten, die Dienst-URL sowie einen Tokenanbieter, um das JSON Web Token (JWT) zu generieren, das zur Autorisierung des aktuellen Benutzers für den Dienst verwendet wird. Das @fluidframework/test-client-utils-Paket stellt einen InsecureTokenProvider bereit, der für Entwicklungszwecke verwendet werden kann.

Achtung

Dies InsecureTokenProvider sollte nur für Entwicklungszwecke verwendet werden, da die Verwendung den geheimen Mandantenschlüssel in Ihrem clientseitigen Codebundle verfügbar macht. Dies muss durch eine Implementierung von ITokenProvider ersetzt werden, die das Token aus Ihrem eigenen Back-End-Dienst abruft, der für das Signieren mit dem Mandantenschlüssel verantwortlich ist. Eine Beispielimplementierung ist AzureFunctionTokenProvider. Weitere Informationen finden Sie unter Schreiben eines TokenProvider-Elements mit einer Azure-Funktion. Beachten Sie, dass die Felder id und name beliebig sind.

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

Jetzt, da Sie eine Instanz von AzureClient besitzen, können Sie diese verwenden, um Fluid-Container zu erstellen oder zu laden!

Tokenanbieter

Der AzureFunctionTokenProvider ist eine Implementierung, mit der ITokenProvider sichergestellt wird, dass Der geheime Mandantenschlüssel nicht im clientseitigen Bundlecode verfügbar gemacht wird. Der AzureFunctionTokenProvider übernimmt Ihre Azure-Funktions-URL, an die /api/GetAzureToken zusammen mit dem aktuellen Benutzerobjekt angefügt wird. Später wird eine GET-Anforderung an Ihre Azure-Funktion gestellt, indem „tenantId“, „documentId“ und „userId/userName“ als optionale Parameter übergeben werden.

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

Hinzufügen benutzerdefinierter Daten zu Token

Das Benutzerobjekt kann auch optionale zusätzliche Benutzerdetails enthalten. Beispiel:

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

Ihre Azure-Funktion generiert das Token für den angegebenen Benutzer, der mit dem geheimen Schlüssel des Mandanten signiert wurde, und gibt es an den Client zurück, ohne das Geheimnis selbst verfügbar zu machen.

Verwalten von Containern

Die AzureClient API macht createContainer- und getContainer-Funktionen verfügbar, um Container zu erstellen bzw. abzurufen. Beide Funktionen verwenden ein Containerschema, das das Containerdatenmodell definiert. Für die getContainer-Funktion gibt es einen zusätzlichen Parameter für die Container-id des Containers, den Sie abrufen möchten.

Im Szenario der Containererstellung können Sie das folgende Muster verwenden:

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

Der container.attach()-Aufruf erfolgt, wenn der Container tatsächlich mit dem Dienst verbunden und in seinem Blobspeicher aufgezeichnet wird. Er gibt eine id zurück, die der eindeutige Bezeichner für diese Containerinstanz ist.

Jeder Client, der derselben in Zusammenarbeit durchgeführten Sitzung beitreten möchte, muss getContainer mit derselben Container-id aufrufen.

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

Weitere Informationen zum Starten der Aufzeichnung von Protokollen, die von Fluid ausgegeben werden, finden Sie unter Protokollierung und Telemetrie.

Der zurückgegebene Container enthält die initialObjects wie im Containerschema definiert. Weitere Informationen zum Einrichten des Schemas und zum Verwenden des container-Objekts finden Sie unter Data modeling (Datenmodellierung) auf „fluidframework.com“.

Abrufen von Zielgruppendetails

Aufrufe an createContainer und getContainer zurückgeben zwei Werte: ein container -- wie oben beschrieben - und ein Dienstobjekt.

Der container enthält das Fluid-Datenmodell und ist dienstunabhängig. Jeglicher Code, den Sie für dieses Containerobjekt schreiben, das von AzureClient zurückgegeben wird, kann mit dem Client für einen anderen Dienst wiederverwendet werden. Ein Beispiel ist, wenn Sie Ihr Szenario mit TinyliciousClient prototypiert haben, dann kann der gesamte Code, der mit den freigegebenen Objekten innerhalb des Fluid-Containers interagiert, wiederverwendet werden, wenn Sie zu verwenden AzureClient.

Das services-Objekt enthält Daten, die spezifisch für den Azure Fluid Relay-Dienst sind. Dieses Objekt enthält einen Zielgruppen-Wert, der verwendet werden kann, um die Liste der Benutzer zu verwalten, die derzeit mit dem Container verbunden sind.

Der folgende Code veranschaulicht, wie Sie das audience-Objekt verwenden können, um eine aktualisierte Ansicht aller Member zu verwalten, die sich derzeit in einem Container befinden.

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 stellt zwei Funktionen bereit, die AzureMember-Objekte zurückgeben, die über eine Benutzer-ID und einen Benutzernamen verfügen:

getMembers gibt eine Zuordnung aller Benutzer zurück, die mit dem Container verbunden sind. Diese Werte ändern sich, wenn ein Member dem Container beitritt oder ihn verlässt.
getMyself gibt den aktuellen Benutzer auf diesem Client zurück.

audience gibt auch Ereignisse für den Fall aus, dass sich die Liste der Member ändert. membersChanged wird für alle Änderungen an der Liste ausgelöst, während memberAdded und memberRemoved für die jeweiligen Änderungen mit den geänderten clientId- und member-Werten ausgelöst werden. Nachdem eines dieser Ereignisse ausgelöst wurde, gibt ein neuer Aufruf von getMembers die aktualisierte Memberliste zurück.

Ein AzureMember-Beispielobjekt sieht wie folgt aus:

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

Neben der Benutzer-ID, dem Namen und weiteren Details AzureMember enthalten Objekte auch ein Array von Verbindungen. Wenn der Benutzer mit nur einem Client bei der Sitzung angemeldet ist, enthält connections nur einen Wert mit der ID des Clients und den Status, ob er sich im Lese-/Schreibmodus befindet. Wenn derselbe Benutzer jedoch über mehrere Clients angemeldet ist (d. h. er ist von verschiedenen Geräten angemeldet oder hat mehrere Browserregisterkarten mit demselben Container geöffnet), enthält connections hier mehrere Werte für jeden Client. In den Beispieldaten oben sehen wir, dass ein Benutzer mit dem Namen „Test User“ und der ID „0e662aca-9d7d-4ff0-8faf-9f8672b70f15“ den Container derzeit von zwei verschiedenen Clients aus geöffnet hat. Die Werte im Feld "additionalDetails" stimmen mit den werten überein, die in der AzureFunctionTokenProvider Tokengenerierung bereitgestellt werden.

Diese Funktionen und Ereignisse können kombiniert werden, um eine Echtzeitansicht der Benutzer in der aktuellen Sitzung darzustellen.

Herzlichen Glückwunsch! Sie haben jetzt Ihren Fluid-Container erfolgreich mit dem Azure Fluid Relay-Dienst verbunden und die Benutzerdetails für die Member in Ihrer gemeinsamen Sitzung abgerufen!