Azure Batch CLI テンプレートとファイル転送を使用するUse Azure Batch CLI templates and file transfer

Azure CLI に対して Azure Batch 拡張機能を使用すると、コードを記述せずに Batch ジョブを実行できます。Using an Azure Batch extension to the Azure CLI, it is possible to run Batch jobs without writing code.

Azure CLI で JSON テンプレート ファイルを作成および使用して、Batch のプール、ジョブ、タスクを作成します。Create and use JSON template files with the Azure CLI to create Batch pools, jobs, and tasks. CLI 拡張機能コマンドを使用して、Batch アカウントに関連付けられたストレージ アカウントにジョブ入力ファイルを簡単にアップロードし、ジョブ出力ファイルを簡単にダウンロードします。Use CLI extension commands to easily upload job input files to the storage account associated with the Batch account, and download job output files.

概要Overview

Azure CLI の拡張機能を使用すると、開発者以外のユーザーが Batch をエンド ツー エンドで使用できます。An extension to the Azure CLI enables Batch to be used end-to-end by users who are not developers. CLI コマンドのみで、プールの作成、入力データのアップロード、ジョブと関連するタスクの作成、結果の出力データのダウンロードを行うことができます。With only CLI commands, you can create a pool, upload input data, create jobs and associated tasks, and download the resulting output data. コードを追加する必要はありません。No additional code is required. CLI コマンドを直接実行するか、スクリプトに統合します。Run the CLI commands directly or integrate them into scripts.

JSON ファイル用の Azure CLI での既存の Batch サポートに基づく Batch テンプレートで、プール、ジョブ、タスクなどのアイテムを作成するときのプロパティ値を指定します。Batch templates build on the existing Batch support in the Azure CLI for JSON files to specify property values when creating pools, jobs, tasks, and other items. Batch テンプレートは、次の機能を追加します。Batch templates add the following capabilities:

  • パラメーターを定義できます。Parameters can be defined. テンプレートを使用するときに、アイテムを作成するためのパラメーター値だけを指定します。アイテムの他のプロパティ値は、テンプレートの本文で指定されます。When the template is used, only the parameter values are specified to create the item, with other item property values specified in the template body. Batch と Batch によって実行されるアプリケーションの知識があるユーザーは、プール、ジョブ、タスクのプロパティ値を指定してテンプレートを作成できます。A user who understands Batch and the applications to be run by Batch can create templates, specifying pool, job, and task property values. Batch やアプリケーションの知識が乏しいユーザーは、定義済みのパラメーターの値を指定するだけで済みます。A user less familiar with Batch and/or the applications only needs to specify the values for the defined parameters.

  • ジョブ タスク ファクトリは、ジョブに関連する 1 つまたは複数のタスクを作成し、多くのタスクの定義を作成する必要をなくし、ジョブの送 信を大幅に簡略化します。Job task factories create one or more tasks associated with a job, avoiding the need for many task definitions to be created and significantly simplifying job submission.

通常、ジョブは入力データ ファイルを使用して出力データ ファイルを生成します。Jobs typically use input data files and produce output data files. 既定では、ストレージ アカウントは各 Batch アカウントに関連付けられています。A storage account is associated, by default, with each Batch account. コーディングやストレージの資格情報を使用せずに、CLI を使用してこのストレージ アカウントとの間でファイルを転送します。Transfer files to and from this storage account using the CLI, with no coding and no storage credentials.

たとえば、ffmpeg は、オーディオ/ビデオ ファイルを処理する一般的なアプリケーションです。For example, ffmpeg is a popular application that processes audio and video files. Azure Batch CLI を使用して ffmpeg を呼び出し、ソース ビデオ ファイルをさまざまな解像度にトランスコードする手順は次のとおりです。Here are steps with the Azure Batch CLI to invoke ffmpeg to transcode source video files to different resolutions.

  • プール テンプレートを作成します。Create a pool template. テンプレートを作成するユーザーには、ffmpeg アプリケーションを呼び出す方法とその要件に関する知識があります。作成者は、適切な OS、VM サイズ、ffmpeg のインストール方法 (アプリケーション パッケージの使用、パッケージ マネージャーの使用など)、プールの他のプロパティ値を指定します。The user creating the template knows how to call the ffmpeg application and its requirements; they specify the appropriate OS, VM size, how ffmpeg is installed (from an application package or using a package manager, for example), and other pool property values. テンプレートを使用するときにパラメーターが作成されます。指定する必要があるのは、プール ID と VM の数だけです。Parameters are created so when the template is used, only the pool ID and number of VMs need to be specified.

  • ジョブ テンプレートを作成します。Create a job template. テンプレートを作成するユーザーは、ffmpeg を呼び出してソース ビデオを別の解像度にトランスコードする必要があることをわかっており、タスク コマンド ラインを指定します。作成者は、ソース ビデオ ファイルを格納するフォルダーがあり、入力ファイルごとにタスクが必要であることもわかっています。The user creating the template knows how ffmpeg needs to be invoked to transcode source video to a different resolution and specifies the task command line; they also know that there is a folder containing the source video files, with a task required per input file.

  • トランスコードする一連のビデオ ファイルを持つエンド ユーザーは、まずプール テンプレートを使用してプールを作成し、プール ID と必要な VM の数のみを指定します。An end user with a set of video files to transcode first creates a pool using the pool template, specifying only the pool ID and number of VMs required. これで、トランスコードするソース ファイルをアップロードできるようになります。They can then upload the source files to transcode. 次に、ジョブ テンプレートを使用し、プール ID とアップロードするソース ファイルの場所だけを指定してジョブを送信できます。A job can then be submitted using the job template, specifying only the pool ID and location of the source files uploaded. 生成される入力ファイルごとに 1 つのタスクを含む Batch ジョブが作成されます。The Batch job is created, with one task per input file being generated. 最後に、トランスコードされた出力ファイルをダウンロードできます。Finally, the transcoded output files can be downloaded.

インストールInstallation

Azure Batch CLI 拡張機能をインストールするには、まず Azure CLI 2.0 をインストールするか、Azure CLI を Azure Cloud Shell で実行します。To install the Azure Batch CLI extension, first Install the Azure CLI 2.0, or run the Azure CLI in Azure Cloud Shell.

次の Azure CLI コマンドを使って、最新バージョンの Batch 拡張機能をインストールします。Install the latest version of the Batch extension using the following Azure CLI command:

az extension add --name azure-batch-cli-extensions

Batch CLI 拡張機能と追加のインストール オプションの詳細については、GitHub リポジトリを参照してください。For more information about the Batch CLI extension and additional installation options, see the GitHub repo.

CLI 拡張機能を使用するには、Azure Batch アカウントが必要です。ストレージにファイルを転送するコマンドとストレージからファイルを転送するコマンドでは、リンクされたストレージ アカウントが必要です。To use the CLI extension features, you need an Azure Batch account and, for the commands that transfer files to and from storage, a linked storage account.

Azure CLI を使用して Batch アカウントにログインするには、Azure CLI を使用した Batch リソースの管理の関する記事を参照してください。To log into a Batch account with the Azure CLI, see Manage Batch resources with Azure CLI.

テンプレートTemplates

Azure Batch テンプレートは、機能と構文が Azure Resource Manager テンプレートと似ています。Azure Batch templates are similar to Azure Resource Manager templates, in functionality and syntax. これらのテンプレートは、アイテムのプロパティの名前と値が含まれた JSON ファイルですが、次の主要概念が追加されます。They are JSON files that contain item property names and values, but add the following main concepts:

  • パラメーターParameters

    • 本文セクションでプロパティ値を指定し、テンプレートを使用するときに指定する必要があるパラメーター値だけを含めることができます。Allow property values to be specified in a body section, with only parameter values needing to be supplied when the template is used. たとえば、プールの完全な定義を本文に配置し、プール ID の 1 つのパラメーターだけを定義します。これにより、プールを作成するために指定する必要があるのはプール ID 文字列だけになります。For example, the complete definition for a pool could be placed in the body and only one parameter defined for pool id; only a pool ID string therefore needs to be supplied to create a pool.

    • テンプレートの本文は、Batch と Batch によって実行されるアプリケーションの知識があるユーザーが作成できます。テンプレートを使用するときは、作成者が定義したパラメーターの値だけを指定する必要があります。The template body can be authored by someone with knowledge of Batch and the applications to be run by Batch; only values for the author-defined parameters must be supplied when the template is used. そのため、Batch やアプリケーションの深い知識のないユーザーがテンプレートを使用できます。A user without the in-depth Batch and/or application knowledge can therefore use the templates.

  • 変数Variables

    • 単純または複雑なパラメーター値を 1 つの場所で指定し、テンプレートの本文内の 1 つ以上の場所で使用できます。Allow simple or complex parameter values to be specified in one place and used in one or more places in the template body. 変数により、テンプレートを簡素化し、サイズを小さくすることができるだけでなく、プロパティを 1 か所で変更できるので、テンプレートの保守が容易になります。Variables can simplify and reduce the size of the template, as well as make it more maintainable by having one location to change properties.
  • 高度なコンストラクトHigher-level constructs

    • Batch API ではまだ使用できない一部の高度なコンストラクトをテンプレートで使用できます。Some higher-level constructs are available in the template that are not yet available in the Batch APIs. たとえば、タスク ファクトリは、共通のタスク定義を使って、ジョブの複数のタスクを作成するジョブ テンプレート内に定義できます。For example, a task factory can be defined in a job template that creates multiple tasks for the job, using a common task definition. これらのコンストラクトにより、複数の JSON ファイル (タスクごとに 1 ファイルなど) を動的に作成するコードを記述したり、パッケージ マネージャーを使用してアプリケーションをインストールするためのスクリプト ファイルを作成したりする必要がなくなります。These constructs avoid the need to code to dynamically create multiple JSON files, such as one file per task, as well as create script files to install applications via a package manager.

    • ある時点で、これらのコンストラクトを Batch サービスに追加し、Batch API、UI などで使用できます。At some point, these constructs may be added to the Batch service and available in the Batch APIs, UIs, etc.

プール テンプレートPool templates

プール テンプレートは、パラメーターと変数の標準的なテンプレートの機能をサポートします。Pool templates support the standard template capabilities of parameters and variables. 次の高度なコンストラクトもサポートします。They also support the following higher-level construct:

  • パッケージ参照Package references

    • 必要に応じて、パッケージ マネージャーを使用して、ソフトウェアをプール ノードにコピーできます。Optionally allows software to be copied to pool nodes by using package managers. パッケージ マネージャーとパッケージ ID が指定されます。The package manager and package ID are specified. 1 つ以上のパッケージを宣言することで、必要なパッケージを取得するスクリプトを作成し、そのスクリプトをインストールして、各プール ノードで実行する必要がなくなります。By declaring one or more packages, you avoid creating a script that gets the required packages, installing the script, and running the script on each pool node.

ffmpeg がインストールされた Linux VM のプールを作成するテンプレートの例を次に示します。The following is an example of a template that creates a pool of Linux VMs with ffmpeg installed. これを使用するには、プールの ID 文字列と、プール内の VM の数のみを指定します。To use it, supply only a pool ID string and the number of VMs in the pool:

{
    "parameters": {
        "nodeCount": {
            "type": "int",
            "metadata": {
                "description": "The number of pool nodes"
            }
        },
        "poolId": {
            "type": "string",
            "metadata": {
                "description": "The pool ID "
            }
        }
    },
    "pool": {
        "type": "Microsoft.Batch/batchAccounts/pools",
        "apiVersion": "2016-12-01",
        "properties": {
            "id": "[parameters('poolId')]",
            "virtualMachineConfiguration": {
                "imageReference": {
                    "publisher": "Canonical",
                    "offer": "UbuntuServer",
                    "sku": "16.04-LTS",
                    "version": "latest"
                },
                "nodeAgentSKUId": "batch.node.ubuntu 16.04"
            },
            "vmSize": "STANDARD_D3_V2",
            "targetDedicatedNodes": "[parameters('nodeCount')]",
            "enableAutoScale": false,
            "maxTasksPerNode": 1,
            "packageReferences": [
                {
                    "type": "aptPackage",
                    "id": "ffmpeg"
                }
            ]
        }
    }
}

このテンプレート ファイルに pool-ffmpeg.json という名前を付けた場合、テンプレートを次のように呼び出します。If the template file was named pool-ffmpeg.json, then invoke the template as follows:

az batch pool create --template pool-ffmpeg.json

CLI は、poolId パラメーターと nodeCount パラメーターの値を指定することを要求します。The CLI prompts you to provide values for the poolId and nodeCount parameters. JSON ファイル内にこれらのパラメーターを指定することもできます。You can also supply the parameters in a JSON file. 例:For example:

