Accesso all'API di Servizi multimediali di Azure con l'autenticazione di Azure ADAccess the Azure Media Services API with Azure AD authentication

L'API di Servizi multimediali di Azure è di tipo RESTful.The Azure Media Services API is a RESTful API. È possibile usarla per eseguire operazioni sulle risorse multimediali tramite un'API REST o tramite gli SDK client disponibili.You can use it to perform operations on media resources by using a REST API or by using available client SDKs. Servizi multimediali di Azure offre un SDK client di Servizi multimediali per Microsoft .NET.Azure Media Services offers a Media Services client SDK for Microsoft .NET. 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. Il servizio REST di Servizi multimediali di Azure richiede che l'utente o l'applicazione che invia le richieste all'API REST abbia almeno il ruolo di Collaboratore o Proprietario per poter accedere alle risorse.The Azure Media REST service requires that the user or application that makes the REST API requests have either the Contributor or Owner role to access the resources. Per altre informazioni, vedere Introduzione al controllo degli accessi in base al ruolo nel portale di Azure.For more information, see Get started with Role-Based Access Control in the Azure portal.

Importante

Attualmente, Servizi multimediali supporta il modello di autenticazione del Servizio di controllo di accesso Azure.Currently, Media Services supports the Azure Access Control service authentication model. L'autorizzazione di Controllo di accesso, tuttavia, verrà dichiarata deprecata il 1° giugno 2018.However, Access Control authorization will be deprecated on June 1, 2018. È consigliabile eseguire la migrazione all'autenticazione di Azure AD il più presto possibile.We recommend that you migrate to the Azure AD authentication model as soon as possible.

Questo documento offre una panoramica su come accedere all'API di Servizi multimediali tramite l'API REST o .NET.This document gives an overview of how to access the Media Services API by using REST or .NET APIs.

Controllo di accessoAccess control

Perché la richiesta REST di Servizi multimediali di Azure abbia esito positivo, l'utente chiamante deve avere il ruolo di Collaboratore o Proprietario per l'account di Servizi multimediali al quale sta tentando di accedere.For the Azure Media REST request to succeed, the calling user must have a Contributor or Owner role for the Media Services account it is trying to access.
Solo un utente con il ruolo di Proprietario può concedere a nuovi utenti o a nuove app l'accesso (account) alle risorse multimediali.Only a user with the Owner role can give media resource (account) access to new users or apps. Il ruolo di Collaboratore consente di accedere solo alla risorsa multimediale.The Contributor role can access only the media resource. Le richieste non autorizzate hanno esito negativo e restituiscono il codice di stato 401.Unauthorized requests fail, with status code of 401. Se viene visualizzato questo codice di errore, verificare se all'utente è stato assegnato il ruolo di Collaboratore o Proprietario per l'account di Servizi multimediali.If you see this error code, check whether your user has the Contributor or Owner role assigned for the user's Media Services account. Questa operazione può essere eseguita nel portale di Azure.You can check this in the Azure portal. Cercare l'account dei servizi multimediali e quindi fare clic sulla scheda Controllo di accesso.Search for your media account, and then click the Access control tab.

Scheda Controllo di accesso

Tipi di autenticazioneTypes of authentication

Quando si utilizza l'autenticazione di Azure AD con Servizi multimediali di Azure, sono disponibili due opzioni di autenticazione:When you use Azure AD authentication with Azure Media Services, you have two authentication options:

  • Autenticazione utente.User authentication. Consente di eseguire l'autenticazione di una persona che usa l'app per interagire con le risorse di Servizi multimediali.Authenticate a person who is using the app to interact with Media Services resources. L'applicazione interattiva deve prima richiedere all'utente le credenziali.The interactive application 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.
  • Autenticazione basata su entità servizio.Service principal authentication. Consente di eseguire l'autenticazione di un servizio.Authenticate a service. 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. Esempi sono le app Web, le app per le funzioni, le app per la logica, l'interfaccia API e i microservizi.Examples are web apps, function apps, logic apps, API, and microservices.

Autenticazione utenteUser authentication

