تكامل موارد القارئ الشامل المتعددة

مقالة
03/05/2024

في النظرة العامة، تعرفت على القارئ الشامل وكيفية تنفيذ التقنيات المثبتة لتحسين فهم القراءة لمتعلمي اللغة والقراء الناشئين والطلاب الذين لديهم اختلافات في التعلم. في التشغيل السريع، تعرفت على كيفية استخدام القارئ الشامل مع مورد واحد. يغطي هذا البرنامج التعليمي كيفية دمج موارد القارئ الشامل المتعددة في نفس التطبيق.

في هذا البرنامج التعليمي، تتعلم كيفية:

إنشاء مورد القارئ الشامل متعدد ضمن مجموعة موارد موجودة.
قم بتشغيل القارئ الشامل باستخدام موارد متعددة.

المتطلبات الأساسية

اشتراك Azure. في حال لم يكن لديك اشتراك Azure، أنشئ حسابًا مجّانيًّا.
مورد القارئ الشامل واحد تم تكوينه لمصادقة Microsoft Entra. اتبع هذه التعليمات لضبط الإعدادات.
تطبيق ويب NodeJS الذي يقوم بتشغيل القارئ الشامل.

إنشاء موارد متعددة

اتبع هذه الإرشادات مرة أخرى لإنشاء كل مورد القارئ الشامل. يحتوي Create-ImmersiveReaderResource البرنامج النصي على ResourceNameو ResourceSubdomainو ResourceLocation كمعلمات. يجب أن تكون هذه المعلمات فريدة لكل مورد يتم إنشاؤه. يجب أن تكون المعلمات المتبقية هي نفسها التي استخدمتها عند إعداد مورد القارئ الشامل الأول. بهذه الطريقة، يمكن ربط كل مورد بنفس مجموعة موارد Azure وتطبيق Microsoft Entra.

يوضح المثال التالي كيفية إنشاء موردين، أحدهما في WestUS والآخر في EastUS. يحتوي كل مورد على قيم فريدة ل ResourceNameو ResourceSubdomainو.ResourceLocation

Create-ImmersiveReaderResource
  -SubscriptionName <SUBSCRIPTION_NAME>
  -ResourceName Resource_name_westus
  -ResourceSubdomain resource-subdomain-westus
  -ResourceSKU <RESOURCE_SKU>
  -ResourceLocation westus
  -ResourceGroupName <RESOURCE_GROUP_NAME>
  -ResourceGroupLocation <RESOURCE_GROUP_LOCATION>
  -AADAppDisplayName <MICROSOFT_ENTRA_DISPLAY_NAME>
  -AADAppIdentifierUri <MICROSOFT_ENTRA_IDENTIFIER_URI>
  -AADAppClientSecret <MICROSOFT_ENTRA_CLIENT_SECRET>

Create-ImmersiveReaderResource
  -SubscriptionName <SUBSCRIPTION_NAME>
  -ResourceName Resource_name_eastus
  -ResourceSubdomain resource-subdomain-eastus
  -ResourceSKU <RESOURCE_SKU>
  -ResourceLocation eastus
  -ResourceGroupName <RESOURCE_GROUP_NAME>
  -ResourceGroupLocation <RESOURCE_GROUP_LOCATION>
  -AADAppDisplayName <MICROSOFT_ENTRA_DISPLAY_NAME>
  -AADAppIdentifierUri <MICROSOFT_ENTRA_IDENTIFIER_URI>
  -AADAppClientSecret <MICROSOFT_ENTRA_CLIENT_SECRET>

إضافة الموارد إلى تكوين البيئة

في التشغيل السريع، قمت بإنشاء ملف تكوين بيئة يحتوي على المعلمات TenantId وClientId وClientSecret وSubdomain. نظرا لأن جميع مواردك تستخدم نفس تطبيق Microsoft Entra، يمكنك استخدام نفس القيم ل TenantIdو ClientIdو.ClientSecret يتمثل التغيير الوحيد الذي يجب إجراؤه في سرد كل مجال فرعي لكل مورد.

