Biblioteca de cliente do Azure Remote Rendering para Python – versão 1.0.0b2

O Azure Remote Rendering (ARR) é um serviço que lhe permite compor conteúdo 3D interativo 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.

Este SDK suporta a versão "2021-01-01" da API REST Remote Rendering.

NOTA: assim que uma sessão estiver em execução, uma aplicação cliente ligar-se-á à mesma através de 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

Exclusão de Responsabilidade

O suporte de pacotes Python do SDK do Azure para Python 2.7 terminou a 01 de janeiro de 2022. Para obter mais informações e perguntas, veja https://github.com/Azure/azure-sdk-for-python/issues/20691

Introdução

Pré-requisitos

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

Para seguir este tutorial, recomendamos vivamente que associe a sua conta de armazenamento à sua conta ARR.

Instalar o pacote

Instale a biblioteca de cliente do Azure Remote Rendering para Python com pip:

pip install --pre azure-mixedreality-remoterendering

Criar e autenticar o cliente

Construir 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 de 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 para 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, pode conceder 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 Azure AD tokens de um serviço Web que suporte a sua aplicação. Recomendamos este método para aplicações de produção, uma vez que lhe permite evitar incorporar as credenciais para acesso 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 endpoint parâmetro. Os pontos finais disponíveis correspondem às regiões e a escolha do ponto final determina a região na qual o serviço realiza o seu trabalho. Um exemplo é https://remoterendering.eastus2.mixedreality.azure.com.

Pode encontrar uma lista completa dos pontos finais em regiões suportadas na lista de regiões do Azure Remote Rendering.

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 AzureKeyCredential objeto para utilizar um identificador de conta e uma chave de conta para autenticar:

from azure.core.credentials import AzureKeyCredential
from azure.mixedreality.remoterendering import RemoteRenderingClient

account_id = "<ACCOUNT_ID>"
account_domain = "<ACCOUNT_DOMAIN>"
account_key = "<ACCOUNT_KEY>"
arr_endpoint = "<ARR_ENDPOINT>"

key_credential = AzureKeyCredential(account_key)
client = RemoteRenderingClient(
    endpoint=arr_endpoint,
    account_id=account_id,
    account_domain=account_domain,
    credential=key_credential
)

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:

from azure.mixedreality.authentication import MixedRealityStsClient
from azure.mixedreality.remoterendering import RemoteRenderingClient
account_id = "<ACCOUNT_ID>"
account_domain = "<ACCOUNT_DOMAIN>"
account_key = "<ACCOUNT_KEY>"

key_credential = AzureKeyCredential(account_key)

client = MixedRealityStsClient(account_id, account_domain, key_credential)

token = client.get_token()

client = RemoteRenderingClient(
    endpoint=arr_endpoint,
    account_id=account_id,
    account_domain=account_domain,
    credential=token,
)

Autenticar com uma Credencial do Azure Active Directory

A autenticação da chave de conta é utilizada na maioria dos exemplos, mas também pode autenticar com o Azure Active Directory com a biblioteca de Identidade do Azure. Este é o método recomendado para aplicações de produção. Para utilizar o fornecedor [DefaultAzureCredential][defaultazurecredential] mostrado abaixo ou outros fornecedores de credenciais fornecidos com o SDK do Azure, instale o @azure/identity pacote:

Também terá de [registar uma nova aplicação do AAD][register_aad_app] e conceder acesso ao recurso Mixed Reality ao atribuir a função adequada para o serviço Mixed Reality ao principal de serviço.

from azure.identity import DefaultAzureCredential
from azure.mixedreality.remoterendering import RemoteRenderingClient

account_id = "<ACCOUNT_ID>"
account_domain = "<ACCOUNT_DOMAIN>"
default_credential = DefaultAzureCredential()

client = RemoteRenderingClient(
    endpoint=arr_endpoint,
    account_id=account_id,
    account_domain=account_domain,
    credential=default_credential
)

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.

Operações de Long-Running

As operações de execução prolongada são operações que consistem num pedido inicial enviado ao serviço para iniciar uma operação, seguidas de consulta do serviço em intervalos para determinar se a operação foi concluída ou falhou e, se foi bem-sucedida, para obter o resultado.

Os métodos que convertem recursos ou giram sessões de composição são modelados como operações de execução prolongada. O cliente expõe um método que devolve um begin_<method-name> LROPoller ou AsyncLROPoller. Os chamadores devem aguardar que a operação seja concluída ao chamar result() no objeto poller devolvido do begin_<method-name> método . Os fragmentos de código de exemplo são fornecidos para ilustrar a utilização de operações de execução prolongada abaixo.

Exemplos

• Converter um recurso
• Conversões de lista
• Criar uma sessão
• Prolongar o tempo de concessão de uma sessão
• Listar sessões
• Parar uma sessão

Converter um recurso

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 num caminho de "/input/box/box.fbx" do contentor de blobs no URI do contentor de armazenamento especificado, seja convertido.

A conversão de um recurso pode demorar entre segundos e horas. Este código utiliza um poller de conversão existente e consulta regularmente até que a conversão seja concluída ou falhe. O período de consulta predefinido é de 5 segundos. Tenha em atenção que um poller de conversão pode ser obtido com o client.get_asset_conversion_poller com o ID de uma conversão existente e um cliente.

