Perintah untuk pengelogan
Layanan Azure DevOps | Azure DevOps Server 2022 - Azure DevOps Server 2019
Perintah pengelogan adalah cara tugas dan skrip berkomunikasi dengan agen. Mereka mencakup tindakan seperti membuat variabel baru, menandai langkah sebagai gagal, dan mengunggah artefak. Perintah pengelogan berguna saat Anda memecahkan masalah alur.
Penting
Kami berupaya menutupi rahasia agar tidak muncul di output Azure Pipelines, tetapi Anda masih perlu mengambil tindakan pencegahan. Jangan pernah menggaungkan rahasia sebagai output. Beberapa argumen baris perintah log sistem operasi. Jangan pernah meneruskan rahasia pada baris perintah. Sebagai gantinya, kami sarankan Anda memetakan rahasia Anda ke dalam variabel lingkungan.
Kami tidak pernah menutupi substring rahasia. Jika, misalnya, "abc123" diatur sebagai rahasia, "abc" tidak ditutupi dari log. Ini untuk menghindari menutupi rahasia terlalu terperinci dari tingkat, membuat log tidak dapat dibaca. Untuk alasan ini, rahasia tidak boleh berisi data terstruktur. Jika, misalnya, "{ "foo": "bar" }" diatur sebagai rahasia, "bar" tidak ditutupi dari log.
Jenis | Perintah |
---|---|
Perintah tugas | AddAttachment, Complete, LogDetail, LogIssue, PrependPath, SetEndpoint, SetProgress, SetVariable, SetSecret, UploadFile, UploadSummary |
Perintah artefak | Kaitkan, Unggah |
Perintah build | AddBuildTag, UpdateBuildNumber, UploadLog |
Perintah rilis | UpdateReleaseName |
Format perintah pengelogan
Format umum untuk perintah pengelogan adalah:
##vso[area.action property1=value;property2=value;...]message
Ada juga beberapa perintah pemformatan dengan sintaks yang sedikit berbeda:
##[command]message
Untuk memanggil perintah pengelogan, gemakan perintah melalui output standar.
#!/bin/bash
echo "##vso[task.setvariable variable=testvar;]testvalue"
Jalur file harus diberikan sebagai jalur absolut: di-root ke drive di Windows, atau dimulai dengan /
di Linux dan macOS.
Catatan
Harap dicatat bahwa Anda tidak dapat menggunakan set -x
perintah sebelum perintah pengelogan saat Anda menggunakan Linux atau macOS. Lihat pemecahan masalah, untuk mempelajari cara menonaktifkan set -x
sementara untuk Bash.
Perintah pemformatan
Catatan
Gunakan pengodean UTF-8 untuk perintah pengelogan.
Perintah ini adalah pesan ke pemformat log di Azure Pipelines. Mereka menandai baris log tertentu sebagai kesalahan, peringatan, bagian yang dapat diciutkan, dan sebagainya.
Perintah pemformatan adalah:
##[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]
Anda bisa menggunakan perintah pemformatan dalam tugas bash atau 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]"
Perintah tersebut akan dirender dalam log seperti ini:
Blok perintah tersebut juga dapat diciutkan, dan terlihat seperti ini:
Perintah tugas
LogIssue: Mencatat kesalahan atau peringatan
##vso[task.logissue]error/warning message
Penggunaan
Catat kesalahan atau pesan peringatan dalam catatan garis waktu tugas saat ini.
Properti
type
=error
atauwarning
(Diperlukan)sourcepath
= lokasi file sumberlinenumber
= nomor bariscolumnnumber
= nomor kolomcode
= kode kesalahan atau peringatan
Contoh: Mencatat kesalahan
#!/bin/bash
echo "##vso[task.logissue type=error]Something went very wrong."
exit 1
Tip
exit 1
bersifat opsional, tetapi sering kali merupakan perintah yang akan Anda terbitkan segera setelah kesalahan dicatat. Jika Anda memilih Opsi Kontrol: Lanjutkan pada kesalahan, maka exit 1
akan menghasilkan build yang berhasil sebagian alih-alih build yang gagal. Sebagai alternatif, Anda juga dapat menggunakan task.logissue type=error
.
Contoh: Mencatat peringatan tentang tempat tertentu dalam file
#!/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: Tampilkan persentase selesai
##vso[task.setprogress]current operation
Penggunaan
Atur kemajuan dan operasi saat ini untuk tugas saat ini.
Properti
value
= persentase penyelesaian
Contoh
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."
Untuk melihat tampilannya, simpan dan antre build, lalu tonton build run. Amati bahwa indikator kemajuan berubah ketika tugas menjalankan skrip ini.
Selesai: Selesaikan garis waktu
##vso[task.complete]current operation
Penggunaan
Selesaikan catatan garis waktu untuk tugas saat ini, atur hasil tugas dan operasi saat ini. Jika hasil tidak disediakan, atur hasil ke berhasil.
Properti
result
=Succeeded
Tugas berhasil.SucceededWithIssues
Tugas mengalami masalah. Build akan diselesaikan karena sebagian berhasil di terbaik.Failed
Build akan selesai sebagai gagal. (Jika Opsi Kontrol: Lanjutkan pada opsi kesalahan dipilih, build akan diselesaikan sebagai berhasil sebagian di terbaik.)
Contoh
Catat tugas sebagai berhasil.
##vso[task.complete result=Succeeded;]DONE
Atur tugas sebagai gagal. Sebagai alternatif, Anda juga dapat menggunakan 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: Membuat atau memperbarui catatan garis waktu untuk tugas
##vso[task.logdetail]current operation
Penggunaan
Membuat dan memperbarui rekaman garis waktu. Ini terutama digunakan secara internal oleh Azure Pipelines untuk melaporkan langkah- langkah, pekerjaan, dan tahapan. Meskipun pelanggan dapat menambahkan entri ke garis waktu, mereka biasanya tidak akan ditampilkan di UI.
Pertama kali kita melihat ##vso[task.detail]
selama langkah, kita membuat catatan "garis waktu detail" untuk langkah tersebut. Kita dapat membuat dan memperbarui catatan garis waktu berlapis berdasarkan id
dan parentid
.
Penulis tugas harus mengingat GUID mana yang mereka gunakan untuk setiap rekaman garis waktu. Sistem pengelogan akan melacak GUID untuk setiap rekaman garis waktu, sehingga GUID baru akan menghasilkan catatan garis waktu baru.
Properti
id
= GUID rekaman garis waktu (Diperlukan)parentid
= GUID rekaman garis waktu induktype
= Jenis rekaman (Diperlukan untuk pertama kalinya, tidak dapat menimpa)name
= Nama rekaman (Diperlukan untuk pertama kalinya, tidak dapat menimpa)order
= urutan rekaman garis waktu (Diperlukan untuk pertama kalinya, tidak dapat menimpa)starttime
=Datetime
finishtime
=Datetime
progress
= persentase penyelesaianstate
=Unknown
|Initialized
|InProgress
|Completed
result
=Succeeded
|SucceededWithIssues
|Failed
Contoh
Buat catatan garis waktu akar baru:
##vso[task.logdetail id=new guid;name=project1;type=build;order=1]create new timeline record
Buat catatan garis waktu berlapis baru:
##vso[task.logdetail id=new guid;parentid=exist timeline record guid;name=project1;type=build;order=1]create new nested timeline record
Perbarui catatan garis waktu yang ada:
##vso[task.logdetail id=existing timeline record guid;progress=15;state=InProgress;]update timeline record
SetVariable: Menginisialisasi atau memodifikasi nilai variabel
##vso[task.setvariable]value
Penggunaan
Mengatur variabel dalam layanan variabel taskcontext. Tugas pertama dapat mengatur variabel, dan tugas berikut dapat menggunakan variabel . Variabel diekspos ke tugas berikut sebagai variabel lingkungan.
Ketika issecret
diatur ke true
, nilai variabel akan disimpan sebagai rahasia dan ditutupi dari log. Variabel rahasia tidak diteruskan ke tugas sebagai variabel lingkungan dan sebaliknya harus diteruskan sebagai input.
Ketika isoutput
diatur ke true
sintaks untuk mereferensikan variabel yang ditetapkan bervariasi berdasarkan apakah Anda mengakses variabel tersebut dalam pekerjaan yang sama, pekerjaan di masa mendatang, atau tahap mendatang. Selain itu, jika isoutput
diatur ke false
sintaks untuk menggunakan variabel tersebut dalam pekerjaan yang sama berbeda. Lihat tingkat variabel output untuk menentukan sintaks yang sesuai untuk setiap kasus penggunaan.
Lihat mengatur variabel dalam skrip dan menentukan variabel untuk detail selengkapnya.
Properti
variable
= nama variabel (Diperlukan)issecret
= boolean (Opsional, default ke false)isoutput
= boolean (Opsional, default ke false)isreadonly
= boolean (Opsional, default ke false)
Contoh
Atur variabel:
- 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
Baca variabel:
- 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)"
Output konsol:
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: Mendaftarkan nilai sebagai rahasia
##vso[task.setsecret]value
Penggunaan
Nilai terdaftar sebagai rahasia selama durasi pekerjaan. Nilai akan ditutupi dari log dari titik ini ke depan. Perintah ini berguna ketika rahasia diubah (misalnya base64 dikodekan) atau diturunkan.
Catatan: Kemunculan sebelumnya dari nilai rahasia tidak akan ditutupi.
Contoh
Atur variabel:
- bash: |
NEWSECRET=$(echo $OLDSECRET|base64)
echo "##vso[task.setsecret]$NEWSECRET"
name: SetSecret
env:
OLDSECRET: "SeCrEtVaLuE"
Baca variabel:
- bash: |
echo "Transformed and derived secrets will be masked: $(echo $OLDSECRET|base64)"
env:
OLDSECRET: "SeCrEtVaLuE"
Output konsol:
Transformed and derived secrets will be masked: ***
SetEndpoint: Mengubah bidang koneksi layanan
##vso[task.setendpoint]value
Penggunaan
Atur bidang koneksi layanan dengan nilai tertentu. Nilai yang diperbarui akan dipertahankan di titik akhir untuk tugas berikutnya yang dijalankan dalam pekerjaan yang sama.
Properti
id
= ID koneksi layanan (Diperlukan)field
= jenis bidang, salah satu dariauthParameter
,dataParameter
, atauurl
(Diperlukan)key
= kunci (Diperlukan, kecualifield
=url
)
Contoh
##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: Melampirkan file ke build
##vso[task.addattachment]value
Penggunaan
Unggah dan lampirkan lampiran ke rekaman garis waktu saat ini. File-file ini tidak tersedia untuk diunduh dengan log. Ini hanya dapat dirujuk oleh ekstensi menggunakan nilai jenis atau nama.
Properti
type
= jenis lampiran (Diperlukan)name
= nama lampiran (Diperlukan)
Contoh
##vso[task.addattachment type=myattachmenttype;name=myattachmentname;]c:\myattachment.txt
UploadSummary: Menambahkan beberapa konten Markdown ke ringkasan build
##vso[task.uploadsummary]local file path
Penggunaan
Unggah dan lampirkan ringkasan Markdown dari file .md di repositori ke rekaman garis waktu saat ini. Ringkasan ini akan ditambahkan ke ringkasan build/rilis dan tidak tersedia untuk diunduh dengan log. Ringkasan harus dalam format UTF-8 atau ASCII. Ringkasan akan muncul pada tab Ekstensi dari eksekusi alur Anda. Penyajian markdown pada tab Ekstensi berbeda dari penyajian wiki Azure DevOps.
Contoh
##vso[task.uploadsummary]$(System.DefaultWorkingDirectory)/testsummary.md
Ini adalah bentuk tangan pendek untuk perintah
##vso[task.addattachment type=Distributedtask.Core.Summary;name=testsummaryname;]c:\testsummary.md
UploadFile: Mengunggah file yang dapat diunduh dengan log tugas
##vso[task.uploadfile]local file path
Penggunaan
Unggah file yang menarik pengguna sebagai informasi log tambahan ke catatan garis waktu saat ini. File akan tersedia untuk diunduh bersama dengan log tugas.
Contoh
##vso[task.uploadfile]c:\additionalfile.log
PrependPath: Menambahkan jalur ke variabel lingkungan PATH
##vso[task.prependpath]local file path
Penggunaan
Perbarui variabel lingkungan PATH dengan menambahkan sebelumnya ke PATH. Variabel lingkungan yang diperbarui akan tercermin dalam tugas berikutnya.
Contoh
##vso[task.prependpath]c:\my\directory\path
Perintah artefak
Kaitkan: Menginisialisasi artefak
##vso[artifact.associate]artifact location
Penggunaan
Buat tautan ke Artefak yang ada. Lokasi artefak harus berupa jalur kontainer file, jalur VC, atau jalur berbagi UNC.
Properti
artifactname
= nama artefak (Diperlukan)type
= jenis artefak (Diperlukan)container
|filepath
|versioncontrol
|gitref
|tfvclabel
Contoh
container
##vso[artifact.associate type=container;artifactname=MyServerDrop]#/1/build
jalur file
##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
Artefak Kustom
##vso[artifact.associate artifactname=myDrop;artifacttype=myartifacttype]https://downloads.visualstudio.com/foo/bar/package.zip
Unggah: Mengunggah artefak
##vso[artifact.upload]local file path
Penggunaan
Unggah file lokal ke folder kontainer file, dan secara opsional menerbitkan artefak sebagai artifactname
.
Properti
containerfolder
= folder tempat file akan diunggah, folder akan dibuat jika diperlukan.artifactname
= nama artefak. (Diperlukan)
Contoh
##vso[artifact.upload containerfolder=testresult;artifactname=uploadedresult]c:\testresult.trx
Catatan
Perbedaan antara Artifact.associate dan Artifact.upload adalah bahwa yang pertama dapat digunakan untuk membuat tautan ke artefak yang ada, sementara yang terakhir dapat digunakan untuk mengunggah/menerbitkan Artefak baru.
Perintah build
UploadLog: Mengunggah log
##vso[build.uploadlog]local file path
Penggunaan
Unggah log yang tertarik pengguna untuk membangun folder "logs\tool
" kontainer.
Contoh
##vso[build.uploadlog]c:\msbuild.log
UpdateBuildNumber: Mengambil alih nomor build yang dihasilkan secara otomatis
##vso[build.updatebuildnumber]build number
Penggunaan
Anda dapat secara otomatis membuat nomor build dari token yang Anda tentukan dalam opsi alur. Namun, jika Anda ingin menggunakan logika Anda sendiri untuk mengatur nomor build, maka Anda dapat menggunakan perintah pengelogan ini.
Contoh
##vso[build.updatebuildnumber]my-new-build-number
AddBuildTag: Menambahkan tag ke build
##vso[build.addbuildtag]build tag
Penggunaan
Tambahkan tag untuk build saat ini. Anda dapat memperluas tag dengan variabel yang telah ditentukan atau ditentukan pengguna. Misalnya, di sini tag baru ditambahkan dalam tugas Bash dengan nilai last_scanned-$(currentDate)
. Anda tidak dapat menggunakan titik dua dengan AddBuildTag.
Contoh
- task: Bash@3
inputs:
targetType: 'inline'
script: |
last_scanned="last_scanned-$(currentDate)"
echo "##vso[build.addbuildtag]$last_scanned"
displayName: 'Apply last scanned tag'
Perintah rilis
UpdateReleaseName: Ganti nama rilis saat ini
##vso[release.updatereleasename]release name
Penggunaan
Perbarui nama rilis untuk rilis yang sedang berjalan.
Catatan
Didukung di Azure DevOps dan Azure DevOps Server mulai versi 2020.
Contoh
##vso[release.updatereleasename]my-new-release-name