构建扫描中的自定义数据
介绍
构建扫描是轻松共享构建数据的绝佳方式，但如果您的团队想要将自己的数据添加到这些构建扫描中呢？他们可以！除了构建扫描中自动捕获的大量信息外，您还可以附加自己的自定义数据，以便更深入地了解您的构建。此自定义数据可以采用标签、链接和键值格式的任意自定义值的形式。
通过向构建扫描添加自定义数据，您可以轻松找到特定类型的构建，提供指向 GitHub 上适用源代码提交的快速链接，添加有用的 CI 构建信息等等。然后，当您与队友共享单个构建扫描链接时，他们可以快速轻松地访问有关您构建的大量信息，从而更轻松地诊断构建环境问题、修复测试失败等等。
如果您不熟悉构建扫描，您可以在我们关于该主题的介绍性博文中了解它们。您还可以在《构建扫描用户手册》中找到更多详细信息，浏览一些示例构建扫描或使用此示例构建扫描项目进行实验。
现在，让我们来看一些将自定义数据添加到构建扫描中的示例（有关更多示例，请参阅用户手册）。
标签 #
让我们从最简单的自定义数据类型开始：标签。标签是一种向构建扫描添加简单元数据的方式。您可以使用标签为构建添加上下文，例如构建是在本地还是在 CI 服务器上运行，构建是否有任何本地更改，失败构建的错误类型等等。这是一个示例构建扫描，它将构建标记为具有
- 在 CI 上运行
- 来自 master 分支
- 包含本地代码更改（“脏”）
例如，要附加一个标签以显示构建是在本地还是在 CI 服务器上运行，您可以将以下内容添加到其构建脚本中
if (System.getenv("CI")) {
buildScan.tag "CI"
} else {
buildScan.tag "LOCAL"
}
然后，在查看构建扫描时，标签会显示在项目名称下方
链接 #
除了标签之外，您还可以包含构建扫描的读者可能会觉得有用的链接。例如，您可以包含指向 GitHub 上项目源代码的便捷链接，或指向 Gradle 构建的 CI 结果的链接。此示例构建扫描演示了此类链接的外观。
假设您的 CI 工具将构建结果 URL 作为环境变量提供。您可以获取该值，并使用以下代码将其作为自定义链接添加到您的构建脚本中
if (System.getenv("CI")) {
buildScan.link "CI build", System.getenv("BUILD_URL")
}
您还可以灵活地添加指向项目源代码的当前修订版或提交的链接。以下示例将构建扫描链接到其在 GitHub 上的对应提交（只要 Git 命令行工具可用）
String commitId = 'git rev-parse --verify HEAD'.execute().text.trim()
buildScan.link "Source", "https://github.com/gradle/gradle-build-scan-quickstart/tree/" + commitId
链接在查看构建扫描时显示在顶部区域
自定义值 #
自定义值可用于使任何信息成为构建扫描的一部分。在此示例构建扫描中，您可以看到相应的 CI 构建日期、CI 构建编号和 Git 分支名称作为自定义值。在查看构建扫描或在 Gradle Enterprise 中搜索构建扫描时，可以使用这些值。让我们来看几个示例，说明如何将自定义值添加到您的构建扫描中。
在我们的第一个示例中，我们假设您的 CI 工具通过环境变量将构建信息注入到构建中。然后，您可以使用以下代码在您的构建脚本中将构建编号和日期附加到构建扫描中
if (System.getenv("CI")) {
buildScan.value "CI build number", System.getenv("BUILD_NUMBER")
buildScan.value "CI build date", System.getenv("BUILD_DATE")
}
由于我们是从 Gradle 构建脚本内部设置这些自定义值，因此您有权执行诸如运行外部命令以捕获有关项目状态的更多信息之类的操作。例如，您可以通过运行 Git 命令并将结果设置为自定义值来添加构建的当前 Git 分支
String branchName = 'git rev-parse --abbrev-ref HEAD'.execute().text.trim()
buildScan.value "Git branch", branchName
自定义值在查看构建扫描时显示在主页上
命令行 #
为了让您在如何将自定义数据传递到构建扫描方面具有更大的灵活性，您还可以在命令行上指定标签、链接和自定义值。例如，您可以快速将临时信息附加到构建扫描，以便
- 帮助调试特定的本地构建失败
- 标记实验性构建
- 添加 CI 特定的自定义数据，而无需修改您的构建脚本
您可以通过使用适当的名称指定系统属性来完成此操作，如以下示例所示
$ gradle build -Dscan.tag.EXPERIMENTAL
$ gradle build -Dscan.link.buildUrl=$CI_BUILD_URL
$ gradle build -Dscan.value.buildNumber=$CI_BUILD_NUMBER
第一个添加一个名为“EXPERIMENTAL”的标签，第二个添加一个标题为“buildUrl”的链接，第三个添加一个名为“buildNumber”的自定义值。
基于自定义数据搜索 #
当在本地使用 Gradle Enterprise 构建扫描时，您可以根据自定义数据（例如标签和自定义值）搜索构建扫描。例如，您可以使用此屏幕截图所示的术语搜索所有在 CI 上针对 master 分支运行的构建
在线演示 #
有关添加自定义数据的现场演示以及更多示例，请查看 Luke Daley 和 Etienne Studer 最近在 Bay Area Gradle Users 聚会上的演讲。视频首先概述了构建扫描，并在 22:30 左右深入探讨了添加自定义数据的细节。
向构建扫描添加自定义数据使您能够灵活地使用标签、链接或其他针对您团队特定需求的数据来增强构建扫描。然后，您将拥有更多信息，可以轻松地在构建扫描中与您的队友共享，从而减少诊断构建失败时的猜测。扫描愉快！