Verwalten von Datennutzungskennzeichnungen für Datensätze mithilfe von APIs

Mit Dataset Service API können Sie Nutzungskennzeichnungen für Datensätze anwenden und bearbeiten. Sie gehört zu den Datenkatalogfunktionen von Adobe Experience Platform, ist jedoch von der Catalog Service-API getrennt, die Datensatz-Metadaten verwaltet.

In diesem Dokument wird beschrieben, wie Sie Kennzeichnungen für Datensätze und Felder mit der Dataset Service API verwalten. Anweisungen zum Verwalten von Datennutzungskennzeichnungen selbst mithilfe von API-Aufrufen finden Sie im Handbuch zu Endpunktkennzeichnungen für die Policy Service API.

Erste Schritte

Bevor Sie dieses Handbuch lesen, führen Sie die Schritte aus, die im Abschnitt Erste Schritte im Catalog-Entwicklerhandbuch beschrieben sind, um die erforderlichen Anmeldeinformationen für Aufrufe an Platform-APIs zu sammeln.

Um die in diesem Dokument beschriebenen Endpunkte aufrufen zu können, müssen Sie über den eindeutigen id-Wert für einen bestimmten Datensatz verfügen. Wenn Sie diesen Wert nicht haben, finden Sie im Handbuch Auflistung der Catalog-Objekte die IDs der vorhandenen Datensätze.

Suchen nach Kennzeichnungen für einen Datensatz look-up

Sie können die Datennutzungskennzeichnungen nachschlagen, die auf einen vorhandenen Datensatz angewendet wurden, indem Sie eine GET-Anfrage an die Dataset Service-API stellen.

API-Format

GET /datasets/{DATASET_ID}/labels

Anfrage

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

Antwort

Eine erfolgreiche Antwort gibt die Datennutzungsbeschriftungen zurück, die auf den Datensatz angewendet wurden.

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

Anwenden von Kennzeichnungen auf einen Datensatz apply

Sie können einen Satz von Kennzeichnungen für einen kompletten Datensatz erstellen, indem Sie diese in der Payload einer POST- oder PUT-Anfrage an die Dataset Service-API bereitstellen. Der Anfragetext ist für beide Aufrufe identisch. Sie können einzelnen Datensatzfeldern keine Kennzeichnungen hinzufügen.

API-Format

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

Anfrage

Mit der nachstehenden POST-Beispielanfrage wird der komplette Datensatz mit einer C1-Kennzeichnung aktualisiert. Die in der Payload bereitgestellten Felder entsprechen den Feldern, die für eine PUT-Anfrage erforderlich sind.

Wenn API-Aufrufe durchgeführt werden, die die vorhandenen Kennzeichnungen eines Datensatzes aktualisieren (PUT), muss eine If-Match-Kopfzeile eingefügt werden, die die aktuelle Version der Entität für die Datensatzkennzeichnung in Dataset Service angibt. Um Datenkollisionen zu vermeiden, aktualisiert der Service die Datensatzentität nur, wenn die enthaltene If-Match-Zeichenfolge mit dem neuesten vom System für diesen Datensatz generierten Versions-Tag übereinstimmt.

Um die neueste Version der Datensatzkennzeichnungsentität abzurufen, stellen Sie eine GET-Anfrage an den /datasets/{DATASET_ID}/labels-Endpunkt. Der aktuelle Wert wird in der Antwort unter einer etag-Kopfzeile zurückgegeben. Beim Aktualisieren vorhandener Datensatzkennzeichnungen sollten Sie zunächst eine Suchanfrage für den Datensatz durchführen, um den neuesten etag-Wert abzurufen, bevor Sie diesen Wert in der If-Match-Kopfzeile Ihrer nachfolgenden PUT-Anfrage verwenden.

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

Antwort

Eine erfolgreiche Antwort gibt den aktualisierten Satz von Kennzeichnungen für den Datensatz zurück.

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

Entfernen von Kennzeichnungen aus einem Datensatz remove

Sie können alle zuvor angewendeten Feldkennzeichnungen vollständig entfernen, indem Sie entweder vorhandene optionalLabels-Werte mit einer Teilmenge der vorhandenen Feldkennzeichnungen oder einer leeren Liste aktualisieren. Stellen Sie eine PUT-Anfrage an die Dataset Service-API, um zuvor angewendete Kennzeichnungen zu aktualisieren oder zu entfernen.

API-Format

PUT /datasets/{DATASET_ID}/labels

Anfrage

Der folgende Datensatz, auf den der PUT-Vorgang angewendet wird, enthielt „C1 optionalLabel“ für das Feld „properties/person/properties/address“ und „C1, C2 optionalLabels“ für das Feld „/properties/person/properties/name/properties/fullName“. Nach dem PUT-Vorgang weist das erste Feld keine Kennzeichnung auf (C1-Kennzeichnung wurde entfernt) und das zweite Feld nur die C1-Kennzeichnung (C2-Kennzeichnung wurde entfernt)

Im folgenden Beispielszenario wird eine PUT-Anfrage verwendet, um zu einzelnen Feldern hinzugefügte Kennzeichnungen zu entfernen. Vor Stellen der Anfrage wurden auf das Feld fullName die Kennzeichnungen C1 und C2 angewendet und auf das Feld address war bereits die Kennzeichnung C1 angewandt worden. Die PUT-Anfrage überschreibt mithilfe des Parameters optionalLabels.labels vorhandene Kennzeichnungen C1, C2 des Felds fullName mit der Kennzeichnung C1. Mit der Anfrage wird ebenfalls die Kennzeichnung C1 des Felds address mit einem leeren Satz von Feldkennzeichnungen überschrieben.

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

Antwort

Eine erfolgreiche Antwort gibt den aktualisierten Satz von Kennzeichnungen für den Datensatz zurück.

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

Nächste Schritte

Durch das Lesen dieses Dokuments haben Sie gelernt, wie Sie mit der Dataset Service-API Datennutzungskennzeichnungen für Datensätze und Felder verwalten können. Sie können jetzt Datennutzungsrichtlinien und Zugriffssteuerungsrichtlinien basierend auf den von Ihnen angewendeten Kennzeichnungen definieren.

Weitere Informationen zum Verwalten von Datensätzen in Experience Platform finden Sie unter Datensätze – Übersicht.