Biblioteca de clientes do Azure Remote Rendering para .NET – versão 1.1.0

Artigo
04/27/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 em (.net ou (C++).

Documentação do produto

Introdução

Instalar o pacote

Instale a biblioteca de clientes do Azure Realidade Misturada ARR para .NET usando um dos métodos a seguir.

Do Gerenciador de Pacotes do Visual Studio:

Install-Package Azure.MixedReality.RemoteRendering

Da CLI do .NET

dotnet add package Azure.MixedReality.RemoteRendering

Adicione uma referência de pacote:

<PackageReference Include="Azure.MixedReality.RemoteRendering" Version="1.0.0" />

Pré-requisitos

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

Autenticar o cliente

Construir 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 formato "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 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 remoteRenderingEndpoint objeto Uri. Os pontos de extremidade disponíveis correspondem às 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 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 AccountKeyCredential objeto para usar um identificador de conta e uma chave de conta para autenticar:

AzureKeyCredential accountKeyCredential = new AzureKeyCredential(accountKey);

RemoteRenderingClient client = new RemoteRenderingClient(remoteRenderingEndpoint, accountId, accountDomain, accountKeyCredential);

Autenticação com um segredo do cliente do AAD

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

TokenCredential credential = new ClientSecretCredential(tenantId, clientId, clientSecret, new TokenCredentialOptions
{
    AuthorityHost = new Uri($"https://login.microsoftonline.com/{tenantId}")
});

RemoteRenderingClient client = new RemoteRenderingClient(remoteRenderingEndpoint, 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.

Task deviceCodeCallback(DeviceCodeInfo deviceCodeInfo, CancellationToken cancellationToken)
{
    Debug.WriteLine(deviceCodeInfo.Message);
    Console.WriteLine(deviceCodeInfo.Message);
    return Task.FromResult(0);
}

TokenCredential credential = new DeviceCodeCredential(deviceCodeCallback, tenantId, clientId, new TokenCredentialOptions
{
    AuthorityHost = new Uri($"https://login.microsoftonline.com/{tenantId}"),
});

RemoteRenderingClient client = new RemoteRenderingClient(remoteRenderingEndpoint, 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:

TokenCredential credential = new DefaultAzureCredential(includeInteractiveCredentials: true);

RemoteRenderingClient client = new RemoteRenderingClient(remoteRenderingEndpoint, accountId, accountDomain, credential);

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 RemoteRenderingClient(remoteRenderingEndpoint, accountId, accountDomain, 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
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 no URI fornecido, seja convertido.

    AssetConversionInputOptions inputOptions = new AssetConversionInputOptions(storageUri, "box.fbx");
    AssetConversionOutputOptions outputOptions = new AssetConversionOutputOptions(storageUri);
    AssetConversionOptions conversionOptions = new AssetConversionOptions(inputOptions, outputOptions);

    // A randomly generated GUID is a good choice for a conversionId.
    string conversionId = Guid.NewGuid().ToString();

    AssetConversionOperation conversionOperation = client.StartConversion(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 inputStorageUri 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:

    AssetConversionInputOptions input = new AssetConversionInputOptions(inputStorageUri, "bicycle.gltf")
    {
        BlobPrefix = "Bicycle"
    };
    AssetConversionOutputOptions output = new AssetConversionOutputOptions(outputStorageUri)
    {
        BlobPrefix = "ConvertedBicycle"
    };
    AssetConversionOptions conversionOptions = new AssetConversionOptions(inputOptions, outputOptions);

    string conversionId = Guid.NewGuid().ToString();

    AssetConversionOperation conversionOperation = client.StartConversion(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.WaitForCompletionAsync().Result;
    if (conversion.Status == AssetConversionStatus.Succeeded)
    {
        Console.WriteLine($"Conversion succeeded: Output written to {conversion.Output.OutputAssetUri}");
    }
    else if (conversion.Status == AssetConversionStatus.Failed)
    {
        Console.WriteLine($"Conversion failed: {conversion.Error.Code} {conversion.Error.Message}");
    }

Conversões de lista

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.

    foreach (var conversion in client.GetConversions())
    {
        if ((conversion.Status == AssetConversionStatus.Succeeded) && (conversion.CreatedOn > DateTimeOffset.Now.AddDays(-1)))
        {
            Console.WriteLine($"output asset URI: {conversion.Output.OutputAssetUri}");
        }
    }

Criar uma sessã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.

    RenderingSessionOptions options = new RenderingSessionOptions(TimeSpan.FromMinutes(30), RenderingServerSize.Standard);

    // A randomly generated GUID is a good choice for a sessionId.
    string sessionId = Guid.NewGuid().ToString();

    StartRenderingSessionOperation startSessionOperation = client.StartSession(sessionId, options);

    RenderingSession newSession = startSessionOperation.WaitForCompletionAsync().Result;
    if (newSession.Status == RenderingSessionStatus.Ready)
    {
        Console.WriteLine($"Session {sessionId} is ready.");
    }
    else if (newSession.Status == RenderingSessionStatus.Error)
    {
        Console.WriteLine($"Session {sessionId} encountered an error: {newSession.Error.Code} {newSession.Error.Message}");
    }

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

    if (currentSession.MaxLeaseTime - DateTimeOffset.Now.Subtract(currentSession.CreatedOn.Value) < TimeSpan.FromMinutes(2))
    {
        TimeSpan newLeaseTime = currentSession.MaxLeaseTime.Value.Add(TimeSpan.FromMinutes(30));

        UpdateSessionOptions longerLeaseSettings = new UpdateSessionOptions(newLeaseTime);

        client.UpdateSession(sessionId, longerLeaseSettings);
    }

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.

    foreach (var properties in client.GetSessions())
    {
        if (properties.Status == RenderingSessionStatus.Starting)
        {
            Console.WriteLine($"Session \"{properties.SessionId}\" is starting.");
        }
        else if (properties.Status == RenderingSessionStatus.Ready)
        {
            Console.WriteLine($"Session \"{properties.SessionId}\" is ready at host {properties.Host}");
        }
    }

Parar uma sessão

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

    client.StopSession(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 Erro status e carregará um RemoteRenderingServiceError com detalhes.

Próximas etapas

Ler a documentação do produto
Saiba mais sobre os SDKs de runtime:
- .NET: https://docs.microsoft.com/dotnet/api/microsoft.azure.remoterendering
- C++: https://docs.microsoft.com/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.

Compartilhar via