Hantera dataanvändningsetiketter för datauppsättningar med API:er

Med Dataset Service API kan du använda och redigera användningsetiketter för datauppsättningar. Den ingår i Adobe Experience Platform datakatalogfunktioner, men är skild från Catalog Service-API:t som hanterar datauppsättningsmetadata.

Det här dokumentet beskriver hur du hanterar etiketter för datauppsättningar och fält med hjälp av Dataset Service API. Anvisningar om hur du hanterar själva dataanvändningsetiketter med API-anrop finns i etikettens slutpunktshandbok för Policy Service API.

Komma igång

Innan du läser den här guiden följer du de steg som beskrivs i avsnittet Komma igång i guiden för katalogutvecklare för att samla in de nödvändiga inloggningsuppgifterna för att ringa anrop till Platform API:er.

För att kunna anropa slutpunkterna som beskrivs i det här dokumentet måste du ha det unika id-värdet för en specifik datauppsättning. Om du inte har det här värdet läser du i guiden lista katalogobjekt för att hitta ID:n för dina befintliga datauppsättningar.

Söka efter etiketter för en datauppsättning look-up

Du kan söka efter dataanvändningsetiketter som har tillämpats på en befintlig datauppsättning genom att göra en GET-begäran till Dataset Service-API:t.

API-format

GET /datasets/{DATASET_ID}/labels

Begäran

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}'

Svar

Ett lyckat svar returnerar dataanvändningsetiketterna som har tillämpats på datauppsättningen.

{
  "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" ]
      }
    ]
  }
}

Tillämpa etiketter på en datauppsättning apply

Du kan använda en uppsättning etiketter för en hel datauppsättning genom att ange dem i nyttolasten för en POST- eller PUT-begäran i Dataset Service-API:t. Begärandetexten är densamma för båda anropen. Du kan inte lägga till etiketter i enskilda datauppsättningsfält.

API-format

POST /datasets/{DATASET_ID}/labels
PUT /datasets/{DATASET_ID}/labels

Begäran

Exempelbegäran nedan uppdaterar hela datauppsättningen med en C1-POST. Fälten i nyttolasten är desamma som skulle behövas för en PUT-begäran.

När API-anrop görs som uppdaterar de befintliga etiketterna för en datauppsättning (PUT), måste ett If-Match-huvud som anger den aktuella versionen av datauppsättningsetiketten i datauppsättningstjänsten inkluderas. För att förhindra datakonflikter uppdaterar tjänsten bara datauppsättningsentiteten om den inkluderade If-Match-strängen matchar den senaste versionstaggen som genererats av systemet för den datauppsättningen.

Om du vill hämta den senaste versionen av datauppsättningsetiketten skapar du en GET-begäran till /datasets/{DATASET_ID}/labels-slutpunkten. Det aktuella värdet returneras i svaret under en etag-rubrik. När du uppdaterar befintliga datauppsättningsrubriker är det bästa sättet att först utföra en sökbegäran för datauppsättningen för att hämta det senaste etag-värdet innan du använder det värdet i If-Match-huvudet för din efterföljande PUT-begäran.

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": []
      } '

Svar

Ett lyckat svar returnerar den uppdaterade uppsättningen etiketter för datauppsättningen.

{
  "parents": [
      {
        "id": "_ddgduleint.schemas.4a95cdba7d560e3bca7d8c5c7b58f00ca543e2bb1e4137d6",
        "type": "schema",
        "namespace": "AEP"
      }
  ],
  "optionalLabels": [],
  "labels": [
      "C1"
  ],
  "code": "PES-201",
  "message": "POST Successful"
}

Ta bort etiketter från en datauppsättning remove

Du kan ta bort tidigare använda fältetiketter genom att antingen uppdatera de befintliga optionalLabels värdena med en delmängd av de befintliga fältetiketterna eller genom att ta bort en tom lista helt. Gör en PUT-begäran till Dataset Service-API:t om att uppdatera eller ta bort etiketter som redan används.

API-format

PUT /datasets/{DATASET_ID}/labels

Begäran

The below dataset on which PUT operation is applied was C1 optionalLabel on properties/person/properties/address field and C1, C2 optionalLabels on /properties/person/properties/name/properties/fullName field. Efter placeringsåtgärden har det första fältet ingen etikett (C1-etiketten har tagits bort) och det andra fältet har bara C1-etikett (C2-etiketten har tagits bort)

I exemplet nedan används en PUT-begäran för att ta bort etiketter som lagts till i enskilda fält. Innan begäran gjordes användes etiketterna C1 och C2 för fältet fullName, och etiketten address användes redan för fältet C1. PUT-begäran åsidosätter befintliga etiketter C1, C2 från fältet fullName med en C1-etikett som använder parametern optionalLabels.labels. Begäran åsidosätter även etiketten C1 från fältet address med en tom uppsättning fältetiketter.

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": []
          }
        ]
      }'

Svar

Ett lyckat svar returnerar den uppdaterade uppsättningen etiketter för datauppsättningen.

{
  "parents": [
      {
        "id": "_xdm.context.identity-graph-flattened-export",
        "type": "schema",
        "namespace": "AEP"
      }
  ],
  "optionalLabels": [],
  "labels": [
      "C1"
  ],
  "code": "PES-200",
  "message": "PUT Successful"
}

Nästa steg

Genom att läsa det här dokumentet har du lärt dig att hantera dataanvändningsetiketter för datauppsättningar och fält med API:t Dataset Service. Du kan nu definiera dataanvändningsprinciper och åtkomstkontrollprinciper baserat på de etiketter du har använt.

Mer information om hur du hanterar datauppsättningar i Experience Platform finns i översikten över datauppsättningar.