Gerenciamento dos ativos e entidades relacionadas com o .NET SDK dos Serviços de MídiaManaging Assets and Related Entities with Media Services .NET SDK

Observação

Não estão sendo adicionados novos recursos ou funcionalidades aos Serviços de Mídia v2.No new features or functionality are being added to Media Services v2.
Confira a versão mais recente, Serviços de Mídia v3.Check out the latest version, Media Services v3. Consulte também diretrizes de migração da v2 para v3Also, see migration guidance from v2 to v3

Este tópico mostra como gerenciar as entidades dos Serviços de Mídia do Azure com .NET.This topic shows how to manage Azure Media Services entities with .NET.

A partir de 1º de abril de 2017, qualquer registro de trabalho em sua conta com mais de 90 dias será excluído automaticamente, junto com seus registros de tarefas associados, mesmo que o número total de registros esteja abaixo da cota máxima.Starting April 1, 2017, any Job record in your account older than 90 days will be automatically deleted, along with its associated Task records, even if the total number of records is below the maximum quota. Por exemplo, no dia 1º de abril de 2017, qualquer registro de Trabalho em sua conta que seja mais antigo do que 31 de dezembro de 2016 será excluído automaticamente.For example, on April 1, 2017, any Job record in your account older than December 31, 2016, will be automatically deleted. Se você precisar arquivar as informações de trabalho/tarefa, poderá usar o código descrito neste tópico.If you need to archive the job/task information, you can use the code described in this topic.

Pré-requisitosPrerequisites

Configure seu ambiente de desenvolvimento e preencha o arquivo de configuração app.config com as informações de conexão, conforme descrito em Desenvolvimento de Serviços de Mídia com o .NET.Set up your development environment and populate the app.config file with connection information, as described in Media Services development with .NET.

Obter uma referência de ativoGet an Asset Reference

Uma tarefa frequente é obter uma referência a um ativo existente nos serviços de mídia.A frequent task is to get a reference to an existing asset in Media Services. O exemplo de código a seguir mostra como obter uma referência de ativo da coleção de ativos no objeto de contexto do servidor, com base em uma ID de ativo. O exemplo de código a seguir usa uma consulta Linq para obter uma referência a um objeto IAsset existente.The following code example shows how you can get an asset reference from the Assets collection on the server context object, based on an asset Id. The following code example uses a Linq query to get a reference to an existing IAsset object.

    static IAsset GetAsset(string assetId)
    {
        // Use a LINQ Select query to get an asset.
        var assetInstance =
            from a in _context.Assets
            where a.Id == assetId
            select a;
        // Reference the asset as an IAsset.
        IAsset asset = assetInstance.FirstOrDefault();

        return asset;
    }

Listar todos os ativosList All Assets

À medida que cresce o número de ativos que você tem no armazenamento, é útil listar seus ativos.As the number of assets you have in storage grows, it is helpful to list your assets. O exemplo de código a seguir mostra como percorrer a coleção de ativos no objeto de contexto do servidor.The following code example shows how to iterate through the Assets collection on the server context object. Com cada ativo, o exemplo de código também grava alguns de seus valores de propriedade no console.With each asset, the code example also writes some of its property values to the console. Por exemplo, cada ativo pode conter vários arquivos de mídia.For example, each asset can contain many media files. O exemplo de código grava todos os arquivos associados a cada ativo.The code example writes out all files associated with each asset.

    static void ListAssets()
    {
        string waitMessage = "Building the list. This may take a few "
            + "seconds to a few minutes depending on how many assets "
            + "you have."
            + Environment.NewLine + Environment.NewLine
            + "Please wait..."
            + Environment.NewLine;
        Console.Write(waitMessage);

        // Create a Stringbuilder to store the list that we build. 
        StringBuilder builder = new StringBuilder();

        foreach (IAsset asset in _context.Assets)
        {
            // Display the collection of assets.
            builder.AppendLine("");
            builder.AppendLine("******ASSET******");
            builder.AppendLine("Asset ID: " + asset.Id);
            builder.AppendLine("Name: " + asset.Name);
            builder.AppendLine("==============");
            builder.AppendLine("******ASSET FILES******");

            // Display the files associated with each asset. 
            foreach (IAssetFile fileItem in asset.AssetFiles)
            {
                builder.AppendLine("Name: " + fileItem.Name);
                builder.AppendLine("Size: " + fileItem.ContentFileSize);
                builder.AppendLine("==============");
            }
        }

        // Display output in console.
        Console.Write(builder.ToString());
    }