Le applicazioni che devono usare il metodo di autenticazione utente sono app native di gestione o monitoraggio: app per dispositivi mobili, app di Windows e app console.Applications that should use the user authentication method are management or monitoring native apps: mobile apps, Windows apps, and Console applications. Questo tipo di soluzione è utile quando si desidera un'interazione umana con il servizio in uno degli scenari seguenti:This type of solution is useful when you want human interaction with the service in one of the following scenarios:

  • Dashboard di monitoraggio per i processi di codifica.Monitoring dashboard for your encoding jobs.
  • Dashboard di monitoraggio per lo streaming live.Monitoring dashboard for your live streams.
  • Applicazione di gestione per gli utenti di computer desktop o di dispositivi mobili per amministrare le risorse in un account di Servizi multimediali.Management application for desktop or mobile users to administer resources in a Media Services account.

Nota

Questo metodo di autenticazione non deve essere usato con le applicazioni per consumatori.This authentication method should not be used for consumer-facing applications.

Un'applicazione nativa deve innanzitutto acquisire un token di accesso da Azure AD e quindi usarlo quando si inviano richieste HTTP all'API REST di Servizi multimediali.A native application must first acquire an access token from Azure AD, and then use it when you make HTTP requests to the Media Services REST API. Aggiungere il token di accesso all'intestazione della richiesta.Add the access token to the request header.

Nel diagramma seguente viene illustrato un tipico flusso interattivo di autenticazione di un'applicazione:The following diagram shows a typical interactive application authentication flow:

Diagramma di app native

Nel diagramma precedente i numeri rappresentano il flusso delle richieste in ordine cronologico.In the preceding diagram, the numbers represent the flow of the requests in chronological order.

Nota

Quando si usa il metodo di autenticazione utente, tutte le app condividono gli stessi ID client (predefinito) e URI di reindirizzamento dell'applicazione nativa.When you use the user authentication method, all apps share the same (default) native application client ID and native application redirect URI.

  1. Richiedere le credenziali all'utente.Prompt a user for credentials.
  2. Richiedere un token di accesso di Azure AD con i parametri seguenti:Request an Azure AD access token with the following parameters:

    • Endpoint tenant di Azure AD.Azure AD tenant endpoint.

      Le informazioni sul tenant possono essere recuperate dal portale di Azure.The tenant information can be retrieved from the Azure portal. Posizionare il cursore sul nome dell'utente connesso nell'angolo in alto a destra.Place your cursor over the name of the signed-in user in the top right corner.

    • URI di risorsa per Servizi multimediali.Media Services resource URI.

      Questo URI è identico a quello degli account di Servizi multimediali inclusi nello stesso ambiente Azure, ad esempio https://rest.media.azure.net.This URI is the same for Media Services accounts that are in the same Azure environment (for example, https://rest.media.azure.net).

    • ID client dell'applicazione Servizi multimediali (nativa).Media Services (native) application client ID.

    • URI di reindirizzamento dell'applicazione Servizi multimediali (nativa).Media Services (native) application redirect URI.
    • URI di risorsa per Servizi multimediali REST.Resource URI for REST Media Services.

      L'URI rappresenta l'endpoint API REST, ad esempio https://test03.restv2.westus.media.azure.net/api/.The URI represents the REST API endpoint (for example, https://test03.restv2.westus.media.azure.net/api/).

      Per ottenere i valori di questi parametri, vedere Uso del portale di Azure per accedere alle impostazioni di autenticazione di Azure AD usando l'opzione di autenticazione utente.To get values for these parameters, see Use the Azure portal to access Azure AD authentication settings using the user authentication option.

  3. Il token di accesso di Azure AD viene inviato al client.The Azure AD access token is sent to the client.

  4. Il client invia una richiesta all'API REST di Servizi multimediali di Azure con il token di accesso di Azure AD.The client sends a request to the Azure Media REST API with the Azure AD access token.
  5. Il client ottiene nuovamente i dati da Servizi multimediali.The client gets back the data from Media Services.

Per informazioni su come usare l'autenticazione di Azure AD per comunicare con le richieste REST tramite l'SDK del client .NET di Servizi multimediali, vedere Uso dell'autenticazione Azure AD per accedere all'API di Servizi multimediali con .NET.For information about how to use Azure AD authentication to communicate with REST requests by using the Media Services .NET client SDK, see Use Azure AD authentication to access the Media Services API with .NET.

Se non si usa l'SDK del client .NET di Servizi multimediali , è necessario creare manualmente una richiesta di token di accesso di Azure AD tramite i parametri descritti nel passaggio 2.If you are not using the Media Services .NET client SDK, you must manually create an Azure AD access token request by using the parameters described in step 2. Per altre informazioni, vedere Come usare Azure AD Authentication Library per ottenere il token di Azure AD.For more information, see How to use the Azure AD Authentication Library to get the Azure AD token.

