次の方法で共有

ログ コマンド

Azure DevOps サービス |Azure DevOps Server |Azure DevOps Server 2022

ログ コマンドは、tasks およびスクリプトがAzure Pipelines エージェントと通信する方法です。 パイプライン ステップが特別に書式設定された文字列を標準出力 (stdout) に書き込むと、エージェントはそれをインターセプトし、要求されたアクション (変数の設定、成果物のアップロード、ステップの失敗のマークなど) を実行します。 ログ コマンドは、パイプラインの動作のカスタマイズとトラブルシューティングに役立ちます。

重要

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

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

ログ コマンドのしくみ

Azure Pipelines エージェントは、各タスクとスクリプト ステップの標準出力 (stdout) をステップの実行時にリアルタイムでスキャンすることで、ログ コマンドを処理します。 エージェントは、stdout の または パターンに一致する行を検出すると、コマンドを解釈し、要求されたアクション (変数の設定や成果物のアップロードなど) を実行します。

重要

ログ 記録コマンドは、エージェントで直接実行されているタスクとスクリプトによって stdout に書き込まれる場合 にのみ 処理されます。 これらは、次の場所から解析 されません 。

  • または
  • 結果ファイルまたは添付ファイルをテストする
  • stdout ではなくファイルに書き込む外部ツールまたはテスト フレームワーク (CloudTest など) からの出力
  • エージェントによってキャプチャされないコンテナー ログまたはサイドカー プロセスの出力

外部ツールからコマンドをログに記録して処理する必要がある場合は、スクリプトの stdout を使用してそのツールの出力をパイプまたはリダイレクトします。 例えば次が挙げられます。

./my-external-tool 2>&1 | while IFS= read -r line; do echo "$line"; done
タイプ コマンド
タスク コマンド 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

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

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

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

注意

Linux または macOS を使用している場合は、ログ コマンドの前に コマンドを使用できないことに注意してください。 Bash で を一時的に無効にする方法については、に関する記事をご覧ください。

書式設定コマンド

注意

ログ コマンドには 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 タスクで使用できます。

  • 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

使用方法

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

プロパティ

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

例: エラーをログする

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

ヒント

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

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

  • Bash
  • PowerShell 
#!/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

使用方法

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

プロパティ

  • = 完了率

例

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

例

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

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

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

- 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 に表示されません。

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

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

プロパティ

  • = タイムライン レコードの GUID (必須)
  • = 親タイムライン レコードの GUID
  • = レコードの種類 (初めての場合は必須、上書きできません)
  • = レコードの名前 (初めての場合は必須、上書きできません)
  • = タイムライン レコードの順序 (初めての場合は必須、上書きできません)
  • starttime = Datetime
  • finishtime = Datetime
  • = 完了率
  • 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 の変数サービスで変数を設定します。 最初のタスクでは変数を設定でき、以降のタスクではその変数を使用できます。 変数は、環境変数として後続のタスクに公開されます。

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

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

出力変数の詳細については、スクリプト で変数を設定、変数 定義を参照してください。

プロパティ

  • = 変数の名前 (必須)
  • = ブール値 (オプション、既定値は false)
  • = ブール値 (オプション、既定値は false)
  • = ブール値 (オプション、既定値は false)

例

  • Bash
  • PowerShell

変数を設定します。

- 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
  • PowerShell

変数を設定します。

- 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 (必須)
  • = フィールドの種類、、、または (必須)
  • = キー (必須、 がない場合)

例

##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 の値を使って、拡張機能によってのみ参照できます。

プロパティ

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

例

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

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

##vso[task.uploadsummary]local file path

使用方法

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

例

##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 共有パスである必要があります。

プロパティ

  • = 成果物の名前 (必須)
  • = 成果物の種類 (必須)

例

  • 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

使用方法

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

プロパティ

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

例

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

注意

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

ビルド コマンド

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

##vso[build.uploadlog]local file path

使用方法

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

例

##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

使用方法

現在のビルドにタグを追加します。 定義済みまたはユーザー定義の変数を使って、タグを拡張できます。 たとえば、次の場合、新しいタグが値 で 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

ログ コマンドのトラブルシューティング

ログ 記録コマンドが処理されない

ログ 記録コマンドは、エージェントによるステップ実行中に stdout に書き込む必要があります。 コマンドが生ログに表示され、処理されていない場合:

  • ファイルへの外部ツールの書き込み: ツールが stdout ではなく 文字列をログ ファイルに書き込む場合、エージェントはそれらを解析しません。 ツールの出力をスクリプトの stdout にリダイレクトします。
  • バッファー出力: 一部のプログラムは、ターミナルに接続されていないときに stdout をバッファーします。 言語固有のオプションを使用して出力をフラッシュします ( や の設定など)。
  • Linux/macOS での干渉の: オプションによってログ コマンドが破損する可能性があります。 回避策については 、トラブルシューティング を参照してください。
  • エンコード: ログ 記録コマンドでは UTF-8 エンコードを使用する必要があります。 その他のエンコードにより、エージェントがコマンドをスキップする可能性があります。
  • コマンド内の改行: 各ログ コマンドは 1 行に配置する必要があります。 文字列内に改行文字が表示された場合、エージェントはコマンドを認識しません。

値に含まれる特殊文字

コマンド値のログ記録で使用する場合は、一部の文字をエスケープする必要があります。 これらのエスケープ シーケンスは、 エージェントのソース コードで定義されています。

Character エスケープ シーケンス
セミコロン %3B
改行 %0A
復帰 %0D
角かっこを閉じる %5D

パーセント記号の値をエスケープするには、ではなくを使用します。 この動作は、 変数によって制御されます。 詳細については、「 パーセント エンコード」を参照してください。

  • Last updated on