Documentatie Experience Platform Handleiding Data Governance

Gegevensgebruikslabels voor gegevenssets beheren met behulp van API's

Laatst bijgewerkt: 4 april 2025

Onderwerpen:
Datagovernance

Gemaakt voor:

Gebruiker
Ontwikkelaar
Beheerder

Met Dataset Service APIkunt u gebruikslabels voor gegevenssets toepassen en bewerken. De klasse maakt deel uit van de mogelijkheden van de Adobe Experience Platform-gegevenscatalogus, maar staat los van de API van Catalog Service die metagegevens van gegevenssets beheert.

IMPORTANT

Het toepassen van labels op gegevenssetniveau wordt alleen ondersteund voor gevallen waarin gegevens worden beheerd. Als u probeert om toegangsbeleid voor de gegevens tot stand te brengen, moet u etiketten op het schematoepassen dat de dataset op gebaseerd is. Zie het overzicht op op attributen-gebaseerde toegangsbeheervoor meer informatie.

In dit document wordt beschreven hoe u labels voor gegevenssets en velden kunt beheren met de Dataset Service API . Voor stappen op hoe te om de etiketten van het gegevensgebruik zelf te beheren die API vraag gebruiken, zie de gids van het etiketteneindpuntvoor Policy Service API.

Aan de slag

Alvorens u deze gids leest, volg de stappen die in worden geschetst begonnen sectiein de de ontwikkelaarsgids van de Catalogus worden geschetst om de vereiste geloofsbrieven te verzamelen om vraag aan Experience Platform APIs te maken.

Als u aanroepen wilt uitvoeren naar de eindpunten die in dit document worden beschreven, moet u de unieke id -waarde voor een specifieke gegevensset hebben. Als u deze waarde niet hebt, zie de gids op het van lijstCatalogusvoorwerpenom IDs van uw bestaande datasets te vinden.

De etiketten van de raadpleging voor een dataset

U kunt de labels voor gegevensgebruik opzoeken die zijn toegepast op een bestaande gegevensset door een GET-aanvraag in te dienen bij de Dataset Service API.

API formaat

GET /datasets/{DATASET_ID}/labels

Parameter	Beschrijving
`{DATASET_ID}`	De unieke `id` waarde van de dataset waarvan etiketten u omhoog wilt kijken.

Verzoek

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

Reactie

Een succesvolle reactie keert de etiketten van het gegevensgebruik terug die op de dataset zijn toegepast.

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

Eigenschap	Beschrijving
`labels`	Een lijst van de etiketten van het gegevensgebruik die op de dataset zijn toegepast.
`optionalLabels`	Een lijst van individuele gebieden binnen de dataset die de etiketten van het gegevensgebruik hebben op hen worden toegepast.

Labels toepassen op een gegevensset

U kunt een reeks etiketten voor een volledige dataset toepassen door hen in de lading van een POST of PUT verzoek op Dataset Service API te verstrekken. Het verzoeklichaam is het zelfde voor beide vraag. U kunt geen labels toevoegen aan afzonderlijke gegevenssetvelden.

API formaat

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

Parameter	Beschrijving
`{DATASET_ID}`	De unieke `id` -waarde van de gegevensset waarvoor u labels maakt.

Verzoek

In het onderstaande voorbeeld wordt de gehele gegevensset bijgewerkt met een label C1 . De velden in de lading zijn gelijk aan de velden die vereist zijn voor een PUT-aanvraag.

Wanneer het maken van API vraag die de bestaande etiketten van een dataset (PUT) bijwerkt, moet een If-Match kopbal die op de huidige versie van de dataset-etiket entiteit in de Dienst van de Dataset wijst worden omvat. Om gegevensbotsingen te verhinderen, zal de dienst slechts de datasetentiteit bijwerken als inbegrepen If-Match koord de recentste versiemarkering aanpast die door het systeem voor die dataset wordt geproduceerd.

NOTE

Als er momenteel labels voor de desbetreffende gegevensset bestaan, kunnen nieuwe labels alleen worden toegevoegd via een PUT-aanvraag waarvoor een If-Match header is vereist. Zodra de etiketten aan een dataset zijn toegevoegd, wordt de meest recente etag waarde vereist om de etiketten in een recentere tijd
bij te werken of te verwijderen alvorens de methode van PUT uit te voeren, moet u een verzoek van GET op de datasetetiketten uitvoeren. Zorg ervoor dat u alleen de specifieke velden bijwerkt die zijn bedoeld voor wijziging in de aanvraag, en laat de rest ongewijzigd. Bovendien, zorg ervoor dat de vraag van PUT de zelfde ouderentiteiten zoals de vraag van GET handhaaft. Elke discrepantie zou resulteren in een fout voor de klant.

Om de meest recente versie van de dataset-etiket entiteit terug te winnen, doe a GET verzoekaan het /datasets/{DATASET_ID}/labels eindpunt. De huidige waarde wordt geretourneerd in de reactie onder een etag -header. Wanneer u bestaande gegevenssetlabels bijwerkt, kunt u het beste eerst een opzoekverzoek voor de gegevensset uitvoeren om de laatste etag -waarde op te halen voordat u die waarde in de If-Match -koptekst van uw volgende PUT-verzoek gebruikt.

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

Eigenschap	Beschrijving
`entityId`	Dit identificeert de specifieke gegevenssetentiteit die moet worden bijgewerkt.
`entityId.namespace`	Dit wordt gebruikt om botsingen van identiteitskaart te vermijden. De waarde `namespace` is `AEP` .
`entityId.id`	De id van de bron die wordt bijgewerkt. Dit verwijst naar `datasetId`.
`entityId.type`	Het type van de bron die wordt bijgewerkt. Dit zal altijd `dataset` zijn.
`labels`	Een lijst van de etiketten van het gegevensgebruik die u aan de volledige dataset wilt toevoegen.
`parents`	De `parents` serie bevat een lijst van `entityId` s die deze dataset etiketten van zal erven. Datasets kunnen labels overnemen van schema's en/of gegevenssets.

Reactie

Een succesvolle reactie keert de bijgewerkte reeks etiketten voor de dataset terug.

IMPORTANT

De eigenschap optionalLabels is vervangen voor gebruik met POST-aanvragen. Het is niet meer mogelijk om gegevensetiketten aan datasetgebieden toe te voegen. Een POST-bewerking genereert een fout als er een optionalLabel -waarde aanwezig is. U kunt labels echter uit afzonderlijke velden verwijderen met een PUT-aanvraag en de eigenschap optionalLabels . Voor meer informatie zie de sectie op verwijderend etiketten uit een dataset.

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

Labels uit een gegevensset verwijderen

U kunt eerder toegepaste veldlabels verwijderen door de bestaande optionalLabels -waarde(n) bij te werken met een subset van de bestaande veldlabels of door een lege lijst om deze volledig te verwijderen. Voer een PUT-aanvraag in voor de Dataset Service API om eerder toegepaste labels bij te werken of te verwijderen.

NOTE

U kunt de labels van een gegevensset volledig verwijderen door een lege lijst voor de parameter labels op te geven. Het is niet verplicht dat een gegevensset labels behoudt.

API formaat

PUT /datasets/{DATASET_ID}/labels

Parameter	Beschrijving
`{DATASET_ID}`	De unieke `id` -waarde van de gegevensset waarvoor u labels maakt.

Verzoek

De onderstaande dataset waarop de verrichting van PUT wordt toegepast had C1 optionalLabel op eigenschappen/person/properties/address gebied en C1, C2 optionalLabels op /properties/person/properties/name/properties/fullName gebied. Na de putoptie heeft het eerste veld geen label (label C1 verwijderd) en het tweede veld heeft alleen het label C1 (label C2 verwijderd)

In het onderstaande voorbeeldscenario wordt een PUT-aanvraag gebruikt om labels te verwijderen die aan afzonderlijke velden zijn toegevoegd. Voordat de aanvraag werd uitgevoerd, waren in het veld fullName de labels C1 en C2 toegepast en in het veld address was al een label C1 toegepast. De PUT-aanvraag negeert bestaande labels C1, C2 uit het fullName -veld met een C1 -label met behulp van de optionalLabels.labels -parameter. De aanvraag negeert ook het label C1 uit het veld address met een lege set veldlabels.

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

Parameter	Beschrijving
`entityId`	Dit identificeert de specifieke gegevenssetentiteit die moet worden bijgewerkt. `entityId` moet de volgende drie waarden omvatten: `namespace`: Dit wordt gebruikt om botsingen van identiteitskaart te vermijden. De waarde `namespace` is `AEP` . `id`: De id van de bron die wordt bijgewerkt. Dit verwijst naar `datasetId`. `type`: Het type van de bron die wordt bijgewerkt. Dit zal altijd `dataset` zijn.
`labels`	Een lijst van de etiketten van het gegevensgebruik die u aan de volledige dataset wilt toevoegen.
`parents`	De `parents` serie bevat een lijst van `entityId` s die deze dataset etiketten van zal erven. Datasets kunnen labels overnemen van schema's en/of gegevenssets.
`optionalLabels`	Deze parameter wordt gebruikt om etiketten te verwijderen die eerder op een datasetgebied worden toegepast. Een lijst van om het even welke individuele gebieden binnen de dataset die u de etiketten wilt verwijderen. Elk item in deze array moet de volgende eigenschappen hebben: `option`: Een object dat de Experience Data Model (XDM)-kenmerken van het veld bevat. De volgende drie eigenschappen zijn vereist: `id`: De URI `$id` De waarde van het schema dat aan het veld is gekoppeld. `contentType`: Het inhoudstype en het versienummer van het schema. Dit zou de vorm van één van de geldige moeten aannemen kopballenvoor een XDM raadplegingsverzoek. `schemaPath`: De weg aan het gebied binnen het schema van de dataset. `labels`: deze waarde moet een subset van de bestaande toegepaste veldlabels bevatten of leeg zijn om alle bestaande veldlabels te verwijderen. PUT- of POST-methoden retourneren nu een fout als het `optionalLabels` -veld nieuwe of gewijzigde labels heeft.

Reactie

Een succesvolle reactie keert de bijgewerkte reeks etiketten voor de dataset terug.

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

Volgende stappen

Door dit document te lezen, hebt u geleerd hoe u labels voor gegevensgebruik voor gegevenssets en velden kunt beheren met de API Dataset Service . U kunt beleid van het gegevensgebruiken toegangsbeheerbeleidnu bepalen dat op de etiketten wordt gebaseerd u hebt toegepast.

Voor meer informatie bij het beheren van datasets in Experience Platform, zie het overzicht van datasets.

recommendation-more-help