Partilhar via

Biblioteca de cliente Remote Rendering do Azure para JavaScript – versão 1.0.0-beta.1

  • Artigo

O Azure Remote Rendering (ARR) é um serviço que lhe permite compor conteúdos 3D interativos e de alta qualidade na cloud e transmiti-lo em fluxo em tempo real para dispositivos, como o HoloLens 2.

Este SDK oferece funcionalidades para converter recursos no formato esperado pelo runtime e também para gerir a duração das sessões de composição remota.

NOTA: assim que uma sessão estiver em execução, uma aplicação cliente ligar-se-á à mesma com um dos "SDKs de runtime". Estes SDKs foram concebidos para suportar melhor as necessidades de uma aplicação interativa com composição 3D. Estão disponíveis no (.net ou (C++).

Documentação do produto

Introdução

Ambientes atualmente suportados

Pré-requisitos

Precisará de uma subscrição do Azure e de uma conta do Azure Remote Rendering para utilizar este pacote.

Instalar o pacote @azure/mixed-reality-remote-rendering

Instale a biblioteca de cliente modelo para JavaScript com npm:

npm install @azure/mixed-reality-remote-rendering

Browser support (Suporte do browser)

Pacote JavaScript

Para utilizar esta biblioteca de cliente no browser, primeiro tem de utilizar um bundler. Para obter detalhes sobre como fazê-lo, consulte a nossa documentação de agrupamento.

CORS

Esta biblioteca não pode ser utilizada para efetuar chamadas diretas para o serviço Remote Rendering do Azure a partir de um browser. Consulte este documento para obter orientações.

Autenticar o cliente

A construção de um cliente de composição remota requer uma conta autenticada e um ponto final de composição remota. Para uma conta criada na região eastus, o domínio da conta terá o formulário "eastus.mixedreality.azure.com". Existem várias formas diferentes de autenticação:

  • Autenticação da Chave de Conta
    • As chaves de conta permitem-lhe começar rapidamente a utilizar o Azure Remote Rendering. Contudo, antes de implementar a sua aplicação na produção, recomendamos que atualize a sua aplicação para utilizar Azure AD autenticação.
  • Autenticação de tokens do Azure Active Directory (AD)
    • Se estiver a criar uma aplicação empresarial e a sua empresa estiver a utilizar Azure AD como o respetivo sistema de identidade, pode utilizar a autenticação Azure AD baseada no utilizador na sua aplicação. Em seguida, concede acesso às suas contas do Azure Remote Rendering através dos grupos de segurança Azure AD existentes. Também pode conceder acesso diretamente aos utilizadores na sua organização.
    • Caso contrário, recomendamos que obtenha tokens de Azure AD a partir de um serviço Web que suporte a sua aplicação. Recomendamos este método para aplicações de produção porque lhe permite evitar incorporar as credenciais para acesso às Âncoras Espaciais do Azure na sua aplicação cliente.

Consulte aqui para obter instruções e informações detalhadas.

Em todos os exemplos seguintes, o cliente é construído com um remoteRenderingEndpoint. Os pontos finais disponíveis correspondem às regiões e a escolha do ponto final determina a região na qual o serviço executa o seu trabalho. Um exemplo é https://remoterendering.eastus2.mixedreality.azure.com.

NOTA: para converter recursos, é preferível escolher uma região próxima do armazenamento que contém os recursos.

NOTA: para a composição, recomenda-se vivamente que escolha a região mais próxima dos dispositivos que utilizam o serviço. O tempo necessário para comunicar com o servidor afeta a qualidade da experiência.

Autenticação com autenticação de chave de conta

Utilize o AccountKeyCredential objeto para utilizar um identificador de conta e uma chave de conta para autenticar:

const credential = new AzureKeyCredential(accountKey);

const client = new RemoteRenderingClient(serviceEndpoint, accountId, accountDomain, credential);

Autenticar com um segredo do cliente do AAD

Utilize o ClientSecretCredential objeto para efetuar a autenticação secreta do cliente.

let credential = new ClientSecretCredential(tenantId, clientId, clientSecret, {
  authorityHost: "https://login.microsoftonline.com/" + tenantId
});

const client = new RemoteRenderingClient(serviceEndpoint, accountId, accountDomain, credential);

Autenticar um utilizador com a autenticação de código do dispositivo

Utilize o DeviceCodeCredential objeto para efetuar a autenticação de código do dispositivo.

let deviceCodeCallback = (deviceCodeInfo: DeviceCodeInfo) => {
  console.debug(deviceCodeInfo.message);
  console.log(deviceCodeInfo.message);
};

let credential = new DeviceCodeCredential(tenantId, clientId, deviceCodeCallback, {
  authorityHost: "https://login.microsoftonline.com/" + tenantId
});

const client = new RemoteRenderingClient(serviceEndpoint, accountId, accountDomain, credential);

Veja aqui para obter mais informações sobre como utilizar o fluxo de autenticação de código do dispositivo.

Autenticação interativa com DefaultAzureCredential

Utilize o objeto com includeInteractiveCredentials: true para utilizar o DefaultAzureCredential fluxo de autenticação interativa predefinido:

let credential = new DefaultAzureCredential();

return new RemoteRenderingClient(serviceEndpoint, accountId, accountDomain, credential, {
  authenticationEndpointUrl: "https://sts.mixedreality.azure.com"
});

Autenticar com um token de acesso estático

Pode transmitir um token de acesso Mixed Reality como um AccessToken obtido anteriormente a partir do serviço STS do Mixed Reality para ser utilizado com uma biblioteca de cliente Mixed Reality:

// GetMixedRealityAccessTokenFromWebService is a hypothetical method that retrieves
// a Mixed Reality access token from a web service. The web service would use the
// MixedRealityStsClient and credentials to obtain an access token to be returned
// to the client.
const accessToken = GetMixedRealityAccessTokenFromWebService();

RemoteRenderingClient client = new RemoteRenderingClient(remoteRenderingEndpoint, accountId, accessToken);

Conceitos-chave

RemoteRenderingClient

É RemoteRenderingClient a biblioteca de cliente utilizada para aceder ao RemoteRenderingService. Fornece métodos para criar e gerir conversões de recursos e sessões de composição.

Exemplos

Converter um recurso simples

Partimos do princípio de que um RemoteRenderingClient foi construído conforme descrito na secção Autenticar o Cliente . O fragmento seguinte descreve como pedir que "box.fbx", encontrado na raiz do contentor de blobs no URI especificado, seja convertido.

const inputSettings: AssetConversionInputSettings = {
  storageContainerUrl,
  relativeInputAssetPath: "box.fbx"
};
const outputSettings: AssetConversionOutputSettings = {
  storageContainerUrl
};
const conversionSettings: AssetConversionSettings = { inputSettings, outputSettings };

// A randomly generated UUID is a good choice for a conversionId.
const conversionId = uuid();

const conversionPoller: AssetConversionPollerLike = await client.beginConversion(
  conversionId,
  conversionSettings
);

Os ficheiros de saída serão colocados ao lado do recurso de entrada.

Converter um recurso mais complexo

Os recursos podem referenciar outros ficheiros e os contentores de blobs podem conter ficheiros pertencentes a muitos recursos diferentes. Neste exemplo, mostramos como os prefixos podem ser utilizados para organizar os blobs e como converter um recurso para ter em conta essa organização. Suponha que o contentor de blobs em inputStorageUrl contém muitos ficheiros, incluindo "Bike/bike.gltf", "Bike/bike.bin" e "Bike/saddleTexture.jpg". (Portanto, o prefixo "Bicicleta" está a funcionar muito como uma pasta.) Queremos converter o glTF para que tenha acesso aos outros ficheiros que partilham o prefixo, sem exigir que o serviço de conversão aceda a outros ficheiros. Para manter as coisas arrumadas, também queremos que os ficheiros de saída sejam escritos num contentor de armazenamento diferente e um prefixo comum: "ConvertBicycle". O código é o seguinte:

  const inputSettings: AssetConversionInputSettings = {
    storageContainerUrl: inputStorageUrl,
    blobPrefix: "Bicycle"
    relativeInputAssetPath: "bicycle.gltf"
  };
  const outputSettings: AssetConversionOutputSettings = {
    storageContainerUrl: outputStorageUrl,
    blobPrefix: "ConvertedBicycle"
  };
  const conversionSettings: AssetConversionSettings = { inputSettings, outputSettings };

  const conversionId = uuid();

  const conversionPoller: AssetConversionPollerLike = await client.beginConversion(
    conversionId,
    conversionSettings
  );

NOTA: quando é fornecido um prefixo nas opções de entrada, assume-se que o parâmetro de ficheiro de entrada é relativo a esse prefixo. O mesmo se aplica ao parâmetro de ficheiro de saída nas opções de saída.

Obter o resultado quando uma conversão de recursos tiver terminado

A conversão de um recurso pode demorar entre segundos e horas. Este código utiliza o conversionPoller devolvido por beginConversion para consultar regularmente até que a conversão seja concluída ou falhe. O período de consulta predefinido é de 10 segundos.

const conversion = await conversionPoller.pollUntilDone();

console.log("== Check results ==");

if (conversion.status === "Succeeded") {
  console.log("Conversion succeeded: Output written to " + conversion.output?.outputAssetUrl);
} else if (conversion.status === "Failed") {
  console.log("Conversion failed: " + conversion.error.code + " " + conversion.error.message);
}

Tenha em atenção que o estado de um AssetConversionPollerLike pode ser serializado ao chamar conversionPoller.toString(). Esse valor pode ser posteriormente transmitido para beginConversion como um resumeFrom valor, para construir um novo poller que continue a partir do local onde o anterior ficou:

const serializedPollerString = conversionPoller.toString();
// ...
const resumedPoller = client.beginConversion({ resumeFrom: serializedPollerString });

Listar conversões

Pode obter informações sobre as conversões com o getConversions método . Este método pode devolver conversões que ainda não foram iniciadas, conversões em execução e conversões concluídas. Neste exemplo, apenas listamos os URIs de saída de conversões bem-sucedidas iniciadas no último dia.

for await (const conversion of client.listConversions()) {
  if (conversion.status === "Succeeded") {
    console.log(
      `Conversion ${conversion.conversionId} succeeded: Output written to ${conversion.output?.outputAssetUrl}`
    );
  } else if (conversion.status === "Failed") {
    console.log(
      `Conversion ${conversion.conversionId} failed: ${conversion.error.code} ${conversion.error.message}`
    );
  }
}

Criar uma sessão

Partimos do princípio de que um RemoteRenderingClient foi construído conforme descrito na secção Autenticar o Cliente . O fragmento seguinte descreve como pedir que seja iniciada uma nova sessão de composição.

const sessionSettings: RenderingSessionSettings = {
  maxLeaseTimeInMinutes: 4,
  size: "Standard"
};

// A randomly generated UUID is a good choice for a conversionId.
const sessionId = uuid();

const sessionPoller: RenderingSessionPollerLike = await client.beginSession(
  sessionId,
  sessionSettings
);

Tenha em atenção que o estado de uma RenderingSessionPollerLike pode ser serializado ao chamar toString(). Esse valor pode ser posteriormente transmitido para beginSession como um resumeFrom valor, para construir um novo poller que continue a partir do local onde o anterior ficou:

const serializedPollerString = sessionPoller.toString();
// ...
const resumedPoller = client.beginSession({ resumeFrom: serializedPollerString });

Prolongar o tempo de concessão de uma sessão

Se uma sessão estiver a aproximar-se do tempo máximo de concessão, mas quiser mantê-la viva, terá de fazer uma chamada para aumentar o tempo máximo de concessão. Este exemplo mostra como consultar as propriedades atuais e, em seguida, prolongar a concessão se expirar em breve.

NOTA: os SDKs de runtime também oferecem esta funcionalidade e, em muitos cenários típicos, utilizá-los-iam para prolongar a concessão da sessão.

/// When the lease is within 2 minutes of expiring, extend it by 15 minutes.
let currentSession = await client.getSession(sessionId);
if (currentSession.status == "Ready") {
  if (
    currentSession.maxLeaseTimeInMinutes -
      (Date.now() - currentSession.properties.createdOn.valueOf()) / 60000 <
    2
  ) {
    let newLeaseTime = currentSession.maxLeaseTimeInMinutes + 15;

    await client.updateSession(sessionId, { maxLeaseTimeInMinutes: newLeaseTime });
  }
}

Listar sessões

Pode obter informações sobre as suas sessões com o getSessions método . Este método pode devolver sessões que ainda não foram iniciadas e sessões prontas.

for await (const session of client.listSessions()) {
  console.log(`Session ${session.sessionId} is ${session.status}`);
}

Parar uma sessão

O código seguinte irá parar uma sessão em execução com um determinado ID.

client.endSession(sessionId);

Resolução de problemas

Registo

Ativar o registo pode ajudar a descobrir informações úteis sobre falhas. Para ver um registo de pedidos HTTP e respostas, defina a variável de AZURE_LOG_LEVEL ambiente como info. Em alternativa, o registo pode ser ativado no runtime ao chamar setLogLevel no @azure/logger:

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

Resolução de problemas do Azure Remote Rendering

Para obter conselhos gerais de resolução de problemas relativos ao Azure Remote Rendering, veja a página Resolução de problemas de composição remota em docs.microsoft.com.

Os métodos de cliente irão gerar exceções se não for possível efetuar o pedido. No entanto, no caso de conversões e sessões, os pedidos podem ser bem-sucedidos, mas a operação pedida pode não ser bem-sucedida. Neste caso, não será emitida nenhuma exceção, mas os objetos devolvidos podem ser inspecionados para compreender o que aconteceu.

Se o recurso numa conversão for inválido, a operação de conversão devolverá um objeto AssetConversion com o estado Falha e transportará um RemoteRenderingServiceError com detalhes. Assim que o serviço de conversão conseguir processar o ficheiro, será escrito um <ficheiro assetName.result.json> no contentor de saída. Se o recurso de entrada for inválido, esse ficheiro conterá uma descrição mais detalhada do problema.

Da mesma forma, por vezes, quando é pedida uma sessão, a sessão acaba num estado de erro. O método startSessionOperation devolverá um objeto RenderingSession, mas esse objeto terá um Estado de erro e transportará um RemoteRenderingServiceError com detalhes.

Passos seguintes

Contribuir

Se quiser contribuir para esta biblioteca, leia o guia de contribuição para saber mais sobre como criar e testar o código.

Impressões