여러 몰입형 판독기 리소스 통합

아티클
10/16/2024

개요에서는 몰입형 리더란 무엇이며 언어 학습자, 초보 독자와 학습 차이가 있는 학생의 독해력 향상을 위해 입증된 기술을 어떻게 구현하는지를 알아보았습니다. 이 빠른 시작에서는 단일 리소스를 사용하여 몰입형 리더를 사용하는 방법을 알아보았습니다. 이 자습서에서는 여러 개의 몰입형 판독기 리소스를 같은 애플리케이션에 통합하는 방법에 대해 설명합니다.

이 자습서에서는 다음을 하는 방법을 알아볼 수 있습니다.

기존 리소스 그룹에 여러 몰입형 리더 리소스 만들기
여러 리소스를 사용하여 몰입형 리더 시작

필수 구성 요소

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 파일을 수정합니다. 해당 콘텐츠를 다음 코드로 바꿉니다.

이전처럼 이 코드는 서비스 사용자 암호를 사용하여 Microsoft Entra 인증 토큰을 획득하는 API 엔드포인트를 만듭니다. 이번에는 사용자가 리소스 위치를 지정하고 이를 쿼리 매개 변수로 전달하도록 허용합니다. 그런 다음, 토큰과 해당하는 하위 도메인을 포함하는 개체를 반환합니다.

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 몰입형 판독기 단추를 선택하여 해당 리소스를 사용하여 몰입형 판독기를 시작합니다.

다음 단계

Immersive Reader SDK 살펴보기

다음을 통해 공유