使用Artifactory 6。x ? 全部折叠 全部展开 全部折叠
有问题吗?想要报告问题?联系JFrog技术支持
人工查询语言(AQL)是专门设计用来让您发现与Artifactory中存储的工件和构建相关的任何数据的。它的语法提供了一种简单的方法来制定复杂的查询,这些查询可以指定任意数量的搜索条件、过滤器、排序选项和输出参数。AQL作为RESTful API公开,它使用数据流提供输出数据,从而实现极快的响应时间和低内存消耗。目前,AQL只能提取驻留在Artifactory实例中的数据,因此它只能运行局部存储库,远程存储库缓存和虚拟存储库。
下面是一些简单的例子:
//返回"artifactory"构建的所有工件。items.find({"@build.name":{"$eq":"artifactory"}}) //返回所有依赖于非Apache许可证的构建。builds.find({"module.dependency.item.@license":{"$nmatch":"Apache-*"}}) //返回包含一个名为"org/artifactory/Main.class"的文件的所有存档。items.find({“archive.entry.name”:{" $ eq”:“Main.class”},“archive.entry.path”:{" $ eq”:“org/artifactory}})
下面是一个稍微复杂一点的例子。
//返回所有名为"Artifactory.jar"的归档文件的所有条目,来自任何名为"Artifactory"的构建,//构建号为521。archive.entries。找到( { "archive.item.name":{"$eq":"Artifactory.jar"}, "archive.item.artifact.module.build.name":{"$eq":"Artifactory"}, "archive.item.artifact.module.build.number":{"$eq":"521"} })
页面内容
下面是另一个示例,它展示了AQL以其他工具无法比拟的方式从存储库中挖掘信息的全部功能。
//比较2个"maven+example"构建项目中的工件内容。找到( { "name":{"$match":"multi2*.jar"}, "$or":[ { "$and":[ {"artifact.module.build.name":{"$eq":"maven+example"}}, {"artifact.module.build.number":{"$eq":"317"}} ] }, { "$and":[ {"artifact.module.build.name":{"$eq":"maven+example"}}, {"artifact.module.build.number":{"$eq":"318"}} ] } ] }).include("archive.entry")
{"results": [{"repo": "ext-snapshot-local","path": "org/jfrog/test/multi2/3.0.0-SNAPSHOT","name": "multi2-3.0.0-20151012.205507-1.jar","type": "file",size: 1015;"created": "2015-10-12T22:55:23.022+02:00",created_by: admin,"modified": "2015-10-12T22:55:23.013+02:00",modified_by: admin,"updated": "2015-10-12T22:55:23.013+02:00","archives": [{"entries": [{”entry.name:“App.class”,”条目。路径”: "artifactory/test"}, {”entry.name:“舱单。”曼氏金融”,”条目。路径”: "META-INF"})})},{"repo": "ext-snapshot-local","path": "org/jfrog/test/multi2/3.0.0-SNAPSHOT","name": "multi2-3.0.0-20151013.074226-2.jar","type": "file",size: 1015;"created": "2015-10-13T09:42:39.389+02:00",created_by: admin,"modified": "2015-10-13T09:42:39.383+02:00",modified_by: admin,"updated": "2015-10-13T09:42:39.383+02:00","archives": [{"entries": [{”entry.name:“App.class”,”条目。路径”: "artifactory/test"}, {”entry.name:“舱单。”曼氏金融”,”条目。路径”: "META-INF"})})}),"range": {"start_pos": 0,"end_pos": 2,total: 2}}
AQL被构造为一组相互连接的域,如下图所示。您一次只能在一个域上运行查询,这被称为主要的查询的域。
目前支持以下主域:项,构建,条目,和推广。也就是说,你的查询可以是:items.find(…),builds.find(…),Archive.entries.find(…)或build.promotions.find(…)。
您可以使用来自其他域的字段作为搜索条件的一部分,或者指定要在输出中显示的字段,但是在这种情况下,您需要遵循中描述的约定使用字段。
AQL在Artifactory V3.5.0中引入,并支持项作为主域,并附带财产,以及……统计作为二级域。Artifactory的后期版本引入了可以包含在查询中的其他域。下表总结了每个域可以从哪个版本访问。
< domain_query >;(<标准>)其中包括(<字段>).sort (< order_and_fields >) .offset (< offset_records >) .limit (< num_records >)
地点:
限制
排序,限制和抵消元素只在以下情况下起作用:
例如,在下面的查询中,排序,限制和抵消将不起作用,因为主域名是项,但是……包括元素属性中的字段工件,模块和构建应该显示域:
items.find()其中包括(“工件”、“artifact.module”,“artifact.module.build”)
主域中的任何字段都可以直接在查询中的任何地方使用。如果使用来自其他域的字段,则必须使用来自主域的完整关系路径来指定它们。
例如,要查找名为“myrepo”的存储库中的所有项目,您可以使用:
items.find ({”回购”: "myrepo"})
但是要查找由名为"mymodule"的模块创建的所有项,你可以使用:
Items.find ({"artifact.module.name": "mymodule"})
因为您也可以从构建域,以查找生成名为“artifactory”的项的所有构建。War ",你也可以用:
builds.find({“module.artifact.item.name”:“artifactory.war”})
要执行AQL查询,请使用人工查询语言REST API。
你可以发出找到根据语法上面,并配置您的请求以显示来自任何域的字段。
项目类型(文件/文件夹/任意)。
如果类型查询中未指定,则搜索的默认类型为文件
类型
文件
项目的sha256哈希码
从Artifactory版本5.5开始支持SHA-256
您只能对已经部署到Artifactory 5.5或更高版本的工件进行AQL搜索,或者如果您已经部署到Artifactory 5.5或更高版本的工件迁移数据库如sha - 256支持在Artifactory升级到5.5及以上版本之后。
归档域当前不包含任何字段
的标准元素必须是由指定应该返回的项的标准组成的有效JSON格式语句。它本质上是一个复合布尔语句,并且只有该语句求值为的元素真正的由查询返回。
每个标准本质上都是应用于字段或属性的比较语句。请参阅完整的列表比较运算符。虽然每个标准都可以用完整的通用格式表示,但AQL为可读性定义了缩短的格式如下所述。
在字段中指定标准的一般方法如下:
{" <字段> ":{" <比较运算符>”:“< >价值"}}
如果应用于不同域的查询,则字段名必须预先附加到主域的关系路径。
例如:
//查找“name”字段匹配表达式“*test”的项。*”项目。找到({"name": {"$match" : "*test.*"}}) //Find items that have been downloaded over 5 times. //We need to include the "stat" specifier in "stat.downloads" since downloads is a field of the stat domain and not of the item domain. items.find({"stat.downloads":{"$gt":"5"}}) //Find items that have never been downloaded. Note that when specifying zero downloads we use "null" instead of 0. //We need to include the "stat" specifier in "stat.downloads" since downloads is a field of the stat domain and not of the item domain. items.find({"stat.downloads":{"$eq":null}}) //Find builds that use a dependency that is a snapshot builds.find({"module.dependency.item.name":{"$match":"*SNAPSHOT*"}})
stat域中值为“0”的字段
注意,当搜索stat域中具有“零”值的项时,您应该搜索null,而不是0。例如,如上所示,当搜索下载量为零的项目时,指定“null”而不是0。
字段标准的简短符号
AQL支持对字段的搜索条件使用简短表示法。
字段上的"equals" ("$eq")条件可以指定如下:
{"": ""}
items.find ({" name ": {" $ eq”:“ant-1.9.4.jar}})
items.find({“名称”:“ant-1.9.4.jar”})
Artifactory允许您在三个域中附加和搜索属性:项目,模块和构建。
在属性上指定标准的一般方法如下:
{" @ < property_key > ":{“操作符”:“< property_value > "}}
访问正确的属性
如果要从查询的主域指定属性,只需输入如上所述的属性键和值。如果指定来自其他域中的属性,则需要指定属性的完整关系路径。
在下面的示例中,主域是构建域,但是我们希望找到基于属性的构建项域,所以我们必须指定属性的完整路径:
builds.find module.artifact.item({”。@qa_approved": {"$ne": "true"}})
下面是一些例子:
//查找已被QA批准的项目。找到({"@qa_approved" : {"$eq" : "true"}}) //Find builds that were run on a linux machine" builds.find({"@os" : {"$match" : "linux*"}}) //Find items that were created in a build that was run on a linux machine. items.find({"artifact.module.build.@os" : {"$match" : "linux*"}})
属性标准的简短符号
AQL支持属性搜索条件的简短符号。
属性上的"equals" ("$eq")条件可以如下指定:
{"@": ""}
查找属性名为“license”且值等于“GPL”的项。
items.find @artifactory({”。licenses": {"$eq": "GPL"}})
items.find @artifactory({”。许可证":"GPL"})
字段和属性上的搜索条件可以嵌套并组合成逻辑表达式,使用美元和“或者”美元或“运营商。如果未指定操作符,则默认为美元和
<标准> ={<美元”和“|”美元或“>:[{<标准>},{<标准>}]
标准可以任意程度地嵌套
请注意,由于搜索条件可以嵌套到任何程度,因此您可以构建具有任何复杂度的逻辑搜索条件。
//这个例子显示了一个隐式的"$and"操作符(因为这是默认的,所以您不必明确指定它,而是用逗号分隔条件)和一个显式的"$or"操作符。//查找jcenter或my-local存储库中的所有文件项。items.find ({"type": "file",”美元或”:[{"repo" : "jcenter", "repo" : "my-local" }]}) //Find all the items that were created in a build called "my_debian_build" and whose name ends with ".deb" or all items created in a build called "my_yum_build" and whose name ends with ".rpm". items.find( { "$or": [ { "$and": [ {"artifact.module.build.name" : "my_debian_build"} , {"name" : {"$match" : "*.deb"}} ] }, { "$and": [ {"artifact.module.build.name" : "my_yum_build"} , {"name" : {"$match" : "*.rpm"}} ] } ] } ) //Find all items in a repository called "my_local" that have a property with a key called "license" and value that is any variant of "LGPL". items.find({"repo" : "my_local"},{"@artifactory.licenses" : {"$match" : "*LGPL*"}})
在属性上指定多个条件的搜索有时可能会产生意想不到的结果。
这是因为项目经常用几个属性进行注释,只要任何属性的任何条件为真,项目就会以常规方式返回找到。
但有时,我们需要找到其中单个特定属性满足多个标准的项。为此,我们使用$msp(匹配单个属性)操作符。
规则和规则之间的根本区别找到使用msp美元操作符:
这里有一个例子。
考虑两个项目A和B。
A有一个带有value的许可属性AGPL-V3
B有两个许可证属性。一个是lgpl - 2.1,另一个lgpl - 2.2
现在让我们假设我们想要找到使用任何GPL许可证的项目,只要它不是LGPL-2.1。
在我们的例子中,我们期望两者都得到一个项目和B返回自一个有AGPL-V3和B有lgpl - 2.2。
首先,我们可以这样写查询:
items.find ({”@license":{"$match": "*GPL*"}, "@license":{"$nmatch": "LGPL-2.1*"} })
但是这个查询只返回项目一个。
返回项目A是因为它明确地满足了两个条件:“@license”:{“$match”:“*GPL*”}和“@license”:{“$nmatch”:“LGPL-2.1*”}
B项没有返回,因为它的属性license=LGPL-2.1不满足“@license”:{“$”的条件nmatch”:“lgpl - 2.1 *”}。
如果我们使用msp美元操作如下:
”项。找到({ "$msp": [ "@license":{"$match": "*GPL*"}, "@license":{"$nmatch": "LGPL-2.1*"} ]}).
那么两个项目一个和B项返回。
返回项目A是因为它具有@license属性AGPL-V3符合这两个{" @license ":{" $匹配”:“* GPL *}}准则和“@license”:{" $ nmatch”:“lgpl - 2.1 *”}标准。
返回项目B,因为它具有@license属性lgpl - 2.2这也符合这两个{" @license ":{" $匹配”:“* GPL *}}准则和“@license”:{" $ nmatch”:“lgpl - 2.1 *”}标准。
请注意msp美元Operator同样适用于所有具有以下属性的域:项,模块和构建。
msp美元
下表列出了允许的全部比较操作符:
关于基于时间的操作,也请参考相对时间算子。
为了使用非特定条件进行搜索,AQL在常用搜索功能中支持通配符。
当使用“$匹配"和"nmatch美元操作符,“*”通配符替换任何字符串,“?”通配符替换单个字符。
$匹配
nmatch美元
除了支持“$匹配"和"nmatch美元, AQL支持使用通配符进行匹配的符号任何键或任何属性的值。
如果指定“@*”作为属性键,则表示在任何键上都匹配。
如果你指定"*作为属性值,那么它意味着匹配任何值
*
查找具有任何属性值为“GPL”的物品
items.find ({”美元和”: [{"property.key" : {"$eq" : "*"}}, {"property.value" : {"$eq" : "GPL"}}]})
items.find({“@ *”:“GPL”})
查找带有键为“license”的属性注释的任何项(即查找带有“license”属性的任何项)
items.find ({”美元和”: [{"property.key" : {"$eq" : "license"}}, {"property.value" : {"$eq" : "*"}}]})
items.find({“@artifactory.licenses”:“*”})
注意不要误用通配符
在不符合上述规则的查询中使用的通配符(“*”和“?”)将被解释为字面量。
为了避免混淆,这里有一些使用“*”和“?”字符的例子,解释为什么它们被解释为通配符或文字。
items.find ({" name ":{" $匹配”:“ant-1.9.4 *”。}})
允许在字段上使用通配符$匹配操作符。
items.find ({" name ": {" $ eq”:“ant-1.9.4 *”。}})
字段上的通配符只允许使用$匹配和nmatch美元操作符。
对于属性,这种简短的符号是允许的,可以表示任何值
items.find({“@artifactory.licenses”:“* GPL”})
这是替换$eq操作符的简短符号,但它不使用属性的“捕获全部”符号。
所有带有“*GPL”许可证的项目
items.find ({“@artifactory.licenses”:{" $匹配”:“* GPL * "}})
AQL支持日期和时间格式W3C概要日期和时间格式的ISO 8601标准。
完整的日期和时间符号指定为:
YYYY-MM-DDThh: mm: ss。sTZD(例如:2012-07-16T19:20:30.45+01:00)
还支持部分精度指定的日期/时间:(即只指定年份,或年和月,年,月和日等。)
例如,下面的查询将返回2012年7月16日在GMT+1时区下午7:20后30.45秒修改的所有项目:
//查找在2012-07-16T19:20:30.45+01:00项之后被修改的所有项。找到({"modified" : {"$gt" : "2012-07-16T19:20:30.45+01:00"}}) //Find all the builds that have were created after 2012-07-01 builds.find({"created" : {"$gt" : "2012-07-01"}})
有关详情,请参阅W3C文档。
AQL支持使用相对时间为查询指定时间间隔。换句话说,查询的时间间隔总是相对于查询运行的时间,因此您不必在每次运行查询时以其他方式更改或制定时间段。例如,您可能希望运行过去一天的查询,或者运行两周前的时间段的查询。
使用以下两个操作符指定相对时间:
时间段用一个数字和下列后缀之一指定:
例如,要指定五天,您可以使用"5d"。要指定两周,可以使用“2w”。
下面是一些使用相对时间运算符的例子:
//查找最近三天内修改的所有项目。找到({"modified" : {"$last" : "3d"}}) //Find all the builds that were created up to two weeks ago (i.e. no later than two weeks ago) builds.find({"created" : {"$before" : "2w"}})
每个查询在结果集中显示一组默认字段,但是您可以完全控制这一点,并且可以使用可选项指定要显示哪些字段包括元素。
甚至可以指定显示与结果集相关的其他实体的字段。
使用:其中包括(“*”)
//查找所有项目,并显示所有项目字段items. Find ().include("*")
每个查询在输出中显示一组默认字段。使用其中包括元素,您可以覆盖此默认设置并指定希望在输出中接收的任何特定字段集。
其中包括
使用:其中包括(“< field1 >”、“< field2 >”……)
//查找所有项目,只显示"name"和"repo"字段items. Find()。包括(“名字”,“回购”)
还可以显示与查询返回的字段相关联的其他实体中的特定字段。
中指定的任何字段项域,则这将覆盖默认输出设置,并且只有项您明确指定的字段将被显示。
中指定的字段财产或统计域,则输出将显示来自项中明确指定的其他字段财产或统计域。
//查找所有项目,并显示“name”和“repo”字段以及对应的“stat”实体项目的“下载”次数。包括("name", "repo", "stat.downloads") //Find all items, and display the default item fields fields as well as the stat fields items.find().include("stat") //Find all items, and display the default item fields as well as the stat and the property fields items.find().include("stat", "property") //Find all items, and display the "name" and "repo" fields as well as the stat fields items.find().include("name", "repo", "stat") //Find all builds that generated items with an Apache license, and display the build fields as well as the item "name" fields. Click below to view the output of this query builds.find({ "module.artifact.item.@license":{"$match":"Apache*"} } ).include("module.artifact.item.name")
注意,输出显示了“build”域的默认字段,以及项目域的“name”字段。来自模块和工件域的字段没有显示,因为它们没有在include元素中指定。
{
"results": [{“构建。创建”: "2015-09-06T15:49:01.156+03:00",“构建。创建_by" : "admin",”build.name: "maven+example",“构建。数量”: "313",“构建。url”: "http://localhost:9595/jenkins/job/maven+example/313/","modules": [{“artifacts”:[{“items”:[{]“name”:“multi-3.0.0-20150906.124843-”1. pom”})})})},{“构建。创建”: "2015-09-06T15:54:40.726+03:00",“构建。创建_by" : "admin",”build.name: "maven+example",“构建。数量”: "314",“构建。url”: "http://localhost:9595/jenkins/job/maven+example/314/","modules": [{“artifacts”:[{“items”:[{]“name”:“multi-3.0.0-20150906.124843-”1. pom”
为确保非特权用户在没有权限的情况下不会访问信息,没有管理员权限的用户有以下限制:
包括
名字,回购
路径
但是,请注意,一旦满足了这些限制,您就可以包含来自任何域的任何其他可访问字段的包括指令。
如上所述,.include元素的主要用途是指定要在结果集中显示的输出字段。
这个概念以类似的方式应用于属性。每个项目都可以用几个(甚至很多)属性进行注释。在许多情况下,您可能只对属性的特定子集感兴趣,并且只想显示这些属性。
所以。包括元素可以用来从结果中过滤掉不需要的属性,并且只显示(即:(包括)你感兴趣的。
例如,要显示所找到的注释项的所有属性:
//查找所有项目,并显示"name"和"repo"字段,以及与每个项目相关的所有属性items. Find ()包括("name", "repo", "property.*")
但是,如果您只对特定属性感兴趣(例如,您只想知道返回的每个项目的版本),您可以过滤掉所有其他属性,只包含您感兴趣的键的属性:
//查找所有项目,并显示"name"和"repo"字段,以及每个项目的"version"属性的键和值items. Find ()Include ("name", "repo", "@version")
AQL实现默认排序顺序,但是,您可以通过在输出中添加.sort元素添加到查询的末尾,如下所示:
.sort
.sort ({< asc | desc >美元":[< field1 >, < field2 >》……]})
您只能指定对输出中显示的字段进行排序(无论这些字段是默认显示的还是由于其中包括元素)。
//在artifactory中找到所有的jar,并按repo和命名项进行排序。查找({"name": {"$match":"*.jar"})。Sort ({"$asc": ["repo","name"]})// Find all the jars in artifactory and their properties, then sort them by repo and name items.find({"name" : {"$match":"*.jar"}}).include("@").sort({"$asc" : ["repo","name"]})
注意对的重要限制排序,限制和抵消上面描述的。
使用.limit元素,您可以限制查询将显示的记录的数量。
//在artifactory中找到所有的jar并按repo和名称排序,但只显示前100个结果项。查找({"name": {"$match":"*.jar"})。Sort ({"$asc": ["repo","name"]}).limit(100)
方法将重点放在结果的子集上时,还可以实现分页.offset元素。
//运行相同的示例,但这一次,最多显示50项,但跳过前100项。查找({"name": {"$match":"*.jar"})。Sort ({"$asc": ["repo","name"]}).offset(100).limit(50)
从4.8.1版本开始,AQL支持虚拟存储库。由于虚拟存储库只通过它们所包含的本地存储库间接地包含项目,因此已经制定了一些约定,如下面的部分所述。
您可以将查询限制在指定的虚拟存储库中进行搜索。在实践中,这意味着查询将应用于指定虚拟存储库中包含的本地存储库和远程存储库缓存。
例如,查找一个名为“my-virtual”的虚拟存储库中包含的任何存储库中的所有项目:
items.find ({”回购”: "my-virtual"})
的项域有一个virtual_repos字段,该字段包含包含已找到项的虚拟存储库。一般来说,要显示此字段,需要在查询中将其明确指定为输出字段。但是,如果您的查询指定虚拟存储库作为其搜索目标,则virtual_repos字段作为输出字段隐式地包含在搜索结果中。
一个项目必须是可访问的才能被找到
搜索查询只会在虚拟存储库中找到可被该虚拟存储库访问的项。例如,包含项的本地存储库可以指定和包含或排除模式它阻止封装虚拟存储库访问项。在这种情况下,搜索查询将找不到项目。