` HTML com um elemento válido `id` onde você deseja que o Amazon DCV Web Client SDK desenhe o fluxo de conteúdo do servidor Amazon DCV remoto.
Por exemplo:
```
DCV first connection
```
## Etapa 2: Autenticar, conectar e obter o primeiro quadro
Esta seção mostra como concluir o processo de autenticação do usuário, como conectar o servidor Amazon DCV e como receber o primeiro quadro de conteúdo do servidor Amazon DCV.
Primeiro, a partir do arquivo `index.js`, importe o SDK do cliente web do Amazon DCV. Ele pode ser importado como um módulo de Definição de Módulo Universal (UMD), da seguinte forma:
```
import "./dcvjs/dcv.js"
```
Caso contrário, a partir da versão`1.1.0`, ele também pode ser importado como um ECMAScript Módulo (ESM) do pacote correspondente, da seguinte forma:
```
import dcv from "./dcvjs/dcv.js"
```
Defina as variáveis a serem usadas para armazenar o objeto Authentication, o objeto Connection e o URL do servidor Amazon DCV.
```
let auth,
connection,
serverUrl;
```
No carregamento do script, registre a versão do SDK do cliente web do Amazon DCV e, no carregamento da página, chame a função `main`.
```
console.log("Using Amazon DCV Web Client SDK version " + dcv.version.versionStr);
document.addEventListener('DOMContentLoaded', main);
```
A função `main` define o nível do log e inicia o processo de autenticação.
```
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
}
);
}
```
As funções `promptCredentials`, `error` e `success` são funções obrigatórias de retorno de chamada que devem ser definidas no processo de autenticação.
Se o servidor Amazon DCV solicitar credenciais, a função de retorno de chamada `promptCredentials` receberá o desafio de credencial solicitado do servidor Amazon DCV. Se o servidor Amazon DCV estiver configurado para usar a autenticação do sistema, as credenciais de login deverão ser fornecidas. Os exemplos de código a seguir presumem que o nome de usuário é `my_dcv_user` e que a senha é `my_password`.
Se a autenticação falhar, a função de retorno de chamada `error` receberá um objeto de erro do servidor Amazon DCV.
Se a autenticação for bem-sucedida, a função de retorno de chamada `success` receberá uma matriz de pares que inclui o ID da sessão (`sessionId`) e os tokens de autorização (`authToken`) para cada sessão à qual o usuário `my_dcv_user` pode se conectar no servidor Amazon DCV. O exemplo de código a seguir chama a função connect e se conecta à primeira sessão retornada na matriz.
**nota**
No exemplo de código a seguir, substitua `MY_DCV_USER` por seu próprio nome de usuário e `MY_PASSWORD` por sua própria senha.
```
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);
}
```
Conecte-se ao servidor Amazon DCV. O método de retorno de chamada `firstFrame` será chamado quando o primeiro quadro for recebido do servidor 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);
});
}
```
## Bônus: crie automaticamente um formulário de login em HTML
O objeto `challenge` é retornado quando a função de retorno de chamada `promptCredentials` é chamada. Ele inclui uma propriedade chamada `requiredCredentials` que é uma matriz de objetos - um objeto por credencial que é solicitado pelo servidor Amazon DCV. Cada objeto inclui o nome e o tipo da credencial solicitada. Você pode usar os objetos `challenge` e `requiredCredentials` para criar automaticamente um formulário de login em HTML.
O exemplo de código a seguir mostra como fazer isso.
```
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));
}
```
# Trabalhar com os recursos do Amazon DCV
A disponibilidade dos recursos do Amazon DCV depende das permissões configuradas para a sessão do Amazon DCV e dos recursos do navegador da web do cliente.
Os recursos disponíveis em uma sessão do Amazon DCV são gerenciados pelas permissões que foram especificadas para a sessão. Isso significa que mesmo que um recurso seja compatível com o SDK do cliente web do Amazon DCV, o acesso a esse recurso pode ser impedido com base nas permissões definidas pelo administrador da sessão. Para obter mais informações, consulte [Configurar a autorização do Amazon DCV](https://docs.aws.amazon.com/dcv/latest/adminguide/security-authorization.html) no *Guia do administrador do Amazon DCV*.
## Entender a função de retorno de chamada featuresUpdate
Quando a disponibilidade de um recurso em uma sessão do Amazon DCV muda, o SDK do Amazon DCV Web Client notifica você usando a função de retorno de chamada `featuresUpdate` que você especifica no momento do estabelecimento da conexão. Por exemplo:
```
featuresUpdate: function (connection, list) {
...
},
```
A função de retorno de chamada notifica você somente sobre os atributo cuja disponibilidade foi alterada. O parâmetro `list` é uma matriz de strings e inclui somente os nomes dos atributo atualizados. Por exemplo, se a disponibilidade do atributo de entrada de áudio for alterada durante a sessão, o parâmetro incluirá somente `["audio-in"]`. Se, posteriormente, a disponibilidade dos atributo de copiar e colar da área de transferência mudar para a sessão, o parâmetro incluirá somente `["clipboard-copy", "clipboard-paste"]`.
## Controlar atualizações do atributo
A função de retorno de chamada `featuresUpdate` notifica você somente sobre os atributos cuja disponibilidade foi alterada. Para saber quais atributos foram atualizados, você deve consultar o atributo usando o método `connection.queryFeature`. Isso pode ser feito a qualquer momento após o recebimento da notificação de alteração. Esse método retorna uma `Promise` que resolve o status atualizado do atributo solicitado. O valor `status` está sempre associado e tem uma propriedade booleana (`true` \$1 `false`) chamada `enabled`. Alguns atributos podem ter propriedades adicionais no valor `status`. Se a disponibilidade do atributo não tiver sido atualizada, ela será rejeitada.
O exemplo de código a seguir mostra como fazer isso.
```
// Connection callback called
function featuresUpdate (_, list) {
if (list.length > 0) {
list.forEach((feat) => {
connection.queryFeature(feat).then(status => console.log(feat, "is", status.enabled)));
});
}
}
```
# Usar o SDK de Interface do Usuário da Web do Amazon DCV
O tutorial a seguir mostra como se autenticar no servidor Amazon DCV, se conectar a ele e renderizar o componente React do `DCVViewer` a partir do SDK da interface de usuário da Web do Amazon DCV.
**Topics**
+ [Pré-requisitos](#prerequisites)
+ [Etapa 1: Preparar a página HTML](#prep-html-ui)
+ [Etapa 2: Autenticar, conectar e renderizar o componente React do `DCVViewer`.](#auth-conn-render)
+ [Atualizar o AWS-UI para o Cloudscape Design System](#updateawsuitocloudscape)
## Pré-requisitos
Você precisa instalar `React`, `ReactDOM`, `Cloudscape Design Components React`, `Cloudscape Design Global Styles` e `Cloudscape Design Design Tokens`.
```
$ npm i react react-dom @cloudscape-design/components @cloudscape-design/global-styles @cloudscape-design/design-tokens
```
Você também precisaria baixar de `Amazon DCV Web Client SDK`. Leia [Conceitos básicos do SDK do cliente web do Amazon DCV](getting-started.md) o step-by-step guia sobre como fazer isso.
Você deve criar um alias para importar o módulo `dcv`, pois ele é uma dependência externa do SDK da interface de usuário da Web do Amazon DCV. Por exemplo, se você estiver usando o webpack para agrupar seu aplicativo da Web, poderá usar a opção [resolve.alias](https://webpack.js.org/configuration/resolve/#resolvealias) da seguinte forma:
```
const path = require('path');
module.exports = {
//...
resolve: {
alias: {
dcv: path.resolve('path', 'to', 'dcv.js'),
},
},
};
```
Se você estiver usando o rollup para empacotamento, poderá instalar o [@rollup/plugin-alias](https://www.npmjs.com/package/@rollup/plugin-alias) e usá-lo assim:
```
import alias from '@rollup/plugin-alias';
const path = require('path');
module.exports = {
//...
plugins: [
alias({
entries: [
{ find: 'dcv', replacement: path.resolve('path', 'to', 'dcv.js') },
]
})
]
};
```
## Etapa 1: Preparar a página HTML
Em sua página da Web, você deve carregar os JavaScript módulos necessários e ter um elemento `
` HTML com um elemento válido em `id` que o componente de entrada do seu aplicativo será renderizado.
Por exemplo:
```
DCV first connection
```
## Etapa 2: Autenticar, conectar e renderizar o componente React do `DCVViewer`.
Esta seção mostra como concluir o processo de autenticação do usuário, como conectar o servidor Amazon DCV e como renderizar o componente React do `DCVViewer`.
Primeiro, a partir do arquivo `index.js`, importe `React`, `ReactDOM` e seu componente de nível superior `App`.
```
import React from "react";
import ReactDOM from 'react-dom';
import App from './App';
```
Renderize o nó de contêiner de nível superior do seu aplicativo.
```
ReactDOM.render(
,
document.getElementById("root")
);
```
No arquivo `App.js`, importe o SDK do cliente web do Amazon DCV como um módulo ESM, o componente React `DCVViewer` do SDK da Interface do Usuário do Amazon DCV, `React` e o pacote `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";
```
A seguir está um exemplo que mostra como se autenticar no Servidor Amazon DCV e renderizar o componente React do `DCVViewer` a partir do SDK da Interface da Web do Amazon DCV, desde que a autenticação tenha sido bem-sucedida.
```
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;
```
As funções `promptCredentials`, `error` e `success` são funções obrigatórias de retorno de chamada que devem ser definidas no processo de autenticação.
Se o servidor Amazon DCV solicitar credenciais, a função de retorno de chamada `promptCredentials` receberá o desafio de credencial solicitado do servidor Amazon DCV. Se o servidor Amazon DCV estiver configurado para usar a autenticação do sistema, as credenciais deverão ser fornecidas no formato de um nome de usuário e senha.
Se a autenticação falhar, a função de retorno de chamada `error` receberá um objeto de erro do servidor Amazon DCV.
Se a autenticação for bem-sucedida, a função de retorno de chamada `success` receberá uma matriz de pares que inclui o ID da sessão ( `sessionId` ) e os tokens de autorização ( `authToken` ) para cada sessão à qual o usuário pode se conectar no servidor Amazon DCV. O exemplo de código acima atualiza o estado do React para renderizar o componente `DCVViewer` em caso de autenticação bem-sucedida.
Para saber mais sobre as propriedades aceitas por esse componente, consulte a [referência do SDK da interface de usuário da Web do Amazon DCV](https://docs.aws.amazon.com/dcv/latest/websdkguide/dcv-viewer.html#DCVViewer).
Para saber mais sobre certificados autoassinados, consulte [Esclarecimentos sobre redirecionamento com certificados autoassinados](https://docs.aws.amazon.com/dcv/latest/adminguide/redirection-clarifications-with-self-signed-certs.html).
## Atualizar o AWS-UI para o Cloudscape Design System
A partir da versão 1.3.0 do SDK, atualizamos nosso componente `DCVViewer` do AWS-UI para sua evolução: [Cloudscape Design](https://cloudscape.design/).
O Cloudscape usa um tema visual diferente do AWS-UI, mas a base de código subjacente permanece a mesma. Portanto, migrar seu aplicativo com base no `DCVViewer` deve ser fácil. Para migrar, substitua os pacotes NPM relacionados ao AWS-UI que você instalou pelos pacotes associados do Cloudscape:
| Nome do pacote AWS-UI | Nome do pacote 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 |
Para obter mais detalhes sobre a migração, consulte a página de documentação da [AWS-UI GitHub ](https://github.com/aws/awsui-documentation).