Biblioteca de clientes do Azure Remote Rendering para Java – versão 1.1.23

Artigo
10/25/2023

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 remota.

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 no .NET e no C++.

Código-fonte | Documentação | de referência da API Documentação do produto

Introdução

Pré-requisitos

JDK (Java Development Kit) versão 8 ou posterior.
Assinatura do Azure
A conta Remote Rendering do Azure para usar esse pacote.

Incluir o pacote

Incluir o arquivo da BOM

Inclua o azure-sdk-bom em seu projeto para assumir a dependência da versão ga (disponibilidade geral) da biblioteca. No trecho a seguir, substitua o espaço reservado {bom_version_to_target} pelo número de versão. Para saber mais sobre a BOM, consulte o BOM README do SDK do AZURE.

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-sdk-bom</artifactId>
            <version>{bom_version_to_target}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

e inclua a dependência direta na seção dependências sem a marca de versão, conforme mostrado abaixo.

<dependencies>
  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-mixedreality-remoterendering</artifactId>
  </dependency>
</dependencies>

Incluir dependência direta

Nota: Esta versão tem como destino a versão da API do serviço de Remote Rendering do Azure v2021-01-01.

Adicione a seguinte dependência do Maven:

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-mixedreality-remoterendering</artifactId>
    <version>1.1.23</version>
</dependency>

Autenticar o cliente

Construir um cliente de renderização remota requer uma conta autenticada e um ponto de extremidade de renderização remota. Uma conta consiste em sua accountId e um domínio de conta. Para uma conta criada na região eastus, o domínio da conta terá o formato "eastus.mixedreality.azure.com". Há várias formas de autenticação:

Autenticação de chave de conta
- As chaves de conta permitem que você comece rapidamente a usar o Azure Remote Rendering. 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 do Azure Remote Rendering 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 RemoteRenderingClientBuilder objeto . Os parâmetros são sempre os mesmos, exceto para o objeto de credencial, que é explicado em cada exemplo. O remoteRenderingEndpoint parâmetro é uma URL que 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 que você escolha a região mais próxima dos 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 AzureKeyCredential objeto para usar um identificador de conta e uma chave de conta para autenticar:

AzureKeyCredential credential = new AzureKeyCredential(environment.getAccountKey());

RemoteRenderingClient client = new RemoteRenderingClientBuilder()
    .accountId(environment.getAccountId())
    .accountDomain(environment.getAccountDomain())
    .endpoint(environment.getServiceEndpoint())
    .credential(credential)
    .buildClient();

Autenticação com um segredo do cliente do AAD

Use o ClientSecretCredential objeto para executar a autenticação de segredo do cliente.

ClientSecretCredential credential = new ClientSecretCredentialBuilder()
    .tenantId(environment.getTenantId())
    .clientId(environment.getClientId())
    .clientSecret(environment.getClientSecret())
    .authorityHost("https://login.microsoftonline.com/" + environment.getTenantId())
    .build();

RemoteRenderingClient client = new RemoteRenderingClientBuilder()
    .accountId(environment.getAccountId())
    .accountDomain(environment.getAccountDomain())
    .endpoint(environment.getServiceEndpoint())
    .credential(credential)
    .buildClient();

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.

DeviceCodeCredential credential = new DeviceCodeCredentialBuilder()
    .challengeConsumer((DeviceCodeInfo deviceCodeInfo) -> {
        logger.info(deviceCodeInfo.getMessage());
    })
    .clientId(environment.getClientId())
    .tenantId(environment.getTenantId())
    .authorityHost("https://login.microsoftonline.com/" + environment.getTenantId())
    .build();

RemoteRenderingClient client = new RemoteRenderingClientBuilder()
    .accountId(environment.getAccountId())
    .accountDomain(environment.getAccountDomain())
    .endpoint(environment.getServiceEndpoint())
    .credential(credential)
    .buildClient();

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 DefaultAzureCredential objeto :

DefaultAzureCredential credential = new DefaultAzureCredentialBuilder().build();

RemoteRenderingClient client = new RemoteRenderingClientBuilder()
    .accountId(environment.getAccountId())
    .accountDomain(environment.getAccountDomain())
    .endpoint(environment.getServiceEndpoint())
    .credential(credential)
    .buildClient();

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.
AccessToken accessToken = getMixedRealityAccessTokenFromWebService();

RemoteRenderingClient client = new RemoteRenderingClientBuilder()
    .accountId(environment.getAccountId())
    .accountDomain(environment.getAccountDomain())
    .endpoint(environment.getServiceEndpoint())
    .accessToken(accessToken)
    .buildClient();

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
Converter um ativo mais complexo
Obter a saída quando uma conversão de ativo for concluída
Conversões de lista
Criar uma sessão
Estender o tempo de concessão de uma sessão
Listar sessões
Parar uma sessão

Converter um ativo simples

Supomos que um RemoteRenderingClient foi 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 na URL fornecida, seja convertido.

AssetConversionOptions conversionOptions = new AssetConversionOptions()
    .setInputStorageContainerUrl(getStorageURL())
    .setInputRelativeAssetPath("box.fbx")
    .setOutputStorageContainerUrl(getStorageURL());

// A randomly generated UUID is a good choice for a conversionId.
String conversionId = UUID.randomUUID().toString();

SyncPoller<AssetConversion, AssetConversion> conversionOperation = client.beginConversion(conversionId, conversionOptions);

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: "ConvertedBicycle". O código será o seguinte:

AssetConversionOptions conversionOptions = new AssetConversionOptions()
    .setInputStorageContainerUrl(inputStorageURL)
    .setInputRelativeAssetPath("bicycle.gltf")
    .setInputBlobPrefix("Bicycle")
    .setOutputStorageContainerUrl(outputStorageURL)
    .setOutputBlobPrefix("ConvertedBicycle");

String conversionId = UUID.randomUUID().toString();

SyncPoller<AssetConversion, AssetConversion> conversionOperation = client.beginConversion(conversionId, conversionOptions);

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 uma conversionOperation existente e sonda regularmente até que a conversão seja concluída ou falhe. O período de sondagem padrão é de 10 segundos. Observe que uma conversionOperation pode ser construída a partir da conversionId de uma conversão existente e de um cliente.

AssetConversion conversion = conversionOperation.getFinalResult();
if (conversion.getStatus() == AssetConversionStatus.SUCCEEDED) {
    logger.info("Conversion succeeded: Output written to {}", conversion.getOutputAssetUrl());
} else if (conversion.getStatus() == AssetConversionStatus.FAILED) {
    logger.error("Conversion failed: {} {}", conversion.getError().getCode(), conversion.getError().getMessage());
} else {
    logger.error("Unexpected conversion status: {}", conversion.getStatus());
}

Conversões de lista

Você pode obter informações sobre suas conversões usando o listConversions 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 as URLs de saída de conversões bem-sucedidas iniciadas no último dia.

for (AssetConversion conversion : client.listConversions()) {
    if ((conversion.getStatus() == AssetConversionStatus.SUCCEEDED)
        && (conversion.getCreationTime().isAfter(OffsetDateTime.now().minusDays(1)))) {
        logger.info("Output Asset URL: {}", conversion.getOutputAssetUrl());
    }
}

Criar uma sessão de renderização

Supomos que um RemoteRenderingClient foi 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.

BeginSessionOptions options = new BeginSessionOptions()
    .setMaxLeaseTime(Duration.ofMinutes(30))
    .setSize(RenderingSessionSize.STANDARD);

// A randomly generated GUID is a good choice for a sessionId.
String sessionId = UUID.randomUUID().toString();

SyncPoller<RenderingSession, RenderingSession> startSessionOperation = client.beginSession(sessionId, options);

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

Se uma sessão estiver se aproximando do tempo máximo de concessão, mas você quiser mantê-la ativa, será necessário fazer uma chamada para aumentar o 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 de sessão.

RenderingSession currentSession = client.getSession(sessionId);

Duration sessionTimeAlive = Duration.between(OffsetDateTime.now(), currentSession.getCreationTime()).abs();
if (currentSession.getMaxLeaseTime().minus(sessionTimeAlive).toMinutes() < 2) {
    Duration newLeaseTime = currentSession.getMaxLeaseTime().plus(Duration.ofMinutes(30));
    UpdateSessionOptions longerLeaseOptions = new UpdateSessionOptions().maxLeaseTime(newLeaseTime);
    client.updateSession(sessionId, longerLeaseOptions);
}

Listar sessões de renderização

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

for (RenderingSession session : client.listSessions()) {
    if (session.getStatus() == RenderingSessionStatus.STARTING) {
        logger.info("Session {} is starting.");
    } else if (session.getStatus() == RenderingSessionStatus.READY) {
        logger.info("Session {} is ready at host {}", session.getId(), session.getHostname());
    } else if (session.getStatus() == RenderingSessionStatus.ERROR) {
        logger.error("Session {} encountered an error: {} {}", session.getId(), session.getError().getCode(), session.getError().getMessage());
    } else {
        logger.error("Session {} has unexpected status {}", session.getId(), session.getStatus());
    }
}

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

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 com falha e carregando 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 Error status e carregará um RemoteRenderingServiceError com detalhes.

Próximas etapas

Ler a documentação do produto
Saiba mais sobre os SDKs de runtime:
- .NET: /dotnet/api/microsoft.azure.remoterendering
- C++: /cpp/api/remote-rendering/

Contribuição

Este projeto aceita contribuições e sugestões. A maioria das contribuições exige que você concorde com um CLA (Contrato de Licença do Colaborador) declarando que você tem o direito de nos conceder, e de fato concede, os direitos de usar sua contribuição. Para obter detalhes, visite https://cla.microsoft.com.

Quando você envia uma solicitação de pull, um bot do CLA determina automaticamente se você precisa fornecer um CLA e preencher a PR corretamente (por exemplo, rótulo, comentário). Basta seguir as instruções fornecidas pelo bot. Você só precisará fazer isso uma vez em todos os repositórios que usam nosso CLA.

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para obter mais informações, confira as Perguntas frequentes sobre o Código de Conduta ou contate opencode@microsoft.com para enviar outras perguntas ou comentários.

Impressões

Partilhar via