يجب أن يبدو ملف .env الجديد الآن كما يلي:

TENANT_ID={YOUR_TENANT_ID}
CLIENT_ID={YOUR_CLIENT_ID}
CLIENT_SECRET={YOUR_CLIENT_SECRET}
SUBDOMAIN_WUS={YOUR_WESTUS_SUBDOMAIN}
SUBDOMAIN_EUS={YOUR_EASTUS_SUBDOMAIN}

إشعار

تأكد من عدم تثبيت هذا الملف في التحكم بالمصادر لأنه يحتوي على أسرار لا ينبغي الإعلان عنها.

بعد ذلك، قم بتعديل ملف routes\index.js الذي قمت بإنشائه لدعم مواردك المتعددة. استبدل محتوياته بالتعليمات البرمجية التالية.

كما كان الحال من قبل، تنشئ هذه التعليمة البرمجية نقطة نهاية API التي تحصل على رمز مصادقة Microsoft Entra باستخدام كلمة مرور كيان الخدمة. هذه المرة، تتيح للمستخدم تحديد موقع مورد وتمريره كمعلمة استعلام. ثم تعيد عنصر يحتوي على الرمز المميز والمجال الفرعي المقابل.

var express = require('express');
var router = express.Router();
var request = require('request');

/* GET home page. */
router.get('/', function(req, res, next) {
  res.render('index', { title: 'Express' });
});

router.get('/GetTokenAndSubdomain', function(req, res) {
    try {
        request.post({
            headers: {
                'content-type': 'application/x-www-form-urlencoded'
            },
            url: `https://login.windows.net/${process.env.TENANT_ID}/oauth2/token`,
            form: {
                grant_type: 'client_credentials',
                client_id: process.env.CLIENT_ID,
                client_secret: process.env.CLIENT_SECRET,
                resource: 'https://cognitiveservices.azure.com/'
            }
        },
        function(err, resp, tokenResult) {
            if (err) {
                console.log(err);
                return res.status(500).send('CogSvcs IssueToken error');
            }

            var tokenResultParsed = JSON.parse(tokenResult);

            if (tokenResultParsed.error) {
                console.log(tokenResult);
                return res.send({error :  "Unable to acquire Azure AD token. Check the debugger for more information."})
            }

            var token = tokenResultParsed.access_token;

            var subdomain = "";
            var region = req.query && req.query.region;
            switch (region) {
                case "eus":
                    subdomain = process.env.SUBDOMAIN_EUS
                    break;
                case "wus":
                default:
                    subdomain = process.env.SUBDOMAIN_WUS
            }

            return res.send({token, subdomain});
        });
    } catch (err) {
        console.log(err);
        return res.status(500).send('CogSvcs IssueToken error');
    }
});

module.exports = router;

getimmersivereaderlaunchparams يجب تأمين نقطة نهاية واجهة برمجة التطبيقات خلف شكل من أشكال المصادقة (على سبيل المثال، OAuth) لمنع المستخدمين غير المصرح لهم من الحصول على رموز مميزة لاستخدامها مقابل خدمة القارئ الشامل والفوترة؛ هذا العمل خارج نطاق هذا البرنامج التعليمي.

إضافة عينة من المحتوى

افتح views\index.pug، واستبدل محتواه بالتعليمات البرمجية التالية. تملأ هذه التعليمة البرمجية الصفحة ببعض نماذج المحتوى، وتضيف زرين لتشغيل القارئ الشامل. واحد يقوم بتشغيل القارئ الشامل لمورد EastUS، والآخر لمورد WestUS.

