Verwalten von Datennutzungs-Labels für Datensätze mithilfe von APIs

Mit Dataset Service API können Sie Nutzungs-Labels 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 Labels für Datensätze und Felder mit der Dataset Service API verwalten. Anweisungen zum Verwalten von Datennutzungs-Labels selbst mithilfe von API-Aufrufen finden Sie im Handbuch zu Endpunkt-Labels 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 Anmeldedaten für Aufrufe an Experience 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 Labels für einen Datensatz look-up

Sie können die Datennutzungs-Labels 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 Datennutzungs-Labels 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 Labels auf einen Datensatz apply

Sie können einen Satz von Labels 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 Labels 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 einem C1-Label 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 Labels eines Datensatzes aktualisieren (PUT), muss eine If-Match-Kopfzeile eingefügt werden, die die aktuelle Version der Entität für das Datensatz-Label 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 Datensatz-Label-Entitä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 Datensatz-Labels 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 Labels 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 Labels 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 Labels 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 kein Label 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 Labels zu entfernen. Vor Stellen der Anfrage wurden auf das Feld fullName die Labels 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 Labels 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 Labels 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 Datennutzungs-Labels für Datensätze und Felder verwalten können. Sie können jetzt Datennutzungsrichtlinien und Zugriffssteuerungsrichtlinien basierend auf den von Ihnen angewendeten Labels definieren.

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