使用API管理資料集的資料使用標籤
此 Dataset Service API 可讓您套用及編輯資料集的使用標籤。 它是Adobe Experience Platform資料目錄功能的一部分,但與 Catalog Service 管理資料集中繼資料的API。
本檔案說明如何使用 Dataset Service API. 如需如何使用API呼叫管理資料使用標籤本身的步驟,請參閱 標籤端點指南 針對 Policy Service API.
快速入門
閱讀本指南前,請遵循以下說明的步驟 快速入門區段 在目錄開發人員指南中,以收集必要的認證來呼叫 Platform API。
若要呼叫本檔案中概述的端點,您必須擁有 id
特定資料集的值。 如果您沒有此值,請參閱上的指南 列出目錄物件 以尋找現有資料集的ID。
查詢資料集的標籤 look-up
您可以透過向「 」發出GET請求,查詢已套用至現有資料集的資料使用標籤。 Dataset Service API。
API格式
GET /datasets/{DATASET_ID}/labels
{DATASET_ID}
id
您要查詢其標籤的資料集的值。要求
curl -X GET \
'https://platform.adobe.io/data/foundation/dataset/datasets/5abd49645591445e1ba04f87/labels' \
-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}'
回應
成功的回應會傳回已套用至資料集的資料使用標籤。
{
"AEP:dataset:5abd49645591445e1ba04f87": {
"imsOrg": "{ORG_ID}",
"labels": [ "C1", "C2", "C3", "I1", "I2" ],
"optionalLabels": [
{
"option": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/c6b1b09bc3f2ad2627c1ecc719826836",
"contentType": "application/vnd.adobe.xed-full+json;version=1",
"schemaPath": "/properties/repositoryCreatedBy"
},
"labels": [ "S1", "S2" ]
}
]
}
}
labels
optionalLabels
將標籤套用至資料集 apply
您可以在POST或PUT請求的裝載中提供一組標籤,將標籤套用至整個資料集。 Dataset Service API。 兩個呼叫的要求內文相同。 您無法將標籤新增至個別資料集欄位。
API格式
POST /datasets/{DATASET_ID}/labels
PUT /datasets/{DATASET_ID}/labels
{DATASET_ID}
id
您要建立標籤之資料集的值。要求
以下範例POST請求會使用更新整個資料集 C1
標籤。 承載中提供的欄位與PUT請求所需的欄位相同。
進行API呼叫以更新資料集(PUT)的現有標籤時, If-Match
必須包含可指出資料集服務中資料集 — 標籤實體的目前版本的標頭。 為避免資料衝突,服務將僅更新資料集實體(如果包含) If-Match
字串符合系統為該資料集產生的最新版本標籤。
If-Match
標頭。 標籤新增至資料集後,最近一次 etag
稍後需要值才能更新或移除標籤在執行PUT方法之前,您必須先對資料集標籤執行GET要求。 請確定您僅更新請求中要修改的特定欄位,其餘欄位保持不變。 此外,請確定PUT呼叫維護與GET呼叫相同的父項實體。 任何差異都會導致客戶發生錯誤。
若要擷取最新版本的資料集 — 標籤實體,請建立 GET要求 至 /datasets/{DATASET_ID}/labels
端點。 目前的值會在回應中傳回,位於 etag
標頭。 更新現有的資料集標籤時,最佳實務是先執行資料集的查詢請求,以擷取其最新資料 etag
值之前,在中使用該 If-Match
後續PUT請求的標頭。
curl -X POST \
'https://platform.adobe.io/data/foundation/dataset/datasets/5abd49645591445e1ba04f87/labels' \
-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}' \
-H 'Content-Type: application/json' \
-d '{
"entityId": {
"namespace": "AEP",
"id": "test-ds-id",
"type": "dataset"
},
"labels": [
"C1"
],
"parents": []
} '
entityId
entityId.namespace
namespace
是 AEP
.entityId.id
datasetId
.entityId.type
dataset
.labels
parents
parents
陣列包含清單 entityId
此資料集將繼承其標籤的位置。 資料集可以從結構描述和/或資料集繼承標籤。回應
成功的回應會傳回資料集的更新標籤集。
optionalLabels
屬性已棄用,不適用於POST請求。 無法再將資料標籤新增至資料集欄位。 POST如果 optionalLabel
值存在。 不過,您可以使用PUT請求和 optionalLabels
屬性。 如需詳細資訊,請參閱以下章節: 從資料集中移除標籤.{
"parents": [
{
"id": "_ddgduleint.schemas.4a95cdba7d560e3bca7d8c5c7b58f00ca543e2bb1e4137d6",
"type": "schema",
"namespace": "AEP"
}
],
"optionalLabels": [],
"labels": [
"C1"
],
"code": "PES-201",
"message": "POST Successful"
}
從資料集中移除標籤 remove
您可以更新現有的欄位標籤,以移除任何先前套用的欄位標籤 optionalLabels
具有現有欄位標籤子集的值,或是要完全移除它們的空白清單。 向發出PUT請求 Dataset Service 更新或移除先前套用標籤的API。
API格式
PUT /datasets/{DATASET_ID}/labels
{DATASET_ID}
id
您要建立標籤之資料集的值。要求
套用PUT操作的以下資料集在properties/person/properties/address欄位上有C1 optionalLabel,在/properties/person/properties/name/properties/fullName欄位上有C1, C2 optionalLabels。 put作業之後,第一個欄位將沒有標籤(移除C1標籤),而第二個欄位將只有C1標籤(移除C2標籤)
在以下範例案例中,PUT請求用於移除新增至個別欄位的標籤。 在提出要求之前, fullName
欄位具有 C1
和 C2
標籤已套用,而且 address
欄位已有 C1
標籤已套用。 PUT請求會覆寫現有標籤 C1, C2
標籤來自 fullName
欄位包含 C1
標籤使用 optionalLabels.labels
引數。 請求也會覆寫 C1
標籤來自 address
具有空白欄位標籤集的欄位。
curl -X PUT \
'https://platform.adobe.io/data/foundation/dataset/datasets/5abd49645591445e1ba04f87/labels' \
-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}' \
-H 'Content-Type: application/json' \
-H 'If-Match: 8f00d38e-0000-0200-0000-5ef4fc6d0000' \
-d '{
"entityId": {
"namespace": "AEP",
"id": "646b814d52e1691c07b41032",
"type": "dataset"
},
"labels": [
"C1"
],
"parents": [
{
"id": "_xdm.context.identity-graph-flattened-export",
"type": "schema",
"namespace": "AEP"
}
],
"optionalLabels": [
{
"option": {
"id": "https://ns.adobe.com/xdm/context/identity-graph-flattened-export",
"contentType": "application/vnd.adobe.xed-full+json;version=1",
"schemaPath": "/properties/person/properties/name/properties/fullName"
},
"labels": [
"C1"
]
},
{
"option": {
"id": "https://ns.adobe.com/xdm/context/identity-graph-flattened-export",
"contentType": "application/vnd.adobe.xed-full+json;version=1",
"schemaPath": "/properties/person/properties/address"
},
"labels": []
}
]
}'
entityId
entityId
必須包括下列三個值:namespace
:這是用於避免ID衝突。 此 namespace
是 AEP
.id
:正在更新之資源的ID。 這是指 datasetId
.type
:正在更新的資源型別。 永遠是 dataset
.labels
parents
parents
陣列包含清單 entityId
此資料集將繼承其標籤的位置。 資料集可以從結構描述和/或資料集繼承標籤。optionalLabels
此引數用於移除先前套用至資料集欄位的標籤。 資料集中您要移除其標籤的任何個別欄位清單。 此陣列中的每個專案都必須具備下列屬性:option
:包含 Experience Data Model (XDM)欄位的屬性。 需要下列三個屬性:
id
:URI$id
與欄位關聯之結構描述的值。contentType
:結構描述的內容型別和版本號碼。 這應該採用有效的其中一種形式 接受標頭 XDM查詢請求的變數。schemanpath
:資料集結構內欄位的路徑。
labels
:此值必須包含套用的現有欄位標籤的子集,或為空白以移除所有現有欄位標籤。 PUT或POST方法現在會在下列情況下傳回錯誤: optionalLabels
欄位具有任何新標籤或修改的標籤。
回應
成功的回應會傳回資料集的更新標籤集。
{
"parents": [
{
"id": "_xdm.context.identity-graph-flattened-export",
"type": "schema",
"namespace": "AEP"
}
],
"optionalLabels": [],
"labels": [
"C1"
],
"code": "PES-200",
"message": "PUT Successful"
}
後續步驟
閱讀本檔案後,您已瞭解如何使用 Dataset Service API。 您現在可以定義 資料使用原則 和 存取控制原則 根據您已套用的標籤。
有關管理資料集的詳細資訊,請參閱 Experience Platform,請參閱 資料集總覽.