doctype html
html
    head
        title Immersive Reader Quickstart Node.js

        link(rel='stylesheet', href='https://stackpath.bootstrapcdn.com/bootstrap/3.4.1/css/bootstrap.min.css')

        // A polyfill for Promise is needed for IE11 support.
        script(src='https://cdn.jsdelivr.net/npm/promise-polyfill@8/dist/polyfill.min.js')

        script(src='https://ircdname.azureedge.net/immersivereadersdk/immersive-reader-sdk.1.2.0.js')
        script(src='https://code.jquery.com/jquery-3.3.1.min.js')

        style(type="text/css").
            .immersive-reader-button {
            background-color: white;
            margin-top: 5px;
            border: 1px solid black;
            float: right;
            }
    body
        div(class="container")
            button(class="immersive-reader-button" data-button-style="icon" data-locale="en" onclick='handleLaunchImmersiveReader("wus")') WestUS Immersive Reader
            button(class="immersive-reader-button" data-button-style="icon" data-locale="en" onclick='handleLaunchImmersiveReader("eus")') EastUS Immersive Reader

            h1(id="ir-title") About Immersive Reader
            div(id="ir-content" lang="en-us")
            p Immersive Reader is a tool that implements proven techniques to improve reading comprehension for emerging readers, language learners, and people with learning differences. The Immersive Reader is designed to make reading more accessible for everyone. The Immersive Reader

                ul
                    li Shows content in a minimal reading view
                    li Displays pictures of commonly used words
                    li Highlights nouns, verbs, adjectives, and adverbs
                    li Reads your content out loud to you
                    li Translates your content into another language
                    li Breaks down words into syllables

            h3 The Immersive Reader is available in many languages.

            p(lang="es-es") El Lector inmersivo está disponible en varios idiomas.
            p(lang="zh-cn") 沉浸式阅读器支持许多语言
            p(lang="de-de") Der plastische Reader ist in vielen Sprachen verfügbar.
            p(lang="ar-eg" dir="rtl" style="text-align:right") يتوفر \"القارئ الشامل\" في العديد من اللغات.

script(type="text/javascript").
function getTokenAndSubdomainAsync(region) {
        return new Promise(function (resolve, reject) {
            $.ajax({
                url: "/GetTokenAndSubdomain",
                type: "GET",
                data: {
                    region: region
                },
                success: function (data) {
                    if (data.error) {
                        reject(data.error);
                    } else {
                        resolve(data);
                    }
                },
                error: function (err) {
                    reject(err);
                }
            });
        });
    }

    function handleLaunchImmersiveReader(region) {
        getTokenAndSubdomainAsync(region)
            .then(function (response) {
                const token = response["token"];
                const subdomain = response["subdomain"];
                // Learn more about chunk usage and supported MIME types https://learn.microsoft.com/azure/ai-services/immersive-reader/reference#chunk
                const data = {
                    title: $("#ir-title").text(),
                    chunks: [{
                        content: $("#ir-content").html(),
                        mimeType: "text/html"
                    }]
                };
                // Learn more about options https://learn.microsoft.com/azure/ai-services/immersive-reader/reference#options
                const options = {
                    "onExit": exitCallback,
                    "uiZIndex": 2000
                };
                ImmersiveReader.launchAsync(token, subdomain, data, options)
                    .catch(function (error) {
                        alert("Error in launching the Immersive Reader. Check the console.");
                        console.log(error);
                    });
            })
            .catch(function (error) {
                alert("Error in getting the Immersive Reader token and subdomain. Check the console.");
                console.log(error);
            });
    }

    function exitCallback() {
        console.log("This is the callback function. It is executed when the Immersive Reader closes.");
    }

تطبيق الويب الخاص بك جاهز الآن. ابدأ التطبيق عن طريق تشغيل:

npm start

افتح المستعرض وانتقل إلى http://localhost:3000. يجب أن تطلع على المحتوى أعلاه على الصفحة. حدد إما زر القارئ الشامل EastUS أو زر القارئ الشامل WestUS لتشغيل القارئ الشامل باستخدام تلك الموارد المعنية.

الخطوة التالية

استكشاف القارئ الشامل SDK

Share via