{
  "poolId": {
    "value": "mypool"
  },
  "nodeCount": {
    "value": 2
  }
}

パラメーターの JSON ファイルに pool-parameters.json という名前を付けた場合は、テンプレートを次のように呼び出します。If the parameters JSON file was named pool-parameters.json, then invoke the template as follows:

az batch pool create --template pool-ffmpeg.json --parameters pool-parameters.json

ジョブ テンプレートJob templates

ジョブ テンプレートは、パラメーターと変数の標準的なテンプレートの機能をサポートします。Job templates support the standard template capabilities of parameters and variables. 次の高度なコンストラクトもサポートします。They also support the following higher-level construct:

  • タスク ファクトリTask factory

    • 1 つのタスク定義からジョブの複数のタスクを作成します。Creates multiple tasks for a job from one task definition. パラメーター スイープ、ファイルごとのタスク、タスク コレクションの 3 種類のタスク ファクトリがサポートされています。Three types of task factory are supported – parametric sweep, task per file, and task collection.

ffmpeg を使用して MP4 ビデオ ファイルを 2 つの低解像度のいずれかにトランスコードするジョブを作成するテンプレートの例を次に示します。The following is an example of a template that creates a job to transcode MP4 video files with ffmpeg to one of two lower resolutions. ソース ビデオ ファイルごとに 1 つのタスクを作成します。It creates one task per source video file. ジョブの入力と出力用のファイル グループの詳細については、「ファイル グループと ファイル転送」を参照してください。See File groups and file transfer for more about file groups for job input and output.

{
    "parameters": {
        "poolId": {
            "type": "string",
            "metadata": {
                "description": "The name of Azure Batch pool which runs the job"
            }
        },
        "jobId": {
            "type": "string",
            "metadata": {
                "description": "The name of Azure Batch job"
            }
        },
        "resolution": {
            "type": "string",
            "defaultValue": "428x240",
            "allowedValues": [
                "428x240",
                "854x480"
            ],
            "metadata": {
                "description": "Target video resolution"
            }
        }
    },
    "job": {
        "type": "Microsoft.Batch/batchAccounts/jobs",
        "apiVersion": "2016-12-01",
        "properties": {
            "id": "[parameters('jobId')]",
            "constraints": {
                "maxWallClockTime": "PT5H",
                "maxTaskRetryCount": 1
            },
            "poolInfo": {
                "poolId": "[parameters('poolId')]"
            },
            "taskFactory": {
                "type": "taskPerFile",
                "source": { 
                    "fileGroup": "ffmpeg-input"
                },
                "repeatTask": {
                    "commandLine": "ffmpeg -i {fileName} -y -s [parameters('resolution')] -strict -2 {fileNameWithoutExtension}_[parameters('resolution')].mp4",
                    "resourceFiles": [
                        {
                            "blobSource": "{url}",
                            "filePath": "{fileName}"
                        }
                    ],
                    "outputFiles": [
                        {
                            "filePattern": "{fileNameWithoutExtension}_[parameters('resolution')].mp4",
                            "destination": {
                                "autoStorage": {
                                    "path": "{fileNameWithoutExtension}_[parameters('resolution')].mp4",
                                    "fileGroup": "ffmpeg-output"
                                }
                            },
                            "uploadOptions": {
                                "uploadCondition": "TaskSuccess"
                            }
                        }
                    ]
                }
            },
            "onAllTasksComplete": "terminatejob"
        }
    }
}

このテンプレート ファイルに job-ffmpeg.json という名前を付けた場合、テンプレートを次のように呼び出します。If the template file was named job-ffmpeg.json, then invoke the template as follows:

az batch job create --template job-ffmpeg.json

前と同じように、CLI は、パラメーターの値を指定することを要求します。As before, the CLI prompts you to provide values for the parameters. JSON ファイル内にこれらのパラメーターを指定することもできます。You can also supply the parameters in a JSON file.

Batch Explorer でテンプレートを使用するUse templates in Batch Explorer

Batch CLI テンプレートを Batch Explorer デスクトップ アプリケーション (旧称 BatchLabs) にアップロードして、Batch プールまたはジョブを作成できます。You can upload a Batch CLI template to the Batch Explorer desktop application (formerly called BatchLabs) to create a Batch pool or job. Batch Explorer ギャラリーに定義済みのプールとジョブ テンプレートから選択することもできます。You can also select from predefined pool and job templates in the Batch Explorer Gallery.

