使用API管理資料集的資料使用標籤
Dataset Service API可讓您套用及編輯資料集的使用標籤。 它是Adobe Experience Platform資料目錄功能的一部分，但與管理資料集中繼資料的Catalog Service API不同。
本檔案說明如何使用Dataset Service API管理資料集和欄位的標籤。 如需如何使用API呼叫管理資料使用標籤本身的步驟，請參閱Policy Service API的標籤端點指南。
快速入門
在閱讀本指南之前，請依照目錄開發人員指南的快速入門區段中概述的步驟，收集呼叫Platform API所需的認證。
若要呼叫本檔案中概述的端點，您必須具有特定資料集的唯一id值。 如果您沒有這個值，請參閱目錄物件清單上的指南，以尋找現有資料集的ID。
查詢資料集的標籤 look-up
您可以向Dataset Service API發出GET要求，查詢已套用至現有資料集的資料使用標籤。
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" ]
}
]
}
}
labelsoptionalLabels將標籤套用至資料集 apply
您可以在Dataset Service API的POST或PUT要求裝載中提供標籤，藉此為整個資料集套用一組標籤。 兩個呼叫的要求內文相同。 您無法將標籤新增至個別資料集欄位。
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呼叫相同的父項實體。 任何差異都會導致客戶發生錯誤。
若要擷取最新版本的資料集 — 標籤實體，請對/datasets/{DATASET_ID}/labels端點發出GET要求。 目前值是在etag標頭下的回應中傳回。 更新現有的資料集標籤時，最佳實務是先執行資料集的查詢要求，以擷取其最新的etag值，然後再在後續PUT要求的If-Match標頭中使用該值。
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": []
} '
entityIdentityId.namespacenamespace是AEP。entityId.iddatasetId。entityId.typedataset。labelsparentsparents陣列包含此資料集將繼承其標籤的entityId清單。 資料集可以從結構描述和/或資料集繼承標籤。回應
成功的回應會傳回資料集的更新標籤集。
optionalLabels屬性已棄用，無法與POST要求搭配使用。 無法再將資料標籤新增至資料集欄位。 如果出現optionalLabel值，POST作業將擲回錯誤。 不過，您可以使用PUT要求和optionalLabels屬性，從個別欄位中刪除標籤。 如需詳細資訊，請參閱從資料集移除標籤一節。{
"parents": [
{
"id": "_ddgduleint.schemas.4a95cdba7d560e3bca7d8c5c7b58f00ca543e2bb1e4137d6",
"type": "schema",
"namespace": "AEP"
}
],
"optionalLabels": [],
"labels": [
"C1"
],
"code": "PES-201",
"message": "POST Successful"
}
從資料集中移除標籤 remove
您可以透過以現有欄位標籤的子集更新現有optionalLabels值，或透過空白清單以完全移除它們，來移除任何先前套用的欄位標籤。 向Dataset Service API發出PUT要求，以更新或移除先前套用的標籤。
labels引數提供空白清單，以完全移除資料集的標籤。 資料集不必保留任何標籤。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要求使用optionalLabels.labels引數覆寫fullName欄位中具有C1標籤的現有標籤C1, C2標籤。 請求也會以一組空白欄位標籤覆寫address欄位中的C1標籤。
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": []
}
]
}'
entityIdentityId必須包含下列三個值：namespace：這是用來避免ID衝突。 namespace是AEP。id：正在更新的資源識別碼。 這參考datasetId。type：正在更新的資源型別。 這將永遠是dataset。labelsparentsparents陣列包含此資料集將繼承其標籤的entityId清單。 資料集可以從結構描述和/或資料集繼承標籤。optionalLabels此引數用於移除先前套用至資料集欄位的標籤。 資料集中您要移除其標籤的任何個別欄位清單。 此陣列中的每個專案都必須具備下列屬性：option：包含欄位Experience Data Model (XDM)屬性的物件。 需要下列三個屬性：
id： URI$id與欄位關聯之結構描述的值。內容型別：結構描述的內容型別和版本號碼。 這應該採用XDM查閱要求的有效Accept標頭之一的形式。結構描述路徑：資料集結構內欄位的路徑。
labels：此值必須包含套用的現有欄位標籤的子集，或為空白以移除所有現有欄位標籤。 如果optionalLabels欄位具有任何新的或修改的標籤，PUT或POST方法現在會傳回錯誤。
回應
成功的回應會傳回資料集的更新標籤集。
{
"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中管理資料集的詳細資訊，請參閱資料集總覽。