使用查询参数筛选Catalog数据
若要提高性能并检索相关结果,请使用查询参数筛选Catalog Service API响应数据。
了解API中Catalog对象的常用筛选方法。 有关API交互的更多详细信息,请将此文档与Catalog Developer Guide一起使用。 有关Catalog Service的一般信息,请参阅Catalog 概述。
限制返回的对象 limit-returned-objects
limit查询参数限制响应中返回的对象数。 Catalog响应遵循预定义的限制:
- 如果未指定
limit参数,则每个响应的最大对象数为20。 - 对于数据集查询,如果使用
properties查询参数请求observableSchema,则返回的最大数据集数为20。 - 对于用户令牌,最大限制为1。
- 对于服务令牌,最大限制为20。
- 其他目录查询的全局限制为100个对象。
- 无效的
limit值(包括limit=0)导致指定了正确范围的400级错误响应。 - 作为查询参数传递的限制或偏移优先于标头中的限制或偏移。
API格式
GET /{OBJECT_TYPE}?limit={LIMIT}
{OBJECT_TYPE}要检索的Catalog对象的类型。 有效对象:
batchesdataSetsdataSetFiles
{LIMIT}请求
以下请求检索数据集列表,同时将响应限制为三个对象。
curl -X GET \
https://platform.adobe.io/data/foundation/catalog/dataSets?limit=3 \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
响应
成功的响应返回数据集列表,该列表限制为limit查询参数指示的数量。
{
"5ba9452f7de80400007fc52a": {
"name": "Sample Dataset 1",
"description": "Description of dataset.",
"files": "@/dataSetFiles?dataSetId=5ba9452f7de80400007fc52a"
},
"5bb276b03a14440000971552": {
"name": "Sample Dataset 2",
"description": "Description of dataset.",
"files": "@/dataSetFiles?dataSetId=5bb276b03a14440000971552"
},
"5bceaa4c26c115000039b24b": {
"name": "Sample Dataset 3"
}
}
限制显示的属性 limit-displayed-properties
即使使用limit参数过滤返回的对象数,返回的对象本身通常也可能包含比您实际需要更多的信息。 要进一步降低系统上的负载,最佳实践是筛选响应以仅包含所需的属性。
properties参数筛选响应对象,以仅返回一组指定的属性。 可将参数设置为返回一个或多个属性。
properties参数可以接受任何级别对象属性。 可以使用?properties=subItem.sampleKey提取sampleKey。
{
"5ba9452f7de80400007fc52a": {
"name": "Sample Dataset",
"description": "Sample dataset containing important data",
"subitem": {
"sampleKey": "sampleValue"
}
}
}
API格式
GET /{OBJECT_TYPE}?properties={PROPERTY}
GET /{OBJECT_TYPE}?properties={PROPERTY_1},{PROPERTY_2},{PROPERTY_3}
GET /{OBJECT_TYPE}/{OBJECT_ID}?properties={PROPERTY_1},{PROPERTY_2},{PROPERTY_3}
{OBJECT_TYPE}要检索的Catalog对象的类型。 有效对象为:
batchesdataSetsdataSetFiles
{PROPERTY}{OBJECT_ID}请求
以下请求检索数据集列表。 properties参数下提供的以逗号分隔的属性名称列表指示响应中要返回的属性。 还包含一个limit参数,该参数限制返回的数据集数。 如果请求不包含limit参数,则响应将最多包含20个对象。
curl -X GET \
'https://platform.adobe.io/data/foundation/catalog/dataSets?limit=4&properties=name,schemaRef' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
响应
成功的响应返回Catalog对象的列表,其中只显示所请求的属性。
{
"Dataset1": {
"name": "Dataset 1",
"schemaRef": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/bc82c518380478b59a95c63e0f843121",
"contentType": "application/vnd.adobe.xed+json;version=1"
}
},
"Dataset2": {},
"Dataset3": {
"name": {},
},
"Dataset4": {
"name": "Dataset 4",
"schemaRef": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/142afb78d8b368a5ba97a6cc8fc7e033",
"contentType": "application/vnd.adobe.xed+json;version=1"
}
}
}
根据以上响应,可以推断出以下情况:
- 如果对象缺少任何请求的属性,则它只会显示所请求的属性。 (
Dataset1) - 如果对象不包含请求的任何属性,则将显示为空对象。 (
Dataset2) - 如果某个数据集包含所请求的属性但没有值,则该数据集可能会将该属性作为空对象返回。 (
Dataset3) - 否则,数据集将显示所有请求属性的完整值。 (
Dataset4)
schemaRef属性中,版本号表示架构的最新次版本。 有关详细信息,请参阅XDM API指南中有关架构版本控制的部分。响应列表的偏移起始索引 offset-starting-index
start查询参数使用从零开始的编号,将响应列表向前偏移指定的编号。 例如,start=2将偏移响应以在列出的第三个对象上开始。
如果start参数未与limit参数配对,则返回的最大对象数为20。
API格式
GET /{OBJECT_TYPE}?start={OFFSET}
{OBJECT_TYPE}要检索的目录对象的类型。 有效对象为:
batchesdataSetsdataSetFiles
{OFFSET}请求
以下请求检索数据集列表,偏移到第五个对象(start=4)并将响应限制为两个返回的数据集(limit=2)。
curl -X GET \
https://platform.adobe.io/data/foundation/catalog/dataSets?start=4&limit=2 \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
响应
响应包括一个JSON对象,该对象包含两个顶级项(limit=2),每个数据集各一个,且其详细信息(示例中已经压缩了详细信息)。 响应偏移了四(start=4),这意味着所显示的数据集按时间顺序排在第5和第6位。
{
"Dataset5": {},
"Dataset6": {}
}
按标记筛选
某些目录对象支持使用tags属性。 标记可以将信息附加到对象,然后稍后用于检索该对象。 要使用的标记以及如何应用这些标记取决于您的组织流程。
使用标记时,需要考虑一些限制:
-
当前支持标记的目录对象只有数据集、批次和连接。
-
标记名称对您的组织是唯一的。
-
Adobe流程可能会针对特定行为使用标记。 这些标记的名称以“adobe”为标准前缀。 因此,在声明标记名称时,应避免使用此约定。
-
以下标记名称是保留名称,以供在Experience Platform中使用,因此不能声明为您的组织的标记名称:
unifiedProfile:此标记名称是为要由Real-Time Customer Profile引入的数据集而保留的。unifiedIdentity:此标记名称是为要由Identity Service引入的数据集而保留的。
以下是包含tags属性的数据集示例。 该属性中的标记采用键值对的形式,每个标记值都显示为包含单个字符串的数组:
{
"5be1f2ecc73c1714ceba66e2": {
"imsOrg": "{ORG_ID}",
"tags": {
"sampleTag": [
"123456"
],
"secondTag": [
"sample_tag_value"
]
},
"name": "Sample Dataset",
"description": "Same dataset containing sample data.",
"createdUser": "{CREATED_USER}",
"createdClient": "{CREATED_CLIENT}",
"updatedUser": "{UPDATED_USER}",
"version": "1.0.0",
"created": 1541534444286,
"updated": 1541534444286
}
}
API格式
tags参数的值采用键值对的形式,格式为{TAG_NAME}:{TAG_VALUE}。 可以以逗号分隔列表的形式提供多个键值对。 如果提供了多个标记,则假定为AND关系。
参数支持标记值的通配符(*)。 例如,搜索字符串test*返回标记值以“test”开头的任何对象。 仅由通配符组成的搜索字符串可用于根据对象是否包含特定标记对其进行过滤,而不管其值如何。
GET /{OBJECT_TYPE}?tags={TAG_NAME}:{TAG_VALUE}
GET /{OBJECT_TYPE}?tags={TAG_NAME_1}:{TAG_VALUE_1},{TAG_NAME_2}:{TAG_VALUE_2}
GET /{OBJECT_TYPE}?tags={TAG_NAME}:{TAG_VALUE}*
GET /{OBJECT_TYPE}?tags={TAG_NAME}:*
{OBJECT_TYPE}要检索的Catalog对象的类型。 有效对象为:
batchesdataSets
{TAG_NAME}{TAG_VALUE}*)。请求
以下请求检索数据集列表,按具有特定值的一个标记和存在的第二个标记进行筛选。
curl -X GET \
'https://platform.adobe.io/data/foundation/catalog/dataSets?tags=sampleTag:123456,secondTag:* \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
响应
成功的响应返回了一个数据集列表,该列表包含值为“123456”的sampleTag和任意值的secondTag。 除非也指定了限制,否则响应最多包含20个对象。
{
"5b67f4dd9f6e710000ea9da4": {
"version": "1.0.2",
"imsOrg": "{ORG_ID}",
"name": "Example Dataset 1",
"created": 1533539550237,
"updated": 1533539552416,
"createdClient": "{API_KEY}",
"createdUser": "{USER_ID}",
"updatedUser": "{USER_ID}",
"tags": {
"sampleTag": [
"123456"
],
"secondTag": [
"Example tag value"
]
},
},
"5b1e3c867e6d2600003d5b49": {
"version": "1.0.0",
"imsOrg": "{ORG_ID}",
"name": "Example Dataset 2",
"created": 1533539550237,
"updated": 1533539552416,
"createdClient": "{API_KEY}",
"createdUser": "{USER_ID}",
"updatedUser": "{USER_ID}",
"tags": {
"sampleTag": [
"123456"
],
"secondTag": [
"A different tag value"
],
"anotherTag": [
"2.0"
]
},
}
}
按日期范围过滤
Catalog API中的某些端点具有允许范围查询的查询参数,最常见的是日期查询。
API格式
GET /batches?createdAfter={TIMESTAMP_1}&createdBefore={TIMESTAMP_2}
{TIMESTAMP }请求
以下请求会检索在2019年4月期间创建的批次列表。
curl -X GET \
'https://platform.adobe.io/data/foundation/catalog/batches?createdAfter=1554076800000&createdBefore=1556668799000' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
响应
成功的响应包含指定日期范围内的Catalog对象列表。 除非也指定了限制,否则响应最多包含20个对象。
{
"5b67f4dd9f6e710000ea9da4": {
"version": "1.0.2",
"imsOrg": "{ORG_ID}",
"name": "Example Dataset 1",
"created": 1554930967705,
"updated": 1554931119718,
"createdClient": "{API_KEY}",
"createdUser": "{USER_ID}",
"updatedUser": "{USER_ID}",
},
"5b1e3c867e6d2600003d5b49": {
"version": "1.0.0",
"imsOrg": "{ORG_ID}",
"name": "Example Dataset 2",
"created": 1554974386247,
"updated": 1554974386268,
"createdClient": "{API_KEY}",
"createdUser": "{USER_ID}",
"updatedUser": "{USER_ID}",
}
}
按属性排序
orderBy查询参数允许您根据指定的属性值对响应数据排序(排序)。 此参数需要一个“方向”(asc表示升序,desc表示降序),后跟一个冒号(:),然后是一个属性以对结果排序。 如果未指定方向,则默认方向为升序。
可以以逗号分隔列表的形式提供多个排序属性。 如果第一个排序属性生成的多个对象包含该属性的相同值,则第二个排序属性用于进一步排序这些匹配的对象。
例如,请考虑以下查询: orderBy=name,desc:created。 结果根据第一个排序属性name按升序排序。 如果多个记录共享同一name属性,则这些匹配的记录将按第二个排序属性created排序。 如果没有返回的记录共享同一name,则created属性不会考虑排序的因素。
API格式
GET /{OBJECT_TYPE}?orderBy=asc:{PROPERTY_NAME}
GET /{OBJECT_TYPE}?orderBy=desc:{PROPERTY_NAME}
GET /{OBJECT_TYPE}?orderBy={PROPERTY_NAME_1},desc:{PROPERTY_NAME_2}
{OBJECT_TYPE}要检索的目录对象的类型。 有效对象为:
batchesdataSetsdataSetFiles
{PROPERTY_NAME}请求
以下请求检索按其name属性排序的数据集列表。 如果任何数据集共享相同的name,则这些数据集将依次按其updated属性降序排序。
curl -X GET \
'https://platform.adobe.io/data/foundation/catalog/dataSets?orderBy=name,desc:updated' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
响应
成功的响应包含根据orderBy参数排序的Catalog对象的列表。 除非也指定了限制,否则响应最多包含20个对象。
{
"5b67f4dd9f6e710000ea9da4": {
"version": "1.0.2",
"imsOrg": "{ORG_ID}",
"name": "0405",
"created": 1554930967705,
"updated": 1554931119718,
"createdClient": "{API_KEY}",
"createdUser": "{USER_ID}",
"updatedUser": "{USER_ID}",
},
"5b1e3c867e6d2600003d5b49": {
"version": "1.0.3",
"imsOrg": "{ORG_ID}",
"name": "AAM Dataset",
"created": 1554974386247,
"updated": 1554974386268,
"createdClient": "{API_KEY}",
"createdUser": "{USER_ID}",
"updatedUser": "{USER_ID}",
},
"5cd3a129ec106214b722a939": {
"version": "1.0.2",
"imsOrg": "{ORG_ID}",
"name": "AAM Dataset",
"created": 1554028394852,
"updated": 1554130582960,
"createdClient": "{API_KEY}",
"createdUser": "{USER_ID}",
"updatedUser": "{USER_ID}",
}
}
按属性筛选
Catalog提供了两种按属性进行筛选的方法,下面几节将对这些方法作进一步概述:
使用简单过滤器 using-simple-filters
使用简单过滤器,可根据特定的属性值过滤响应。 简单筛选器采用{PROPERTY_NAME}={VALUE}形式。
例如,查询name=exampleName只返回name属性包含“exampleName”值的对象。 相反,查询name=!exampleName只返回name属性为而非“exampleName”的对象。
此外,简单过滤器支持查询单个属性的多个值。 提供多个值时,响应将返回其属性与所提供列表中的值 any 匹配的对象。 您可以通过在列表中添加前缀!字符来反转多值查询,在提供的列表中(例如,name=!exampleName,anotherName)仅返回属性值是 而不是 的对象。
API格式
GET /{OBJECT_TYPE}?{PROPERTY_NAME}={VALUE}
GET /{OBJECT_TYPE}?{PROPERTY_NAME}=!{VALUE}
GET /{OBJECT_TYPE}?{PROPERTY_NAME}={VALUE_1},{VALUE_2},{VALUE_3}
GET /{OBJECT_TYPE}?{PROPERTY_NAME}=!{VALUE_1},{VALUE_2},{VALUE_3}
{OBJECT_TYPE}要检索的Catalog对象的类型。 有效对象为:
batchesdataSetsdataSetFiles
{PROPERTY_NAME}{VALUE}请求
以下请求检索经过筛选的数据集列表,以仅包含其name属性值为“exampleName”或“anotherName”的数据集。
curl -X GET \
'https://platform.adobe.io/data/foundation/catalog/dataSets?name=exampleName,anotherName' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
响应
成功的响应包含数据集列表,不包括name为“exampleName”或“anotherName”的任何数据集。 除非也指定了限制,否则响应最多包含20个对象。
{
"5b67f4dd9f6e710000ea9da4": {
"version": "1.0.2",
"imsOrg": "{ORG_ID}",
"name": "exampleName",
"created": 1554930967705,
"updated": 1554931119718,
"createdClient": "{API_KEY}",
"createdUser": "{USER_ID}",
"updatedUser": "{USER_ID}",
},
"5b1e3c867e6d2600003d5b49": {
"version": "1.0.3",
"imsOrg": "{ORG_ID}",
"name": "anotherName",
"created": 1554974386247,
"updated": 1554974386268,
"createdClient": "{API_KEY}",
"createdUser": "{USER_ID}",
"updatedUser": "{USER_ID}",
}
}
使用property参数 using-the-property-parameter
property查询参数为基于属性的筛选提供了比简单筛选更大的灵活性。 除了根据属性是否具有特定值进行筛选之外,property参数还可以使用其他比较运算符(如“大于”(>)和“小于”(<))以及正则表达式来按属性值筛选。 它还可以按属性是否存在进行筛选,而不管其值如何。
使用&符号(&)组合多个筛选器并在单个请求中优化查询。 当按多个字段过滤时,默认情况下应用AND关系。
property参数,则必须至少将一个参数应用于id或created字段。 以下查询返回id为abc123 且 name不是test的对象:| code language-http |
|---|
|
如果对同一字段使用多个property参数,则只有最后指定的参数生效。
property参数同时筛选多个字段。 每个字段必须具有自己的property参数。 以下示例(property=id>abc,name==myDataset)是 不允许 的,因为它尝试在 单个property参数 中向id和name应用条件。property参数可以接受任何级别对象属性。 sampleKey可用于使用?properties=subItem.sampleKey进行筛选。
{
"5ba9452f7de80400007fc52a": {
"name": "Sample Dataset",
"description": "Sample dataset containing important data",
"subitem": {
"sampleKey": "sampleValue"
}
}
}
API格式
GET /{OBJECT_TYPE}?property={CONDITION}
{OBJECT_TYPE}要检索的Catalog对象的类型。 有效对象为:
batchesdataSetsdataSetFiles
{CONDITION}property参数的值支持多种不同类型的条件表达式。 下表概述了支持的表达式的基本语法:
property=name!”前缀为property参数的值将只返回属性 不 存在的对象。property=!name~)后面提供的正则表达式匹配的对象。property=name~^example==)后提供的字符串的对象。property=name==exampleName!=)后提供的字符串匹配的对象。property=name!=exampleNameproperty=version<1.0.0property=version<=1.0.0property=version>1.0.0property=version>=1.0.0**对文字星号进行转义。property=name==te*stproperty参数与它们之间的AND关系组合在一起。property=id==abc&property=name!=testname属性支持将通配符*用作整个搜索字符串或作为其一部分。 通配符匹配空字符,因此搜索字符串te*st将匹配值“test”。 将星号加倍(**)可避免星号。 搜索字符串中的双星号表示一个星号作为文本字符串。请求
以下请求将返回版本号大于1.0.3的任何数据集。
curl -X GET \
https://platform.adobe.io/data/foundation/catalog/dataSets?property=version>1.0.3 \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
响应
成功的响应包含版本号大于1.0.3的数据集列表。 除非也指定了限制,否则响应最多包含20个对象。
{
"5b67f4dd9f6e710000ea9da4": {
"version": "1.1.2",
"imsOrg": "{ORG_ID}",
"name": "sampleDataset",
"created": 1554930967705,
"updated": 1554931119718,
"createdClient": "{API_KEY}",
"createdUser": "{USER_ID}",
"updatedUser": "{USER_ID}",
},
"5b1e3c867e6d2600003d5b49": {
"version": "1.0.6",
"imsOrg": "{ORG_ID}",
"name": "exampleDataset",
"created": 1554974386247,
"updated": 1554974386268,
"createdClient": "{API_KEY}",
"createdUser": "{USER_ID}",
"updatedUser": "{USER_ID}",
},
"5cd3a129ec106214b722a939": {
"version": "1.0.4",
"imsOrg": "{ORG_ID}",
"name": "anotherDataset",
"created": 1554028394852,
"updated": 1554130582960,
"createdClient": "{API_KEY}",
"createdUser": "{USER_ID}",
"updatedUser": "{USER_ID}",
}
}
使用属性参数筛选数组 filter-arrays
根据数组属性过滤结果时,使用相等和不等运算符可包含或排除特定值。
等式过滤器 equality-filters
要按多个值过滤数组字段,请为每个值使用单独的属性参数。 使用相等过滤器仅返回数组数据中匹配指定值的条目。
id或created在筛选数组字段中的多个值时 不 适用。下面的示例查询只返回数组中同时包含val1和val2的结果。
API格式
GET /{OBJECT_TYPE}?property=arrayField=val1&property=arrayField=val2
不等式过滤器 inequality-filters
对数组字段使用不等式运算符(!=)以排除数组中包含指定值的数据中的任何条目。
API格式
GET /{OBJECT_TYPE}?property=arrayField!=val1&property=arrayField!=val2
此查询返回arrayField不包含val1或val2的文档。
等式和不等式筛选器限制 equality-inequality-limitations
不能在单个查询中将等式(=)和不等式(!=)同时应用于同一字段。