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

  • Artigo

O ARR (Azure Remote Rendering) é um serviço que permite renderizar conteúdo 3D interativo de alta qualidade na nuvem e transmiti-lo em tempo real para dispositivos, como o HoloLens 2.

Esse SDK oferece funcionalidade para converter ativos no formato esperado pelo runtime e também para gerenciar o tempo de vida das sessões de renderização remotas.

OBSERVAÇÃO: depois que uma sessão estiver em execução, um aplicativo cliente se conectará a ela usando um dos "SDKs de runtime". Esses SDKs foram projetados para dar melhor suporte às necessidades de um aplicativo interativo que faz a renderização 3d. Eles estão disponíveis em (.net ou (C++).

Documentação do produto

Introdução

Ambientes com suporte no momento

Pré-requisitos

Você precisará de uma assinatura do Azure e uma conta do Azure Remote Rendering para usar esse pacote.

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

Instale a biblioteca de clientes modelo para JavaScript com npm:

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

Suporte ao navegador

Pacote JavaScript

Para usar essa biblioteca de clientes no navegador, primeiro você precisa usar um empacotador. Para obter detalhes sobre como fazer isso, consulte nossa documentação de agrupamento.

CORS

Essa biblioteca não pode ser usada para fazer chamadas diretas para o serviço de Remote Rendering do Azure de um navegador. Consulte este documento para obter diretrizes.

Autenticar o cliente

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

  • Autenticação de chave de conta
    • As chaves de conta permitem que você comece rapidamente usando o Remote Rendering do Azure. Mas antes de implantar seu aplicativo em produção, recomendamos que você atualize o aplicativo para usar a autenticação do Azure AD.
  • Autenticação de token do Azure Active Directory (AD)
    • Se você estiver criando um aplicativo empresarial e sua empresa estiver usando o Azure AD como sistema de identidade, você poderá usar a autenticação do Azure AD baseada no usuário em seu aplicativo. Em seguida, você concede acesso às suas contas de Remote Rendering do Azure usando seus grupos de segurança Azure AD existentes. Você também pode permitir acesso diretamente aos usuários em sua organização.
    • Caso contrário, é recomendável que você obtenha tokens do Azure AD em um serviço Web que dê suporte ao seu aplicativo. Recomendamos esse método para aplicativos de produção porque ele permite evitar a inserção das credenciais para acesso às Âncoras Espaciais do Azure em seu aplicativo cliente.

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

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

OBSERVAÇÃO: para converter ativos, é preferível escolher uma região próxima ao armazenamento que contém os ativos.

OBSERVAÇÃO: para renderização, é altamente recomendável escolher a região mais próxima para os dispositivos que usam o serviço. O tempo necessário para se comunicar com o servidor afeta a qualidade da experiência.

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

Use o AccountKeyCredential objeto para usar um identificador de conta e uma chave de conta para autenticar:

const credential = new AzureKeyCredential(accountKey);

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

Autenticação com um segredo do cliente do AAD

Use o ClientSecretCredential objeto para executar a autenticação de segredo 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 usuário usando a autenticação de código do dispositivo

Use o DeviceCodeCredential objeto para executar 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);

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

Autenticação interativa com DefaultAzureCredential

Use o objeto com includeInteractiveCredentials: true para usar o DefaultAzureCredential fluxo de autenticação interativa padrão:

let credential = new DefaultAzureCredential();

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

Autenticação com um token de acesso estático

Você pode passar um token de acesso Realidade Misturada como um AccessToken recuperado anteriormente do serviço sts Realidade Misturada a ser usado com uma biblioteca de clientes Realidade Misturada:

// 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);

Principais conceitos

RemoteRenderingClient

O RemoteRenderingClient é a biblioteca de clientes usada para acessar o RemoteRenderingService. Ele fornece métodos para criar e gerenciar conversões de ativos e sessões de renderização.

Exemplos

Converter um ativo simples

Supomos que um RemoteRenderingClient tenha sido construído conforme descrito na seção Autenticar o Cliente . O snippet a seguir descreve como solicitar que "box.fbx", encontrado na raiz do contêiner de blob no URI fornecido, 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 arquivos de saída serão colocados ao lado do ativo de entrada.

Converter um ativo mais complexo

