Útmutató: Csatlakozás az Azure Fluid Relay szolgáltatáshoz

Ez a cikk végigvezeti az Azure Fluid Relay szolgáltatás üzembe helyezésének és használatra kész állapotba helyezésének lépésein.

Fontos

Mielőtt csatlakoztatni szeretné az alkalmazást egy Azure Fluid Relay-kiszolgálóhoz, ki kell építenie egy Azure Fluid Relay-kiszolgálói erőforrást az Azure-fiókjában.

Az Azure Fluid Relay szolgáltatás egy felhőalapú Fluid szolgáltatás. A Fluid-alkalmazást csatlakoztathatja egy Azure Fluid Relay-példányhoz az AzureClient használatával a @fluidframework/azure-client csomagban. AzureClientKezeli a Fluid-tároló szolgáltatáshoz való csatlakoztatásának logikáját, miközben maga a tárolóobjektum szolgáltatás-agnosztikus marad. Az ügyfél egy példányával több tárolót is kezelhet.

Az alábbi szakaszokból megtudhatja, hogyan használható AzureClient a saját alkalmazásában.

Csatlakozás a szolgáltatáshoz

Az Azure Fluid Relay-példányhoz való csatlakozáshoz először létre kell hoznia egy AzureClient. Meg kell adnia néhány konfigurációs paramétert, például a bérlőazonosítót, a szolgáltatás URL-címét és egy jogkivonat-szolgáltatót a JSON Web Token (JWT) létrehozásához, amely az aktuális felhasználó szolgáltatáson keresztüli engedélyezéséhez lesz használva. A @fluidframework/test-client-utils csomag egy fejlesztési célokra használható InsecureTokenProvidert biztosít.

Figyelem

Ezt InsecureTokenProvider csak fejlesztési célokra érdemes használni, mert a használatával elérhetővé teszi a bérlőkulcs titkos kulcsát az ügyféloldali kódcsomagban. Ezt az ITokenProvider olyan implementációjára kell cserélni, amely lekéri a jogkivonatot a saját háttérszolgáltatásából, amely a bérlői kulccsal való aláírásért felelős. Ilyen például az AzureFunctionTokenProvider. További információ : TokenProvider írása Azure-függvényekkel. Vegye figyelembe, hogy a mezők és name a id mezők tetszőlegesek.

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

Most, hogy már rendelkezik egy példánysal AzureClient, elkezdheti használni a Fluid-tárolók létrehozásához vagy betöltéséhez!

Jogkivonat-szolgáltatók

Az AzureFunctionTokenProvider egy olyan implementáció ITokenProvider , amely biztosítja, hogy a bérlőkulcs titkos kulcsa ne legyen közzétéve az ügyféloldali csomagkódban. Az AzureFunctionTokenProvider aktuális felhasználói objektummal kiegészített /api/GetAzureToken Azure-függvény URL-címe. Később kérést GET küld az Azure-függvénynek a bérlőazonosító, a documentId és a userId/userName paraméter opcionális paraméterként való átadásával.

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

Egyéni adatok hozzáadása jogkivonatokhoz

A felhasználói objektum opcionális további felhasználói adatokat is tartalmazhat. Például:

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

Az Azure-függvény létrehozza az adott felhasználóhoz tartozó jogkivonatot, amely a bérlő titkos kulcsával van aláírva, és a titkos kulcs felfedése nélkül adja vissza az ügyfélnek.

A tárolók kezelése

Az AzureClient API elérhetővé teszi a createContainer és a getContainer függvényeket a tárolók létrehozásához és lekéréséhez. Mindkét függvény egy tárolósémát használ, amely meghatározza a tároló adatmodellt. getContainer A függvényhez tartozik egy további paraméter a lekérni kívánt tároló tárolójáhozid.

A tárolólétrehozási forgatókönyvben a következő mintát használhatja:

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

A container.attach() hívás az, amikor a tároló ténylegesen csatlakozik a szolgáltatáshoz, és a blobtárolóban lesz rögzítve. Egy egyedi azonosítót id ad vissza ehhez a tárolópéldányhoz.

