Libreria client di Azure Rendering remoto per Python - versione 1.0.0b2

Rendering remoto di Azure è un servizio che consente di eseguire il rendering di contenuti 3D interattivi di alta qualità nel cloud e di trasmetterli in streaming in tempo reale ai dispositivi come HoloLens 2.

Questo SDK offre funzionalità per convertire gli asset nel formato previsto dal runtime e anche per gestire la durata delle sessioni di rendering remoto.

Questo SDK supporta la versione "2021-01-01" dell'API REST Rendering remoto.

NOTA: quando una sessione è in esecuzione, un'applicazione client si connetterà usando uno degli "SDK di runtime". Questi SDK sono progettati per supportare al meglio le esigenze di un'applicazione interattiva che esegue il rendering 3d. Sono disponibili in (.net o (C++).

Documentazione del prodotto

Dichiarazione di non responsabilità

Il supporto dei pacchetti Python di Azure SDK per Python 2.7 è terminato il 01 gennaio 2022. Per altre informazioni e domande, fare riferimento a https://github.com/Azure/azure-sdk-for-python/issues/20691

Introduzione

Prerequisiti

Per usare questo pacchetto sono necessari una sottoscrizione di Azure e un account azure Rendering remoto.

Per seguire questa esercitazione, è consigliabile collegare l'account di archiviazione con l'account ARR.

Installare il pacchetto

Installare la libreria client di Azure Rendering remoto per Python con pip:

pip install --pre azure-mixedreality-remoterendering

Creare e autenticare il client

La creazione di un client di rendering remoto richiede un account autenticato e un endpoint di rendering remoto. Per un account creato nell'area eastus, il dominio dell'account avrà il formato "eastus.mixedreality.azure.com". Esistono diverse forme di autenticazione:

• Autenticazione della chiave dell'account
  • Le chiavi dell'account consentono di iniziare rapidamente a usare Azure Rendering remoto. Tuttavia, prima di distribuire l'applicazione nell'ambiente di produzione, è consigliabile aggiornare l'app per usare l'autenticazione di Azure AD.
• Autenticazione del token di Azure Active Directory (AD)
  • Se si sta creando un'applicazione aziendale e l'azienda usa Azure AD come sistema di identità, è possibile usare l'autenticazione di Azure AD basata sull'utente nell'app. Si concede quindi l'accesso agli account azure Rendering remoto usando i gruppi di sicurezza di Azure AD esistenti. È anche possibile concedere l'accesso direttamente agli utenti dell'organizzazione.
  • In caso contrario, è consigliabile ottenere i token di Azure AD da un servizio Web che supporta l'app. È consigliabile usare questo metodo per le applicazioni di produzione perché consente di evitare di incorporare le credenziali per l'accesso nell'applicazione client.

Per istruzioni dettagliate e informazioni, vedere qui .

In tutti gli esempi seguenti il client viene costruito con un endpoint parametro . Gli endpoint disponibili corrispondono alle aree e la scelta dell'endpoint determina l'area in cui il servizio esegue il proprio lavoro. Un esempio è https://remoterendering.eastus2.mixedreality.azure.com.

Un elenco completo degli endpoint nelle aree supportate è disponibile nell'elenco di aree di Azure Rendering remoto.

NOTA: per la conversione degli asset, è preferibile selezionare un'area vicina alla risorsa di archiviazione contenente gli asset.

NOTA: per il rendering, è consigliabile selezionare l'area più vicina ai dispositivi che usano il servizio. Il tempo impiegato per comunicare con il server influisce sulla qualità dell'esperienza.

Autenticazione con l'autenticazione con chiave dell'account

Usare l'oggetto per usare un identificatore dell'account AzureKeyCredential e una chiave dell'account per l'autenticazione:

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
)

Autenticazione con un token di accesso statico

È possibile passare un token di accesso Realtà mista come un AccessToken token di accesso recuperato in precedenza dal servizio stS Realtà mista da usare con una libreria client Realtà mista:

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

Autenticazione con credenziali di Azure Active Directory

L'autenticazione della chiave dell'account viene usata nella maggior parte degli esempi, ma è anche possibile eseguire l'autenticazione con Azure Active Directory usando la libreria di identità di Azure. Questo è il metodo consigliato per le applicazioni di produzione. Per usare il provider [DefaultAzureCredential][defaultazurecredential] illustrato di seguito o altri provider di credenziali forniti con Azure SDK, installare il @azure/identity pacchetto:

Sarà anche necessario [registrare una nuova applicazione AAD][register_aad_app] e concedere l'accesso alla risorsa Realtà mista assegnando il ruolo appropriato per il servizio Realtà mista all'entità servizio.

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
)

Concetti chiave

RemoteRenderingClient

RemoteRenderingClient è la libreria client usata per accedere a RemoteRenderingService. Fornisce metodi per creare e gestire le conversioni degli asset e le sessioni di rendering.

Operazioni di Long-Running

Le operazioni a esecuzione prolungata sono operazioni costituite da una richiesta iniziale inviata al servizio per avviare un'operazione, seguita dal polling del servizio a intervalli per determinare se l'operazione è stata completata o non riuscita e, se ha avuto esito positivo, per ottenere il risultato.

I metodi che convertono gli asset o le sessioni di rendering vengono modellati come operazioni a esecuzione prolungata. Il client espone un metodo che restituisce un begin_<method-name> LROPoller o AsyncLROPoller. I chiamanti devono attendere il completamento dell'operazione chiamando result() sull'oggetto poller restituito dal begin_<method-name> metodo . Di seguito vengono forniti frammenti di codice di esempio per illustrare l'uso di operazioni a esecuzione prolungata

Esempio

• Convertire un asset
• Conversioni di elenco
• Creare una sessione
• Estendere il tempo di lease di una sessione
• Elencare le sessioni
• Arrestare una sessione

Convertire un asset

Si presuppone che un RemoteRenderingClient sia stato costruito come descritto nella sezione Autenticare il client . Il frammento di codice seguente descrive come richiedere che "box.fbx", trovato in un percorso di "/input/box/box.fbx" del contenitore BLOB in corrispondenza dell'URI del contenitore di archiviazione specificato, viene convertito.

La conversione di un asset può richiedere da pochi secondi a ore. Questo codice usa regolarmente un poller di conversione esistente ed esegue il polling fino al termine o all'esito negativo della conversione. Il periodo di polling predefinito è 5 secondi. Si noti che un poller di conversione può essere recuperato usando il client.get_asset_conversion_poller usando l'ID di una conversione esistente e un client.

Al termine del processo di conversione, l'output viene scritto nel contenitore di output specificato in un percorso "/output/<conversion_id>/box.arrAsset". Il percorso può essere recuperato dalla output.asset_uri di una conversione riuscita.

    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)

Conversioni di elenco

È possibile ottenere informazioni sulle conversioni usando il list_asset_conversions metodo . Questo metodo può restituire conversioni che devono ancora essere avviate, conversioni che sono in esecuzione e conversioni che sono state completate. In questo esempio vengono elencate tutte le conversioni e l'ID di stampa e l'annuncio di creazione, nonché gli URI degli asset di output delle conversioni riuscite.

    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)

Creare una sessione

Si presuppone che un RemoteRenderingClient sia stato costruito come descritto nella sezione Autenticare il client . Il frammento di codice seguente descrive come richiedere l'avvio di una nuova sessione di rendering.

    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)

Estendere il tempo di lease di una sessione

Se una sessione si avvicina al tempo di lease massimo, ma si vuole mantenerla attiva, sarà necessario effettuare una chiamata per aumentare il tempo di lease massimo. In questo esempio viene illustrato come eseguire una query sulle proprietà correnti e quindi estendere il lease se scadrà a breve.

NOTA: gli SDK di runtime offrono anche questa funzionalità e, in molti scenari tipici, è possibile usarli per estendere il lease di sessione.

    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
        )

