Integrar vários recursos da Leitura Avançada
Na visão geral, você aprendeu sobre a Leitura Avançada e como ela implementa técnicas comprovadas para aprimorar a compreensão de leitura para aprendizes do idioma, leitores emergentes e estudantes com diferenças de aprendizado. No guia de início rápido, você aprendeu a usar a Leitura Avançada com apenas um recurso. Este tutorial aborda como integrar vários recursos da Leitura Avançada no mesmo aplicativo.
Neste tutorial, você aprenderá a:
- Criar vários recursos da Leitura Avançada em um grupo de recursos existente.
- Iniciar a Leitura Avançada usando vários recursos.
Pré-requisitos
- Uma assinatura do Azure. Crie uma conta gratuita se ainda não tiver a sua.
- Um recurso de Leitura Avançada configurado para autenticação do Microsoft Entra. Siga estas instruções para a configuração.
- Um aplicativo Web NodeJS que inicia a Leitura Avançada.
Criar vários recursos
Siga estas instruções novamente para criar cada recurso da Leitura Avançada. O script Create-ImmersiveReaderResource tem ResourceName, ResourceSubdomain e ResourceLocation como parâmetros. Esses parâmetros devem ser exclusivos para cada recurso que está sendo criado. Os parâmetros restantes devem ser iguais aos que você usou ao configurar seu primeiro recurso da Leitura Avançada. Dessa forma, os recursos podem ser vinculados ao mesmo grupo de recursos do Azure e ao aplicativo Microsoft Entra.
O exemplo a seguir mostra como criar dois recursos, um na região WestUS e outro na região EastUS. Cada recurso tem valores exclusivos para ResourceName, ResourceSubdomain e 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>
Adicionar recursos à configuração do ambiente
No guia de início rápido, você criou um arquivo de configuração de ambiente que contém os parâmetros TenantId, ClientId, ClientSecret e Subdomain. Como todos os seus recursos usam o mesmo aplicativo Microsoft Entra, podemos usar os mesmos valores para TenantId, ClientId e ClientSecret. A única alteração que precisa ser feita é listar cada subdomínio de cada recurso.
O novo arquivo .env agora deve ser semelhante ao seguinte:
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}
Observação
Não faça commit desse arquivo no controle do código-fonte, pois ele contém segredos que não devem ser disponibilizados publicamente.
Em seguida, modifique o arquivo routes\index.js que você criou para dar suporte a nossos vários recursos. Substitua o conteúdo dele pelo código a seguir.
Como antes, esse código cria um ponto de extremidade de API que adquire um token de autenticação do Microsoft Entra usando sua senha de entidade de serviço. Desta vez, ele permite que o usuário especifique uma localização para o recurso e o passe como um parâmetro de consulta. Em seguida, ele retorna um objeto que contém o token e o subdomínio correspondente.
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;
O ponto de extremidade da API getimmersivereaderlaunchparams deve ser protegido por alguma forma de autenticação (por exemplo, OAuth) para impedir que usuários não autorizados obtenham tokens para usar em seu serviço de Leitura Avançada e cobrança; esse trabalho está além do escopo deste tutorial.
Adicionar o conteúdo de exemplo
Abra views\index.pug e substitua o conteúdo pelo código a seguir. Esse código preenche a página com conteúdo de exemplo e adiciona dois botões que iniciam a Leitura Avançada. Um para iniciar a Leitura Avançada para o recurso na região EastUS e outro para o recurso na região 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.");
}
Seu aplicativo Web está pronto. Inicie o aplicativo executando:
npm start
Abra o navegador e navegue até http://localhost:3000. Veja o conteúdo acima na página. Clique no botão da Leitura Avançada no EastUS ou no botão da Leitura Avançada no WestUS para iniciar a Leitura Avançada usando esses recursos respectivos.