Sviluppare con le API di Servizi multimediali v3Develop with Media Services v3 APIs

logo di servizi multimediali v3media services logo v3


Gli sviluppatori possono usare l'API REST Servizi multimediali o le librerie client che consentono di interagire con l'API REST per creare, gestire e mantenere facilmente flussi di lavoro multimediali personalizzati.As a developer, you can use Media Services REST API or client libraries that allow you to interact with the REST API to easily create, manage, and maintain custom media workflows. L'API Servizi multimediali v3 è basata sulla specifica OpenAPI (in precedenza nota come Swagger).The Media Services v3 API is based on the OpenAPI specification (formerly known as a Swagger).

Questo articolo descrive le regole applicabili alle entità e alle API quando vengono eseguite attività di sviluppo con Servizi multimediali v3.This article discusses rules that apply to entities and APIs when you develop with Media Services v3.

Accesso all'API di Servizi multimediali di AzureAccessing the Azure Media Services API

Per essere autorizzati ad accedere alle risorse e all'API di Servizi multimediali, è innanzitutto necessario essere autenticati.To be authorized to access Media Services resources and the Media Services API, you must first be authenticated. Servizi multimediali supporta l'autenticazione basata su Azure Active Directory (Azure AD).Media Services supports Azure Active Directory (Azure AD)-based authentication. Esistono due opzioni di autenticazione comuni:Two common authentication options are:

  • Autenticazione tramite entità servizio: usata per autenticare un servizio, ad esempio app Web, app per le funzioni, app per la logica, API e microservizi.Service principal authentication: Used to authenticate a service (for example: web apps, function apps, logic apps, API, and microservices). Le applicazioni che in genere usano questo metodo di autenticazione sono app che eseguono servizi daemon, servizi di livello intermedio o processi pianificati.Applications that commonly use this authentication method are apps that run daemon services, middle-tier services, or scheduled jobs. Per le app Web, ad esempio, deve essere sempre presente un livello intermedio che si connette a Servizi multimediali con un'entità servizio.For example, for web apps there should always be a mid-tier that connects to Media Services with a Service Principal.
  • Autenticazione utente: usata per autenticare una persona che usa l'app per interagire con le risorse di Servizi multimediali.User authentication: Used to authenticate a person who is using the app to interact with Media Services resources. L'app interattiva deve prima richiedere all'utente le credenziali.The interactive app should first prompt the user for the user's credentials. Un esempio è un'app della console di gestione usata dagli utenti autorizzati per monitorare i processi di codifica o lo streaming live.An example is a management console app used by authorized users to monitor encoding jobs or live streaming.

Per l'API di Servizi multimediali è necessario che l'utente o l'app che effettua le richieste all'API REST possa accedere alla risorsa dell'account di Servizi multimediali e usi un ruolo Collaboratore o Proprietario.The Media Services API requires that the user or app making the REST API requests have access to the Media Services account resource and use a Contributor or Owner role. È possibile accedere all'API con il ruolo Lettore, ma saranno disponibili solo operazioni Get o List.The API can be accessed with the Reader role but only Get or List operations will be available.Per altre informazioni, vedere controllo degli accessi in base al ruolo di Azure (RBAC di Azure) per gli account di servizi multimediali. For more information, see Azure role-based access control (Azure RBAC) for Media Services accounts.

Invece di creare un'entità servizio, è consigliabile usare identità gestite per le risorse di Azure per accedere all'API di Servizi multimediali tramite Azure Resource Manager.Instead of creating a service principal, consider using managed identities for Azure resources to access the Media Services API through Azure Resource Manager. Per altre informazioni sulle identità gestite per le risorse di Azure, vedere Informazioni sulle identità gestite per le risorse di Azure.To learn more about managed identities for Azure resources, see What is managed identities for Azure resources.

Entità servizio di Azure ADAzure AD service principal

L'app Azure AD e l'entità servizio devono trovarsi nello stesso tenant.The Azure AD app and service principal should be in the same tenant. Dopo aver creato l'app, concedere al ruolo Collaboratore o Proprietario dell'app l'accesso all'account di Servizi multimediali.After you create the app, give the app Contributor or Owner role access to the Media Services account.

Se non si è certi di avere le autorizzazioni necessarie per creare un'app Azure AD, vedere Autorizzazioni necessarie.If you're not sure whether you have permissions to create an Azure AD app, see Required permissions.

Nella figura seguente i numeri rappresentano il flusso delle richieste in ordine cronologico:In the following figure, the numbers represent the flow of the requests in chronological order:

Autenticazione di app di livello intermedio con AAD da un'API Web

  1. Un'app di livello intermedio richiede un token di accesso di Azure AD con i parametri seguenti:A middle-tier app requests an Azure AD access token that has the following parameters:

    • Endpoint tenant di Azure AD.Azure AD tenant endpoint.
    • URI di risorsa per Servizi multimediali.Media Services resource URI.
    • URI di risorsa per Servizi multimediali REST.Resource URI for REST Media Services.
    • Valori dell'app Azure AD: ID client e segreto client.Azure AD app values: the client ID and client secret.

    Per ottenere tutti i valori necessari, vedere Accedere all'API di Servizi multimediali di Azure.To get all the needed values, see Access Azure Media Services API.

  2. Il token di accesso di Azure AD viene inviato al livello intermedio.The Azure AD access token is sent to the middle tier.

  3. Il livello intermedio invia una richiesta all'API REST di Servizi multimediali di Azure con il token di Azure AD.The middle tier sends request to the Azure Media REST API with the Azure AD token.

  4. Il livello intermedio ottiene nuovamente i dati da Servizi multimediali.The middle tier gets back the data from Media Services.

EsempiSamples

Vedere gli esempi seguenti che illustrano come connettersi con l'entità servizio di Azure AD:See the following samples that show how to connect with Azure AD service principal:

Convenzioni di denominazioneNaming conventions

I nomi delle risorse di Servizi multimediali di Azure v3 (ad esempio, asset, processi e trasformazioni) sono soggetti ai vincoli di denominazione di Azure Resource Manager.Azure Media Services v3 resource names (for example, Assets, Jobs, Transforms) are subject to Azure Resource Manager naming constraints. In conformità con Azure Resource Manager, i nomi delle risorse sono sempre univoci.In accordance with Azure Resource Manager, the resource names are always unique. Di conseguenza, per i nomi delle risorse è possibile usare qualsiasi stringa di identificatore univoco (ad esempio, GUID).Thus, you can use any unique identifier strings (for example, GUIDs) for your resource names.

I nomi delle risorse di Servizi multimediali non possono includere "<", ">", "%", "&", ":", "\", "?", "/", "*", "+", ".", virgolette singole o caratteri di controllo.Media Services resource names can't include: '<', '>', '%', '&', ':', '\', '?', '/', '*', '+', '.', the single quote character, or any control characters. Sono consentiti tutti gli altri caratteri.All other characters are allowed. La lunghezza massima di un nome di risorsa è di 260 caratteri.The max length of a resource name is 260 characters.

Per altre informazioni sulla denominazione di Azure Resource Manager, vedere Requisiti di denominazione e Convenzioni di denominazione.For more information about Azure Resource Manager naming, see Naming requirements and Naming conventions.

Nomi di file/BLOB all'interno di un assetNames of files/blobs within an asset

I nomi di file/BLOB all'interno di un asset devono rispettare i requisiti del nome del BLOB e i requisiti del nome NTFS.The names of files/blobs within an asset must follow both the blob name requirements and the NTFS name requirements. Questi requisiti sono necessari perché i file possano essere copiati dall'archiviazione BLOB in un disco NTFS locale per l'elaborazione.The reason for these requirements is the files can get copied from blob storage to a local NTFS disk for processing.

Operazioni a esecuzione prolungataLong-running operations

Le operazioni contrassegnate con x-ms-long-running-operation nei file Swagger di Servizi multimediali di Azure sono a esecuzione prolungata.The operations marked with x-ms-long-running-operation in the Azure Media Services swagger files are long running operations.

Per informazioni dettagliate su come tenere traccia delle operazioni asincrone di Azure, vedere Operazioni asincrone.For details about how to track asynchronous Azure operations, see Async operations.

Servizi multimediali include le seguenti operazioni a esecuzione prolungata:Media Services has the following long-running operations:

Al termine dell'invio di un'operazione di lunga durata, viene visualizzato il valore "201 creato" ed è necessario eseguire il polling del completamento dell'operazione utilizzando l'ID operazione restituito.On successful submission of a long operation, you receive a '201 Created' and must poll for operation completion using the returned operation ID.

L'articolo Tenere traccia delle operazioni asincrone spiega in maniera approfondita come tenere traccia dello stato delle operazioni asincrone di Azure tramite i valori restituiti nella risposta.The track asynchronous Azure operations article explains in depth how to track the status of asynchronous Azure operations through values returned in the response.

