如何啟動沉浸式閱讀程式
在概觀 中 ,您已瞭解沉浸式閱讀程式是什麼,以及如何實作經過實證的技術,以改善語言學習者、新興讀者和具有學習差異的學生閱讀理解。 本文示範如何啟動 沉浸式閱讀程式 JavaScript、Python、Android 或 iOS。
必要條件
- Azure 訂用帳戶 - 免費建立一個訂用帳戶
- 針對 Microsoft Entra 驗證設定沉浸式閱讀程式資源。 請遵循 這些指示 來設定。 設定環境屬性時,您將需要在這裡建立的一些值。 將會話的輸出儲存至文字檔,以供日後參考。
- Node.js 和 Yarn
- IDE,例如 Visual Studio Code
使用 Express 建立 Node.js Web 應用程式
使用 express-generator
工具建立 Node.js Web 應用程式。
npm install express-generator -g
express --view=pug myapp
cd myapp
安裝 yarn 相依性,並新增相依性和 request
dotenv
,稍後將在教學課程中使用。
yarn
yarn add request
yarn add dotenv
取得 Microsoft Entra 驗證權杖
接下來,撰寫後端 API 以擷取 Microsoft Entra 驗證權杖。
您需要上述 Microsoft Entra 驗證設定必要步驟中的一些值,才能完成此部分。 回到您儲存該會話的文字檔。
TenantId => Azure subscription TenantId
ClientId => Azure AD ApplicationId
ClientSecret => Azure AD Application Service Principal password
Subdomain => Immersive Reader resource subdomain (resource 'Name' if the resource was created in the Azure portal, or 'CustomSubDomain' option if the resource was created with Azure CLI PowerShell. Check the Azure portal for the subdomain on the Endpoint in the resource Overview page, for example, 'https://[SUBDOMAIN].cognitiveservices.azure.com/')
取得這些值之後,請建立名為 .env 的新檔案,並將下列程式碼貼入其中,並提供上述自訂屬性值。 請勿包含引號或 「{」 和 「}」 字元。
TENANT_ID={YOUR_TENANT_ID}
CLIENT_ID={YOUR_CLIENT_ID}
CLIENT_SECRET={YOUR_CLIENT_SECRET}
SUBDOMAIN={YOUR_SUBDOMAIN}
請務必不要將此檔案認可至原始檔控制,因為它包含不應公開的秘密。
接下來,開啟 app.js ,並將下列內容新增至檔案頂端。 這會將 .env 檔案中定義的屬性當做環境變數載入 Node。
require('dotenv').config();
開啟 routes\index.js 檔案,並將其內容取代為下列程式碼。
此程式碼會建立 API 端點,以使用您的服務主體密碼取得 Microsoft Entra 驗證權杖。 它也會擷取子域。 然後,它會傳回包含權杖和子域的物件。
var request = require('request');
var express = require('express');
var router = express.Router();
router.get('/getimmersivereaderlaunchparams', function(req, res) {
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, tokenResponse) {
if (err) {
return res.status(500).send('CogSvcs IssueToken error');
}
const token = JSON.parse(tokenResponse).access_token;
const subdomain = process.env.SUBDOMAIN;
return res.send({token: token, subdomain: subdomain});
}
);
});
/* GET home page. */
router.get('/', function(req, res, next) {
res.render('index', { title: 'Express' });
});
module.exports = router;
getimmersivereaderlaunchparams API 端點應受到某種形式的驗證保護,以防止 未經授權的使用者取得權杖以用於您的沉浸式閱讀程式服務和計費;該工作超出本教學課程的範圍。
使用範例內容啟動沉浸式閱讀程式
開啟 views\layout.pug ,並在 標記之前
body
,于 標籤底下head
新增下列程式碼。 這些script
標籤會 載入沉浸式閱讀程式 SDK 和 jQuery。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')
開啟 views\index.pug ,並以下列程式碼取代其內容。 此程式碼會以一些範例內容填入頁面,並新增啟動沉浸式閱讀程式的按鈕。
extends layout block content h2(id='title') Geography p(id='content') The study of Earth's landforms is called physical geography. Landforms can be mountains and valleys. They can also be glaciers, lakes or rivers. div(class='immersive-reader-button' data-button-style='iconAndText' data-locale='en-US' onclick='launchImmersiveReader()') script. function getImmersiveReaderLaunchParamsAsync() { return new Promise((resolve, reject) => { $.ajax({ url: '/getimmersivereaderlaunchparams', type: 'GET', success: data => { resolve(data); }, error: err => { console.log('Error in getting token and subdomain!', err); reject(err); } }); }); } async function launchImmersiveReader() { const content = { title: document.getElementById('title').innerText, chunks: [{ content: document.getElementById('content').innerText + '\n\n', lang: 'en' }] }; const launchParams = await getImmersiveReaderLaunchParamsAsync(); const token = launchParams.token; const subdomain = launchParams.subdomain; ImmersiveReader.launchAsync(token, subdomain, content); }
我們的 Web 應用程式現已就緒。 執行下列命令以啟動應用程式:
npm start
請開啟瀏覽器,然後瀏覽至 http://localhost:3000。 您應該會在頁面上看到上述內容。 選取 [沈浸式閱讀程式] 按鈕,將您的內容以沈浸式閱讀程式啟動。
指定內容的語言
沉浸式閱讀程式支援許多不同的語言。 您可以遵循下列步驟來指定內容的語言。
開啟 views\index.pug ,並在您在上一個步驟中新增的
p(id=content)
標記下方新增下列程式碼。 此程式碼會將一些西班牙文內容新增至您的頁面。p(id='content-spanish') El estudio de las formas terrestres de la Tierra se llama geografía física. Los accidentes geográficos pueden ser montañas y valles. También pueden ser glaciares, lagos o ríos.
在 JavaScript 程式碼中,將下列內容新增至
ImmersiveReader.launchAsync
的呼叫上方。 此程式碼會將西班牙文內容傳遞至沉浸式閱讀程式。content.chunks.push({ content: document.getElementById('content-spanish').innerText + '\n\n', lang: 'es' });
再次流覽至 http://localhost:3000 。 您應該會在頁面上看到西班牙文文字,當您選取 [沈浸式閱讀程式],它也會顯示在沈浸式閱讀程式中。
指定沉浸式閱讀程式介面的語言
根據預設,沉浸式閱讀程式介面的語言符合瀏覽器的語言設定。 您也可以使用下列程式碼指定沉浸式閱讀程式介面的語言。
在 views\index.pug 中,以下列程式碼取代 對
ImmersiveReader.launchAsync(token, subdomain, content)
的呼叫。const options = { uiLang: 'fr', } ImmersiveReader.launchAsync(token, subdomain, content, options);
瀏覽至 http://localhost:3000。 當您啟動沉浸式閱讀程式時,介面將會以法文顯示。
使用數學內容啟動沉浸式閱讀程式
您可以使用 MathML 在沉浸式閱讀程式 中包含數學內容。
修改 views\index.pug ,以在 呼叫
ImmersiveReader.launchAsync
上方包含下列程式碼:const mathML = '<math xmlns="https://www.w3.org/1998/Math/MathML" display="block"> \ <munderover> \ <mo>∫</mo> \ <mn>0</mn> \ <mn>1</mn> \ </munderover> \ <mrow> \ <msup> \ <mi>x</mi> \ <mn>2</mn> \ </msup> \ <mo>ⅆ</mo> \ <mi>x</mi> \ </mrow> \ </math>'; content.chunks.push({ content: mathML, mimeType: 'application/mathml+xml' });
瀏覽至 http://localhost:3000。 當您啟動沉浸式閱讀程式並捲動到底部時,您會看到數學公式。
下一步
- 探索 沉浸式閱讀程式 SDK 和 沉浸式閱讀程式 SDK 參考
- 在 GitHub 上 檢視程式碼範例
必要條件
- Azure 訂用帳戶 - 免費建立一個訂用帳戶
- 針對 Microsoft Entra 驗證設定沉浸式閱讀程式資源。 請遵循 這些指示 來設定。 設定環境屬性時,您將需要在這裡建立的一些值。 將會話的輸出儲存至文字檔,以供日後參考。
- Git。
- 沉浸式閱讀程式 SDK 。
- Python 和 pip 。 從 Python 3.4 開始,pip 預設會隨附于 Python 二進位安裝程式中。
- Flask 。
- 金賈
- 適用于 Windows 的 virtualenv 和 virtualenvwrapper-win 或 OSX 的 virtualenvwrapper。
- 要求模組 。
- IDE,例如 Visual Studio Code 。
設定驗證認證
建立名為 .env 的新檔案,並將下列名稱和值貼入其中。 提供您在建立沉浸式閱讀程式資源時所提供的值。
TENANT_ID={YOUR_TENANT_ID}
CLIENT_ID={YOUR_CLIENT_ID}
CLIENT_SECRET={YOUR_CLIENT_SECRET}
SUBDOMAIN={YOUR_SUBDOMAIN}
請勿將此檔案認可至原始檔控制,因為它包含不應公開的秘密。
例如, 在某種形式的驗證後方保護 getimmersivereadertoken API 端點,例如 OAuth 。 驗證可防止未經授權的使用者取得權杖,以用於您的沉浸式閱讀程式服務和計費。 這項工作超出本教學課程的範圍。
在 Windows 上建立 Python Web 應用程式
在 flask
Windows 上使用 建立 Python Web 應用程式。
安裝 Git。
安裝 Git 之後,請開啟命令提示字元,並將 沉浸式閱讀程式 SDK Git 存放庫複製到您電腦上的資料夾。
git clone https://github.com/microsoft/immersive-reader-sdk.git
安裝 Python 。
選取 [ 將 Python 新增至 PATH ] 核取方塊。
選取核取方塊以新增 選擇性功能 ,然後選取 [ 下一步 ]。
選取 [ 自訂安裝 ],並將安裝路徑設定為根資料夾,例如 C:\Python37-32\
。 然後選取 [安裝]。
Python 安裝完成之後,請開啟命令提示字元,並使用 cd
移至 [Python 腳本] 資料夾。
cd C:\Python37-32\Scripts
安裝 Flask。
pip install flask
安裝 Jinja2。 它是適用于 Python 的完整範本引擎。
pip install jinja2
安裝 virtualenv。 此工具會建立隔離的 Python 環境。
pip install virtualenv
安裝 virtualenvwrapper-win。 virtualenvwrapper 背後的概念是簡化 virtualenv 的使用。
pip install virtualenvwrapper-win
安裝要求模組。 要求是以 Python 撰寫的 Apache2 授權 HTTP 程式庫。
pip install requests
安裝 python-dotenv 模組。 此模組會從 .env 檔案讀取機碼/值組,並將其新增至環境變數。
pip install python-dotenv
建立虛擬環境。
mkvirtualenv advanced-python
使用 cd
移至範例專案根資料夾。
cd C:\immersive-reader-sdk\js\samples\advanced-python
使用環境連線範例專案。 此動作會將新建立的虛擬環境對應至範例專案根資料夾。
setprojectdir .
啟動虛擬環境。
activate
專案現在應該使用中,而且您會在命令提示字元中看到類似的內容 (advanced-python) C:\immersive-reader-sdk\js\samples\advanced-python>
。
停用環境。
deactivate
前置 (advanced-python)
詞應該消失,因為環境已停用。
若要重新啟用環境,請從範例專案根資料夾執行 workon advanced-python
。
workon advanced-python
使用範例內容啟動沉浸式閱讀程式
當環境處於使用中狀態時,請從範例專案根資料夾輸入 flask run
來執行範例專案。
flask run
開啟瀏覽器並移至 http://localhost:5000.
在 OSX 上建立 Python Web 應用程式
在 flask
OSX 上使用 建立 Python Web 應用程式。
安裝 Git。
安裝 Git 之後,請開啟終端機,並將沉浸式閱讀程式 SDK Git 存放庫複製到您電腦上的資料夾。
git clone https://github.com/microsoft/immersive-reader-sdk.git
安裝 Python 。
例如, Python37-32
Python 根資料夾現在應該位於 [應用程式] 資料夾中。
完成 Python 安裝之後,開啟 [終端機],並使用 cd
移至 [Python 腳本] 資料夾。
cd immersive-reader-sdk/js/samples/advanced-python
安裝 pip。
curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
執行下列程式碼,為目前登入的使用者安裝 pip,以避免許可權問題。
python get-pip.py --user
sudo nano /etc/paths
- 出現提示時,輸入您的密碼。
- 將 pip 安裝的路徑新增至 PATH 變數。
- 移至檔案底部,然後輸入您要新增為清單最後一個專案的路徑,例如
PATH=$PATH:/usr/local/bin
。 - 選取 CTRL+X 以結束。
- 輸入 Y 以儲存修改過的緩衝區。
- 介紹完畢 若要測試它,請在新的 [終端機] 視窗中輸入
echo $PATH
。
安裝 Flask。
pip install flask --user
安裝 Jinja2。 它是適用于 Python 的完整範本引擎。
pip install Jinja2 --user
安裝 virtualenv。 此工具會建立隔離的 Python 環境。
pip install virtualenv --user
安裝 virtualenvwrapper。 virtualenvwrapper 背後的概念是簡化 virtualenv 的使用。
pip install virtualenvwrapper --user
安裝要求模組。 要求是以 Python 撰寫的 Apache2 授權 HTTP 程式庫。
pip install requests --user
安裝 python-dotenv 模組。 此模組會從 .env 檔案讀取機碼/值組,並將其新增至環境變數。
pip install python-dotenv --user
選擇您要保留虛擬環境的資料夾,然後執行此命令:
mkdir ~/.virtualenvs
使用 cd
移至 沉浸式閱讀程式 SDK Python 範例應用程式資料夾。
cd immersive-reader-sdk/js/samples/advanced-python
建立虛擬環境。
mkvirtualenv -p /usr/local/bin/python3 advanced-python
使用環境連線範例專案。 此動作會將新建立的虛擬環境對應至範例專案根資料夾。
setprojectdir .
啟動虛擬環境。
activate
專案現在應該使用中,而且您會在命令提示字元中看到類似的內容 (advanced-python) /immersive-reader-sdk/js/samples/advanced-python>
。
停用環境。
deactivate
前置 (advanced-python)
詞應該消失,因為環境已停用。
若要重新啟用環境,請從範例專案根資料夾執行 workon advanced-python
。
workon advanced-python
使用範例內容啟動沉浸式閱讀程式
當環境處於使用中狀態時,請從範例專案根資料夾輸入 flask run
來執行範例專案。
flask run
開啟瀏覽器並移至 http://localhost:5000.
下一步
- 探索 沉浸式閱讀程式 SDK 和 沉浸式閱讀程式 SDK 參考 。
- 在 GitHub 上 檢視程式碼範例。
必要條件
- Azure 訂用帳戶 - 免費建立一個訂用帳戶
- 針對 Microsoft Entra 驗證設定沉浸式閱讀程式資源。 請遵循 這些指示 來設定。 設定環境屬性時,您將需要在這裡建立的一些值。 將會話的輸出儲存至文字檔,以供日後參考。
- Git。
- 沉浸式閱讀程式 SDK 。
- Android Studio 。
設定驗證認證
啟動 Android Studio,然後從 沈浸式閱讀程式 sdk/js/samples/quickstart-java-android 目錄 (JAVA) 或 沈浸式閱讀程式-sdk/js/samples/quickstart-kotlin 目錄 (Kotlin ) 開啟專案。
在 /assets 資料夾內建立名為 env 的 檔案。 新增下列名稱和值,並視需要提供值。 請勿將此檔案認可至原始檔控制,因為它包含不應公開的秘密。
TENANT_ID=<YOUR_TENANT_ID> CLIENT_ID=<YOUR_CLIENT_ID> CLIENT_SECRET=<YOUR_CLIENT_SECRET> SUBDOMAIN=<YOUR_SUBDOMAIN>
使用範例內容啟動沉浸式閱讀程式
從 AVD 管理員選擇裝置模擬器,然後執行專案。
下一步
- 探索 沉浸式閱讀程式 SDK 和 沉浸式閱讀程式 SDK 參考 。
- 在 GitHub 上 檢視程式碼範例。
必要條件
- Azure 訂用帳戶 - 免費建立一個訂用帳戶
- 針對 Microsoft Entra 驗證設定沉浸式閱讀程式資源。 請遵循 這些指示 來設定。 設定環境屬性時,您將需要在這裡建立的一些值。 將會話的輸出儲存至文字檔,以供日後參考。
- macOS。
- Git。
- 沉浸式閱讀程式 SDK 。
- Xcode 。
設定驗證認證
開啟 Xcode,並開啟 沈浸式閱讀程式-sdk/js/samples/ios/quickstart-swift/quickstart-swift.xcodeproj 。
在頂端功能表上,選取 [產品 > 配置編輯配置]。 >
在 [ 執行 ] 檢視中,選取 [ 引數] 索引標籤 。
在 [ 環境變數] 區段中,新增下列名稱和值。 提供您在建立沉浸式閱讀程式資源時所提供的值。
TENANT_ID=<YOUR_TENANT_ID> CLIENT_ID=<YOUR_CLIENT_ID> CLIENT_SECRET<YOUR_CLIENT_SECRET> SUBDOMAIN=<YOUR_SUBDOMAIN>
請勿將此變更認可至原始檔控制,因為它包含不應公開的秘密。
使用範例內容啟動沉浸式閱讀程式
在 Xcode 中,選取 Ctrl+R 以執行專案。
下一步
- 探索 沉浸式閱讀程式 SDK 和 沉浸式閱讀程式 SDK 參考 。
- 在 GitHub 上 檢視程式碼範例。