Obter uma referência de trabalhoGet a Job Reference

Quando você trabalha com o processamento de tarefas em código de serviços de mídia, muitas vezes precisa obter uma referência a um trabalho existente com base em uma ID. O exemplo de código a seguir mostra como obter uma referência a um objeto do IJob da coleção de Trabalhos.When you work with processing tasks in Media Services code, you often need to get a reference to an existing job based on an Id. The following code example shows how to get a reference to an IJob object from the Jobs collection.

Talvez você precise obter uma referência de trabalho ao iniciar um trabalho de codificação de longa duração e precise verificar o status do trabalho em um thread.You may need to get a job reference when starting a long-running encoding job, and need to check the job status on a thread. Em casos como esse, quando o método retorna de um thread, você precisa recuperar uma referência atualizada para um trabalho.In cases like this, when the method returns from a thread, you need to retrieve a refreshed reference to a job.

    static IJob GetJob(string jobId)
    {
        // Use a Linq select query to get an updated 
        // reference by Id. 
        var jobInstance =
            from j in _context.Jobs
            where j.Id == jobId
            select j;
        // Return the job reference as an Ijob. 
        IJob job = jobInstance.FirstOrDefault();

        return job;
    }

Listar trabalhos e ativosList Jobs and Assets

Uma tarefa importante relacionada é listar ativos com seu trabalho associado nos serviços de mídia.An important related task is to list assets with their associated job in Media Services. O exemplo de código a seguir mostra como listar cada objeto IJob e, em seguida, para cada trabalho, exibe as propriedades do trabalho, todas as tarefas relacionadas, todos os ativos e todos os ativos de entrada e de saída.The following code example shows you how to list each IJob object, and then for each job, it displays properties about the job, all related tasks, all input assets, and all output assets. O código neste exemplo pode ser útil para muitas outras tarefas.The code in this example can be useful for numerous other tasks. Por exemplo, se você deseja listar os ativos de saída de um ou mais trabalhos de codificação que você executou anteriormente, este código mostra como acessar os ativos de saída.For example, if you want to list the output assets from one or more encoding jobs that you ran previously, this code shows how to access the output assets. Quando você tem uma referência a um ativo de saída, é possível entregar o conteúdo a outros usuários ou aplicativos baixando-o ou fornecendo URLs.When you have a reference to an output asset, you can then deliver the content to other users or applications by downloading it, or providing URLs.

Para obter mais informações sobre as opções para a entrega de ativos, consulte Fornecer ativos com o SDK dos Serviços de Mídia para .NET.For more information on options for delivering assets, see Deliver Assets with the Media Services SDK for .NET.

    // List all jobs on the server, and for each job, also list 
    // all tasks, all input assets, all output assets.

    static void ListJobsAndAssets()
    {
        string waitMessage = "Building the list. This may take a few "
            + "seconds to a few minutes depending on how many assets "
            + "you have."
            + Environment.NewLine + Environment.NewLine
            + "Please wait..."
            + Environment.NewLine;
        Console.Write(waitMessage);

        // Create a Stringbuilder to store the list that we build. 
        StringBuilder builder = new StringBuilder();

        foreach (IJob job in _context.Jobs)
        {
            // Display the collection of jobs on the server.
            builder.AppendLine("");
            builder.AppendLine("******JOB*******");
            builder.AppendLine("Job ID: " + job.Id);
            builder.AppendLine("Name: " + job.Name);
            builder.AppendLine("State: " + job.State);
            builder.AppendLine("Order: " + job.Priority);
            builder.AppendLine("==============");


            // For each job, display the associated tasks (a job  
            // has one or more tasks). 
            builder.AppendLine("******TASKS*******");
            foreach (ITask task in job.Tasks)
            {
                builder.AppendLine("Task Id: " + task.Id);
                builder.AppendLine("Name: " + task.Name);
                builder.AppendLine("Progress: " + task.Progress);
                builder.AppendLine("Configuration: " + task.Configuration);
                if (task.ErrorDetails != null)
                {
                    builder.AppendLine("Error: " + task.ErrorDetails);
                }
                builder.AppendLine("==============");
            }

            // For each job, display the list of input media assets.
            builder.AppendLine("******JOB INPUT MEDIA ASSETS*******");
            foreach (IAsset inputAsset in job.InputMediaAssets)
            {

                if (inputAsset != null)
                {
                    builder.AppendLine("Input Asset Id: " + inputAsset.Id);
                    builder.AppendLine("Name: " + inputAsset.Name);
                    builder.AppendLine("==============");
                }
            }

            // For each job, display the list of output media assets.
            builder.AppendLine("******JOB OUTPUT MEDIA ASSETS*******");
            foreach (IAsset theAsset in job.OutputMediaAssets)
            {
                if (theAsset != null)
                {
                    builder.AppendLine("Output Asset Id: " + theAsset.Id);
                    builder.AppendLine("Name: " + theAsset.Name);
                    builder.AppendLine("==============");
                }
            }

        }

        // Display output in console.
        Console.Write(builder.ToString());
    }