Minden ügyfélnek, aki ugyanahhoz az együttműködési munkamenethez szeretne csatlakozni, ugyanazzal a tárolóval idkell meghívniagetContainer.

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

A Fluid által kibocsátott naplók felvételének megkezdéséről további információt a naplózás és a telemetriai adatok című témakörben talál.

A visszahívott tároló a initialObjects tárolósémában meghatározottak szerint lesz tárolva. A séma létrehozásáról és az objektum használatáról további információt a fluidframework.com adatmodellezésébencontainer talál.

Célközönség részleteinek lekérése

Két értéket hív meg createContainer és getContainer ad vissza: egy container -- fent leírt - és egy szolgáltatásobjektumot.

A container Fluid-adatmodellt tartalmazza, és szolgáltatás-agnosztikus. Minden olyan kód, amelyet a tárolóobjektumra ír, amelyet a visszaadott, AzureClient újra felhasználható az ügyféllel egy másik szolgáltatáshoz. Ilyen például, ha a TinyliciousClient használatával prototípust készített a forgatókönyvre, akkor a Fluid-tárolóban lévő megosztott objektumokkal interakcióba lépő összes kód újra felhasználható a használatbavételkor AzureClient.

Az services objektum az Azure Fluid Relay szolgáltatásra jellemző adatokat tartalmaz. Ez az objektum egy célközönségértéket tartalmaz, amely a tárolóhoz jelenleg csatlakozó felhasználók névsorának kezelésére használható.

Az alábbi kód bemutatja, hogyan használhatja az objektumot a audience tárolóban lévő összes tag frissített nézetének fenntartására.

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 két függvényt biztosít, amelyek felhasználói azonosítóval és felhasználónévvel rendelkező AzureMember-objektumokat ad vissza:

• getMembers A tárolóhoz csatlakoztatott összes felhasználó térképét adja vissza. Ezek az értékek bármikor megváltoznak, amikor egy tag csatlakozik vagy elhagyja a tárolót.
• getMyself Az ügyfél aktuális felhasználójának visszaadása.

audience eseményeket is bocsát ki, amikor a tagok névsora megváltozik. membersChanged a névsorok változásait, míg memberAddedmemberRemoved a módosított értékeket clientId és member értékeket illetően a megfelelő változások aktiválva lesznek. Ha bármelyik esemény aktiválódik, egy új hívás fogja visszaadni getMembers a frissített taglistát.

A mintaobjektumok AzureMember a következőképpen néznek ki:

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

A felhasználói azonosító, a név és a további részletek AzureMember mellett az objektumok egy kapcsolattömböt is tartalmazhatnak. Ha a felhasználó csak egy ügyféllel van bejelentkezve a munkamenetbe, connections akkor csak egy értéke lesz benne az ügyfél azonosítójával, és hogy írási/olvasási módban van-e. Ha azonban ugyanaz a felhasználó több ügyfélprogramból van bejelentkezve (vagyis különböző eszközökről van bejelentkezve, vagy több böngészőlap is meg van nyitva ugyanazzal a tárolóval), connections itt több érték fog tárolni minden ügyfélhez. A fenti példaadatokban láthatjuk, hogy egy "Tesztfelhasználó" nevű és "0e662aca-9d7d-4ff0-8faf-9f8672b70f15" azonosítójú felhasználó jelenleg két különböző ügyféltől nyitotta meg a tárolót. Az additionalDetails mező értékei egyeznek a jogkivonat-létrehozásban AzureFunctionTokenProvider megadott értékekkel.

Ezek a függvények és események kombinálhatók úgy, hogy valós idejű nézetet jelenítsen meg a felhasználókról az aktuális munkamenetben.

Gratulálunk! Sikeresen csatlakoztatta a Fluid-tárolót az Azure Fluid Relay szolgáltatáshoz, és visszahívta a felhasználói adatokat a tagok számára az együttműködési munkamenetben!