Assim que o processo de conversão terminar, a saída é escrita no contentor de saída especificado num caminho de "/output/<conversion_id>/box.arrAsset". O caminho pode ser obtido a partir da output.asset_uri de uma conversão com êxito.

    conversion_id = str(uuid.uuid4()) # A randomly generated uuid is a good choice for a conversion_id.

    input_settings = AssetConversionInputSettings(
        storage_container_uri="<STORAGE CONTAINER URI>",
        relative_input_asset_path="box.fbx",
        blob_prefix="input/box"
    )
    output_settings = AssetConversionOutputSettings(
        storage_container_uri="<STORAGE CONTAINER URI>",
        blob_prefix="output/"+conversion_id,
        output_asset_filename="convertedBox.arrAsset" #if no output_asset_filename <input asset filename>.arrAsset will be the name of the resulting converted asset
    )
    try:
        conversion_poller = client.begin_asset_conversion(
            conversion_id=conversion_id,
            input_settings=input_settings,
            output_settings=output_settings
        )

        print("Conversion with id:", conversion_id, "created. Waiting for completion.")
        conversion = conversion_poller.result()
        print("conversion output:", conversion.output.asset_uri)

    except Exception as e:
        print("Conversion failed", e)

Conversões de lista

Pode obter informações sobre as conversões com o list_asset_conversions método . Este método pode devolver conversões que ainda não foram iniciadas, conversões em execução e conversões que foram concluídas. Neste exemplo, listamos todas as conversões e id de impressão e o anúncio de criação, bem como os URIs do recurso de saída de conversões bem-sucedidas.

    print("conversions:")
    for c in client.list_asset_conversions():
        print(
            "\t conversion:  id:",
            c.id,
            "status:",
            c.status,
            "created on:",
            c.created_on.strftime("%m/%d/%Y, %H:%M:%S"),
        )
        if c.status == AssetConversionStatus.SUCCEEDED:
            print("\t\tconversion result URI:", c.output.asset_uri)

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 o início de uma nova sessão de composição.

    print("starting rendering session with id:", session_id)
    try:
        session_poller = client.begin_rendering_session(
            session_id=session_id, size=RenderingSessionSize.STANDARD, lease_time_minutes=20
        )
        print(
            "rendering session with id:",
            session_id,
            "created. Waiting for session to be ready.",
        )
        session = session_poller.result()
        print(
            "session with id:",
            session.id,
            "is ready. lease_time_minutes:",
            session.lease_time_minutes,
        )
    except Exception as e:
        print("Session startup failed", e)

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 esta expirar em breve.

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

    session = client.get_rendering_session(session_id)
    if session.lease_time_minutes - session.elapsed_time_minutes < 2:
        session = client.update_rendering_session(
            session_id=session_id, lease_time_minutes=session.lease_time_minutes + 10
        )

Listar sessões

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

    print("sessions:")
    rendering_sessions = client.list_rendering_sessions()
    for session in rendering_sessions:
        print(
            "\t session:  id:",
            session.id,
            "status:",
            session.status,
            "created on:",
            session.created_on.strftime("%m/%d/%Y, %H:%M:%S"),
        )

Parar uma Sessão

O código seguinte irá parar uma sessão em execução com um determinado ID. Uma vez que a execução de sessões incorre em custos contínuos, recomenda-se que pare as sessões que já não são necessárias.

    client.stop_rendering_session(session_id)
    print("session with id:", session_id, "stopped")

Resolução de problemas

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 do cliente e a aguardar pelos resultados do poller irão gerar exceções se o pedido falhar.

Se o recurso numa conversão for inválido, o poller de conversão gerará uma exceção com um erro que contém 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 irá 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 poller apresentará uma exceção que contém detalhes do erro neste caso. Normalmente, os erros de sessão são transitórios e pedir uma nova sessão deve ser bem-sucedido.

Registo

Esta biblioteca utiliza a biblioteca padrão [registo][python_logging] para registo.

As informações básicas sobre sessões HTTP (URLs, cabeçalhos, etc.) são registadas ao INFO nível.

O registo de nível detalhado DEBUG , incluindo os corpos de pedido/resposta e os cabeçalhos não retotados , pode ser ativado no cliente ou por operação com o logging_enable argumento de palavra-chave.

Veja a documentação completa do registo do SDK com exemplos aqui.

Configuração opcional

Os argumentos de palavra-chave opcionais podem ser transmitidos ao nível do cliente e por operação. A documentação de referência azure-core descreve as configurações disponíveis para repetições, registo, protocolos de transporte e muito mais.

Exceções

A biblioteca de cliente Remote Rendering irá gerar exceções definidas no Azure Core.

APIs Assíncronas

Esta biblioteca também inclui uma API assíncrona completa suportada no Python 3.7 ou superior. Para utilizá-lo, primeiro tem de instalar um transporte assíncrono, como o aiohttp. Os clientes assíncrono encontram-se no azure.mixedreality.remoterendering.aio espaço de nomes.

Passos seguintes

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

Contribuir

Agradecemos todas as contribuições e sugestões para este projeto. A maioria das contribuições requerem que celebre um Contrato de Licença de Contribuição (CLA) no qual se declare que tem o direito de conceder e que, na verdade, concede-nos os direitos para utilizar a sua contribuição. Para mais detalhes, visite https://cla.microsoft.com.

Quando submete um pedido Pull, um bot do CLA determina automaticamente se tem de fornecer um CLA e decorar o PR de forma adequada (por exemplo, etiqueta, comentário). Só tem de seguir as instruções fornecidas pelo bot. Apenas terá de fazer isto uma vez em todos os repositórios com o nosso CLA.

Este projeto adotou o Microsoft Open Source Code of Conduct (Código de Conduta do Microsoft Open Source). Para obter mais informações, consulte as FAQ do Código de Conduta ou contacte opencode@microsoft.com com quaisquer perguntas ou comentários adicionais.

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