ログ コマンド

  • [アーティクル]

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

ログ コマンドは、タスクとスクリプトがエージェントとやり取りする方法です。 新しい変数の作成、ステップの失敗としてのマーク、成果物のアップロードなどのアクションが対象です。 ログ コマンドは、パイプラインのトラブルシューティングを行う場合に役立ちます。

重要

Azure Pipelines の出力に表示されないようにシークレットのマスクに努めますが、引き続き予防策を講じる必要があります。 シークレットを出力としてエコーしないでください。 一部のオペレーティング システムでは、コマンド ライン引数がログに記録されます。 コマンド ラインでシークレットを渡さないでください。 代わりに、シークレットを環境変数にマップすることをお勧めします。

シークレットの部分文字列をマスクすることはありません。 たとえば、"abc123" がシークレットとして設定されている場合、"abc" はログからマスクされません。 これは、レベルが細かすぎてログが読み取れなくなるシークレットのマスクを回避するためです。 このため、シークレットには構造化データを含めることはできません。 たとえば、"{ "foo": "bar" }" がシークレットとして設定されている場合、"bar" はログからマスクされません。

Type コマンド
タスク コマンド AddAttachment、Complete、LogDetail、LogIssue、PrependPath、SetEndpoint、SetProgress、SetVariable、SetSecret、UploadFile、UploadSummary
成果物コマンド Associate、Upload
ビルド コマンド AddBuildTag、UpdateBuildNumber、UploadLog
リリース コマンド UpdateReleaseName

ログ コマンドの形式

ログ コマンドの一般的な形式は次のとおりです。

##vso[area.action property1=value;property2=value;...]message

構文が若干異なるいくつかの書式設定コマンドもあります。

##[command]message

ログ コマンドを呼び出すには、標準出力を使ってコマンドをエコーします。

#!/bin/bash
echo "##vso[task.setvariable variable=testvar;]testvalue"

ファイル パスは、絶対パスとして指定する必要があります。Windows ではドライブをルートにし、Linux と macOS では / で始めます。

注意

Linux または macOS を使っている場合は、ログ コマンドの前に set -x コマンドを使用できないことに注意してください。 Bash で set -x を一時的に無効にする方法については、トラブルシューティングに関する記事をご覧ください。

書式設定コマンド

注意

ログ コマンドには UTF-8 エンコードを使います。

これらのコマンドは、Azure Pipelines のログ フォーマッタへのメッセージです。 特定のログ行を、エラー、警告、折りたたみ可能セクションなどとしてマークします。

書式設定コマンドは次のとおりです。

##[group]Beginning of a group
##[warning]Warning message
##[error]Error message
##[section]Start of a section
##[debug]Debug text
##[command]Command-line being run
##[endgroup]

書式設定コマンドは、bash または PowerShell タスクで使用できます。

steps:
- bash: |
    echo "##[group]Beginning of a group"
    echo "##[warning]Warning message"
    echo "##[error]Error message"
    echo "##[section]Start of a section"
    echo "##[debug]Debug text"
    echo "##[command]Command-line being run"
    echo "##[endgroup]"

これらのコマンドは、ログで次のようにレンダリングされます。

カスタム書式設定オプションを含むログのスクリーンショット

コマンドのそのブロックは折りたたむこともでき、次のようになります。

ログの折りたたまれたセクションのスクリーンショット

タスク コマンド

LogIssue: エラーまたは警告をログする

##vso[task.logissue]error/warning message

使用方法

現在のタスクのタイムライン レコードにエラーまたは警告メッセージをログします。

プロパティ

  • type = error または warning (必須)
  • sourcepath = ソース ファイルの場所
  • linenumber = 行番号
  • columnnumber = 列番号
  • code = エラーまたは警告コード

例: エラーをログする

#!/bin/bash
echo "##vso[task.logissue type=error]Something went very wrong."
exit 1

ヒント

exit 1 は省略可能ですが、多くの場合、エラーがログされた直後にこのコマンドを発行します。 [管理オプション] > [エラー時に続行] を選んだ場合、exit 1 は失敗したビルドではなく、部分的に成功したビルドになります。 代わりに、task.logissue type=error を使うこともできます。

例: ファイル内の特定の場所に関する警告をログする

#!/bin/bash
echo "##vso[task.logissue type=warning;sourcepath=consoleapp/main.cs;linenumber=1;columnnumber=1;code=100;]Found something that could be a problem."

SetProgress: 完了率を表示する

##vso[task.setprogress]current operation

使用方法

現在のタスクの進行状況と現在の操作を設定します。

プロパティ

  • value = 完了率

例

echo "Begin a lengthy process..."
for i in {0..100..10}
do
   sleep 1
   echo "##vso[task.setprogress value=$i;]Sample Progress Indicator"
done
echo "Lengthy process is complete."

表示を確認するには、ビルドを保存してキューに入れた後、ビルドの実行を監視します。 タスクでこのスクリプトが実行されたら、進行状況インジケーターの変化を観察します。

完了: タイムラインを終了する

##vso[task.complete]current operation

使用方法

現在のタスクのタイムライン レコードを終了し、タスクの結果と現在の操作を設定します。 結果を指定しないと、結果は成功に設定されます。

プロパティ

  • result =
    • Succeeded タスクは成功しました。
    • SucceededWithIssues タスクで問題が発生しました。 ビルドは、よくても部分的成功として完了します。
    • Failed ビルドは失敗として完了します。 ([管理オプション] > [エラー時に続行] オプションが選ばれている場合は、ビルドはよくても部分的成功として完了します。)

例

タスクを成功としてログします。

##vso[task.complete result=Succeeded;]DONE

タスクを失敗として設定します。 代わりに、exit 1 を使うこともできます。

- bash: |
    if [ -z "$SOLUTION" ]; then
      echo "##vso[task.logissue type=error;]Missing template parameter \"solution\""
      echo "##vso[task.complete result=Failed;]"
    fi

LogDetail: タスクのタイムライン レコードを作成または更新する

##vso[task.logdetail]current operation

使用方法

レコードタイムラインを作成および更新します。 これは主に、ステップ、ジョブ、ステージについて報告するために Azure Pipelines によって内部的に使われます。 お客様はタイムラインにエントリを追加できますが、通常それは UI に表示されません。

ステップの間に初めて ##vso[task.detail] が検出された時点で、ステップの "詳細タイムライン" レコードが作成されます。 id と parentid に基づいて、入れ子になったタイムライン レコードを作成および更新できます。

タスク作成者は、各タイムライン レコードに使った GUID を記録しておく必要があります。 ログ システムは各タイムライン レコードで GUID を追跡するため、新しい GUID の場合は新しいタイムライン レコードが生成されます。

プロパティ

  • id = タイムライン レコードの GUID (必須)
  • parentid = 親タイムライン レコードの GUID
  • type = レコードの種類 (初めての場合は必須、上書きできません)
  • name = レコードの名前 (初めての場合は必須、上書きできません)
  • order = タイムライン レコードの順序 (初めての場合は必須、上書きできません)
  • starttime = Datetime
  • finishtime = Datetime
  • progress = 完了率
  • state = Unknown | Initialized | InProgress | Completed
  • result = Succeeded | SucceededWithIssues | Failed

例

新しいルート タイムライン レコードを作成します。

##vso[task.logdetail id=new guid;name=project1;type=build;order=1]create new timeline record

入れ子になったタイムライン レコードを新しく作成します。

##vso[task.logdetail id=new guid;parentid=exist timeline record guid;name=project1;type=build;order=1]create new nested timeline record

既存のタイムライン レコードを更新します。

##vso[task.logdetail id=existing timeline record guid;progress=15;state=InProgress;]update timeline record

SetVariable: 変数の値を初期化または変更する

##vso[task.setvariable]value

使用方法

taskcontext の変数サービスで変数を設定します。 最初のタスクでは変数を設定でき、以降のタスクではその変数を使用できます。 変数は、環境変数として後続のタスクに公開されます。

issecret が true に設定されている場合、変数の値はシークレットとして保存され、ログからマスクされます。 シークレット変数は環境変数としてタスクに渡されないので、代わりに入力として渡す必要があります。

isoutput が true に設定されていると、設定されている変数を参照する構文は、同じジョブ、将来のジョブ、または将来のステージのどこでその変数にアクセスしているかによって異なります。 さらに、isoutput が false に設定されている場合は、その変数を同じジョブ内で使用するための構文が異なります。 各ユース ケースの適切な構文を決定するには、「出力変数のレベル」をご覧ください。

詳しくは、「スクリプトで変数を設定する」と「変数を定義する」をご覧ください。

プロパティ

  • variable = 変数の名前 (必須)
  • issecret = ブール値 (オプション、既定値は false)
  • isoutput = ブール値 (オプション、既定値は false)
  • isreadonly = ブール値 (省略可能、既定値は false)

例

変数を設定します。

- bash: |
    echo "##vso[task.setvariable variable=sauce;]crushed tomatoes"
    echo "##vso[task.setvariable variable=secretSauce;issecret=true]crushed tomatoes with garlic"
    echo "##vso[task.setvariable variable=outputSauce;isoutput=true]canned goods"
  name: SetVars

変数を読み取ってください。

- bash: |
    echo "Non-secrets automatically mapped in, sauce is $SAUCE"
    echo "Secrets are not automatically mapped in, secretSauce is $SECRETSAUCE"
    echo "You can use macro replacement to get secrets, and they'll be masked in the log: $(secretSauce)"

コンソール出力:

Non-secrets automatically mapped in, sauce is crushed tomatoes
Secrets are not automatically mapped in, secretSauce is 
You can use macro replacement to get secrets, and they'll be masked in the log: ***
Future jobs can also see canned goods
Future jobs can also see canned goods

SetSecret: 値をシークレットとして登録する

##vso[task.setsecret]value

使用方法

値は、ジョブの期間中シークレットとして登録されます。 値は、この時点以降のログからマスクされます。 このコマンドは、シークレットが変換される (たとえば、base64 エンコードなどで) または派生する場合に便利です。

注: 以前に出現したシークレットはマスクされません。

例

変数を設定します。

- bash: |
    NEWSECRET=$(echo $OLDSECRET|base64)
    echo "##vso[task.setsecret]$NEWSECRET"
  name: SetSecret
  env:
    OLDSECRET: "SeCrEtVaLuE"

変数を読み取ってください。

- bash: |
    echo "Transformed and derived secrets will be masked: $(echo $OLDSECRET|base64)"
  env:
    OLDSECRET: "SeCrEtVaLuE"

コンソール出力:

Transformed and derived secrets will be masked: ***

SetEndpoint: サービス接続フィールドを変更する

##vso[task.setendpoint]value

使用方法

指定された値でサービス接続フィールドを設定します。 更新された値は、同じジョブ内で実行される後続のタスクのためにエンドポイントに保持されます。

プロパティ

  • id = サービス接続 ID (必須)
  • field = フィールドの種類、authParameter、dataParameter、または url (必須)
  • key = キー (必須、field = url がない場合)

例

##vso[task.setendpoint id=000-0000-0000;field=authParameter;key=AccessToken]testvalue
##vso[task.setendpoint id=000-0000-0000;field=dataParameter;key=userVariable]testvalue
##vso[task.setendpoint id=000-0000-0000;field=url]https://example.com/service

AddAttachment: ファイルをビルドにアタッチする

##vso[task.addattachment]value

使用方法

添付ファイルをアップロードして現在のタイムライン レコードに添付します。 これらのファイルをログでダウンロードすることはできません。 これらは、type または name の値を使って、拡張機能によってのみ参照できます。

プロパティ

  • type = 添付ファイルの種類 (必須)
  • name = 添付ファイルの名前 (必須)

例

##vso[task.addattachment type=myattachmenttype;name=myattachmentname;]c:\myattachment.txt

UploadSummary: Markdown コンテンツをビルドの概要に追加する

##vso[task.uploadsummary]local file path

使用方法

リポジトリ内の .md ファイルから現在のタイムライン レコードに概要の Markdown をアップロードして添付します。 この概要は、ビルドまたはリリースの概要に追加され、ログでダウンロードすることはできません。 概要は、UTF-8 または ASCII 形式である必要があります。 概要は、パイプライン実行の [拡張機能] タブに表示されます。 [拡張機能] タブでの Markdown レンダリングは、Azure DevOps Wiki のレンダリングとは異なります。

例

##vso[task.uploadsummary]$(System.DefaultWorkingDirectory)/testsummary.md

これは、コマンドの短縮形です

##vso[task.addattachment type=Distributedtask.Core.Summary;name=testsummaryname;]c:\testsummary.md

UploadFile: タスク ログでダウンロードできるファイルをアップロードする

##vso[task.uploadfile]local file path

使用方法

ユーザーが関心のあるファイルを、現在のタイムライン レコードへの追加ログ情報としてアップロードします。 ファイルは、タスク ログと共にダウンロードできます。

例

##vso[task.uploadfile]c:\additionalfile.log

PrependPath: パスを PATH 環境変数の先頭に追加する

##vso[task.prependpath]local file path

使用方法

PATH の前に追加することで、PATH 環境変数を更新します。 更新された環境変数は、後続のタスクに反映されます。

例

##vso[task.prependpath]c:\my\directory\path

成果物コマンド

Associate: 成果物を初期化する

##vso[artifact.associate]artifact location

使用方法

既存の成果物へのリンクを作成します。 成果物の場所は、ファイル コンテナー パス、VC パス、または UNC 共有パスである必要があります。

プロパティ

  • artifactname = 成果物の名前 (必須)
  • type = 成果物の種類 (必須) container | filepath | versioncontrol | gitref | tfvclabel

例

  • container

    ##vso[artifact.associate type=container;artifactname=MyServerDrop]#/1/build

  • filepath

    ##vso[artifact.associate type=filepath;artifactname=MyFileShareDrop]\\MyShare\MyDropLocation

  • versioncontrol

    ##vso[artifact.associate type=versioncontrol;artifactname=MyTfvcPath]$/MyTeamProj/MyFolder

  • gitref

    ##vso[artifact.associate type=gitref;artifactname=MyTag]refs/tags/MyGitTag

  • tfvclabel

    ##vso[artifact.associate type=tfvclabel;artifactname=MyTag]MyTfvcLabel

  • カスタム成果物

    ##vso[artifact.associate artifactname=myDrop;artifacttype=myartifacttype]https://downloads.visualstudio.com/foo/bar/package.zip

Upload: 成果物をアップロードする

##vso[artifact.upload]local file path

使用方法

ローカル ファイルをファイル コンテナー フォルダーにアップロードし、必要に応じて成果物を artifactname として公開します。

プロパティ

  • containerfolder = ファイルのアップロード先のフォルダー。必要な場合、フォルダーが作成されます。
  • artifactname = 成果物の名前。 (必須)

例

##vso[artifact.upload containerfolder=testresult;artifactname=uploadedresult]c:\testresult.trx

注意

Artifact.associate と Artifact.upload の違いは、前者は既存の成果物へのリンクを作成するために使用できるのに対し、後者は新しい成果物をアップロードして公開するために使用できることです。

ビルド コマンド

UploadLog: ログをアップロードする

##vso[build.uploadlog]local file path

使用方法

ユーザーが関心のあるログを、ビルドのコンテナー "logs\tool" フォルダーにアップロードします。

例

##vso[build.uploadlog]c:\msbuild.log

UpdateBuildNumber: 自動生成されたビルド番号をオーバーライドします

##vso[build.updatebuildnumber]build number

使用方法

パイプライン オプションで指定したトークンから、ビルド番号を自動的に生成できます。 一方、独自のロジックを使ってビルド番号を設定したい場合は、このログ コマンドを使用できます。

例

##vso[build.updatebuildnumber]my-new-build-number

AddBuildTag: タグをビルドに追加する

##vso[build.addbuildtag]build tag

使用方法

現在のビルドにタグを追加します。 定義済みまたはユーザー定義の変数を使って、タグを拡張できます。 たとえば、次の場合、新しいタグが値 last_scanned-$(currentDate) で Bash タスクに追加されます。 AddBuildTag でコロンを使うことはできません。

例

- task: Bash@3
    inputs:
    targetType: 'inline'
    script: |
        last_scanned="last_scanned-$(currentDate)"
        echo "##vso[build.addbuildtag]$last_scanned"
    displayName: 'Apply last scanned tag'

リリース コマンド

UpdateReleaseName: 現在のリリースの名前を変更する

##vso[release.updatereleasename]release name

使用方法

実行中のリリースのリリース名を更新します。

注意

バージョン 2020 以降の Azure DevOps と Azure DevOps Server でサポートされます。

例

##vso[release.updatereleasename]my-new-release-name