篩選 Catalog 使用查詢引數的資料
此 Catalog Service API可讓您透過使用請求查詢引數來篩選回應資料。 最佳實務的一部分, Catalog 是在所有API呼叫中使用篩選器,因為它們會降低API的負載,並有助於改善整體效能。
本檔案會概述最常見的篩選方法 Catalog API中的物件。 建議您在閱讀 目錄開發人員指南 以進一步瞭解如何與 Catalog API。 如需更多一般資訊,請參閱 Catalog Service,請參閱 Catalog 概述.
限制傳回的物件
此 limit
查詢引數會限制回應中傳回的物件數。 Catalog 會根據設定的限制自動計量回應:
- 如果
limit
未指定引數,每個回應裝載的物件數目上限為20。 - 針對資料集查詢,如果
observableSchema
是使用properties
查詢引數,傳回的資料集數目上限為20。 - 所有其他目錄查詢的全域限製為100個物件。
- 無效
limit
引數(包括limit=0
)會產生400層級的錯誤回應,指出適當的範圍。 - 以查詢引數傳遞的限制或位移優先於以標頭傳遞的限制或位移。
API格式
GET /{OBJECT_TYPE}?limit={LIMIT}
{OBJECT_TYPE}
型別 Catalog 物件。 有效的物件包括:
batches
dataSets
dataSetFiles
{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
引數,傳回的物件本身通常可包含比您實際需要更多的資訊。 若要進一步降低系統的負載,最佳實務是篩選回應,僅包含您需要的屬性。
此 properties
引數會篩選回應物件,以只傳回一組指定的屬性。 引數可以設定為傳回一或多個屬性。
此 properties
引數可以接受任何層級的物件屬性。 sampleKey
可使用以下專案擷取 ?properties=subItem.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 物件。 有效的物件包括:
batches
dataSets
dataSetFiles
{PROPERTY}
{OBJECT_ID}
要求
以下請求會擷取資料集清單。 以下提供的逗號分隔屬性名稱清單: properties
引數會指出回應中傳回的屬性。 A 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指南以瞭解詳細資訊。回應清單的位移開始索引
此 start
查詢引數會使用從零開始的編號,將回應清單向前位移指定的編號。 例如, start=2
會將回應位移,以便在列出的第三個物件上啟動。
如果 start
引數未與配對 limit
引數,傳回的物件數目上限為20。
API格式
GET /{OBJECT_TYPE}?start={OFFSET}
{OBJECT_TYPE}
要擷取的目錄物件型別。 有效的物件包括:
batches
dataSets
dataSetFiles
{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
),表示所示資料集依時間順序為第五和第六個。
{
"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 物件。 有效的物件包括:
batches
dataSets
{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}'
回應
成功的回應會傳回包含的資料集清單 sampleTag
值為「123456」,並且 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
查詢引數可讓您根據指定的屬性值來排序(排序)回應資料。 此引數需要「direction」(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}
要擷取的目錄物件型別。 有效的物件包括:
batches
dataSets
dataSetFiles
{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}'
回應
成功的回應包含清單 Catalog 根據下列專案排序的物件: orderBy
引數。 除非也指定限制,否則回應最多包含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"。
此外,簡單篩選器可支援查詢單一屬性的多個值。 提供多個值時,回應會傳回屬性相符的物件 任何 提供的清單中的值。 您可以藉由為多值查詢加上前置詞來反轉 !
字元至清單,只傳回屬性值為的物件 非 在提供的清單中(例如, 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 物件。 有效的物件包括:
batches
dataSets
dataSetFiles
{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
引數可使用其他比較運運算元(例如「大於」(>
)和「小於」(<
))以及規則運算式,以依據屬性值篩選。 它也可以依屬性是否存在進行篩選,無論其值為何。
此 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 物件。 有效的物件包括:
batches
dataSets
dataSetFiles
{CONDITION}
的值 property
引數支援數種不同的條件運算式。 下表概述支援運算式的基本語法:
property=name
!
」至的值 property
引數只會傳回屬性執行的物件 非 存在。property=!name
~
)符號。property=name~^example
==
)。property=name==exampleName
!=
)。property=name!=exampleName
property=version<1.0.0
property=version<=1.0.0
property=version>1.0.0
property=version>=1.0.0
name
屬性支援使用萬用字元 *
,當作整個搜尋字串或其中一部分。 萬用字元與空白字元相符,例如搜尋字串 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}",
}
}
合併多個篩選器
使用&符號(&
),您便可以在單一請求中合併多個篩選器。 將其他條件新增至請求時,假設為AND關係。
API格式
GET /{OBJECT_TYPE}?{FILTER_1}={VALUE}&{FILTER_2}={VALUE}&{FILTER_3}={VALUE}