DCV first connection

` HTML 要素を、Amazon DCV ウェブクライアント SDK で Amazon DCV サーバーからコンテンツストリームを描画させる場所に追加する必要があります。例えば、次のようになります。 ``` DCV first connection

``` ## ステップ 2: 最初のフレームの認証、接続、取得を行うこのセクションでは、ユーザー認証プロセスを完了する方法、Amazon DCV サーバーを接続する方法、および Amazon DCV サーバーからコンテンツの最初のフレームを受信する方法について説明します。まず、`index.js` ファイルから Amazon DCV ウェブクライアント SDK をインポートします。以下のようにユニバーサルモジュール定義 (UMD) モジュールとしてインポートできます。 ``` import "./dcvjs/dcv.js" ``` または、バージョン `1.1.0` 以降の場合、以下のように対応するパッケージから ECMAScript モジュール (ESM) としてインポートすることもできます。 ``` import dcv from "./dcvjs/dcv.js" ``` 認証オブジェクト、接続オブジェクト、および Amazon DCV サーバー URL の保存に使用する変数を定義します。 ``` let auth, connection, serverUrl; ``` スクリプトのロード時に、Amazon DCV ウェブクライアント SDK のバージョンをログに記録し、ページのロード時に `main` 関数を呼び出します。 ``` console.log("Using Amazon DCV Web Client SDK version " + dcv.version.versionStr); document.addEventListener('DOMContentLoaded', main); ``` `main` 関数により、ログレベルの設定と認証プロセスの開始が実行されます。 ``` function main () { console.log("Setting log level to INFO"); dcv.setLogLevel(dcv.LogLevel.INFO); serverUrl = "https://your-dcv-server-url:port/"; console.log("Starting authentication with", serverUrl); auth = dcv.authenticate( serverUrl, { promptCredentials: onPromptCredentials, error: onError, success: onSuccess } ); } ``` `promptCredentials` 関数、`error` 関数、`success` 関数は、必須コールバック関数であり、認証プロセスで定義する必要があります。。 Amazon DCV サーバーから認証情報が要求された場合、`promptCredentials` コールバック関数に、Amazon DCV サーバーから要求された認証情報チャレンジが送られます。システム認証が使用されるように Amazon DCV サーバーが設定されている場合、認証情報を提供する必要があります。次のコードサンプルでは、仮に、ユーザー名を `my_dcv_user` 、パスワード `my_password` にしています。認証に失敗した場合、`error` コールバック関数に Amazon DCV サーバーからエラーオブジェクトが送られます。認証が成功すると、`success` コールバック関数に、`my_dcv_user` ユーザーが Amazon DCV サーバーに接続できる各セッションのセッション ID (`sessionId`) と認可トークン (`authToken`) が含まれているカップルの配列が送られます。次のコードサンプルでは、接続関数を呼び出して、配列で返された最初のセッションに接続します。 **注記** 以下のコード例では、`MY_DCV_USER` を自分のユーザー名に、`MY_PASSWORD` を自分のパスワードに置き換えてください。 ``` function onPromptCredentials(auth, challenge) { // Let's check if in challege we have a username and password request if (challengeHasField(challenge, "username") && challengeHasField(challenge, "password")) { auth.sendCredentials({username: MY_DCV_USER, password: MY_PASSWORD}) } else { // Challenge is requesting something else... } } function challengeHasField(challenge, field) { return challenge.requiredCredentials.some(credential => credential.name === field); } function onError(auth, error) { console.log("Error during the authentication: " + error.message); } // We connect to the first session returned function onSuccess(auth, result) { let {sessionId, authToken} = {...result[0]}; connect(sessionId, authToken); } ``` Amazon DCV サーバーに接続します。`firstFrame` コールバック関数は、Amazon DCV サーバーから最初のフレームが届いたときに呼び出されます。 ``` function connect (sessionId, authToken) { console.log(sessionId, authToken); dcv.connect({ url: serverUrl, sessionId: sessionId, authToken: authToken, divId: "dcv-display", callbacks: { firstFrame: () => console.log("First frame received") } }).then(function (conn) { console.log("Connection established!"); connection= conn; }).catch(function (error) { console.log("Connection failed with error " + error.message); }); } ``` ## ボーナス: HTML ログインフォームを自動的に作成する `challenge` オブジェクトは `promptCredentials` コールバック関数が呼び出されたときに返されます。これには、オブジェクトの配列である `requiredCredentials` という名前のプロパティが含まれています。Amazon DCV サーバーからリクエストされる認証情報 1 件につきオブジェクトは 1 つです。各オブジェクトには、リクエストされた認証情報の名前とタイプが含まれます。`challenge` オブジェクトと `requiredCredentials` オブジェクトを使用して、HTML ログインフォームを自動的に作成することができます。次のコードサンプルでは、その実行方法を説明しています。 ``` let form, fieldSet; function submitCredentials (e) { var credentials = {}; fieldSet.childNodes.forEach(input => credentials[input.id] = input.value); auth.sendCredentials(credentials); e.preventDefault(); } function createLoginForm () { var submitButton = document.createElement("button"); submitButton.type = "submit"; submitButton.textContent = "Login"; form = document.createElement("form"); fieldSet = document.createElement("fieldset"); form.onsubmit = submitCredentials; form.appendChild(fieldSet); form.appendChild(submitButton); document.body.appendChild(form); } function addInput (name) { var type = name === "password" ? "password" : "text"; var inputField = document.createElement("input"); inputField.name = name; inputField.id = name; inputField.placeholder = name; inputField.type = type; fieldSet.appendChild(inputField); } function onPromptCredentials (_, credentialsChallenge) { createLoginForm(); credentialsChallenge.requiredCredentials.forEach(challenge => addInput(challenge.name)); } ``` # Amazon DCV 機能の操作 Amazon DCV 機能の可用性は、Amazon DCV セッションに対して設定されたアクセス許可と、クライアントのウェブブラウザの機能に左右されます。 Amazon DCV セッションで使用できる機能は、そのセッションに対して指定されたアクセス許可によって管理されます。機能が Amazon DCV ウェブクライアント SDK でサポートされていても、セッション管理者が定義したアクセス許可に基づいて、その機能へのアクセスが妨げられることがあります。詳細については、「*Amazon DCV 管理者ガイド*」の「[Amazon DCV 認可の設定](https://docs.aws.amazon.com/dcv/latest/adminguide/security-authorization.html)」を参照してください。 ## FeatureUpdate コールバック関数について Amazon DCV セッションの機能の可用性が変わると、接続の確立時に指定した `featuresUpdate` コールバック関数により、Amazon DCV ウェブクライアント SDK から通知を受けます。例えば、次のようになります。 ``` featuresUpdate: function (connection, list) { ... }, ``` コールバック関数は、可用性が変化した機能のみを通知します。`list` パラメータは一連の文字列で、更新された機能の名前のみが含まれます。例えば、セッションでオーディオ入力機能の可用性が変化した場合、パラメータには `["audio-in"]` のみが含まれます。後に、セッションでクリップボードのコピー/貼り付け機能の可用性が変わった場合は、パラメータに `["clipboard-copy", "clipboard-paste"]` のみが含まれます。 ## 機能更新の処理 `featuresUpdate` コールバック関数は、可用性が変化した機能のみを通知します。どの機能が更新されたかを知るには、`connection.queryFeature` メソッドを使用して機能のクエリを行う必要があります。これは、変更通知の受信後にいつでも実行できます。このメソッドでは、解決を行う `Promise` が、リクエストされた機能の更新ステータスに返されます。`status` 値は常に関連付けられ、`enabled` というブール値 (`true`\$1`false`) プロパティを含みます。場合によっては、`status` 値に追加のプロパティがある機能もあります。機能の可用性が更新されていない場合は、拒否されます。次のコード例では、その実行方法を説明しています。 ``` // Connection callback called function featuresUpdate (_, list) { if (list.length > 0) { list.forEach((feat) => { connection.queryFeature(feat).then(status => console.log(feat, "is", status.enabled))); }); } } ``` # Amazon DCV ウェブ UI SDK の使用以下のチュートリアルでは、Amazon DCV サーバーに対して認証を行い、接続して Amazon DCV ウェブ UI SDK から `DCVViewer` React コンポーネントをレンダリングする方法を説明します。 **Topics** + [ ## 前提条件 ](#prerequisites) + [ ## ステップ 1: HTML ページを準備する ](#prep-html-ui) + [ ## ステップ 2: `DCVViewer` React コンポーネントの認証、接続、レンダリングを行う ](#auth-conn-render) + [ ## AWS-UI から Cloudscape Design System へのアップデート ](#updateawsuitocloudscape) ## 前提条件 `React`、`ReactDOM`、`Cloudscape Design Components React`、`Cloudscape Design Global Styles`、`Cloudscape Design Design Tokens` をインストールする必要があります。 ``` $ npm i react react-dom @cloudscape-design/components @cloudscape-design/global-styles @cloudscape-design/design-tokens ``` また、`Amazon DCV Web Client SDK` のダウンロードも必要になります。その手順については、「[Amazon DCV ウェブクライアント SDK の開始方法](getting-started.md)」のステップごとのガイドをご覧ください。 Amazon DCV ウェブ UI SDK の外部依存関係であるため、`dcv` モジュールをインポートするためのエイリアスを作成する必要があります。例えば、webpack を使用してウェブアプリケーションをバンドルする場合、以下のように [resolve.alias](https://webpack.js.org/configuration/resolve/#resolvealias) オプションを使用できます。 ``` const path = require('path'); module.exports = { //... resolve: { alias: { dcv: path.resolve('path', 'to', 'dcv.js'), }, }, }; ``` バンドルにロールアップを使用している場合は、[@rollup /plugin-alias](https://www.npmjs.com/package/@rollup/plugin-alias) をインストールして以下のように使用できます。 ``` import alias from '@rollup/plugin-alias'; const path = require('path'); module.exports = { //... plugins: [ alias({ entries: [ { find: 'dcv', replacement: path.resolve('path', 'to', 'dcv.js') }, ] }) ] }; ``` ## ステップ 1: HTML ページを準備するウェブページには、必要な JavaScript モジュールをロードする必要があります。また、アプリケーションのエントリコンポーネントがレンダリングされる、有効な `id` を持つ `

` HTML 要素が必要です。例えば、次のようになります。 ``` DCV first connection

``` ## ステップ 2: `DCVViewer` React コンポーネントの認証、接続、レンダリングを行うこのセクションでは、ユーザー認証プロセスを完了する方法、Amazon DCV サーバーを接続する方法、`DCVViewer` React コンポーネントをレンダリングする方法を説明します。まず、`index.js` ファイルから `React`、`ReactDOM`、および最上位の `App` コンポーネントをインポートします。 ``` import React from "react"; import ReactDOM from 'react-dom'; import App from './App'; ``` アプリケーションの最上位のコンテナノードをレンダリングします。 ``` ReactDOM.render( , document.getElementById("root") ); ``` `App.js` ファイルで、ESM モジュールとしての Amazon DCV ウェブクライアント SDK、Amazon DCV ウェブ UI SDK の `DCVViewer` React コンポーネント、`React` および `Cloudscape Design Global Styles` パッケージをインポートします。 ``` import React from "react"; import dcv from "dcv"; import "@cloudscape-design/global-styles/index.css"; import {DCVViewer} from "./dcv-ui/dcv-ui.js"; ``` 以下は、認証が成功した場合に Amazon DCV サーバーに対して認証を行い、Amazon DCV ウェブ UI SDK から `DCVViewer` React コンポーネントをレンダリングする方法の例です。 ``` const LOG_LEVEL = dcv.LogLevel.INFO; const SERVER_URL = "https://your-dcv-server-url:port/"; const BASE_URL = "/static/js/dcvjs"; let auth; function App() { const [authenticated, setAuthenticated] = React.useState(false); const [sessionId, setSessionId] = React.useState(''); const [authToken, setAuthToken] = React.useState(''); const [credentials, setCredentials] = React.useState({}); const onSuccess = (_, result) => { var { sessionId, authToken } = { ...result[0] }; console.log("Authentication successful."); setSessionId(sessionId); setAuthToken(authToken); setAuthenticated(true); setCredentials({}); } const onPromptCredentials = (_, credentialsChallenge) => { let requestedCredentials = {}; credentialsChallenge.requiredCredentials.forEach(challenge => requestedCredentials[challenge.name] = ""); setCredentials(requestedCredentials); } const authenticate = () => { dcv.setLogLevel(LOG_LEVEL); auth = dcv.authenticate( SERVER_URL, { promptCredentials: onPromptCredentials, error: onError, success: onSuccess } ); } const updateCredentials = (e) => { const { name, value } = e.target; setCredentials({ ...credentials, [name]: value }); } const submitCredentials = (e) => { auth.sendCredentials(credentials); e.preventDefault(); } React.useEffect(() => { if (!authenticated) { authenticate(); } }, [authenticated]); const handleDisconnect = (reason) => { console.log("Disconnected: " + reason.message + " (code: " + reason.code + ")"); auth.retry(); setAuthenticated(false); } return ( authenticated ? :

); } const onError = (_, error) => { console.log("Error during the authentication: " + error.message); } export default App; ``` `promptCredentials` 関数、`error` 関数、`success` 関数は、必須コールバック関数であり、認証プロセスで定義する必要があります。。 Amazon DCV サーバーから認証情報が要求された場合、`promptCredentials` コールバック関数に、Amazon DCV サーバーから要求された認証情報チャレンジが送られます。システム認証が使用されるように Amazon DCV サーバーが設定されている場合、ユーザー名とパスワードの形式で認証情報を提供する必要があります。認証に失敗した場合、`error` コールバック関数に Amazon DCV サーバーからエラーオブジェクトが送られます。認証が成功すると、`success` コールバック関数に、ユーザーが Amazon DCV サーバーに接続できる各セッションのセッション ID (`sessionId`) と認可トークン (`authToken`) が含まれるカップルの配列が送られます。上記のコードサンプルは、認証に成功すると React ステータスを更新し、`DCVViewer` コンポーネントをレンダリングします。このコンポーネントで承認されるプロパティの詳細については、「[Amazon DCV ウェブ UI SDK のリファレンス](https://docs.aws.amazon.com/dcv/latest/websdkguide/dcv-viewer.html#DCVViewer)」を参照してください。自己署名証明書の詳細については、「[自己署名証明書によるリダイレクトの説明](https://docs.aws.amazon.com/dcv/latest/adminguide/redirection-clarifications-with-self-signed-certs.html)」をご覧ください。 ## AWS-UI から Cloudscape Design System へのアップデート SDK バージョン 1.3.0 以降、`DCVViewer` コンポーネントを AWS-UI から進化した [Cloudscape Design](https://cloudscape.design/) にアップデートしました。 Cloudscape は AWS-UI とは異なるビジュアルテーマを使用していますが、基盤となるコードベースに変わりはありません。したがって、`DCVViewer` ベースのアプリケーションの移行は容易です。移行するには、インストールした AWS-UI 関連の NPM パッケージを関連する Cloudscape パッケージに置き換えます。 | AWS-UI パッケージ名 | Cloudscape パッケージ名 | | --- | --- | | @awsui/components-react | @cloudscape-design/components | | @awsui/global-styles | @cloudscape-design/global-styles | | @awsui/collection-hooks | @cloudscape-design/collection-hooks | | @awsui/design-tokens | @cloudscape-design/design-tokens | 移行の詳細については、[AWS-UI GitHub ドキュメントページ](https://github.com/aws/awsui-documentation)を参照してください。