Elencare le sessioni

È possibile ottenere informazioni sulle sessioni usando il list_rendering_sessions metodo del client. Questo metodo può restituire sessioni che devono ancora essere avviate e sessioni pronte.

    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"),
        )

Arrestare una sessione

Il codice seguente arresterà una sessione in esecuzione con id specificato. Poiché le sessioni in esecuzione comportano costi continui, è consigliabile arrestare le sessioni che non sono più necessarie.

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

Risoluzione dei problemi

Per consigli generali sulla risoluzione dei problemi relativi alle Rendering remoto di Azure, vedere la pagina Risoluzione dei problemi per il rendering remoto in docs.microsoft.com.

I metodi client e l'attesa dei risultati del poller genereranno eccezioni se la richiesta non è riuscita.

Se l'asset in una conversione non è valido, il poller di conversione genererà un'eccezione con un errore contenente i dettagli. Dopo che il servizio di conversione è in grado di elaborare il file, un <file assetName.result.json> verrà scritto nel contenitore di output. Se l'asset di input non è valido, il file conterrà una descrizione più dettagliata del problema.

Analogamente, a volte quando viene richiesta una sessione, la sessione termina con uno stato di errore. Il poller genererà un'eccezione contenente i dettagli dell'errore in questo caso. Gli errori della sessione sono in genere temporanei e la richiesta di una nuova sessione deve essere completata.

Registrazione

Questa libreria usa la libreria standard [logging][python_logging] per la registrazione.

Le informazioni di base sulle sessioni HTTP (URL, intestazioni e così via) vengono registrate a INFO livello.

La registrazione dettagliata DEBUG a livello, inclusi i corpi di richiesta/risposta e le intestazioni non contrassegnate , può essere abilitata nel client o per operazione con l'argomento logging_enable parola chiave.

Vedere la documentazione completa sulla registrazione sdk con esempi qui.

Configurazione facoltativa

Gli argomenti delle parole chiave facoltativi possono essere passati al client e a livello di operazione. La documentazione di riferimento di azure-core descrive le configurazioni disponibili per tentativi, registrazione, protocolli di trasporto e altro ancora.

Eccezioni

La libreria client Rendering remoto genererà eccezioni definite in Azure Core.

API asincrone

Questa libreria include anche un'API asincrona completa supportata in Python 3.7+. Per usarlo, è prima necessario installare un trasporto asincrono, ad esempio aiohttp. I client asincroni vengono trovati nello azure.mixedreality.remoterendering.aio spazio dei nomi.

Passaggi successivi

• Leggere la documentazione del prodotto
• Informazioni sugli SDK di runtime:
  • .NET: /dotnet/api/microsoft.azure.remoterendering
  • C++: /cpp/api/remote-rendering/

Contributo

In questo progetto sono benvenuti i contributi e i suggerimenti. Per la maggior parte dei contenuti è necessario sottoscrivere un contratto di licenza di collaborazione (CLA, Contributor License Agreement) che stabilisce che l'utente ha il diritto di concedere, e di fatto concede a Microsoft i diritti d'uso del suo contributo. Per informazioni dettagliate, vedere https://cla.microsoft.com.

Quando si invia una richiesta pull, un bot CLA determina automaticamente se è necessario specificare un contratto CLA e completare la richiesta pull in modo appropriato (ad esempio con un'etichetta e un commento). Seguire le istruzioni specificate dal bot. È sufficiente eseguire questa operazione una sola volta per tutti i repository che usano il contratto CLA Microsoft.

Questo progetto ha adottato il Codice di comportamento di Microsoft per l'open source. Per altre informazioni, vedere Code of Conduct FAQ (Domande frequenti sul Codice di comportamento Open Source di Microsoft) oppure contattare opencode@microsoft.com per eventuali altre domande o commenti.

Per contribuire a questa libreria, leggere la guida ai contributi per altre informazioni su come compilare e testare il codice.