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

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
Parameter Beschreibung
{DATASET_ID} Der eindeutige id-Wert des Datensatzes, dessen Kennzeichnungen Sie nachschlagen möchten.

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: {IMS_ORG}' \
  -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": "{IMS_ORG}",
    "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" ]
      }
    ]
  }
}
Eigenschaft Beschreibung
labels Eine Liste von Datennutzungsbeschriftungen, die auf den Datensatz angewendet wurden.
optionalLabels Eine Liste einzelner Felder im Datensatz, auf die Datennutzungsbeschriftungen angewendet werden bzw. wurden.

Anwenden von Kennzeichnungen auf einen Datensatz

Sie können einen Satz von Kennzeichnungen für einen Datensatz erstellen, indem Sie sie in der Payload einer POST- oder PUT-Anfrage an die Dataset Service-API bereitstellen. Wenn Sie eine dieser Methoden verwenden, werden vorhandene Beschriftungen überschrieben und durch die in der Payload bereitgestellten ersetzt.

API-Format

POST /datasets/{DATASET_ID}/labels
PUT /datasets/{DATASET_ID}/labels
Parameter Beschreibung
{DATASET_ID} Der eindeutige id-Wert des Datensatzes, für den Sie Kennzeichnungen erstellen.

Anfrage

Die folgende Beispielanfrage aktualisiert die vorhandenen PUT-Bezeichnungen für einen Datensatz sowie ein bestimmtes Feld in diesem Datensatz. Die in der Payload bereitgestellten Felder entsprechen den Feldern, die für eine POST-Anfrage erforderlich wären.

Wenn Sie API-Aufrufe durchführen, die die vorhandenen Bezeichnungen eines Datensatzes (PUT) aktualisieren, wird ein If-Match -Kopfzeile, die die aktuelle Version der Entität für die Datensatzbeschriftung im Datensatzdienst anzeigt, muss enthalten sein. 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.

HINWEIS

Wenn für den betreffenden Datensatz derzeit keine Kennzeichnungen vorhanden sind, können neue Kennzeichnungen nur über eine POST-Anfrage hinzugefügt werden, wofür keine If-Match-Kopfzeile erforderlich ist. Nachdem Kennzeichnungen zu einem Datensatz hinzugefügt wurden, wird ihm ein etag-Wert zugewiesen, mit dem die Kennzeichnungen zu einem späteren Zeitpunkt aktualisiert oder entfernt werden können.

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 Datensatzbezeichnungen empfiehlt es sich, zunächst eine Suchanfrage für den Datensatz durchzuführen, um den neuesten Datensatz abzurufen etag -Wert, bevor Sie diesen Wert in If-Match -Kopfzeile Ihrer nachfolgenden PUT-Anfrage.

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: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -H 'Content-Type: application/json' \
  -H 'If-Match: 8f00d38e-0000-0200-0000-5ef4fc6d0000' \
  -d '{
        "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" ]
          }
        ]
      }'
Eigenschaft Beschreibung
labels Eine Liste von Datennutzungsbeschriftungen, die Sie dem Datensatz hinzufügen möchten.
optionalLabels Eine Liste der einzelnen Felder im Datensatz, denen Sie Beschriftungen hinzufügen möchten. Jedes Element in diesem Array muss die folgenden Eigenschaften aufweisen:

optionEin Objekt, das die Experience Data Model (XDM)-Attribute des Felds enthält. Die folgenden drei Eigenschaften sind erforderlich:
  • id: Der URI-$id-Wert des Schemas, das dem Feld zugeordnet ist.
  • contentType: Der Content-Typ und die Versionsnummer des Schemas. Dies sollte in Form eines der gültigen Accept-Header für eine XDM-Suchanfrage erfolgen.
  • schemaPath: Der Pfad zum Feld im Schema des Datensatzes.
labels: Eine Liste von Datennutzungskennzeichnungen, die Sie zu dem Feld hinzufügen möchten.

Antwort

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

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

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.

Nachdem Sie Datennutzungskennzeichnungen auf der Datensatz- und Feldebene hinzugefügt haben, können Sie beginnen, Daten in Experience Platform aufzunehmen. Um mehr darüber zu erfahren, lesen Sie zunächst die Dokumentation zur Datenaufnahme.

Sie können jetzt auch Datennutzungsrichtlinien auf Basis der von Ihnen angewendeten Kennzeichnungen definieren. Weitere Informationen finden Sie unter Datennutzungsrichtlinien – Übersicht.

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

Auf dieser Seite