有问题吗?想要报告问题?联系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")
体系结构
AQL被构造为一组相互连接的域，如下图所示。您一次只能在一个域上运行查询，这被称为主要的查询的域。
目前支持以下主域:项，构建,条目,和推广。也就是说，你的查询可以是:items.find(…),builds.find(…)，Archive.entries.find(…)或build.promotions.find(…)。
您可以使用来自其他域的字段作为搜索条件的一部分，或者指定要在输出中显示的字段，但是在这种情况下，您需要遵循中描述的约定使用字段。
支持域
AQL在Artifactory V3.5.0中引入，并支持项作为主域，并附带财产，以及……统计作为二级域。Artifactory的后期版本引入了可以包含在查询中的其他域。下表总结了每个域可以从哪个版本访问。
| 3.5.0 | 4.2.0 | 4.7.0 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
项 |
项。财产 |
统计 |
 存档 |
 档案。条目 |
工件 |
依赖 |
模块 |
模块。财产 |
构建 |
构建。财产 |
促销活动 |
使用
语法< 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。 实体和字段你可以发出找到根据语法上面，并配置您的请求以显示来自任何域的字段。
构建搜索条件的标准元素必须是由指定应该返回的项的标准组成的有效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")条件可以指定如下:
性能标准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")条件可以如下指定: {"@
复合标准字段和属性上的搜索条件可以嵌套并组合成逻辑表达式，使用美元和“或者”美元或“运营商。如果未指定操作符，则默认为美元和 <标准> ={<美元”和“|”美元或“>:[{<标准>},{<标准>}]
标准可以任意程度地嵌套 请注意，由于搜索条件可以嵌套到任何程度，因此您可以构建具有任何复杂度的逻辑搜索条件。 下面是一些例子: //这个例子显示了一个隐式的"$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(匹配单个属性)操作符。 规则和规则之间的根本区别找到使用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 *”}标准。 请注意 比较运算符下表列出了允许的全部比较操作符:
关于基于时间的操作，也请参考相对时间算子。 使用通配符为了使用非特定条件进行搜索，AQL在常用搜索功能中支持通配符。 使用通配符$匹配和nmatch美元当使用“ 属性上的“全部捕获”符号除了支持“ 如果指定“@*”作为属性键，则表示在任何键上都匹配。 如果你指定"
注意不要误用通配符 在不符合上述规则的查询中使用的通配符(“*”和“?”)将被解释为字面量。 例子为了避免混淆，这里有一些使用“*”和“?”字符的例子，解释为什么它们被解释为通配符或文字。
日期和时间格式AQL支持日期和时间格式W3C概要日期和时间格式的ISO 8601标准。 完整的日期和时间符号指定为:
还支持部分精度指定的日期/时间:(即只指定年份，或年和月，年，月和日等。) 例如，下面的查询将返回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")
没有管理员权限的用户为确保非特权用户在没有权限的情况下不会访问信息，没有管理员权限的用户有以下限制:
但是，请注意，一旦满足了这些限制，您就可以包含来自任何域的任何其他可访问字段的 按键过滤属性如上所述，.include元素的主要用途是指定要在结果集中显示的输出字段。 这个概念以类似的方式应用于属性。每个项目都可以用几个(甚至很多)属性进行注释。在许多情况下，您可能只对属性的特定子集感兴趣，并且只想显示这些属性。 所以。包括元素可以用来从结果中过滤掉不需要的属性，并且只显示(即:(包括)你感兴趣的。 例如，要显示所找到的注释项的所有属性: //查找所有项目，并显示"name"和"repo"字段，以及与每个项目相关的所有属性items. Find ()包括("name"， "repo"， "property.*")
但是，如果您只对特定属性感兴趣(例如，您只想知道返回的每个项目的版本)，您可以过滤掉所有其他属性，只包含您感兴趣的键的属性: //查找所有项目，并显示"name"和"repo"字段，以及每个项目的"version"属性的键和值items. Find ()Include ("name"， "repo"， "@version")
排序AQL实现默认排序顺序，但是，您可以通过在输出中添加 .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)
//运行相同的示例，但这一次，最多显示50项，但跳过前100项。查找({"name": {"$match":"*.jar"})。Sort ({"$asc": ["repo"，"name"]}).offset(100).limit(50)
|
