Creazione di filtri con l'API REST di Servizi multimediali di AzureCreating Filters with Azure Media Services REST API

A partire dalla versione 2.11, Servizi multimediali consente di definire filtri per i propri asset.Starting with 2.11 release, Media Services enables you to define filters for your assets. I filtri sono costituiti da regole lato server che consentono ai clienti di eseguire operazioni particolari, come riprodurre solo una sezione di un video (anziché il video intero) oppure specificare solo un sottoinsieme di rendering audio e video, in modo che possa essere gestito dal dispositivo del cliente (anziché tutti i rendering associati all'asset).These filters are server side rules that will allow your customers to choose to do things like: playback only a section of a video (instead of playing the whole video), or specify only a subset of audio and video renditions that your customer's device can handle (instead of all the renditions that are associated with the asset). Il filtro degli asset viene archiviato attraverso manifesti dinamicicreati su richiesta del cliente per trasmettere un video in streaming in base ai filtri specificati.This filtering of your assets is archived through Dynamic Manifests that are created upon your customer's request to stream a video based on specified filter(s).

Per altre informazioni sui filtri e sul manifesto dinamico, vedere Filtri e manifesti dinamici.For more detailed information related to filters and Dynamic Manifest, see Dynamic manifests overview.

Questo argomento illustra come usare le API REST per creare, aggiornare ed eliminare filtri.This topic shows how to use REST APIs to create, update, and delete filters.

Tipi usati per la creazione dei filtriTypes used to create filters

Durante la creazione dei filtri vengono usati i tipi seguenti:The following types are used when creating filters:

Nota

Quando si accede alle entità in Servizi multimediali, è necessario impostare valori e campi di intestazione specifici nelle richieste HTTP.When accessing entities in Media Services, you must set specific header fields and values in your HTTP requests. Per altre informazioni, vedere Panoramica dell'API REST di Servizi multimediali.For more information, see Setup for Media Services REST API Development.

Connettersi a Servizi multimedialiConnect to Media Services

Per informazioni su come connettersi all'API AMS, vedere Accedere all'API di Servizi multimediali di Azure con l'autenticazione di Azure AD.For information on how to connect to the AMS API, see Access the Azure Media Services API with Azure AD authentication.

Nota

Dopo avere stabilito la connessione a https://media.windows.net, si riceverà un reindirizzamento 301 che indica un altro URI di Servizi multimediali.After successfully connecting to https://media.windows.net, you will receive a 301 redirect specifying another Media Services URI. Le chiamate successive dovranno essere effettuate al nuovo URI.You must make subsequent calls to the new URI.

Creare filtriCreate filters

Creare filtri globaliCreate global Filters

Per creare un filtro globale, usare le richieste HTTP seguenti:To create a global Filter, use the following HTTP requests:

Richiesta HTTPHTTP Request

Intestazioni richiestaRequest Headers

POST https://media.windows.net/API/Filters HTTP/1.1 
DataServiceVersion:3.0 
MaxDataServiceVersion: 3.0 
Content-Type: application/json 
Accept: application/json 
Accept-Charset: UTF-8 
Authorization: Bearer <token value> 
x-ms-version: 2.11 
x-ms-client-request-id: 00000000-0000-0000-0000-000000000000 
Host:media.windows.net 

Corpo della richiestaRequest body

{  
   "Name":"GlobalFilter",
   "PresentationTimeRange":{  
      "StartTimestamp":"0",
      "EndTimestamp":"9223372036854775807",
      "PresentationWindowDuration":"12000000000",
      "LiveBackoffDuration":"0",
      "Timescale":"10000000"
   },
   "Tracks":[  
      {  
         "PropertyConditions":
              [  
            {  
               "Property":"Type",
               "Value":"audio",
               "Operator":"Equal"
            },
            {  
               "Property":"Bitrate",
               "Value":"0-2147483647",
               "Operator":"Equal"
            }
         ]
      }
   ]
}

Risposta HTTPHTTP Response

HTTP/1.1 201 Created 

Creare AssetFilters localiCreate local AssetFilters

Per creare un AssetFilter locale, usare le richieste HTTP seguenti:To create a local AssetFilter, use the following HTTP requests:

Richiesta HTTPHTTP Request

Intestazioni richiestaRequest Headers

POST https://media.windows.net/API/AssetFilters HTTP/1.1 
DataServiceVersion: 3.0 
MaxDataServiceVersion: 3.0 
Content-Type: application/json 
Accept: application/json 
Accept-Charset: UTF-8 
Authorization: Bearer <token value> 
x-ms-version: 2.11 
x-ms-client-request-id: 00000000-0000-0000-0000-000000000000 
Host: media.windows.net  

Corpo della richiestaRequest body

{   
   "Name":"AssetFilter", 
   "ParentAssetId":"nb:cid:UUID:536e555d-1500-80c3-92dc-f1e4fdc6c592", 
   "PresentationTimeRange":{   
      "StartTimestamp":"0", 
      "EndTimestamp":"9223372036854775807", 
      "PresentationWindowDuration":"12000000000", 
      "LiveBackoffDuration":"0", 
      "Timescale":"10000000" 
   }, 
   "Tracks":[   
      {   
         "PropertyConditions": 
              [   
            {   
               "Property":"Type", 
               "Value":"audio", 
               "Operator":"Equal" 
            }, 
            {   
               "Property":"Bitrate", 
               "Value":"0-2147483647", 
               "Operator":"Equal" 
            } 
         ] 
      } 
   ] 
} 

Risposta HTTPHTTP Response

HTTP/1.1 201 Created 
. . . 

Elencare i filtriList filters

Ottenere tutti i Filterglobali nell'account di Servizi multimediali di AzureGet all global Filters in the AMS account

Per elencare i filtri, usare le richieste HTTP seguenti:To list filters, use the following HTTP requests:

Richiesta HTTPHTTP Request

GET https://media.windows.net/API/Filters HTTP/1.1 
DataServiceVersion:3.0 
MaxDataServiceVersion: 3.0 
Accept: application/json 
Accept-Charset: UTF-8 
Authorization: Bearer <token value> 
x-ms-version: 2.11 
Host: media.windows.net 

Ottenere gli AssetFilterassociati a un assetGet AssetFilters associated with an asset

Richiesta HTTPHTTP Request

GET https://media.windows.net/API/Assets('nb%3Acid%3AUUID%3A536e555d-1500-80c3-92dc-f1e4fdc6c592')/AssetFilters HTTP/1.1 
DataServiceVersion: 3.0 
MaxDataServiceVersion: 3.0 
Accept: application/json 
Accept-Charset: UTF-8 
Authorization: Bearer <token value> 
x-ms-version: 2.11 
x-ms-client-request-id: 00000000-0000-0000-0000-000000000000 
Host: media.windows.net 

Ottenere un AssetFilter in base all'IDGet an AssetFilter based on its Id

Richiesta HTTPHTTP Request

GET https://media.windows.net/API/AssetFilters('nb%3Acid%3AUUID%3A536e555d-1500-80c3-92dc-f1e4fdc6c592__%23%23%23__TestFilter') HTTP/1.1 
DataServiceVersion: 3.0 
MaxDataServiceVersion: 3.0 
Accept: application/json 
Accept-Charset: UTF-8 
Authorization: Bearer <token value> 
x-ms-version: 2.11 
x-ms-client-request-id: 00000000

Aggiornare i filtriUpdate filters

Usare PATCH, PUT o MERGE per aggiornare un filtro con i nuovi valori di proprietà.Use PATCH, PUT or MERGE to update a filter with new property values. Per altre informazioni su queste operazioni, vedere PATCH, PUT, MERGE.For more information about these operations, see PATCH, PUT, MERGE.

Se si aggiorna un filtro, l'endpoint di streaming può impiegare fino a due minuti per aggiornare le regole.If you update a filter, it can take up to 2 minutes for streaming endpoint to refresh the rules. Se il contenuto è stato trasmesso usando dei filtri (e memorizzato nelle cache dei proxy e delle reti CDN), l'aggiornamento del filtro può determinare un errore del lettore.If the content was served using this filter (and cached in proxies and CDN caches), updating this filter can result in player failures. È consigliabile quindi cancellare la cache dopo aver aggiornato il filtro.It is recommend to clear the cache after updating the filter. Se questa operazione non è consentita, prendere in considerazione la possibilità di usare un filtro diverso.If this option is not possible, consider using a different filter.

Aggiornare filtri globaliUpdate global Filters

Per aggiornare un filtro globale, usare le richieste HTTP seguenti:To update a global filter, use the following HTTP requests:

Richiesta HTTPHTTP Request

Intestazioni della richiesta:Request headers:

MERGE https://media.windows.net/API/Filters('filterName') HTTP/1.1 
DataServiceVersion:3.0 
MaxDataServiceVersion: 3.0 
Content-Type: application/json 
Accept: application/json 
Accept-Charset: UTF-8 
Authorization: Bearer <token value> 
x-ms-version: 2.11 
x-ms-client-request-id: 00000000-0000-0000-0000-000000000000 
Host: media.windows.net 
Content-Length: 384

Corpo della richiesta:Request body:

{ 
   "Tracks":[   
      {   
         "PropertyConditions": 
         [   
            {   
               "Property":"Type", 
               "Value":"audio", 
               "Operator":"Equal" 
            }, 
            {   
               "Property":"Bitrate", 
               "Value":"0-2147483647", 
               "Operator":"Equal" 
            } 
         ] 
      } 
   ] 
} 

Aggiornare AssetFilters localiUpdate local AssetFilters

Per aggiornare un filtro locale, usare le richieste HTTP seguenti:To update a local filter, use the following HTTP requests:

Richiesta HTTPHTTP Request

Intestazioni della richiesta:Request headers:

MERGE https://media.windows.net/API/AssetFilters('nb%3Acid%3AUUID%3A536e555d-1500-80c3-92dc-f1e4fdc6c592__%23%23%23__TestFilter')  HTTP/1.1 
DataServiceVersion: 3.0 
MaxDataServiceVersion: 3.0 
Content-Type: application/json 
Accept: application/json 
Accept-Charset: UTF-8 
Authorization: Bearer <token value> 
x-ms-version: 2.11 
x-ms-client-request-id: 00000000-0000-0000-0000-000000000000 
Host: media.windows.net 

Corpo della richiesta:Request body:

{ 
   "Tracks":[   
      {   
         "PropertyConditions": 
         [   
            {   
               "Property":"Type", 
               "Value":"audio", 
               "Operator":"Equal" 
            }, 
            {   
               "Property":"Bitrate", 
               "Value":"0-2147483647", 
               "Operator":"Equal" 
            } 
         ] 
      } 
   ] 
} 

Eliminare filtriDelete filters

Eliminare filtri globaliDelete global Filters

Per eliminare un filtro globale, usare le richieste HTTP seguenti:To delete a global Filter, use the following HTTP requests:

Richiesta HTTPHTTP Request

DELETE https://media.windows.net/api/Filters('GlobalFilter') HTTP/1.1 
DataServiceVersion:3.0 
MaxDataServiceVersion: 3.0 
Accept: application/json 
Accept-Charset: UTF-8 
Authorization: Bearer <token value> 
x-ms-version: 2.11 
Host: media.windows.net 

Eliminare AssetFilter localiDelete local AssetFilters

Per eliminare un AssetFilter locale, usare le richieste HTTP seguenti:To delete a local AssetFilter, use the following HTTP requests:

Richiesta HTTPHTTP Request

DELETE https://media.windows.net/API/AssetFilters('nb%3Acid%3AUUID%3A536e555d-1500-80c3-92dc-f1e4fdc6c592__%23%23%23__LocalFilter') HTTP/1.1 
DataServiceVersion: 3.0 
MaxDataServiceVersion: 3.0 
Accept: application/json 
Accept-Charset: UTF-8 
Authorization: Bearer <token value> 
x-ms-version: 2.11 
Host: media.windows.net 

Creare URL di streaming basati su filtriBuild streaming URLs that use filters

Per informazioni su come pubblicare e distribuire asset, vedere Informazioni generali sulla distribuzione di contenuti ai clienti.For information on how to publish and deliver your assets, see Delivering Content to Customers Overview.

Gli esempi seguenti illustrano come aggiungere filtri agli URL di streaming.The following examples show how to add filters to your streaming URLs.

MPEG DASHMPEG DASH

http://testendpoint-testaccount.streaming.mediaservices.windows.net/fecebb23-46f6-490d-8b70-203e86b0df58/BigBuckBunny.ism/Manifest(format=mpd-time-csf, filter=MyFilter)

Apple HTTP Live Streaming (HLS) V4Apple HTTP Live Streaming (HLS) V4

http://testendpoint-testaccount.streaming.mediaservices.windows.net/fecebb23-46f6-490d-8b70-203e86b0df58/BigBuckBunny.ism/Manifest(format=m3u8-aapl, filter=MyFilter)

Apple HTTP Live Streaming (HLS) V3Apple HTTP Live Streaming (HLS) V3

http://testendpoint-testaccount.streaming.mediaservices.windows.net/fecebb23-46f6-490d-8b70-203e86b0df58/BigBuckBunny.ism/Manifest(format=m3u8-aapl-v3, filter=MyFilter)

Smooth StreamingSmooth Streaming

http://testendpoint-testaccount.streaming.mediaservices.windows.net/fecebb23-46f6-490d-8b70-203e86b0df58/BigBuckBunny.ism/Manifest(filter=MyFilter)

Percorsi di apprendimento di Servizi multimedialiMedia Services learning paths

Altre informazioni sui percorsi di apprendimento di Servizi multimediali di Azure:Read about the Azure Media Services learning paths:

Fornire commenti e suggerimentiProvide feedback

Usare il forum di suggerimenti degli utenti per fornire commenti e suggerimenti su come migliorare Servizi multimediali di Azure.Use the User Voice forum to provide feedback and make suggestions on how to improve Azure Media Services. È anche possibile passare direttamente a una delle categorie seguenti:You also can go directly to one of the following categories:

Vedere ancheSee Also

Filtri e manifesti dinamiciDynamic manifests overview