前提条件ステップ 1: HTML ページを準備するステップ 2: DCVViewer React コンポーネントの認証、接続、レンダリングを行う AWS-UI から Cloudscape Design System へのアップデート

NICE DCV ウェブ UI SDK の使用

以下のチュートリアルでは、NICE DCV サーバーに対して認証を行い、接続して NICE DCV ウェブ UI SDK から DCVViewer React コンポーネントをレンダリングする方法を説明します。

トピック

前提条件
ステップ 1: HTML ページを準備する
ステップ 2: DCVViewer React コンポーネントの認証、接続、レンダリングを行う
AWS-UI から Cloudscape Design System へのアップデート

前提条件

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

また、NICE DCV Web Client SDK のダウンロードも必要になります。その手順については、「NICE DCV ウェブクライアント SDK の開始方法」のステップごとのガイドをご覧ください。

NICE DCV ウェブ UI SDK の外部依存関係であるため、dcv モジュールをインポートするためのエイリアスを作成する必要があります。例えば、webpack を使用してウェブアプリケーションをバンドルする場合、以下のように resolve.alias オプションを使用できます。


const path = require('path');

module.exports = {
  //...
  resolve: {
    alias: {
      dcv: path.resolve('path', 'to', 'dcv.js'),
    },
  },
};

バンドルにロールアップを使用している場合は、@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 を持つ <div> HTML 要素が必要です。

例:


<!DOCTYPE html>
<html lang="en" style="height: 100%;">
  <head>
    <title>DCV first connection</title>
  </head>
  <body style="height: 100%;">
    <div id="root" style="height: 100%;"></div>
    <script type="module" src="index.js"></script>
  </body>
</html>

ステップ 2: `DCVViewer` React コンポーネントの認証、接続、レンダリングを行う

このセクションでは、ユーザー認証プロセスを完了する方法、NICE DCV サーバーを接続する方法、DCVViewer React コンポーネントをレンダリングする方法を説明します。

まず、index.js ファイルから React、ReactDOM、および最上位の App コンポーネントをインポートします。


import React from "react";
import ReactDOM from 'react-dom';
import App from './App';

アプリケーションの最上位のコンテナノードをレンダリングします。


ReactDOM.render(
  <React.StrictMode>
    <App />
  </React.StrictMode>,
  document.getElementById("root")
);

App.js ファイルで、ESM モジュールとしての NICE DCV ウェブクライアント SDK、NICE 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";

以下は、認証が成功した場合に NICE DCV サーバーに対して認証を行い、NICE 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 ?
    <DCVViewer
      dcv={{
        sessionId: sessionId,
        authToken: authToken,
        serverUrl: SERVER_URL,
        baseUrl: BASE_URL,
        onDisconnect: handleDisconnect,
        logLevel: LOG_LEVEL
      }}
      uiConfig={{
        toolbar: {
          visible: true,
          fullscreenButton: true,
          multimonitorButton: true,
        },
      }}
    />
    :
    <div
      style={{
        height: window.innerHeight,
        backgroundColor: "#373737",
        display: 'flex',
        alignItems: 'center',
        justifyContent: 'center',
      }}
    >
      <form>
        <fieldset>
          {Object.keys(credentials).map((cred) => (
            <input
              key={cred}
              name={cred}
              placeholder={cred}
              type={cred === "password" ? "password" : "text"}
              onChange={updateCredentials}
              value={credentials[cred]}
            />
          ))}
        </fieldset>
        <button
          type="submit"
          onClick={submitCredentials}
        >
          Login
        </button>
      </form>
    </div>
  );
}

const onError = (_, error) => {
  console.log("Error during the authentication: " + error.message);
}

export default App;

promptCredentials 関数、error 関数、success 関数は必須コールバック関数であり、認証プロセスで定義する必要があります。

NICE DCV サーバーから認証情報が要求された場合、promptCredentials コールバック関数に、NICE DCV サーバーから要求された認証情報チャレンジが送られます。システム認証が使用されるように NICE DCV サーバーが設定されている場合、ユーザー名とパスワードの形式で認証情報を提供する必要があります。

認証に失敗した場合、error コールバック関数に NICE DCV サーバーからエラーオブジェクトが送られます。

認証が成功すると、success コールバック関数に、ユーザーが NICE DCV サーバーに接続できる各セッションのセッション ID (sessionId) と認証トークン (authToken) が含まれるカップルの配列が送られます。上記のコードサンプルは、認証に成功すると React ステータスを更新し、DCVViewer コンポーネントをレンダリングします。

このコンポーネントで承認されるプロパティの詳細については、「NICE DCV ウェブ UI SDK のリファレンス」をご覧ください。

自己署名証明書の詳細については、「自己署名証明書によるリダイレクトの説明」をご覧ください。

AWS-UI から Cloudscape Design System へのアップデート

SDK バージョン 1.3.0 以降、DCVViewer コンポーネントを AWS-UI から進化した 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 ドキュメントページを参照してください。

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

NICE DCV 機能の操作

SDK リファレンス