Интеграция нескольких ресурсов иммерсивного средства чтения

Статья
02.09.2024

В обзоре вы узнали о Иммерсивное средство чтения и о том, как он реализует проверенные методы для улучшения понимания чтения для учащихся языка, новых читателей и учащихся с различиями в обучении. В кратком руководстве вы узнали, как использовать иммерсивное средство чтения, применяя один ресурс. В этом учебнике описано, как интегрировать несколько ресурсов иммерсивного средства чтения в одном приложении.

В этом руководстве описано следующее:

Создайте несколько Иммерсивное средство чтения ресурсов в существующей группе ресурсов.
Запустите Иммерсивное средство чтения с помощью нескольких ресурсов.

Необходимые компоненты

Подписка Azure. Если ее нет, создайте бесплатную учетную запись.
Один ресурс Иммерсивное средство чтения, настроенный для проверки подлинности Microsoft Entra. Инструкции по настройке см. здесь.
Веб-приложение NodeJS, которое запускает Иммерсивное средство чтения.

Создание нескольких ресурсов

Следуйте этим инструкциям еще раз, чтобы создать каждый Иммерсивное средство чтения ресурс. Скрипт Create-ImmersiveReaderResource имеет и ResourceSubdomainResourceLocation в ResourceNameкачестве параметров. Эти параметры должны быть уникальными для каждого создаваемого ресурса. Остальные параметры должны совпадать с параметрами, которые использовались при настройке первого ресурса иммерсивного средства чтения. Таким образом, каждый ресурс можно связать с одной группой ресурсов 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 Конечная точка API должна быть защищена за какой-то формой проверки подлинности (например, 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 для Иммерсивное средство чтения

The future is yours

Поделиться через