Integrieren mehrerer Ressourcen für den plastischen Reader

In der Übersicht haben Sie gelernt, was Immersive Reader ist und wie der Dienst bewährte Techniken implementiert, um das Leseverständnis von Sprachschülern, Leseanfängern und Schülern mit Lernschwierigkeiten zu verbessern. Im Schnellstart haben Sie erfahren, wie Sie das Tool „Plastischer Reader“ mit einer einzelnen Ressource verwenden. In diesem Tutorial wird erläutert, wie Sie mehrere Ressourcen des plastischen Readers in dieselbe Anwendung integrieren.

In diesem Tutorial lernen Sie Folgendes:

  • Erstellen von mehreren Immersive Reader-Ressourcen unter einer vorhandenen Ressourcengruppe.
  • Starten von Immersive Reader unter Verwendung mehrerer Ressourcen.

Voraussetzungen

  • Ein Azure-Abonnement. Falls Sie nicht über eine Subscription verfügen, können Sie ein kostenloses Konto erstellen.
  • Eine einzelne Immersive Reader-Ressource, die für die Microsoft Entra-Authentifizierung konfiguriert ist. Befolgen Sie diese Anweisungen für die Einrichtung.
  • NodeJS-Web-App zum Starten von Immersive Reader

Erstellen mehrerer Ressourcen

Befolgen Sie erneut diese Anweisungen, um die einzelnen Immersive Reader-Ressourcen zu erstellen. Das Skript Create-ImmersiveReaderResource enthält ResourceName, ResourceSubdomain und ResourceLocation als Parameter. Diese Parameter müssen für jede erstellte Ressource eindeutig sein. Die übrigen Parameter sollten mit denen identisch sein, die Sie beim Einrichten der ersten Ressource für den plastischen Reader verwendet haben. Auf diese Weise kann jede Ressource mit derselben Azure-Ressourcengruppe und derselben Microsoft Entra-Anwendung verknüpft werden.

Im folgenden Beispiel wird gezeigt, wie zwei Ressourcen erstellt werden: eine in der Region „WestUS und eine in der Region EastUS. Jede Ressource verfügt über eindeutige Werte für ResourceName, ResourceSubdomain und 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>

Hinzufügen von Ressourcen zur Umgebungskonfiguration

In der Schnellstartanleitung haben Sie eine Umgebungskonfigurationsdatei mit den Parametern TenantId, ClientId, ClientSecret und Subdomain erstellt. Da Ihre sämtlichen Ressourcen dieselbe Microsoft Entra-Anwendung verwenden, können Sie für TenantId, ClientId und ClientSecret dieselben Werte angeben. Die einzige Änderung, die vorgenommen werden muss, besteht in der Auflistung aller Unterdomänen für die einzelnen Ressourcen.

Ihre neue Datei vom Typ .env sollte in etwa wie folgt aussehen:

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}

Hinweis

Stellen Sie sicher, dass Sie diese Datei nicht in die Quellcodeverwaltung committen, da sie Geheimnisse enthält, die nicht veröffentlicht werden sollten.

Als Nächstes ändern Sie die Datei routes\index.js, die Sie zur Unterstützung mehrerer Ressourcen erstellt haben. Ersetzen Sie ihren Inhalt durch den folgenden Code.

Wie zuvor erstellt dieser Code einen API-Endpunkt, der unter Verwendung Ihres Dienstprinzipalkennworts ein Microsoft Entra-Authentifizierungstoken bezieht. Dieses Mal kann der Benutzer einen Ressourcenspeicherort angeben und als Abfrageparameter übergeben. Anschließend wird ein Objekt zurückgegeben, das das Token und die entsprechende Unterdomäne enthält.

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;

Der API-Endpunkt getimmersivereaderlaunchparams muss durch Authentifizierung (beispielsweise OAuth) geschützt werden, um zu verhindern, dass nicht autorisierte Benutzer Token abrufen und für Ihren Immersive Reader-Dienst bzw. für die Abrechnung verwenden. Dies wird jedoch in diesem Tutorial nicht behandelt.

Hinzufügen von Beispielinhalten

Öffnen Sie die Datei views\index.pug, und ersetzen Sie ihren Inhalt durch den folgenden Code. Dieser Code füllt die Seite mit Beispielinhalten und fügt zwei Schaltflächen zum Starten von Immersive Reader hinzu: Eine zum Starten von Immersive Reader für die EastUS-Ressource und eine weitere für die WestUS-Ressource.

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.");
    }

Die Web-App ist nun bereit. Führen Sie den folgenden Befehl aus, um die App zu starten:

npm start

Navigieren Sie in Ihrem Browser zu http://localhost:3000. Auf der Seite sollte der oben angegebene Inhalt angezeigt werden. Wählen Sie entweder die Schaltfläche für den Immersive Reader in EastUS oder die Schaltfläche für den Immersive Reader in WestUS aus, um den Immersive Reader mit den jeweiligen Ressourcen zu starten.

Nächster Schritt