Os ativos podem fazer referência a outros arquivos, e os contêineres de blob podem conter arquivos pertencentes a muitos ativos diferentes. Neste exemplo, mostramos como os prefixos podem ser usados para organizar seus blobs e como converter um ativo para levar em conta essa organização. Suponha que o contêiner de blob em inputStorageUrl contenha muitos arquivos, incluindo "Bicycle/bicycle.gltf", "Bicycle/bicycle.bin" e "Bicycle/saddleTexture.jpg". (Portanto, o prefixo "Bike" está agindo muito como uma pasta.) Queremos converter o glTF para que ele tenha acesso aos outros arquivos que compartilham o prefixo, sem exigir que o serviço de conversão acesse outros arquivos. Para manter as coisas arrumadas, também queremos que os arquivos de saída sejam gravados em um contêiner de armazenamento diferente e recebem um prefixo comum: "ConvertBicycle". O código será 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
  );

OBSERVAÇÃO: quando um prefixo é dado nas opções de entrada, o parâmetro de arquivo de entrada é considerado relativo a esse prefixo. O mesmo se aplica ao parâmetro de arquivo de saída nas opções de saída.

Obter a saída quando uma conversão de ativo for concluída

A conversão de um ativo pode levar de segundos a horas. Esse código usa o conversionPoller retornado por beginConversion para sondar regularmente até que a conversão seja concluída ou falhe. O período de sondagem padrão é 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);
}

Observe que o estado de um AssetConversionPollerLike pode ser serializado chamando conversionPoller.toString(). Esse valor pode ser passado posteriormente para beginConversion como um resumeFrom valor, para construir um novo poller que continua de onde o anterior parou:

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

Listar conversões

Você pode obter informações sobre suas conversões usando o getConversions método . Esse método pode retornar conversões que ainda não foram iniciadas, conversões que estão em execução e conversões que foram concluídas. Neste exemplo, listamos apenas 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

Supomos que um RemoteRenderingClient tenha sido construído conforme descrito na seção Autenticar o Cliente . O snippet a seguir descreve como solicitar que uma nova sessão de renderização seja iniciada.

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
);

Observe que o estado de um RenderingSessionPollerLike pode ser serializado chamando toString(). Esse valor pode ser passado posteriormente para beginSession como um resumeFrom valor, para construir um novo poller que continua de onde o anterior parou:

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

Estender o tempo de concessão de uma sessão

Se uma sessão estiver se aproximando de seu tempo máximo de concessão, mas você quiser mantê-la ativa, você precisará fazer uma chamada para aumentar seu tempo máximo de concessão. Este exemplo mostra como consultar as propriedades atuais e, em seguida, estender a concessão se ela expirar em breve.

OBSERVAÇÃO: os SDKs de runtime também oferecem essa funcionalidade e, em muitos cenários típicos, você os usaria para estender 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

Você pode obter informações sobre suas sessões usando o getSessions método . Esse método pode retornar sessões que ainda não foram iniciadas e sessões que estão prontas.

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

Parar uma sessão

O código a seguir interromperá uma sessão em execução com a ID fornecida.

client.endSession(sessionId);

Solução de problemas

Log

A habilitação do log pode ajudar a descobrir informações úteis sobre falhas. Para ver um log de solicitações e respostas HTTP, defina a variável de ambiente AZURE_LOG_LEVEL como info. Como alternativa, o log pode ser habilitado no runtime chamando setLogLevel em @azure/logger:

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

setLogLevel("info");

Solução de problemas do Azure Remote Rendering

Para obter conselhos gerais de solução de problemas sobre o Azure Remote Rendering, consulte a página Solução de problemas para renderização remota em docs.microsoft.com.

Os métodos de cliente gerarão exceções se a solicitação não puder ser feita. No entanto, no caso de conversões e sessões, as solicitações podem ser bem-sucedidas, mas a operação solicitada pode não ser bem-sucedida. Nesse caso, nenhuma exceção será gerada, mas os objetos retornados podem ser inspecionados para entender o que aconteceu.

Se o ativo em uma conversão for inválido, a operação de conversão retornará um objeto AssetConversion com um status Failed e carregará um RemoteRenderingServiceError com detalhes. Depois que o serviço de conversão for capaz de processar o arquivo, um <arquivo assetName.result.json> será gravado no contêiner de saída. Se o ativo de entrada for inválido, esse arquivo conterá uma descrição mais detalhada do problema.

Da mesma forma, às vezes, quando uma sessão é solicitada, a sessão acaba em um estado de erro. O método startSessionOperation retornará um objeto RenderingSession, mas esse objeto terá um status Error e carregará um RemoteRenderingServiceError com detalhes.

Próximas etapas

Contribuição

Se você quiser contribuir com essa biblioteca, leia o guia de contribuição para saber como criar e testar o código.

Impressões