Caricare file in un account di Servizi multimediali mediante .NETUpload files into a Media Services account using .NET

In Servizi multimediali i file digitali vengono caricati (o inseriti) in un asset.In Media Services, you upload (or ingest) 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 aver caricato i file, 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, your content is stored securely in the cloud for further processing and streaming.

I file nell'asset sono denominati File di asset.The files in the asset are called Asset Files. L'istanza di AssetFile e il file multimediale effettivo sono due oggetti distinti.The AssetFile instance and the actual media file are two distinct objects. L'istanza di AssetFile contiene metadati relativi al file multimediale, mentre quest'ultimo contiene l'effettivo contenuto multimediale.The AssetFile instance contains metadata about the media file, while the media file contains the actual media content.

Nota

Si applicano le considerazioni seguenti:The following considerations apply:

  • 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 argomento per informazioni dettagliate sulla limitazione per le dimensioni dei file.Please see this topic for details about the file size limitation.
  • È 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 argomento.For more information, see this topic.

Quando si creano asset, è possibile specificare le seguenti opzioni di crittografia.When you create assets, you can specify the following encryption options.

  • None : non viene usata alcuna crittografia.None - No encryption is used. Si tratta del valore predefinito.This is the default value. Quando si usa questa opzione, il contenuto non è protetto durante il transito, né nell'archiviazione locale.Note that when using this option your content is not protected in transit or at rest in storage. Se si pianifica la distribuzione di un file MP4 con il download progressivo, usare questa opzione.If you plan to deliver an MP4 using progressive download, use this option.
  • CommonEncryption : usare questa opzione per caricare contenuti già crittografati e protetti con Common Encryption o PlayReady DRM (ad esempio, Smooth Streaming protetto con PlayReady DRM).CommonEncryption - Use this option if you are uploading content that has already been encrypted and protected with Common Encryption or PlayReady DRM (for example, Smooth Streaming protected with PlayReady DRM).
  • EnvelopeEncrypted : usare questa opzione se si sta caricando contenuto HLS crittografato con AES.EnvelopeEncrypted – Use this option if you are uploading HLS encrypted with AES. I file devono essere stati codificati e crittografati da Transform Manager.Note that the files must have been encoded and encrypted by Transform Manager.
  • StorageEncrypted : crittografa il contenuto non crittografato localmente usando la crittografia AES a 256 bit, quindi li carica in Archiviazione di Azure dove vengono archiviati con crittografia in modo inattivo.StorageEncrypted - Encrypts your clear content locally using AES-256 bit encryption and then uploads it to Azure Storage where it is stored encrypted at rest. Gli asset protetti con la crittografia di archiviazione vengono decrittografati automaticamente e inseriti in un file system crittografato prima della codifica, quindi ricrittografati facoltativamente prima di essere ricaricati di nuovo come nuovo asset di output.Assets protected with Storage Encryption are automatically unencrypted and placed in an encrypted file system prior to encoding, and optionally re-encrypted prior to uploading back as a new output asset. La crittografia di archiviazione viene usata principalmente quando si vogliono proteggere i file multimediali con input di alta qualità con una crittografia avanzata sul disco locale.The primary use case for Storage Encryption is when you want to secure your high quality input media files with strong encryption at rest on disk.

    Servizi multimediali offre una crittografia di archiviazione su disco per gli asset, non in rete come Digital Rights Management (DRM).Media Services provides on-disk storage encryption for your assets, not over-the-wire like Digital Rights Manager (DRM).

    Se l'asset è protetto con crittografia di archiviazione, è necessario configurare i criteri di distribuzione degli asset.If your asset is storage encrypted, you must configure asset delivery policy. Per altre informazioni, vedere Procedura: Configurare i criteri di distribuzione degli asset.For more information see Configuring asset delivery policy.

Se si specifica che l'asset deve essere crittografato con un'opzione CommonEncrypted o EnvelopeEncypted, sarà necessario associare l'asset a ContentKey.If you specify for your asset to be encrypted with a CommonEncrypted option, or an EnvelopeEncypted option, you will need to associate your asset with a ContentKey. Per alte informazioni, vedere Creare entità ContentKey mediante .NET.For more information, see How to create a ContentKey.