Listar todas as políticas de acessoList all Access Policies

Nos serviços de mídia, você pode definir uma política de acesso em um ativo ou seus arquivos.In Media Services, you can define an access policy on an asset or its files. Uma política de acesso define as permissões para um arquivo ou um ativo (o tipo de acesso e a duração).An access policy defines the permissions for a file or an asset (what type of access, and the duration). Em seu código de serviços de mídia, você normalmente define uma política de acesso criando um objeto IAccessPolicy e associá-la a um ativo existente.In your Media Services code, you typically define an access policy by creating an IAccessPolicy object and then associating it with an existing asset. Em seguida, você pode criar um objeto ILocator, que permite que você forneça acesso direto aos ativos nos serviços de mídia.Then you create an ILocator object, which lets you provide direct access to assets in Media Services. O projeto do Visual Studio que acompanha esta série de documentação contém vários exemplos de código que mostram como criar e atribuir políticas de acesso e localizadores a ativos.The Visual Studio project that accompanies this documentation series contains several code examples that show how to create and assign access policies and locators to assets.

O exemplo de código a seguir mostra como listar todas as políticas de acesso no servidor e mostra o tipo de permissões associadas a cada um.The following code example shows how to list all access policies on the server, and shows the type of permissions associated with each. Outra maneira útil para exibir as políticas de acesso é listar todos os objetos de ILocator no servidor e, em seguida, para cada localizador, você pode listar sua política de acesso associada usando sua propriedade AccessPolicy.Another useful way to view access policies is to list all ILocator objects on the server, and then for each locator, you can list its associated access policy by using its AccessPolicy property.

    static void ListAllPolicies()
    {
        foreach (IAccessPolicy policy in _context.AccessPolicies)
        {
            Console.WriteLine("");
            Console.WriteLine("Name:  " + policy.Name);
            Console.WriteLine("ID:  " + policy.Id);
            Console.WriteLine("Permissions: " + policy.Permissions);
            Console.WriteLine("==============");

        }
    }

Limitar as políticas de acessoLimit Access Policies

Observação

Há um limite de 1.000.000 políticas para diferentes políticas de AMS (por exemplo, para política de Localizador ou ContentKeyAuthorizationPolicy).There is a limit of 1,000,000 policies for different AMS policies (for example, for Locator policy or ContentKeyAuthorizationPolicy). Use a mesma ID de política, se você estiver sempre usando os mesmos dias/permissões de acesso, por exemplo, políticas de localizadores que devem permanecer no local por um longo período (políticas de não carregamento).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).

Por exemplo, crie um conjunto genérico de políticas com o seguinte código, que será executado somente uma vez em seu aplicativo.For example, you can create a generic set of policies with the following code that would only run one time in your application. Você pode registrar IDs em um arquivo de log para uso posterior:You can log IDs to a log file for later use:

    double year = 365.25;
    double week = 7;
    IAccessPolicy policyYear = _context.AccessPolicies.Create("One Year", TimeSpan.FromDays(year), AccessPermissions.Read);
    IAccessPolicy policy100Year = _context.AccessPolicies.Create("Hundred Years", TimeSpan.FromDays(year * 100), AccessPermissions.Read);
    IAccessPolicy policyWeek = _context.AccessPolicies.Create("One Week", TimeSpan.FromDays(week), AccessPermissions.Read);

    Console.WriteLine("One year policy ID is: " + policyYear.Id);
    Console.WriteLine("100 year policy ID is: " + policy100Year.Id);
    Console.WriteLine("One week policy ID is: " + policyWeek.Id);

Em seguida, use as IDs existentes em seu código, da seguinte maneira:Then, you can use the existing IDs in your code like this:

    const string policy1YearId = "nb:pid:UUID:2a4f0104-51a9-4078-ae26-c730f88d35cf";


    // Get the standard policy for 1 year read only
    var tempPolicyId = from b in _context.AccessPolicies
                       where b.Id == policy1YearId
                       select b;
    IAccessPolicy policy1Year = tempPolicyId.FirstOrDefault();

    // Get the existing asset
    var tempAsset = from a in _context.Assets
                where a.Id == assetID
                select a;
    IAsset asset = tempAsset.SingleOrDefault();

    ILocator originLocator = _context.Locators.CreateLocator(LocatorType.OnDemandOrigin, asset,
        policy1Year,
        DateTime.UtcNow.AddMinutes(-5));
    Console.WriteLine("The locator base path is " + originLocator.BaseUri.ToString());

Listar todos os localizadoresList All Locators

Um localizador é uma URL que fornece um caminho direto para acessar um recurso, juntamente com as permissões para o ativo conforme definido pela política de acesso associada do localizador.A locator is a URL that provides a direct path to access an asset, along with permissions to the asset as defined by the locator's associated access policy. Cada ativo pode ter uma coleção de objetos ILocator associados a ele em sua propriedade de Localizadores.Each asset can have a collection of ILocator objects associated with it on its Locators property. O contexto do servidor também tem uma coleção de localizadores que contém todos os localizadores.The server context also has a Locators collection that contains all locators.

O exemplo de código a seguir lista todos os localizadores no servidor.The following code example lists all locators on the server. Para cada localizador, ele mostra a Id da política de ativo e de acesso relacionada.For each locator, it shows the Id for the related asset and access policy. Ele também exibe o tipo de permissões, a data de expiração e o caminho completo para o ativo.It also displays the type of permissions, the expiration date, and the full path to the asset.

Observe que um caminho de localizador para um ativo é apenas uma URL base para o ativo.Note that a locator path to an asset is only a base URL to the asset. Para criar um caminho direto para arquivos individuais para os quais um usuário ou aplicativo pode navegar, seu código deve adicionar o caminho do arquivo específico ao caminho do localizador.To create a direct path to individual files that a user or application could browse to, your code must add the specific file path to the locator path. Para obter mais informações sobre como fazer isso, consulte Fornecer ativos com o SDK dos Serviços de Mídia para .NET.For more information on how to do this, see the topic Deliver Assets with the Media Services SDK for .NET.

    static void ListAllLocators()
    {
        foreach (ILocator locator in _context.Locators)
        {
            Console.WriteLine("***********");
            Console.WriteLine("Locator Id: " + locator.Id);
            Console.WriteLine("Locator asset Id: " + locator.AssetId);
            Console.WriteLine("Locator access policy Id: " + locator.AccessPolicyId);
            Console.WriteLine("Access policy permissions: " + locator.AccessPolicy.Permissions);
            Console.WriteLine("Locator expiration: " + locator.ExpirationDateTime);
            // The locator path is the base or parent path (with included permissions) to access  
            // the media content of an asset. To create a full URL to a specific media file, take 
            // the locator path and then append a file name and info as needed.  
            Console.WriteLine("Locator base path: " + locator.Path);
            Console.WriteLine("");
        }
    }

Enumerar através de grandes coleções de entidadesEnumerating through large collections of entities

Ao consultar entidades, um limite de 1.000 entidades podem ser retornadas ao mesmo tempo porque a REST v2 pública limita os resultados da consulta a 1.000 resultados.When querying entities, there is a limit of 1000 entities returned at one time because public REST v2 limits query results to 1000 results. Você precisa usar Ignorar e Levar ao enumerar através de grandes coleções de entidades.You need to use Skip and Take when enumerating through large collections of entities.

A função a seguir faz um loop por todos os trabalhos na conta de Serviços de Mídia fornecida.The following function loops through all the jobs in the provided Media Services Account. Os Serviços de Mídia retornam 1.000 trabalhos da coleção de trabalhos.Media Services returns 1000 jobs in Jobs Collection. A função utiliza Ignorar e Levar para certificar-se de que todos os trabalhos sejam enumerados (caso você tenha mais de 1.000 trabalhos em sua conta).The function makes use of Skip and Take to make sure that all jobs are enumerated (in case you have more than 1000 jobs in your account).

    static void ProcessJobs()
    {
        try
        {

            int skipSize = 0;
            int batchSize = 1000;
            int currentBatch = 0;

            while (true)
            {
                // Loop through all Jobs (1000 at a time) in the Media Services account
                IQueryable _jobsCollectionQuery = _context.Jobs.Skip(skipSize).Take(batchSize);
                foreach (IJob job in _jobsCollectionQuery)
                {
                    currentBatch++;
                    Console.WriteLine("Processing Job Id:" + job.Id);
                }

                if (currentBatch == batchSize)
                {
                    skipSize += batchSize;
                    currentBatch = 0;
                }
                else
                {
                    break;
                }
            }
        }
        catch (Exception ex)
        {
            Console.WriteLine(ex.Message);
        }
    }

Excluir um ativoDelete an Asset

O exemplo a seguir exclui um ativo.The following example deletes an asset.

    static void DeleteAsset( IAsset asset)
    {
        // delete the asset
        asset.Delete();

        // Verify asset deletion
        if (GetAsset(asset.Id) == null)
            Console.WriteLine("Deleted the Asset");

    }

Excluir um trabalhoDelete a Job

Para excluir um trabalho, você deve verificar o estado do trabalho, conforme indicado na propriedade Estado.To delete a job, you must check the state of the job as indicated in the State property. Os Trabalhos que foram concluídos ou cancelados podem ser excluídos, enquanto os trabalhos que estão em alguns outros estados, como enfileirado, agendado ou em processamento devem ser cancelados primeiro e, em seguida, eles podem ser excluídos.Jobs that are finished or canceled can be deleted, while jobs that are in certain other states, such as queued, scheduled, or processing, must be canceled first, and then they can be deleted.

O exemplo de código a seguir mostra um método para exclusão de um trabalho de verificação de estados de trabalho e a exclusão quando o estado é concluído ou cancelado.The following code example shows a method for deleting a job by checking job states and then deleting when the state is finished or canceled. Esse código depende da seção anterior deste tópico para obter uma referência a um trabalho: Obtenha uma referência de trabalho.This code depends on the previous section in this topic for getting a reference to a job: Get a job reference.

    static void DeleteJob(string jobId)
    {
        bool jobDeleted = false;

        while (!jobDeleted)
        {
            // Get an updated job reference.  
            IJob job = GetJob(jobId);

            // Check and handle various possible job states. You can 
            // only delete a job whose state is Finished, Error, or Canceled.   
            // You can cancel jobs that are Queued, Scheduled, or Processing,  
            // and then delete after they are canceled.
            switch (job.State)
            {
                case JobState.Finished:
                case JobState.Canceled:
                case JobState.Error:
                    // Job errors should already be logged by polling or event 
                    // handling methods such as CheckJobProgress or StateChanged.
                    // You can also call job.DeleteAsync to do async deletes.
                    job.Delete();
                    Console.WriteLine("Job has been deleted.");
                    jobDeleted = true;
                    break;
                case JobState.Canceling:
                    Console.WriteLine("Job is cancelling and will be deleted "
                        + "when finished.");
                    Console.WriteLine("Wait while job finishes canceling...");
                    Thread.Sleep(5000);
                    break;
                case JobState.Queued:
                case JobState.Scheduled:
                case JobState.Processing:
                    job.Cancel();
                    Console.WriteLine("Job is scheduled or processing and will "
                        + "be deleted.");
                    break;
                default:
                    break;
            }

        }
    }

Excluir uma política de acessoDelete an Access Policy

O exemplo de código a seguir mostra como obter uma referência a uma política de acesso com base em uma Id de política e, em seguida, excluir a política.The following code example shows how to get a reference to an access policy based on a policy Id, and then to delete the policy.

    static void DeleteAccessPolicy(string existingPolicyId)
    {
        // To delete a specific access policy, get a reference to the policy.  
        // based on the policy Id passed to the method.
        var policyInstance =
                from p in _context.AccessPolicies
                where p.Id == existingPolicyId
                select p;
        IAccessPolicy policy = policyInstance.FirstOrDefault();

        policy.Delete();

    }

Roteiros de aprendizagem dos Serviços de MídiaMedia Services learning paths

Serviços de mídia v3 (mais recente)Media Services v3 (latest)

Confira a versão mais recente dos serviços de mídia do Azure!Check out the latest version of Azure Media Services!

Serviços de mídia v2 (Herdado)Media Services v2 (legacy)

Fornecer comentáriosProvide feedback

Use o fórum User Voice para fazer comentários e sugestões sobre como melhorar os Serviços de Mídia do Azure.Use the User Voice forum to provide feedback and make suggestions on how to improve Azure Media Services. Você também pode ir diretamente para uma das seguintes categorias:You also can go directly to one of the following categories: