クイック スタート:Python API で最初の Batch ジョブを実行するQuickstart: Run your first Batch job with the Python API

このクイック スタートでは、Azure Batch Python API に基づいて構築されたアプリケーションから Azure Batch ジョブを実行します。This quickstart runs an Azure Batch job from an application built on the Azure Batch Python API. このアプリでは、複数の入力データ ファイルを Azure Storage にアップロードしてから、Batch コンピューティング ノード (仮想マシン) の "プール" を作成します。The app uploads several input data files to Azure storage and then creates a pool of Batch compute nodes (virtual machines). その後、基本的なコマンドを使用してプールの各入力ファイルを処理するための "タスク" を実行するサンプル "ジョブ" を作成します。Then, it creates a sample job that runs tasks to process each input file on the pool using a basic command. このクイック スタートを完了すると、Batch サービスの主要な概念を理解し、より大規模でより現実的なワークロードで Batch を試せるようになります。After completing this quickstart, you will understand the key concepts of the Batch service and be ready to try Batch with more realistic workloads at larger scale.

クイック スタート アプリのワークフロー

Azure サブスクリプションをお持ちでない場合は、開始する前に無料アカウントを作成してください。If you don't have an Azure subscription, create a free account before you begin.

前提条件Prerequisites

Azure へのサインインSign in to Azure

Azure Portal (https://portal.azure.com) にサインインします。Sign in to the Azure portal at https://portal.azure.com.

アカウントの資格情報を取得するGet account credentials

この例では、Batch アカウントと Storage アカウントの資格情報を指定する必要があります。For this example, you need to provide credentials for your Batch and Storage accounts. Azure Portal を使用すると、必要な資格情報を簡単に取得できますA straightforward way to get the necessary credentials is in the Azure portal. (Azure API やコマンドライン ツールを使用してこれらの資格情報を取得することもできます)。(You can also get these credentials using the Azure APIs or command-line tools.)

  1. [すべてのサービス] > [Batch アカウント] の順に選択し、Batch アカウントの名前を選択します。Select All services > Batch accounts, and then select the name of your Batch account.

  2. Batch 資格情報を表示するには、 [キー] を選択します。To see the Batch credentials, select Keys. [Batch アカウント][URL][プライマリ アクセス キー] の値をテキスト エディターにコピーします。Copy the values of Batch account, URL, and Primary access key to a text editor.

  3. Storage アカウント名とキーを表示するには、 [ストレージ アカウント] を選択します。To see the Storage account name and keys, select Storage account. [ストレージ アカウント名][Key1] の値をテキスト エディターにコピーします。Copy the values of Storage account name and Key1 to a text editor.

サンプルのダウンロードDownload the sample

GitHub からサンプル アプリをダウンロードまたは複製します。Download or clone the sample app from GitHub. Git クライアントを使用してサンプル アプリ リポジトリを複製するには、次のコマンドを使用します。To clone the sample app repo with a Git client, use the following command:

git clone https://github.com/Azure-Samples/batch-python-quickstart.git

Python スクリプト python_quickstart_client.py が含まれているディレクトリに移動します。Go to the directory that contains the Python script python_quickstart_client.py.

ご利用の Python 開発環境で、pip を使用して必要なパッケージをインストールします。In your Python development environment, install the required packages using pip.

pip install -r requirements.txt

ファイル config.pyを開きます。Open the file config.py. Batch アカウントとストレージ アカウントの資格情報文字列を、アカウント用に取得した値で更新します。Update the Batch and storage account credential strings with the values you obtained for your accounts. 例:For example:

_BATCH_ACCOUNT_NAME = 'mybatchaccount'
_BATCH_ACCOUNT_KEY = 'xxxxxxxxxxxxxxxxE+yXrRvJAqT9BlXwwo1CwF+SwAYOxxxxxxxxxxxxxxxx43pXi/gdiATkvbpLRl3x14pcEQ=='
_BATCH_ACCOUNT_URL = 'https://mybatchaccount.mybatchregion.batch.azure.com'
_STORAGE_ACCOUNT_NAME = 'mystorageaccount'
_STORAGE_ACCOUNT_KEY = 'xxxxxxxxxxxxxxxxy4/xxxxxxxxxxxxxxxxfwpbIC5aAWA8wDu+AFXZB827Mt9lybZB1nUcQbQiUrkPtilK5BQ=='

アプリの実行Run the app

Batch ワークフローの動作を確認するには、スクリプトを実行します。To see the Batch workflow in action, run the script:

python python_quickstart_client.py

スクリプトの実行後に、コードを確認して、アプリケーションの各部分での処理内容を学習します。After running the script, review the code to learn what each part of the application does.

サンプル アプリケーションを実行すると、コンソールの出力は次のようになります。When you run the sample application, the console output is similar to the following. 実行中、プールのコンピューティング ノードを開始する際に、Monitoring all tasks for 'Completed' state, timeout in 00:30:00... で一時停止が発生します。During execution, you experience a pause at Monitoring all tasks for 'Completed' state, timeout in 00:30:00... while the pool's compute nodes are started. タスクは、最初のコンピューティング ノードが実行中になるとすぐに、実行するためにキューに登録されます。Tasks are queued to run as soon as the first compute node is running. Batch アカウントにプール、コンピューティング ノード、ジョブ、タスクを監視するには、Azure Portal で Batch アカウントに移動します。Go to your Batch account in the Azure portal to monitor the pool, compute nodes, job, and tasks in your Batch account.

Sample start: 11/26/2018 4:02:54 PM

Container [input] created.
Uploading file taskdata0.txt to container [input]...
Uploading file taskdata1.txt to container [input]...
Uploading file taskdata2.txt to container [input]...
Creating pool [PythonQuickstartPool]...
Creating job [PythonQuickstartJob]...
Adding 3 tasks to job [PythonQuickstartJob]...
Monitoring all tasks for 'Completed' state, timeout in 00:30:00...

タスクが完了すると、タスクごとに次のような出力が表示されます。After tasks complete, you see output similar to the following for each task:

Printing task output...
Task: Task0
Node: tvm-2850684224_3-20171205t000401z
Standard out:
Batch processing began with mainframe computers and punch cards. Today it still plays a central role in business, engineering, science, and other pursuits that require running lots of automated tasks....
...

既定の構成でアプリケーションを実行する場合、通常の実行時間は約 3 分間です。Typical execution time is approximately 3 minutes when you run the application in its default configuration. 最初のプールの設定に最も時間がかかります。Initial pool setup takes the most time.

コードの確認Review the code

このクイック スタートの Python アプリでは、次の処理を実行します。The Python app in this quickstart does the following:

  • 3 つの小さいテキスト ファイルを Azure ストレージ アカウントの BLOB コンテナーにアップロードします。Uploads three small text files to a blob container in your Azure storage account. これらのファイルは、Batch タスクで処理するための入力です。These files are inputs for processing by Batch tasks.
  • Ubuntu 18.04 LTS を実行している 2 つのコンピューティング ノードのプールを作成します。Creates a pool of two compute nodes running Ubuntu 18.04 LTS.
  • ノードで実行するジョブと 3 つのタスクを作成します。Creates a job and three tasks to run on the nodes. 各タスクは、Bash シェル コマンド ラインを使用して入力ファイルの 1 つを処理します。Each task processes one of the input files using a Bash shell command line.
  • タスクによって返されるファイルを表示します。Displays files returned by the tasks.

詳細については、python_quickstart_client.py ファイルと以降のセクションを参照してください。See the file python_quickstart_client.py and the following sections for details.

準備Preliminaries

ストレージ アカウントを操作するには、アプリで azure-storage-blob パッケージを使用して BlockBlobService オブジェクトを作成します。To interact with a storage account, the app uses the azure-storage-blob package to create a BlockBlobService object.

blob_client = azureblob.BlockBlobService(
    account_name=config._STORAGE_ACCOUNT_NAME,
    account_key=config._STORAGE_ACCOUNT_KEY)

このアプリでは、blob_client 参照を使用して、ストレージ アカウントにコンテナーを作成したり、そのコンテナーにデータ ファイルをアップロードしたりします。The app uses the blob_client reference to create a container in the storage account and to upload data files to the container. ストレージ内のファイルは、Batch の ResourceFile オブジェクトとして定義されており、Batch が後でコンピューティング ノードにダウンロードできます。The files in storage are defined as Batch ResourceFile objects that Batch can later download to compute nodes.

input_file_paths = [os.path.join(sys.path[0], 'taskdata0.txt'),
                    os.path.join(sys.path[0], 'taskdata1.txt'),
                    os.path.join(sys.path[0], 'taskdata2.txt')]

input_files = [
    upload_file_to_container(blob_client, input_container_name, file_path)
    for file_path in input_file_paths]

このアプリは BatchServiceClient オブジェクトを作成して、Batch サービスでプール、ジョブ、タスクを作成および管理します。The app creates a BatchServiceClient object to create and manage pools, jobs, and tasks in the Batch service. このサンプルの Batch クライアントでは共有キー認証を使用します。The Batch client in the sample uses shared key authentication. Batch では Azure Active Directory 認証もサポートされます。Batch also supports Azure Active Directory authentication.

credentials = batch_auth.SharedKeyCredentials(config._BATCH_ACCOUNT_NAME,
                                              config._BATCH_ACCOUNT_KEY)

batch_client = batch.BatchServiceClient(
    credentials,
    batch_url=config._BATCH_ACCOUNT_URL)

コンピューティング ノードのプールの作成Create a pool of compute nodes

Batch プールを作成するために、このアプリでは PoolAddParameter クラスを使用して、ノードの数、VM のサイズ、プールの構成を設定します。To create a Batch pool, the app uses the PoolAddParameter class to set the number of nodes, VM size, and a pool configuration. ここでは、VirtualMachineConfiguration オブジェクトで ImageReference に、Azure Marketplace で公開されている Ubuntu Server 18.04 LTS イメージを指定します。Here, a VirtualMachineConfiguration object specifies an ImageReference to an Ubuntu Server 18.04 LTS image published in the Azure Marketplace. Batch は、Azure Marketplace の Linux および Windows Server のさまざまなイメージだけでなく、カスタム VM イメージもサポートしています。Batch supports a wide range of Linux and Windows Server images in the Azure Marketplace, as well as custom VM images.

ノードの数 (_POOL_NODE_COUNT) と VM のサイズ (_POOL_VM_SIZE) は、定義済みの定数です。The number of nodes (_POOL_NODE_COUNT) and VM size (_POOL_VM_SIZE) are defined constants. このサンプルでは、既定で、サイズ Standard_A1_v2 の 2 つのノードで構成されるプールが作成されます。The sample by default creates a pool of 2 size Standard_A1_v2 nodes. 推奨されるサイズは、この簡単な例についてパフォーマンスとコストのバランスが取れています。The size suggested offers a good balance of performance versus cost for this quick example.

pool.add メソッドは、プールを Batch サービスを送信します。The pool.add method submits the pool to the Batch service.

new_pool = batch.models.PoolAddParameter(
    id=pool_id,
    virtual_machine_configuration=batchmodels.VirtualMachineConfiguration(
        image_reference=batchmodels.ImageReference(
            publisher="Canonical",
            offer="UbuntuServer",
            sku="18.04-LTS",
            version="latest"
        ),
        node_agent_sku_id="batch.node.ubuntu 18.04"),
    vm_size=config._POOL_VM_SIZE,
    target_dedicated_nodes=config._POOL_NODE_COUNT
)
batch_service_client.pool.add(new_pool)

Batch ジョブの作成Create a Batch job

Batch ジョブは、1 つ以上のタスクの論理グループです。A Batch job is a logical grouping of one or more tasks. ジョブには、優先度やタスクの実行対象プールなど、タスクに共通する設定が含まれています。A job includes settings common to the tasks, such as priority and the pool to run tasks on. このアプリでは、JobAddParameter クラスを使用して、プールにジョブを作成します。The app uses the JobAddParameter class to create a job on your pool. job.add メソッドにより、指定の Batch アカウントにジョブが追加されます。The job.add method adds a job to the specified Batch account. 最初、ジョブにはタスクがありません。Initially the job has no tasks.

job = batch.models.JobAddParameter(
    id=job_id,
    pool_info=batch.models.PoolInformation(pool_id=pool_id))
batch_service_client.job.add(job)

タスクの作成Create tasks

このアプリは、TaskAddParameter クラスを使用して、タスク オブジェクトの一覧を作成します。The app creates a list of task objects using the TaskAddParameter class. 各タスクは、command_line プロパティを使用して入力の resource_files オブジェクトを処理します。Each task processes an input resource_files object using a command_line parameter. このサンプルのコマンド ラインでは、Bash シェルの cat コマンドを実行してテキスト ファイルを表示します。In the sample, the command line runs the Bash shell cat command to display the text file. このコマンドは、デモンストレーション用の簡単な例です。This command is a simple example for demonstration purposes. Batch を使用する場合、コマンド ラインは、アプリまたはスクリプトを指定する場所です。When you use Batch, the command line is where you specify your app or script. Batch には、アプリやスクリプトをコンピューティング ノードにデプロイする方法が多数用意されています。Batch provides a number of ways to deploy apps and scripts to compute nodes.

その後、アプリは、task.add_collection メソッドを使用してジョブにタスクを追加します。これにより、タスクは、コンピューティング ノードで実行するためにキューに登録されます。Then, the app adds tasks to the job with the task.add_collection method, which queues them to run on the compute nodes.

tasks = list()

for idx, input_file in enumerate(input_files):
    command = "/bin/bash -c \"cat {}\"".format(input_file.file_path)
    tasks.append(batch.models.TaskAddParameter(
        id='Task{}'.format(idx),
        command_line=command,
        resource_files=[input_file]
    )
    )
batch_service_client.task.add_collection(job_id, tasks)

タスク出力の表示View task output

アプリは、タスクの状態を監視し、タスクが完了したことを確認します。The app monitors task state to make sure the tasks complete. その後、アプリには、完了した各タスクによって生成される stdout.txt ファイルが表示されます。Then, the app displays the stdout.txt file generated by each completed task. タスクが正常に実行されると、タスク コマンドの出力は stdout.txt に書き込まれます。When the task runs successfully, the output of the task command is written to stdout.txt:

tasks = batch_service_client.task.list(job_id)

for task in tasks:

    node_id = batch_service_client.task.get(job_id, task.id).node_info.node_id
    print("Task: {}".format(task.id))
    print("Node: {}".format(node_id))

    stream = batch_service_client.file.get_from_task(
        job_id, task.id, config._STANDARD_OUT_FILE_NAME)

    file_text = _read_stream_as_string(
        stream,
        encoding)
    print("Standard output:")
    print(file_text)

リソースのクリーンアップClean up resources

アプリは自動的に、作成された入力用ストレージ コンテナーを削除し、Batch プールとジョブを削除するためのオプションを表示します。The app automatically deletes the storage container it creates, and gives you the option to delete the Batch pool and job. ジョブがスケジュールされていない場合でも、ノードの実行中はプールに対して料金が発生します。You are charged for the pool while the nodes are running, even if no jobs are scheduled. プールは不要になったら、削除してください。When you no longer need the pool, delete it. プールを削除すると、ノード上のタスク出力はすべて削除されます。When you delete the pool, all task output on the nodes is deleted.

リソース グループ、Batch アカウント、ストレージ アカウントは、不要になったら削除します。When no longer needed, delete the resource group, Batch account, and storage account. Azure portal でこれを行うには、Batch アカウントのリソース グループを選択し、 [リソース グループの削除] を選択します。To do so in the Azure portal, select the resource group for the Batch account and select Delete resource group.

次の手順Next steps

このクイック スタートでは、Batch Python API を使用して構築された小さいアプリを実行し、Batch プールと Batch ジョブを作成しました。In this quickstart, you ran a small app built using the Batch Python API to create a Batch pool and a Batch job. このジョブによってサンプル タスクが実行され、作成された出力がノードにダウンロードされました。The job ran sample tasks, and downloaded output created on the nodes. Batch サービスの主要な概念を理解できたので、より大規模でより現実的なワークロードを使用して Batch を試す準備が整いました。Now that you understand the key concepts of the Batch service, you are ready to try Batch with more realistic workloads at larger scale. Azure Batch の詳細を確認し、実際のアプリケーションで並列ワークロードを詳しく見てみるには、Batch Python のチュートリアルに進んでください。To learn more about Azure Batch, and walk through a parallel workload with a real-world application, continue to the Batch Python tutorial.