Se si specifica che l'asset deve essere crittografato con un'opzione StorageEncrypted, Media Services SDK per .NET creerà un'entità StorateEncrypted ContentKey per l'asset.If you specify for your asset to be encrypted with a StorageEncrypted option, the Media Services SDK for .NET will create a StorateEncrypted ContentKey for your asset.

Questo argomento illustra come usare l'SDK di Servizi multimediali per .NET e le relative estensioni per caricare file in un asset di Servizi multimediali.This topic shows how to use Media Services .NET SDK as well as Media Services .NET SDK extensions to upload files into a Media Services asset.

Caricare un singolo file con SDK di Servizi multimediali per .NETUpload a single file with Media Services .NET SDK

L'esempio di codice seguente usa l'SDK .NET per caricare un singolo file.The sample code below uses .NET SDK to upload a single file. AccessPolicy e Localizzatore vengono creati e distrutti dalla funzione di caricamento.The AccessPolicy and Locator are created and destroyed by the Upload function.

    static public IAsset CreateAssetAndUploadSingleFile(AssetCreationOptions assetCreationOptions, string singleFilePath)
    {
        if (!File.Exists(singleFilePath))
        {
            Console.WriteLine("File does not exist.");
            return null;
        }

        var assetName = Path.GetFileNameWithoutExtension(singleFilePath);
        IAsset inputAsset = _context.Assets.Create(assetName, assetCreationOptions);

        var assetFile = inputAsset.AssetFiles.Create(Path.GetFileName(singleFilePath));

        Console.WriteLine("Upload {0}", assetFile.Name);

        assetFile.Upload(singleFilePath);
        Console.WriteLine("Done uploading {0}", assetFile.Name);

        return inputAsset;
    }

Caricare più file con SDK di Servizi multimediali per .NETUpload multiple files with Media Services .NET SDK

Il seguente codice illustra come creare un asset e caricare più file.The following code shows how to create an asset and upload multiple files.

Il codice esegue le seguenti attività:The code does the following:

  • Crea un'entità Asset vuota usando il metodo CreateEmptyAsset definito nel passaggio precedente.Creates an empty asset using the CreateEmptyAsset method defined in the previous step.
  • Crea un'istanza di AccessPolicy che definisce le autorizzazioni e la durata dell'accesso all'asset.Creates an AccessPolicy instance that defines the permissions and duration of access to the asset.
  • Crea un'istanza di Locator che consente l'accesso all'asset.Creates a Locator instance that provides access to the asset.
  • Crea un'istanza di BlobTransferClient .Creates a BlobTransferClient instance. Questo tipo rappresenta un client che agisce sugli oggetti BLOB di Azure.This type represents a client that operates on the Azure blobs. In questo esempio viene usato il client per monitorare lo stato del caricamento.In this example we use the client to monitor the upload progress.
  • Enumera i file della directory specificata e crea un'istanza di AssetFile per ogni file.Enumerates through files in the specified directory and creates an AssetFile instance for each file.
  • Carica i file in Servizi multimediali usando il metodo UploadAsync .Uploads the files into Media Services using the UploadAsync method.

Nota