Autenticazione di un'entità servizioService principal authentication

Le applicazioni che usano in genere questo metodo di autenticazione sono app che eseguono servizi di livello intermedio e processi pianificati: app Web, app per le funzioni, app per la logica, API e microservizi.Applications that commonly use this authentication method are apps that run middle-tier services and scheduled jobs: web apps, function apps, logic apps, APIs, and microservices. Questo metodo di autenticazione è anche adatto per le applicazioni interattive in cui è possibile usare un account del servizio per gestire le risorse.This authentication method also is suitable for interactive applications in which you might want to use a service account to manage resources.

Quando si usa il metodo di autenticazione basato sull'entità servizio per compilare scenari di consumer, l'autenticazione è gestita in genere nel livello intermedio (tramite alcune API) e non direttamente in un'applicazione desktop o per dispositivi mobili.When you use the service principal authentication method to build consumer scenarios, authentication typically is handled in the middle tier (through some API) and not directly in a mobile or desktop application.

Per usare questo metodo, creare un'applicazione Azure AD e l'entità servizio nel relativo tenant.To use this method, create an Azure AD application and service principal in its own tenant. Dopo aver creato l'applicazione, è possibile assegnare all'app l'accesso associato al ruolo di Collaboratore o Proprietario all'account di Servizi multimediali.After you create the application, give the app Contributor or Owner role access to the Media Services account. È possibile eseguire questa operazione dal portale di Azure mediante l'interfaccia della riga di comando di Azure o uno script di PowerShell.You can do this in the Azure portal, by using Azure CLI, or with a PowerShell script. È anche possibile usare un'applicazione Azure AD esistente.You also can use an existing Azure AD application. Per registrare e gestire l'app e l'entità servizio di Azure AD accedere al portale di AzureYou can register and manage your Azure AD app and service principal in the Azure portal. oppure usare l'interfaccia della riga di comando di Azure 2.0 o PowerShell.You also can do this by using Azure CLI 2.0 or PowerShell.

App di livello intermedio

Dopo aver creato l'applicazione Azure AD, si otterranno i valori per le impostazioni riportate di seguito.After you create your Azure AD application, you get values for the following settings. Per l'autenticazione sono necessari i valori seguenti:You need these values for authentication:

  • ID ClientClient ID
  • Segreto clientClient secret

Nel diagramma precedente i numeri rappresentano il flusso delle richieste in ordine cronologico:In the preceding figure, the numbers represent the flow of the requests in chronological order:

  1. Un'app di livello intermedio (API Web o applicazione Web) richiede un token di accesso di Azure AD con i parametri seguenti:A middle-tier app (web API or web application) requests an Azure AD access token that has the following parameters:

  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.

Per altre informazioni su come usare l'autenticazione di Azure AD per comunicare con le richieste REST tramite l'SDK del client .NET di Servizi multimediali, vedere Uso dell'autenticazione Azure AD per accedere all'API di Servizi multimediali di Azure con .NET.For more information about how to use Azure AD authentication to communicate with REST requests by using the Media Services .NET client SDK, see Use Azure AD authentication to access Azure Media Services API with .NET.

Se non si usa l'SDK del client .NET di Servizi multimediali , è necessario creare manualmente una richiesta di token di Azure AD tramite i parametri descritti nel passaggio 1.If you are not using the Media Services .NET client SDK, you must manually create an Azure AD token request by using parameters described in step 1. Per altre informazioni, vedere Come usare Azure AD Authentication Library per ottenere il token di Azure AD.For more information, see How to use the Azure AD Authentication Library to get the Azure AD token.

Risoluzione dei problemiTroubleshooting

Eccezione: "Il server remoto ha restituito un errore: (401) Non autorizzato."Exception: "The remote server returned an error: (401) Unauthorized."

Soluzione: perché la richiesta REST di Servizi multimediali abbia esito positivo, l'utente chiamante deve avere il ruolo di Collaboratore o Proprietario per l'account di Servizi multimediali al quale sta tentando di accedere.Solution: For the Media Services REST request to succeed, the calling user must be a Contributor or Owner role in the Media Services account it is trying to access. Per altre informazioni, vedere la sezione Controllo dell'accesso.For more information, see the Access control section.

RisorseResources

Gli articoli seguenti contengono alcune panoramiche dei concetti di autenticazione di Azure AD:The following articles are overviews of Azure AD authentication concepts:

Passaggi successiviNext steps