Informazioni generali sull'API REST di Servizi multimedialiMedia Services operations REST API overview

L'API REST di Servizi multimediali viene usata per la creazione di processi, asset, criteri di accesso e altre operazioni sugli oggetti in un account di Servizi multimediali.The Media Services Operations REST API is used for creating jobs, assets, access policies, and other operations on objects in a Media Service account. Per altre informazioni, vedere le informazioni di riferimento sull'API REST di Servizi multimediali.For more information, see Media Services Operations REST API reference.

Servizi multimediali di Microsoft Azure è un servizio che accetta richieste HTTP basate su OData e può rispondere in formato JSON dettagliato o atom+pub.Microsoft Azure Media Services is a service that accepts OData-based HTTP requests and can respond back in verbose JSON or atom+pub. Poiché Servizi multimediali è conforme alle linee guida di progettazione di Azure, esiste un set di intestazioni HTTP obbligatorie che devono essere usate da ogni client per la connessione a Servizi multimediali, oltre a un set di intestazioni facoltative.Because Media Services conforms to Azure design guidelines, there is a set of required HTTP headers that each client must use when connecting to Media Services, as well as a set of optional headers that can be used. Le seguenti sezioni descrivono le intestazioni e i verbi HTTP che è possibile usare quando si creano richieste e si ricevono risposte da Servizi multimediali.The following sections describe the headers and HTTP verbs you can use when creating requests and receiving responses from Media Services.

Questo argomento offre una panoramica su come usare REST v2 con Servizi multimediali.This topic gives an overview of how to use REST v2 with Media Services.

ConsiderazioniConsiderations

Quando si usa REST, si applicano le considerazioni seguenti:The following considerations apply when using REST.

  • Quando si esegue una query di entità, è previsto un limite di 1000 entità restituite in una sola volta perché la versione 2 pubblica di REST limita i risultati della query a 1000 risultati.When querying entities, there is a limit of 1000 entities returned at one time because public REST v2 limits query results to 1000 results. È necessario usare Skip e Take (.NET)/top (REST) come descritto in questo esempio .NET e in questo esempio di API REST.You need to use Skip and Take (.NET)/ top (REST) as described in this .NET example and this REST API example.
  • Se si usa JSON e si specifica di usare la parola chiave __metadata nella richiesta, ad esempio, per fare riferimento a un oggetto collegato, SI DEVE impostare l'intestazione Accept sul formato JSON Verbose. Vedere l'esempio seguente.When using JSON and specifying to use the __metadata keyword in the request (for example, to references a linked object) you MUST set the Accept header to JSON Verbose format (see the following example). OData non riconosce la proprietà __metadata nella richiesta, a meno che non venga impostata su verbose.Odata does not understand the __metadata property in the request, unless you set it to verbose.

      POST https://media.windows.net/API/Jobs HTTP/1.1
      Content-Type: application/json;odata=verbose
      Accept: application/json;odata=verbose
      DataServiceVersion: 3.0
      MaxDataServiceVersion: 3.0
      x-ms-version: 2.11
      Authorization: Bearer <token> 
      Host: media.windows.net
    
      {
          "Name" : "NewTestJob", 
          "InputMediaAssets" : 
              [{"__metadata" : {"uri" : "https://media.windows.net/api/Assets('nb%3Acid%3AUUID%3Aba5356eb-30ff-4dc6-9e5a-41e4223540e7')"}}]
      . . . 
    

Intestazioni delle richieste HTTP standard supportate da Servizi multimedialiStandard HTTP request headers supported by Media Services

Per ogni chiamata effettuata in Servizi multimediali, è necessario includere nella richiesta un set di intestazioni obbligatorie ed eventualmente un set di intestazioni facoltative.For every call you make into Media Services, there is a set of required headers you must include in your request and also a set of optional headers you may want to include. Nella seguente tabella sono elencate le intestazioni obbligatorie:The following table lists the required headers:

IntestazioneHeader TipoType ValoreValue
AuthorizationAuthorization BearerBearer Bearer è l'unico meccanismo di autorizzazione accettato.Bearer is the only accepted authorization mechanism. Il valore deve includere anche il token di accesso fornito da ACS.The value must also include the access token provided by ACS.
x-ms-versionx-ms-version DecimaleDecimal 2.112.11
DataServiceVersionDataServiceVersion DecimalDecimal 3.03.0
MaxDataServiceVersionMaxDataServiceVersion DecimalDecimal 3.03.0

Nota

Poiché Servizi multimediali usa OData per esporre l'archivio di metadati di asset sottostante tramite le API REST, le intestazioni DataServiceVersion e MaxDataServiceVersion devono essere incluse in tutte le richieste. Se non vengono incluse, Servizi multimediali suppone che il valore di DataServiceVersion in uso sia 3.0.Because Media Services uses OData to expose its underlying asset metadata repository through REST APIs, the DataServiceVersion and MaxDataServiceVersion headers should be included in any request; however, if they are not, then currently Media Services assumes the DataServiceVersion value in use is 3.0.

Nella seguente tabella è riportato un set di intestazioni facoltative:The following is a set of optional headers:

IntestazioneHeader TipoType ValoreValue
DateDate Data RFC 1123RFC 1123 date Timestamp della richiesta.Timestamp of the request
AcceptAccept Tipo di contenutoContent type Tipo di contenuto richiesto per la risposta, ad esempio:The requested content type for the response such as the following:

-application/json;odata=verbose-application/json;odata=verbose

- application/atom+xml- application/atom+xml

Nelle risposte può essere presente un tipo di contenuto diverso, ad esempio di recupero BLOB. In questo caso, una risposta corretta deve contenere il flusso BLOB come payload.Responses may have a different content type, such as a blob fetch, where a successful response will contain the blob stream as the payload.

Accept-EncodingAccept-Encoding Gzip, deflateGzip, deflate Codifica GZIP e DEFLATE, se applicabile.GZIP and DEFLATE encoding, when applicable. Nota: in caso di risorse di grandi dimensioni, Servizi multimediali può ignorare questa intestazione e restituire dati non compressi.Note: For large resources, Media Services may ignore this header and return noncompressed data.
Accept-LanguageAccept-Language "en", "es" e così via."en", "es", and so on. Lingua preferita per la risposta.Specifies the preferred language for the response.
Accept-CharsetAccept-Charset Tipo di set di caratteri, ad esempio "UTF-8"Charset type like “UTF-8” L'impostazione predefinita è UTF-8.Default is UTF-8.
X-HTTP-MethodX-HTTP-Method Metodo HTTPHTTP Method Consente ai client o ai firewall che non supportano metodi HTTP come PUT o DELETE di usarli, con tunneling tramite una chiamata GET.Allows clients or firewalls that do not support HTTP methods like PUT or DELETE to use these methods, tunneled via a GET call.
Content-TypeContent-Type Tipo di contenutoContent type Tipo di contenuto del corpo delle richieste PUT o POST.Content type of the request body in PUT or POST requests.
client-request-idclient-request-id StringString Valore definito dal chiamante che identifica la richiesta fornita.A caller-defined value that identifies the given request. Se specificato, questo valore viene incluso nel messaggio di risposta per consentire il mapping della richiesta.If specified, this value will be included in the response message as a way to map the request.

ImportanteImportant

Le dimensioni di questi valori dovrebbero essere limitate a 2096 b (2 k).Values should be capped at 2096b (2k).

Intestazioni delle risposte HTTP standard supportate da Servizi multimedialiStandard HTTP response headers supported by Media Services

Nella seguente tabella è riportato un set di intestazioni che possono essere restituite a seconda della risorsa richiesta e dell'azione che si intende eseguire.The following is a set of headers that may be returned to you depending on the resource you were requesting and the action you intended to perform.

IntestazioneHeader TipoType ValoreValue
request-idrequest-id StringString Identificatore univoco per l'operazione corrente, generato dal servizio.A unique identifier for the current operation, service generated.
client-request-idclient-request-id StringString Identificatore specificato dal chiamante nella richiesta originale, se presente.An identifier specified by the caller in the original request, if present.
DateDate Data RFC 1123RFC 1123 date Data di elaborazione della richiesta.The date that the request was processed.
Content-TypeContent-Type VariabileVaries Tipo di contenuto del corpo della risposta.The content type of the response body.
Content-EncodingContent-Encoding VariabileVaries Gzip o deflate, a seconda delle esigenze.Gzip or deflate, as appropriate.

Verbi HTTP standard supportati da Servizi multimedialiStandard HTTP verbs supported by Media Services

Nella seguente tabella è riportato l'elenco completo dei verbi HTTP che è possibile usare per la creazione di richieste HTTP:The following is a complete list of HTTP verbs that can be used when making HTTP requests:

VerboVerb DescrizioneDescription
GETGET Restituisce il valore corrente di un oggetto.Returns the current value of an object.
POSTPOST Crea un oggetto in base ai dati forniti o invia un comando.Creates an object based on the data provided, or submits a command.
PUTPUT Sostituisce un oggetto o ne crea uno nuovo con nome, se applicabile.Replaces an object, or creates a named object (when applicable).
DELETEDELETE Elimina un oggetto.Deletes an object.
MERGEMERGE Aggiorna un oggetto esistente con le modifiche alle proprietà denominate.Updates an existing object with named property changes.
HEADHEAD Restituisce i metadati di un oggetto per una risposta GET.Returns metadata of an object for a GET response.

Individuare il modello di Servizi multimedialiDiscover Media Services model

Per rendere più facilmente individuabili le entità di Servizi multimediali, è possibile usare l'operazione $metadata,To make Media Services entities more discoverable, the $metadata operation can be used. che consente di recuperare tutti i tipi validi di entità, le proprietà di entità, le associazioni, le funzioni, le azioni e così via.It allows you to retrieve all valid entity types, entity properties, associations, functions, actions, and so on. L'esempio seguente illustra come costruire l'URI: https://media.windows.net/API/$metadata.The following example shows how to construct the URI: https://media.windows.net/API/$metadata.

Aggiungere "?api-version=2.x" alla fine dell'URI se si desidera visualizzare i metadati in un browser o se nella richiesta non è stata inclusa l'intestazione x-ms-version.You should append "?api-version=2.x" to the end of the URI if you want to view the metadata in a browser, or do not include the x-ms-version header in your request.

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. 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.

Passaggi successiviNext steps

Per accedere all'API di AMS con REST, vedere Usare l'autenticazione di Azure AD per accedere all'API Servizi multimediali di Microsoft Azure con REST.To access AMS APIs with REST, see Use Azure AD authentication to access the Azure Media Services API with REST.

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: