Caricare file in un account di Servizi multimediali mediante RESTUpload files into a Media Services account using REST

In Servizi multimediali è possibile caricare i file digitali in un asset.In Media Services, you upload your digital files into an asset. L'entità Asset può contenere video, audio, immagini, raccolte di anteprime, tracce di testo e file di sottotitoli codificati, oltre ai metadati relativi a questi file. Dopo il caricamento dei file nell'asset, i contenuti vengono archiviati in modo sicuro nel cloud per altre operazioni di elaborazione e streaming.The Asset entity can contain video, audio, images, thumbnail collections, text tracks and closed caption files (and the metadata about these files.) Once the files are uploaded into the asset, your content is stored securely in the cloud for further processing and streaming.

Questa esercitazione illustra come caricare un file ed eseguire altre operazioni associate:In this tutorial, you learn how to upload a file and other operation associated with it:

  • Configurare Postman per tutte le operazioni di caricamentoSet up Postman for all the upload operations
  • Connettersi a Servizi multimedialiConnect to Media Services
  • Creare un criterio di accesso con autorizzazione di scritturaCreate an access policy with write permission
  • Creare un assetCreate an asset
  • Creare un localizzatore di firma di accesso condiviso e creare l'URL di caricamentoCreate a SAS locator and create the upload URL
  • Caricare un file nell'archiviazione BLOB usando l'URL di caricamentoUpload a file to blob storage using the upload URL
  • Creare nell'asset i metadati per il file multimediale caricatoCreate a metadata in the asset for the media file you uploaded

prerequisitiPrerequisites

ConsiderazioniConsiderations

Quando si usa l'API REST di Servizi multimediali, tenere presenti le seguenti considerazioni:The following considerations apply when using Media Services REST API:

  • Quando si accede alle entità con l'API REST di Servizi multimediali, è necessario impostare valori e campi di intestazione specifici nelle richieste HTTP.When accessing entities using Media Services REST API, 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.
    Con la raccolta Postman usata in questa esercitazione vengono impostate tutte le intestazioni necessarie.The Postman collection used in this tutorial takes care of setting all the necessary headers.
  • Servizi multimediali usa il valore della proprietà IAssetFile.Name durante la creazione di URL per i contenuti in streaming, ad esempio http://{AMSAccount}.origin.mediaservices.windows.net/{GUID}/{IAssetFile.Name}/streamingParameters. Per questo motivo, la codifica percentuale non è consentita.Media Services uses the value of the IAssetFile.Name property when building URLs for the streaming content (for example, http://{AMSAccount}.origin.mediaservices.windows.net/{GUID}/{IAssetFile.Name}/streamingParameters.) For this reason, percent-encoding is not allowed. Il valore della proprietà Name non può contenere i caratteri riservati per la codifica percentuale seguenti: !*'();:@&=+$,/?%#[]".The value of the Name property cannot have any of the following percent-encoding-reserved characters: !*'();:@&=+$,/?%#[]". L'estensione del nome di file, inoltre, può essere preceduta da un solo punto (.).Also, there can only be one '.' for the file name extension.
  • La lunghezza del nome non deve essere superare i 260 caratteri.The length of the name should not be greater than 260 characters.
  • È previsto un limite per le dimensioni massime dei file supportate per l'elaborazione in Servizi multimediali.There is a limit to the maximum file size supported for processing in Media Services. Vedere questo articolo per informazioni dettagliate sulla limitazione per le dimensioni dei file.See this article for details about the file size limitation.

Configurare PostmanSet up Postman

Per la procedura di configurazione di Postman per questa esercitazione, vedere Configurare Postman per le chiamate API REST di Servizi multimediali.For steps on how to set up Postman for this tutorial, see Configure Postman.

Connettersi a Servizi multimedialiConnect to Media Services

  1. Aggiungere i valori della connessione all'ambiente.Add connection values to your environment.

    Alcune variabili che fanno parte dell'ambiente MediaServices devono essere impostate manualmente prima di iniziare a eseguire le operazioni definite nella raccolta.Some variables that are part of the MediaServices environment need to be set manually before you can start executing operations defined in the collection.

    Per ottenere i valori per le prime cinque variabili, vedere Accesso all'API di Servizi multimediali di Azure con l'autenticazione di Azure AD.To get values for the first five variables, see Access the Azure Media Services API with Azure AD authentication.

    Caricare un file

  2. Specificare il valore per la variabile di ambiente MediaFileName.Specify the value for the MediaFileName environment variable.

    Specificare il nome file del file multimediale che si intende caricare.Specify the file name of the media you are planning to upload. In questo esempio verrà usato il file BigBuckBunny.mp4.In this example, we are going to upload the BigBuckBunny.mp4.

  3. Esaminare il file AzureMediaServices.postman_environment.json.Examine the AzureMediaServices.postman_environment.json file. Si noterà che quasi tutte le operazioni nella raccolta eseguono uno script "test".You will see that almost all operations in the collection execute a "test" script. Gli script accettano alcuni valori restituito dalla risposta e impostano le variabili di ambiente appropriate.The scripts take some values returned by the response and set appropriate environment variables.

    Ad esempio, la prima operazione ottiene un token di accesso e lo imposta nella variabile di ambiente AccessToken che viene usata in tutte le altre operazioni.For example, the first operation gets an access token and set it on the AccessToken environment variable that is used in all other operations.

    "listen": "test",
    "script": {
        "type": "text/javascript",
        "exec": [
            "var json = JSON.parse(responseBody);",
            "postman.setEnvironmentVariable(\"AccessToken\", json.access_token);"
        ]
    }
    
  4. Nella parte sinistra della finestra Postman fare clic su 1. Get AAD Auth token -> Get Azure AD Token for Service Principal.On the left of the Postman window, click on 1. Get AAD Auth token -> Get Azure AD Token for Service Principal.

    La parte dell'URL viene compilata con la variabile di ambiente AzureADSTSEndpoint (il cui valore è stato impostato in precedenza in questa esercitazione).The URL portion is filled with the AzureADSTSEndpoint environment variable (the value of which you set earlier in this tutorial).

  5. Fare clic su Invia.Press Send.

    Caricare un file

    Si noterà che la risposta contiene "access_token".You can see the response that contains "access_token". Lo script "test" accetta questo valore e imposta la variabile di ambiente AccessToken (come descritto in precedenza).The "test" script takes this value and sets the AccessToken environment variable (as described above). Se si esaminano le variabili di ambiente, si noterà che questa variabile contiene ora il valore del token di accesso (bearer token) usato nel resto delle operazioni.If you examine your environment variables, you will see that this variable now contains the access token (bearer token) value that is used in the rest of the operations.

    Se il token scade, ripetere il passaggio "Get Azure AD Token for Service Principal".If the token expires go through the "Get Azure AD Token for Service Principal" step again.

Creare un criterio di accesso con autorizzazione di scritturaCreate an access policy with write permission

PanoramicaOverview

Nota

È previsto un limite di 1.000.000 di criteri per i diversi criteri AMS (ad esempio per i criteri Locator o ContentKeyAuthorizationPolicy).There is a limit of 1,000,000 policies for different AMS policies (for example, for Locator policy or ContentKeyAuthorizationPolicy). Usare lo stesso ID criterio se si usano sempre gli stessi giorni/autorizzazioni di accesso, come nel cado di criteri per i localizzatori che devono rimanere attivi per molto tempo (criteri di non caricamento).You should use the same policy ID if you are always using the same days / access permissions, for example, policies for locators that are intended to remain in place for a long time (non-upload policies). Per altre informazioni, vedere questo articolo.For more information, see this article.