Per un determinato evento live o per qualsiasi output live associato è supportata una sola operazione a esecuzione prolungata.Only one long-running operation is supported for a given Live Event or any of its associated Live Outputs. Dopo l'avvio, un'operazione a esecuzione prolungata deve essere completata prima di avviare una successiva operazione a esecuzione prolungata per lo stesso evento live o per qualsiasi output live associato.Once started, a long running operation must complete before starting a subsequent long-running operation on the same LiveEvent or any associated Live Outputs. Per gli eventi live con più output live, è necessario attendere il completamento di un'operazione a esecuzione prolungata per un output live prima di attivare un'operazione a esecuzione prolungata per un altro output live.For Live Events with multiple Live Outputs, you must await the completion of a long running operation on one Live Output before triggering a long running operation on another Live Output.

SDKSDKs

Nota

Gli SDK di Servizi multimediali di Azure v3 non sono garantiti come thread-safe.The Azure Media Services v3 SDKs aren't guaranteed to be thread-safe. Quando si sviluppa un'app multithreading, è necessario aggiungere la propria logica di sincronizzazione thread per proteggere il client oppure usare un nuovo oggetto AzureMediaServicesClient per ogni thread.When developing a multi-threaded app, you should add your own thread synchronization logic to protect the client or use a new AzureMediaServicesClient object per thread. È anche necessario prestare attenzione ai problemi di multithreading introdotti da oggetti facoltativi forniti dal codice al client (ad esempio, un'istanza di HttpClient in .NET).You should also be careful of multi-threading issues introduced by optional objects provided by your code to the client (like an HttpClient instance in .NET).

SDKSDK Informazioni di riferimentoReference
.NET SDK.NET SDK Informazioni di riferimento su .NET.NET ref
SDK per JavaJava SDK Informazioni di riferimento su JavaJava ref
Python SDKPython SDK Informazioni di riferimento su PythonPython ref
Node.js SDKNode.js SDK Informazioni di riferimento su Node.jsNode.js ref
Go SDKGo SDK Informazioni di riferimento su GoGo ref
Ruby SDKRuby SDK

Vedere ancheSee also

Explorer di Servizi multimediali di AzureAzure Media Services Explorer

Azure Media Services Explorer (AMSE) è uno strumento disponibile per i clienti di Windows che vogliono informazioni su Servizi multimediali.Azure Media Services Explorer (AMSE) is a tool available to Windows customers who want to learn about Media Services. AMSE è un'applicazione Winforms/C# che esegue operazioni di caricamento, download, codifica, streaming di VOD e contenuti live con Servizi multimediali.AMSE is a Winforms/C# application that does upload, download, encode, stream VOD and live content with Media Services. Lo strumento AMSE è stato pensato per i clienti che vogliono testare Servizi multimediali senza scrivere codice.The AMSE tool is for clients who want to test Media Services without writing any code. Il codice AMSE viene fornito come risorsa per i clienti che vogliono sviluppare con Servizi multimediali.The AMSE code is provided as a resource for customers who want to develop with Media Services.

AMSE è un progetto open source il cui supporto viene fornito dalla community (i problemi possono essere segnalati a https://github.com/Azure/Azure-Media-Services-Explorer/issues).AMSE is an Open Source project, support is provided by the community (issues can be reported to https://github.com/Azure/Azure-Media-Services-Explorer/issues). Questo progetto ha adottato il Codice di comportamento di Microsoft per l'open source.This project has adopted the Microsoft Open Source Code of Conduct. Per altre informazioni, vedere Domande frequenti sul codice di comportamento oppure scrivere a opencode@microsoft.com per qualsiasi altro commento o domanda.For more information, see the Code of Conduct FAQ or contact opencode@microsoft.com with any other questions or comments.

Applicazione di filtri, ordinamento e restituzione di più pagine delle entità di Servizi multimedialiFiltering, ordering, paging of Media Services entities

Vedere Applicazione di filtri, ordinamento e paging delle entità di Servizi multimediali di Azure.See Filtering, ordering, paging of Azure Media Services entities.

Porre domande, fornire feedback, ottenere aggiornamentiAsk questions, give feedback, get updates

Consultare l'articolo Community di Servizi multimediali di Azure per esaminare i diversi modi in cui è possibile porre domande, fornire feedback e ottenere aggiornamenti su Servizi multimediali.Check out the Azure Media Services community article to see different ways you can ask questions, give feedback, and get updates about Media Services.

Vedere ancheSee also

Per ottenere tutti i valori necessari, vedere Accedere all'API di Servizi multimediali di Azure.To get all the needed values, see Access Azure Media Services API.

Passaggi successiviNext steps