Usare il metodo UploadAsync in modo che non si verifichino blocchi delle chiamate e i file vengano caricati in parallelo.Use the UploadAsync method to ensure that the calls are not blocking and the files are uploaded in parallel.

    static public IAsset CreateAssetAndUploadMultipleFiles(AssetCreationOptions assetCreationOptions, string folderPath)
    {
        var assetName = "UploadMultipleFiles_" + DateTime.UtcNow.ToString();

        IAsset asset = _context.Assets.Create(assetName, assetCreationOptions);

        var accessPolicy = _context.AccessPolicies.Create(assetName, TimeSpan.FromDays(30),
                                                            AccessPermissions.Write | AccessPermissions.List);

        var locator = _context.Locators.CreateLocator(LocatorType.Sas, asset, accessPolicy);

        var blobTransferClient = new BlobTransferClient();
        blobTransferClient.NumberOfConcurrentTransfers = 20;
        blobTransferClient.ParallelTransferThreadCount = 20;

        blobTransferClient.TransferProgressChanged += blobTransferClient_TransferProgressChanged;

        var filePaths = Directory.EnumerateFiles(folderPath);

        Console.WriteLine("There are {0} files in {1}", filePaths.Count(), folderPath);

        if (!filePaths.Any())
        {
            throw new FileNotFoundException(String.Format("No files in directory, check folderPath: {0}", folderPath));
        }

        var uploadTasks = new List<Task>();
        foreach (var filePath in filePaths)
        {
            var assetFile = asset.AssetFiles.Create(Path.GetFileName(filePath));
            Console.WriteLine("Created assetFile {0}", assetFile.Name);

            // It is recommended to validate AccestFiles before upload. 
            Console.WriteLine("Start uploading of {0}", assetFile.Name);
            uploadTasks.Add(assetFile.UploadAsync(filePath, blobTransferClient, locator, CancellationToken.None));
        }

        Task.WaitAll(uploadTasks.ToArray());
        Console.WriteLine("Done uploading the files");

        blobTransferClient.TransferProgressChanged -= blobTransferClient_TransferProgressChanged;

        locator.Delete();
        accessPolicy.Delete();

        return asset;
    }

static void  blobTransferClient_TransferProgressChanged(object sender, BlobTransferProgressChangedEventArgs e)
{
    if (e.ProgressPercentage > 4) // Avoid startup jitter, as the upload tasks are added.
    {
        Console.WriteLine("{0}% upload competed for {1}.", e.ProgressPercentage, e.LocalFile);
    }
}

Quando si carica un numero elevato di asset, prendere in considerazione quanto segue.When uploading a large number of assets, consider the following.

  • Creare un nuovo oggetto CloudMediaContext per thread.Create a new CloudMediaContext object per thread. La classe CloudMediaContext non è di tipo thread-safe.The CloudMediaContext class is not thread safe.
  • Aumentare il valore di NumberOfConcurrentTransfers sostituendo il valore 2 predefinito con uno maggiore, ad esempio 5.Increase NumberOfConcurrentTransfers from the default value of 2 to a higher value like 5. L'impostazione di questa proprietà ha effetto su tutte le istanze di CloudMediaContext.Setting this property affects all instances of CloudMediaContext.
  • Mantenere su 10 l'impostazione predefinita di ParallelTransferThreadCount.Keep ParallelTransferThreadCount at the default value of 10.

Inserimento di asset in blocco tramite SDK di Servizi multimediali per .NETIngesting Assets in Bulk using Media Services .NET SDK

Il caricamento di file di asset di grandi dimensioni costituisce un collo di bottiglia nella creazione di asset.Uploading large asset files can be a bottleneck during asset creation. L'inserimento di asset in blocco prevede il disaccoppiamento del processo di creazione di asset da quello di caricamento.Ingesting Assets in Bulk or “Bulk Ingesting”, involves decoupling asset creation from the upload process. Per usare un approccio di inserimento in blocco, creare un manifesto (IngestManifest) in cui vengono descritti l'asset e i relativi file associati.To use a bulk ingesting approach, create a manifest (IngestManifest) that describes the asset and its associated files. Usare quindi il metodo di caricamento che si preferisce per caricare i file associati nel contenitore BLOB del manifesto.Then use the upload method of your choice to upload the associated files to the manifest’s blob container. Servizi multimediali di Microsoft Azure controlla il contenitore BLOB associato al manifesto.Microsoft Azure Media Services watches the blob container associated with the manifest. Dopo che un file è stato caricato nel contenitore BLOB, Servizi multimediali di Microsoft Azure completa la creazione dell'asset in base alla configurazione dell'asset nel manifesto (IngestManifestAsset).Once a file is uploaded to the blob container, Microsoft Azure Media Services completes the asset creation based on the configuration of the asset in the manifest (IngestManifestAsset).

