كيفية القيام بما يلي: التوصيل ببند خدمة Azure Fluid Relay

تتناول هذه المقالة الخطوات للحصول على خدمة Azure Fluid Relay المتوفرة وجاهزة للاستخدام.

هام

قبل أن تتمكن من توصيل تطبيقك بخادم Azure Fluid Relay، يجب توفير مورد خادم Azure Fluid Relay على حساب Azure الخاص بك.

خدمة Azure Fluid Relay هي خدمة Fluid مستضافة على السحابة. يمكنك توصيل تطبيق Fluid بمثيل Azure Fluid Relay باستخدام AzureClient في حزمة @fluidframework/azure-client . AzureClientيعالج منطق توصيل حاوية Fluid الخاصة بك بالخدمة مع الحفاظ على كائن الحاوية نفسه غير محدد الخدمة. يمكنك استخدام مثيل واحد من هذا العميل لإدارة حاويات متعددة.

ستشرح الأقسام أدناه كيفية الاستخدام AzureClient في التطبيق الخاص بك.

الاتصال إلى الخدمة

للاتصال بمثيل Azure Fluid Relay، تحتاج أولا إلى إنشاء AzureClient. يجب توفير بعض معلمات التكوين بما في ذلك معرف المستأجر وعنوان URL للخدمة وموفر الرمز المميز لإنشاء رمز ويب JSON المميز (JWT) الذي سيتم استخدامه لتخويل المستخدم الحالي مقابل الخدمة. توفر حزمة @fluidframework/test-client-utils موفر غير آمن يمكن استخدامه لأغراض التطوير.

تنبيه

InsecureTokenProvider يجب استخدام فقط لأغراض التطوير لأن استخدامه يكشف سر مفتاح المستأجر في مجموعة التعليمات البرمجية من جانب العميل. يجب استبدال هذا بتنفيذ ITokenProvider الذي يجلب الرمز المميز من خدمة الواجهة الخلفية الخاصة بك المسؤولة عن توقيعه باستخدام مفتاح المستأجر. مثال على التنفيذ هو AzureFunctionTokenProvider. لمزيد من المعلومات، راجع كيفية: كتابة TokenProvider باستخدام Azure Function. لاحظ أن 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، يمكنك البدء في استخدامه لإنشاء أو تحميل حاويات Fluid!

موفرو الرموز المميزة

AzureFunctionTokenProvider هو تنفيذ ITokenProvider يضمن عدم كشف سر مفتاح المستأجر في رمز المجموعة من جانب العميل. يأخذ AzureFunctionTokenProvider في عنوان URL لوظيفة Azure الملحقة /api/GetAzureToken جنبا إلى جنب مع كائن المستخدم الحالي. في وقت لاحق، فإنه يقدم GET طلبا إلى وظيفة Azure الخاصة بك عن طريق تمرير في tenantId، 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 تعرض واجهة برمجة التطبيقات وظائف 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() الاستدعاء هو عندما تصبح الحاوية متصلة بالفعل بالخدمة ويتم تسجيلها في تخزين الكائن الثنائي كبير الحجم الخاص بها. يقوم بإرجاع id هذا هو المعرف الفريد لمثيل الحاوية هذا.

يحتاج أي عميل يريد الانضمام إلى نفس الجلسة التعاونية إلى الاتصال getContainer بنفس الحاوية id.

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

لمزيد من المعلومات حول كيفية بدء تسجيل السجلات التي يتم إرسالها بواسطة Fluid، راجع التسجيل وبيانات تتبع الاستخدام.

ستحتفظ الحاوية التي يتم إحضارها مرة أخرى كما initialObjects هو محدد في مخطط الحاوية. راجع نمذجة البيانات على fluidframework.com لمعرفة المزيد حول كيفية إنشاء المخطط واستخدام container العنصر.

الحصول على تفاصيل الجمهور

يستدعي قيمتين createContainer وإرجاعهما getContainer : container -- الموضحة أعلاه -- وعنصر الخدمات.

container يحتوي على نموذج بيانات Fluid وهو غير محدد للخدمة. أي تعليمة برمجية تكتبها مقابل كائن الحاوية AzureClient هذا الذي تم إرجاعه بواسطة قابل لإعادة الاستخدام مع العميل لخدمة أخرى. مثال على ذلك هو إذا قمت بنموذج أولي للسيناريو الخاص بك باستخدام TinyliciousClient، فيمكن إعادة استخدام جميع التعليمات البرمجية التي تتفاعل مع الكائنات المشتركة داخل حاوية Fluid عند الانتقال إلى استخدام AzureClient.

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 سيتم إطلاق أي تغييرات في القائمة، بينما memberAddedmemberRemoved سيتم إطلاق التغييرات الخاصة بكل منها مع 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" لديه حاليا الحاوية مفتوحة من عميلين مختلفين. تتطابق القيم الموجودة في حقل additionalDetails مع القيم المتوفرة AzureFunctionTokenProvider في إنشاء الرمز المميز.

يمكن دمج هذه الدالات والأحداث لتقديم عرض في الوقت الحقيقي للمستخدمين في جلسة العمل الحالية.

تهانينا! لقد نجحت الآن في توصيل حاوية Fluid بخدمة Azure Fluid Relay وجلبت تفاصيل المستخدم للأعضاء في جلسة العمل التعاونية الخاصة بك!