テンプレートをアップロードするには:To upload a template:

  1. Batch Explorer で、 [ギャラリー] > [ローカル テンプレート] を選択します。In Batch Explorer, select Gallery > Local templates.

  2. ローカル プールまたはジョブ テンプレートを選択するか、ドラッグ アンド ドロップします。Select, or drag and drop, a local pool or job template.

  3. [このテンプレートを使用する] を選択し、画面のプロンプトに従います。Select Use this template, and follow the on-screen prompts.

ファイル グループとファイル転送File groups and file transfer

ほとんどのジョブとタスクは、入力ファイルを必要し、出力ファイルを生成します。Most jobs and tasks require input files and produce output files. 通常、入力ファイルと出力ファイルは、クライアントからノードまたはノードからクライアントに転送します。Usually, input files and output files are transferred, either from the client to the node, or from the node to the client. Azure Batch CLI 拡張機能では、ファイル転送を排除し、各 Batch アカウントに関連付けることができるストレージ アカウントを利用します。The Azure Batch CLI extension abstracts away file transfer and utilizes the storage account that you can associate with each Batch account.

ファイル グループは Azure ストレージ アカウントに作成されるコンテナーに相当します。A file group equates to a container that is created in the Azure storage account. ファイル グループにはサブフォルダーを含めることができます。The file group may have subfolders.

Batch CLI 拡張機能には、クライアントから指定したファイル グループにファイルをアップロードするコマンドと、指定したファイル グループからクライアントにファイルをダウンロードするコマンドが用意されています。The Batch CLI extension provides commands to upload files from client to a specified file group and download files from the specified file group to a client.

az batch file upload --local-path c:\source_videos\*.mp4 
    --file-group ffmpeg-input

az batch file download --file-group ffmpeg-output --local-path
    c:\output_lowres_videos

プール テンプレートとジョブ テンプレートでは、プール ノードにコピーしたり、プール ノードからファイル グループにコピーしたりするために、ファイル グループに保存されたファイルを指定できます。Pool and job templates allow files stored in file groups to be specified for copy onto pool nodes or off pool nodes back to a file group. たとえば、前に指定したジョブ テンプレートでは、コード変換するためのノードにコピーされるソース ビデオ ファイルの場所として、ファイル グループ ffmpeg-input がタスク ファクトリに指定されています。For example, in the job template specified previously, the file group ffmpeg-input is specified for the task factory as the location of the source video files copied down to the node for transcoding. ファイル グループ ffmpeg-output は、コード変換された出力ファイルが各タスクを実行するノードからコピーされる場所です。The file group ffmpeg-output is the location where the transcoded output files are copied from the node running each task.

まとめSummary

現在、テンプレートとファイル転送のサポートは、Azure CLI にのみ追加されています。Template and file transfer support have currently been added only to the Azure CLI. 目標は、Batch を使用できる対象ユーザーを、Batch API を使用してコードを開発する必要のないユーザー (研究者、IT ユーザーなど) に拡大することです。The goal is to expand the audience that can use Batch to users who do not need to develop code using the Batch APIs, such as researchers and IT users. Azure、Batch、Batch によって実行されるアプリケーションの知識があるユーザーは、コードを記述せずにプールやジョブを作成するためのテンプレートを作成できます。Without coding, users with knowledge of Azure, Batch, and the applications to be run by Batch can create templates for pool and job creation. テンプレートのパラメーターにより、Batch やアプリケーションの詳細な知識のないユーザーがテンプレートを使用できるようになります。With template parameters, users without detailed knowledge of Batch and the applications can use the templates.

Azure CLI の Batch 拡張機能を試し、フィードバックまたは提案をお寄せください。その際には、この記事に対するコメントまたは Batch コミュニティ リポジトリをご利用ください。Try out the Batch extension for the Azure CLI and provide us with any feedback or suggestions, either in the comments for this article or via the Batch Community repo.

次の手順Next steps

  • インストールと使用方法に関する詳細なドキュメント、サンプル、ソース コードは、Azure GitHub リポジトリで入手できます。Detailed installation and usage documentation, samples, and source code are available in the Azure GitHub repo.

  • Batch Explorer を使用した Batch リソースの作成と管理方法を確認します。Learn more about using Batch Explorer to create and manage Batch resources.