Per creare una nuova entità IngestManifest, chiamare il metodo Create esposto dalla raccolta IngestManifests in CloudMediaContext.To create a new IngestManifest call the Create method exposed by the IngestManifests collection on the CloudMediaContext. Questo metodo creerà una nuova entità IngestManifest con il nome di manifesto specificato.This method will create a new IngestManifest with the manifest name you provide.

IIngestManifest manifest = context.IngestManifests.Create(name);

Creare gli asset che verranno associati all'entità IngestManifest in blocco.Create the assets that will be associated with the bulk IngestManifest. Configurare le opzioni di crittografia desiderate nell'asset per l'inserimento in blocco.Configure the desired encryption options on the asset for bulk ingesting.

// Create the assets that will be associated with this bulk ingest manifest
IAsset destAsset1 = _context.Assets.Create(name + "_asset_1", AssetCreationOptions.None);
IAsset destAsset2 = _context.Assets.Create(name + "_asset_2", AssetCreationOptions.None);

Un'entità IngestManifestAsset associa un Asset a un IngestManifest in blocco per l'inserimento in blocco.An IngestManifestAsset associates an Asset with a bulk IngestManifest for bulk ingesting. Associa anche le entità AssetFiles che costituiranno i singoli Asset.It also associates the AssetFiles that will make up each Asset. Per creare un'entità IngestManifestAsset, usare il metodo Create nel contesto server.To create an IngestManifestAsset, use the Create method on the server context.

Il seguente esempio illustra come aggiungere due nuove entità IngestManifestAssets che associano i due asset creati in precedenza al manifesto di inserimento in blocco.The following example demonstrates adding two new IngestManifestAssets that associate the two assets previously created to the bulk ingest manifest. Ogni entità IngestManifestAsset associa anche un set di file che verrà caricato per ogni asset durante l'inserimento in blocco.Each IngestManifestAsset also associates a set of files that will be uploaded for each asset during bulk ingesting.

string filename1 = _singleInputMp4Path;
string filename2 = _primaryFilePath;
string filename3 = _singleInputFilePath;

IIngestManifestAsset bulkAsset1 =  manifest.IngestManifestAssets.Create(destAsset1, new[] { filename1 });
IIngestManifestAsset bulkAsset2 =  manifest.IngestManifestAssets.Create(destAsset2, new[] { filename2, filename3 });

È possibile usare qualsiasi applicazione client ad alta velocità in grado di caricare i file di asset nell'URI del contenitore di archiviazione BLOB fornito dalla proprietà IIngestManifest.BlobStorageUriForUpload di IngestManifest.You can use any high speed client application capable of uploading the asset files to the blob storage container URI provided by the IIngestManifest.BlobStorageUriForUpload property of the IngestManifest. Un servizio di caricamento ad alta velocità consigliato è l'applicazione Aspera On Demand for Azure.One notable high speed upload service is Aspera On Demand for Azure Application. È anche possibile scrivere codice per il caricamento dei file di asset, come descritto nel seguente esempio di codice.You can also write code to upload the assets files as shown in the following code example.

static void UploadBlobFile(string destBlobURI, string filename)
{
    Task copytask = new Task(() =>
    {
        var storageaccount = new CloudStorageAccount(new StorageCredentials(_storageAccountName, _storageAccountKey), true);
        CloudBlobClient blobClient = storageaccount.CreateCloudBlobClient();
        CloudBlobContainer blobContainer = blobClient.GetContainerReference(destBlobURI);

        string[] splitfilename = filename.Split('\\');
        var blob = blobContainer.GetBlockBlobReference(splitfilename[splitfilename.Length - 1]);

        using (var stream = System.IO.File.OpenRead(filename))
            blob.UploadFromStream(stream);

        lock (consoleWriteLock)
        {
            Console.WriteLine("Upload for {0} completed.", filename);
        }
    });

    copytask.Start();
}

Il codice per il caricamento dei file di asset per l'esempio utilizzato in questo argomento è riportato nel seguente esempio.The code for uploading the asset files for the sample used in this topic is shown in the following code example.

UploadBlobFile(manifest.BlobStorageUriForUpload, filename1);
UploadBlobFile(manifest.BlobStorageUriForUpload, filename2);
UploadBlobFile(manifest.BlobStorageUriForUpload, filename3);

È possibile determinare lo stato dell'inserimento in blocco per tutti gli asset associati a un'entità IngestManifest eseguendo il polling della proprietà Statistics di IngestManifest.You can determine the progress of the bulk ingesting for all assets associated with an IngestManifest by polling the Statistics property of the IngestManifest. Per aggiornare le informazioni sullo stato, è necessario usare una nuova entità CloudMediaContext ogni volta che si esegue il polling della proprietà Statistics.In order to update progress information, you must use a new CloudMediaContext each time you poll the Statistics property.

Il seguente esempio illustra il polling di un'entità IngestManifest in base alla relativa proprietà Id.The following example demonstrates polling an IngestManifest by its Id.

static void MonitorBulkManifest(string manifestID)
{
   bool bContinue = true;
   while (bContinue)
   {
      CloudMediaContext context = GetContext();
      IIngestManifest manifest = context.IngestManifests.Where(m => m.Id == manifestID).FirstOrDefault();

      if (manifest != null)
      {
         lock(consoleWriteLock)
         {
            Console.WriteLine("\nWaiting on all file uploads.");
            Console.WriteLine("PendingFilesCount  : {0}", manifest.Statistics.PendingFilesCount);
            Console.WriteLine("FinishedFilesCount : {0}", manifest.Statistics.FinishedFilesCount);
            Console.WriteLine("{0}% complete.\n", (float)manifest.Statistics.FinishedFilesCount / (float)(manifest.Statistics.FinishedFilesCount + manifest.Statistics.PendingFilesCount) * 100);

            if (manifest.Statistics.PendingFilesCount == 0)
            {
               Console.WriteLine("Completed\n");
               bContinue = false;
            }
         }

         if (manifest.Statistics.FinishedFilesCount < manifest.Statistics.PendingFilesCount)
            Thread.Sleep(60000);
      }
      else // Manifest is null
         bContinue = false;
   }
}

Caricare file mediante le estensioni dell'SDK per .NETUpload files using .NET SDK Extensions

Il seguente esempio mostra come caricare un singolo file mediante le estensioni dell'SDK per .NET.The example below shows how to upload a single file using .NET SDK Extensions. In questo caso viene usato il metodo CreateFromFile, ma è disponibile anche la versione asincrona (CreateFromFileAsync).In this case the CreateFromFile method is used, but the asynchronous version is also available (CreateFromFileAsync). Il metodo CreateFromFile consente di specificare il nome del file, l'opzione di crittografia e un callback per segnalare lo stato di caricamento del file.The CreateFromFile method lets you specify the file name, encryption option, and a callback in order to report the upload progress of the file.

static public IAsset UploadFile(string fileName, AssetCreationOptions options)
{
    IAsset inputAsset = _context.Assets.CreateFromFile(
        fileName,
        options,
        (af, p) =>
        {
            Console.WriteLine("Uploading '{0}' - Progress: {1:0.##}%", af.Name, p.Progress);
        });

    Console.WriteLine("Asset {0} created.", inputAsset.Id);

    return inputAsset;
}

Il seguente esempio esegue una chiamata alla funzione UploadFile e specifica la crittografia di archiviazione come opzione di creazione dell'asset.The following example calls UploadFile function and specifies storage encryption as the asset creation option.

var asset = UploadFile(@"C:\VideoFiles\BigBuckBunny.mp4", AssetCreationOptions.StorageEncrypted);

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.

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:

Passaggio successivoNext step

Dopo aver caricato un asset in Servizi multimediali, è possibile passare all'argomento Procedura: Ottenere un'istanza del processore di contenuti multimediali.Now that you have uploaded an asset to Media Services, go to the How to Get a Media Processor topic.