Prima di caricare i file nell'archiviazione BLOB, impostare i diritti dei criteri di accesso per la scrittura in un asset.Before uploading any files into blob storage, set the access policy rights for writing to an asset. A questo scopo, inviare una richiesta HTTP al set di entità AccessPolicies.To do that, POST an HTTP request to the AccessPolicies entity set. Definire un valore DurationInMinutes durante la creazione. In caso contrario, si riceverà il messaggio di errore interno 500 del server in risposta.Define a DurationInMinutes value upon creation or you receive a 500 Internal Server error message back in response. Per altre informazioni su AccessPolicies, vedere AccessPolicy.For more information on AccessPolicies, see AccessPolicy.

Creare i criteri di accessoCreate an access policy

  1. Selezionare AccessPolicy -> Create AccessPolicy for Upload.Select AccessPolicy -> Create AccessPolicy for Upload.
  2. Fare clic su Invia.Press Send.

    Caricare un file

    Lo script "test" ottiene l'ID AccessPolicy e imposta la variabile di ambiente appropriata.The "test" script gets the AccessPolicy Id and sets the appropriate environment variable.

Creare un assetCreate an asset

PanoramicaOverview

Un asset è un contenitore di più tipi o set di oggetti in Servizi multimediali, inclusi elementi video e audio, immagini, raccolte di anteprime, tracce di testo e file di sottotitoli chiusi.An asset is a container for multiple types or sets of objects in Media Services, including video, audio, images, thumbnail collections, text tracks, and closed caption files. Nell'API REST, la creazione di un asset richiede l'invio di una richiesta POST a Servizi multimediali e l'inserimento di tutte le informazioni sulle proprietà relative all'asset nel corpo della richiesta.In the REST API, creating an Asset requires sending POST request to Media Services and placing any property information about your asset in the request body.

Una delle proprietà che è possibile aggiungere quando si crea un asset è Options.One of the properties that you can add when creating an asset is Options. È possibile specificare una delle opzioni di crittografia seguenti: None (impostazione predefinita, non viene usata alcuna crittografia), StorageEncrypted (per contenuto che è stato pre-crittografato con crittografia di archiviazione lato client), CommonEncryptionProtected o EnvelopeEncryptionProtected.You can specify one of the following encryption options: None (default, no encryption is used), StorageEncrypted (for content that has been pre-encrypted with client-side storage encryption), CommonEncryptionProtected, or EnvelopeEncryptionProtected. Se è presente un asset crittografato, è necessario configurare un criterio di recapito.When you have an encrypted asset, you need to configure a delivery policy. Per altre informazioni, vedere l'articolo Procedura: Configurare i criteri di distribuzione degli asset.For more information, see Configuring asset delivery policies.

Se l'asset è crittografato, è necessario creare un'entità ContentKey e collegarla all'asset, come descritto nell'articolo Creazione di entità ContentKey mediante REST.If your asset is encrypted, you must create a ContentKey and link it to your asset as described in the following article: How to create a ContentKey. Dopo il caricamento dei file nell'asset è necessario aggiornare le proprietà di crittografia nell'entità AssetFile con i valori ottenuti durante la crittografia dell'entità Asset.After you upload the files into the asset, you need to update the encryption properties on the AssetFile entity with the values you got during the Asset encryption. Effettuare questa operazione usando la richiesta HTTP MERGE .Do it by using the MERGE HTTP request.

In questo esempio viene creato un asset non crittografato.In this example, we are creating an unencrypted asset.

Creare un assetCreate an asset

  1. Selezionare Asset -> Create Asset (Crea asset).Select Assets -> Create Asset.
  2. Fare clic su Invia.Press Send.

    Caricare un file

    Lo script "test" ottiene l'ID Asset e imposta la variabile di ambiente appropriata.The "test" script gets the Asset Id and sets the appropriate environment variable.

Creare un localizzatore di firma di accesso condiviso e creare l'URL di caricamentoCreate a SAS locator and create the Upload URL

PanoramicaOverview

Una volta impostati AccessPolicy e Locator, il file effettivo viene caricato nel contenitore di archiviazione BLOB di Azure usando le API REST di Archiviazione di Azure.Once you have the AccessPolicy and Locator set, the actual file is uploaded to an Azure Blob Storage container using the Azure Storage REST APIs. È necessario caricare i file come BLOB in blocchi.You must upload the files as block blobs. I BLOB di pagine non sono supportati da Servizi multimediali di Azure.Page blobs are not supported by Azure Media Services.

Per altre informazioni sull'uso dei BLOB di Archiviazione di Azure, vedere API REST del servizio BLOB.For more information on working with Azure storage blobs, see Blob Service REST API.

Per ricevere l'URL di caricamento effettivo, creare un localizzatore di firma di accesso condiviso (illustrato di seguito).To receive the actual upload URL, create a SAS Locator (shown below). I localizzatori definiscono l'ora di inizio e il tipo di endpoint della connessione per i client che richiedono l'accesso ai file in un asset.Locators define the start time and type of connection endpoint for clients that want to access Files in an Asset. È possibile creare più entità Locator per una specifica coppia AccessPolicy e Asset in modo da gestire le diverse richieste ed esigenze dei client.You can create multiple Locator entities for a given AccessPolicy and Asset pair to handle different client requests and needs. Ogni localizzatore usa i valori StartTime e DurationInMinutes di AccessPolicy per determinare la durata d'uso di un URL.Each of these Locators uses the StartTime value plus the DurationInMinutes value of the AccessPolicy to determine the length of time a URL can be used. Per altre informazioni, vedere Locator.For more information, see Locator.

Un URL di firma di accesso condiviso ha il seguente formato:A SAS URL has the following format:

{https://myaccount.blob.core.windows.net}/{asset name}/{video file name}?{SAS signature}

ConsiderazioniConsiderations

Considerazioni applicabili:Some considerations apply:

  • Non è possibile avere più di cinque localizzatori univoci associati contemporaneamente a un determinato asset.You cannot have more than five unique Locators associated with a given Asset at one time. Per altre informazioni, vedere Locator.For more information, see Locator.
  • Se è necessario caricare i file immediatamente, impostare il valore StartTime su cinque minuti prima dell'ora corrente.If you need to upload your files immediately, you should set your StartTime value to five minutes before the current time. Potrebbe infatti essere presente una leggera differenza di orario tra il computer client e Servizi multimediali.This is because there may be clock skew between your client machine and Media Services. Inoltre, il formato DateTime del valore StartTime deve essere il seguente: AAAA-MM-GGTHH:mm:ssZ (ad esempio, "2014-05-23T17:53:50Z").Also, your StartTime value must be in the following DateTime format: YYYY-MM-DDTHH:mm:ssZ (for example, "2014-05-23T17:53:50Z").
  • Può verificarsi un ritardo di 30-40 secondi tra la creazione di un localizzatore e la relativa disponibilità per l'uso.There may be a 30-40 second delay after a Locator is created to when it is available for use.

Creare un localizzatore di firma di accesso condivisoCreate a SAS locator

  1. Selezionare Localizzatore -> Create SAS Locator (Crea localizzatore di firma di accesso condiviso).Select Locator -> Create SAS Locator.
  2. Fare clic su Invia.Press Send.

    Lo script "test" crea l'URl di caricamento sulla base del nome del file multimediale specificato e delle informazioni del localizzatore di firma di accesso condiviso e imposta la variabile di ambiente appropriata.The "test" script creates the "Upload URL" based on the media file name you specified and SAS locator information and sets the appropriate environment variable.

    Caricare un file

Caricare un file nell'archiviazione BLOB usando l'URL di caricamentoUpload a file to blob storage using the upload URL

PanoramicaOverview

Dopo aver creato l'URL di caricamento, è necessario scrivere codice usando direttamente le API di BLOB di Azure per caricare il file nel contenitore della firma di accesso condiviso.Now that you have the upload URL, you need to write some code using the Azure Blob APIs directly to upload your file to the SAS container. Per altre informazioni, vedere gli articoli seguenti:For more information, see the following articles:

Caricare un file con PostmanUpload a file with Postman

A titolo di esempio verrà usato Postman per caricare un file MP4 di piccole dimensioni.As an example, we use Postman to upload a small .mp4 file. Il caricamento di file binari tramite Postman potrebbe essere soggetto a limitazioni relative alle dimensioni file.There may be a file size limit on uploading binary through Postman.

La richiesta di caricamento non fa parte della raccolta AzureMedia.The upload request is not part of the AzureMedia collection.

Creare e configurare una nuova richiesta:Create and set up a new request:

  1. Fare clic su + per creare una nuova scheda per la richiesta.Press +, to create a new request tab.
  2. Selezionare l'operazione PUT e incollare {{UploadURL}} nell'URL.Select PUT operation and paste {{UploadURL}} in the URL.
  3. Lasciare invariata la scheda Autorizzazione (non impostarla su Bearer Token).Leave Authorization tab as is (do not set it to the Bearer Token).
  4. Nella scheda Intestazioni specificare "x-ms-blob-type" in Chiave e "BlockBlob" in Valore.In the Headers tab, specify: Key: "x-ms-blob-type" and Value: "BlockBlob".
  5. Nella scheda Corpo fare clic su binario.In the Body tab, click binary.
  6. Scegliere il file con il nome specificato nella variabile di ambiente MediaFileName.Choose the file with the name that you specified in the MediaFileName environment variable.
  7. Fare clic su Invia.Press Send.

    Caricare un file

Creare i metadati nell'assetCreate a metadata in the asset

Dopo aver caricato il file è necessario creare nell'asset i metadati per il file multimediale caricato nella risorsa di archiviazione BLOB associata all'asset.Once the file has been uploaded, you need to create a metadata in the asset for the media file you uploaded into the blob storage associated with your asset.

  1. Selezionare AssetFiles -> CreateFileInfos.Select AssetFiles -> CreateFileInfos.
  2. Fare clic su Invia.Press Send.

    Caricare un file

È necessario che il file sia caricato e che i relativi metadati siano impostati.The file should be uploaded and its metadata set.

ConvalidaValidate

Per convalidare il corretto caricamento del file, è possibile eseguire una query su AssetFile e confrontare il valore di ContentFileSize (o altri dettagli) con quanto dovrebbe essere presente nel nuovo asset.To validate that the file has been uploaded successfully, you might want to query the AssetFile and compare the ContentFileSize (or other details) to what you expect to see in the new asset.

Ad esempio, l'operazione GET consente di ottenere i dati relativi al file di asset, in questo caso il file BigBuckBunny.mp4.For example, the following GET operation brings file data for your asset file (in or case, the BigBuckBunny.mp4 file). Per la query vengono usate le variabili di ambiente impostate in precedenza.The query is using the environment variables that you set earlier.

{{RESTAPIEndpoint}}/Assets('{{LastAssetId}}')/Files

La risposta conterrà dimensioni, nome e altre informazioni.Response will contain size, name, and other information.

"Id": "nb:cid:UUID:69e72ede-2886-4f2a-8d36-80a59da09913",
"Name": "BigBuckBunny.mp4",
"ContentFileSize": "3186542",
"ParentAssetId": "nb:cid:UUID:0b8f3b04-72fb-4f38-8e7b-d7dd78888938",

Passaggi successiviNext steps

Ora è possibile codificare gli asset caricati.You can now encode your uploaded assets. Per altre informazioni, vedere Encode assets(Codificare gli asset).For more information, see Encode assets.

È anche possibile usare Funzioni di Azure per attivare un processo di codifica basato su un file che arriva nel contenitore configurato.You can also use Azure Functions to trigger an encoding job based on a file arriving in the configured container. Per altre informazioni, vedere questo esempio.For more information, see this sample.