Media Services .NET SDK を使用するアセットと関連エンティティの管理Managing Assets and Related Entities with Media Services .NET SDK

このトピックでは、.NET で Azure Media Services エンティティを管理する方法を説明します。This topic shows how to manage Azure Media Services entities with .NET.

注意

2017 年 4 月 1 日からは、レコードの合計数が最大クォータより小さい場合でも、アカウント内の 90 日前より古いすべてのジョブ レコードが、関連付けられているタスク レコードと共に自動的に削除されます。 たとえば、2017 年 4 月 1 日には、アカウント内の 2016 年 12 月 31 日より古いジョブ レコードはすべて、自動的に削除されます。 ジョブやタスクの情報をアーカイブする必要がある場合は、このトピックで説明するコードを使うことができます。

前提条件Prerequisites

.NET を使用した Media Services 開発」の説明に従って、開発環境をセットアップし、app.config ファイルに接続情報を指定します。Set up your development environment and populate the app.config file with connection information, as described in Media Services development with .NET.

アセット参照を取得するGet an Asset Reference

頻繁に実行するタスクでは、Media Services の既存のアセットへの参照を取得します。A frequent task is to get a reference to an existing asset in Media Services. 次のコード例では、アセット ID に基づいて、サーバー コンテキスト オブジェクトで Assets コレクションからアセット参照を取得する方法を示します。次のコード例では、Linq クエリを使用して、既存の IAsset オブジェクトへの参照を取得します。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;
}

すべてのアセットを一覧表示するList All Assets

ストレージに保持しているアセットの数が増えていくと、アセットの一覧表示が役立ちます。As the number of assets you have in storage grows, it is helpful to list your assets. 次のコード例では、サーバー コンテキスト オブジェクトで Assets コレクションを反復処理する方法を示します。The following code example shows how to iterate through the Assets collection on the server context object. またこのコード例では、各アセットについて、そのプロパティ値の一部をコンソールに出力します。With each asset, the code example also writes some of its property values to the console. たとえば、各アセットには多数のメディア ファイルが含まれることがあります。For example, each asset can contain many media files. このコード例では、各アセットに関連付けられているすべてのファイルを書き出します。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());
}

ジョブ参照を取得するGet a Job Reference

Media Services のコードで処理タスクを使用するときは、多くの場合、ID に基づいて既存のジョブへの参照を取得する必要があります。次のコード例では、Jobs コレクションから IJob オブジェクトへの参照を取得する方法を示します。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.

実行時間の長いエンコード ジョブを開始するときは、ジョブ参照を取得し、スレッドのジョブの状態を確認する必要があります。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. このような場合は、メソッドがスレッドから返されるときに、更新されたジョブ参照を取得する必要があります。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;
}

ジョブとアセットを一覧表示するList Jobs and Assets

重要な関連タスクとして、Media Services のアセットと関連付けられているジョブを一覧表示することがあります。An important related task is to list assets with their associated job in Media Services. 次のコード例では、各 IJob オブジェクトを一覧表示し、各ジョブについて、ジョブに関するプロパティ、すべての関連するタスク、すべての入力アセット、およびすべての出力アセットを表示する方法を示します。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. この例のコードは、他の多数のタスクに役立てることができます。The code in this example can be useful for numerous other tasks. たとえば、これまでに実行した 1 つまたは複数のエンコード ジョブの出力アセットを一覧表示する場合は、このコードから出力アセットへのアクセス方法が分かります。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. 出力アセットへの参照が分かっている場合は、コンテンツをダウンロードまたは URL を提供することで、他のユーザーやアプリケーションにコンテンツを配信できます。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.

アセットを配信するためのオプションの詳細については、「 Media Services SDK for .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());
}

すべてのアクセス ポリシーを一覧表示するList all Access Policies

Media Services では、アセットまたはそのファイルに関するアクセス ポリシーを定義できます。In Media Services, you can define an access policy on an asset or its files. アクセス ポリシーで、ファイルやアセットに対するアクセス許可 (アクセスの種類や期間) を定義します。An access policy defines the permissions for a file or an asset (what type of access, and the duration). Media Services のコードでアクセス ポリシーを定義するには、通常は IAccessPolicy オブジェクトを作成して既存のアセットに関連付けます。In your Media Services code, you typically define an access policy by creating an IAccessPolicy object and then associating it with an existing asset. 次に、ILocator オブジェクトを作成します。このオブジェクトにより、Media Services のアセットに直接アクセスできるようになります。Then you create a ILocator object, which lets you provide direct access to assets in Media Services. このドキュメント シリーズ付属の Visual Studio プロジェクトには、アクセス ポリシーとロケーターを作成してアセットに割り当てる方法を示すコード例がいくつか含まれています。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.

次のコード例では、サーバーのすべてのアクセス ポリシーを一覧表示し、それぞれに関連付けられている権限の種類を表示する方法を示します。The following code example shows how to list all access policies on the server, and shows the type of permissions associated with each. アクセス ポリシーを表示するもう 1 つの便利な方法は、サーバーのすべての ILocator オブジェクトを一覧表示することです。各ロケーターについて、関連付けられているアクセス ポリシーを一覧表示するには、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("==============");

    }
}

アクセス ポリシーを制限するLimit Access Policies

注意

さまざまな AMS ポリシー (ロケーター ポリシーや ContentKeyAuthorizationPolicy など) に 1,000,000 ポリシーの制限があります。 常に同じ日数、アクセス許可などを使う場合は、同じポリシー ID を使う必要があります (たとえば、長期間存在するように意図されたロケーターのポリシー (非アップロード ポリシー))。

たとえば、アプリケーションで 1 回だけ実行する次のコードで、汎用的なポリシーのセットを作成できます。For example, you can create a generic set of policies with the following code that would only run one time in your application. 後で使うために、ID をログ ファイルに記録できます。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);

その後、次のようなコードで既存の ID を使うことができます。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());

すべてのロケーターを一覧表示するList All Locators

ロケーターは、アセットに直接アクセスできる直接パス、およびロケーターの関連付けられているアクセス ポリシーの定義に従ってアセットへのアクセス許可を提供する URL です。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. 各アセットの Locators プロパティは、関連付けられている ILocator オブジェクトのコレクションを持つことがあります。Each asset can have a collection of ILocator objects associated with it on its Locators property. サーバー コンテキストも、すべてのロケーターが含まれる Locators コレクションを持ちます。The server context also has a Locators collection that contains all locators.

次のコード例では、サーバーのすべてのロケーターを一覧表示します。The following code example lists all locators on the server. 各ロケーターについて、関連するアセットの ID とアクセス ポリシーを表示します。For each locator, it shows the Id for the related asset and access policy. また、アクセス許可の種類、有効期限、およびアセットの完全パスも表示します。It also displays the type of permissions, the expiration date, and the full path to the asset.

アセットのロケーター パスがアセットの唯一のベース URL であることに注意してください。Note that a locator path to an asset is only a base URL to the asset. ユーザーまたはアプリケーションが参照することができる個々のファイルへの直接パスを作成するには、コードで、ロケーター パスに個別のファイルのパスを追加する必要があります。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. 個別のファイル パスを追加する方法の詳細については、「 Media Services SDK for .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("");
    }
}

大規模なコレクションのエンティティの列挙Enumerating through large collections of entities

パブリック REST v2 では、クエリ結果が 1000 件に制限されているため、エンティティを照会するときには、一度に返されるエンティティが 1000 個に制限されます。When querying entities, there is a limit of 1000 entities returned at one time because public REST v2 limits query results to 1000 results. 大規模なコレクションのエンティティを列挙するときは、Skip と Take を使用する必要があります。You need to use Skip and Take when enumerating through large collections of entities.

次の関数は、指定された Media Services アカウントのすべてのジョブをループします。The following function loops through all the jobs in the provided Media Services Account. Media Services は、Jobs コレクションの 1000 個のジョブを返します。Media Services returns 1000 jobs in Jobs Collection. この関数は、Skip と Take を使用してすべてのジョブが確実に列挙されるようにします (アカウントに 1,000 個を超えるジョブがある場合)。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);
    }
}

アセットを削除するDelete an Asset

次の例では、アセットを削除します。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");

}

ジョブを削除するDelete a Job

ジョブを削除するには、State プロパティで指定されているジョブの状態を確認する必要があります。To delete a job, you must check the state of the job as indicated in the State property. 終了または取り消し済みのジョブは削除できますが、キューに登録済み、スケジュール済み、処理中などの他の状態のジョブは、取り消さないと削除できません。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.

次のコード例では、ジョブを削除する方法を示します。この例では、ジョブの状態をチェックして、状態が終了または取り消し済みであるときに削除します。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. このコードは、ジョブ参照の取得については、このトピックの前述のセクション「ジョブ参照を取得する」に依存します。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;
        }

    }
}

アクセス ポリシーを削除するDelete an Access Policy

次のコード例では、ポリシー ID に基づいてアクセス ポリシーへの参照を取得し、ポリシーを削除する方法を示します。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();

}

Media Services のラーニング パスMedia Services learning paths

Azure Media Services のラーニング パスについて読む。Read about the Azure Media Services learning paths:

フィードバックの提供Provide feedback

フィードバック フォーラムでは、Azure Media Services の改善方法について、フィードバックの提供や提案を行うことができます。Use the User Voice forum to provide feedback and make suggestions on how to improve Azure Media Services. また、次のカテゴリのいずれかをクリックすると、そのカテゴリのフォーラムに直接アクセスすることもできます。You also can go directly to one of the following categories: