Verwalten von Datenverwendungsbeschriftungen für Datasets mithilfe von APIs

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

In diesem Dokument wird beschrieben, wie Sie Beschriftungen für Datasets und Felder mit dem Dataset Service APIOperator verwalten. Anweisungen zum Verwalten von Datenverwendungsbeschriftungen selbst mithilfe von API-Aufrufen finden Sie in der Beschreibungen-Endpunktanleitung 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 Handbuch für den Katalogentwickler beschrieben sind, um die erforderlichen Anmeldeinformationen für Aufrufe von 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 zur Auflistung von Katalogobjekten die IDs der vorhandenen Datensätze.

Suchen von Beschriftungen für einen Datensatz

Sie können die Datenverwendungsbeschriftungen nachschlagen, die auf einen vorhandenen Datensatz angewendet wurden, indem Sie eine GET an die Dataset Service API anfordern.

API-Format

GET /datasets/{DATASET_ID}/labels
Parameter Beschreibung
{DATASET_ID} Der eindeutige id Wert des Datensatzes, dessen Beschriftungen 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 Datenverwendungsbeschriftungen 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 Datenverwendungsbeschriftungen, die auf den Datensatz angewendet wurden.
optionalLabels Eine Liste einzelner Felder im Datensatz, auf die Datenverwendungsbeschriftungen angewendet wurden.

Anwenden von Beschriftungen auf einen Datensatz

Sie können einen Satz von Bezeichnungen für ein Dataset erstellen, indem Sie sie in der Nutzlast einer POST oder einer PUT-Anforderung 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 Beschriftungen erstellen.

Anfrage

Mit der folgenden PUT-Anforderung werden die vorhandenen Bezeichnungen für einen Datensatz sowie ein bestimmtes Feld in diesem Datensatz aktualisiert. Die in der Payload bereitgestellten Felder entsprechen den Feldern, die für eine Anforderung der POST erforderlich sind.

WICHTIG

Bei PUT-Anfragen an den If-Match /datasets/{DATASET_ID}/labels Endpunkt muss eine gültige Kopfzeile angegeben werden. Weitere Informationen zur Verwendung der erforderlichen Kopfzeile finden Sie im Anhang .

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 Datenverwendungsbeschriftungen, 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:

option: Ein 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 Inhaltstyp 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 Datenverwendungsbeschriftungen, die Sie dem Feld hinzufügen möchten.

Antwort

Eine erfolgreiche Antwort gibt die Beschriftungen zurück, die dem Datensatz hinzugefügt wurden.

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

Entfernen von Bezeichnungen aus einem Datensatz

Sie können die auf einen Datensatz angewendeten Beschriftungen entfernen, indem Sie eine DELETE-Anforderung an die Dataset Service API senden.

API-Format

DELETE /datasets/{DATASET_ID}/labels
Parameter Beschreibung
{DATASET_ID} Der eindeutige id Wert des Datensatzes, dessen Beschriftungen Sie entfernen möchten.

Anfrage

Die folgende Anforderung entfernt die Beschriftungen für den Datensatz, der im Pfad angegeben ist.

WICHTIG

Eine gültige If-Match Kopfzeile muss bereitgestellt werden, wenn DELETE-Anforderungen an den /datasets/{DATASET_ID}/labels Endpunkt gesendet werden. Weitere Informationen zur Verwendung der erforderlichen Kopfzeile finden Sie im Anhang .

curl -X DELETE \
  '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 'If-Match: 8f00d38e-0000-0200-0000-5ef4fc6d0000'

Antwort

Ein erfolgreicher HTTP-Status 200 (OK), der angibt, dass die Beschriftungen entfernt wurden. Sie können die vorhandenen Bezeichnungen für den Datensatz in einem separaten Aufruf nachschlagen, um dies zu bestätigen.

Nächste Schritte

Durch Lesen dieses Dokuments haben Sie gelernt, wie Sie mit der Dataset Service API Datenverwendungsbeschriftungen für Datensätze und Felder verwalten können.

Nachdem Sie Datenverwendungsbeschriftungen auf der Dataset- und Feldebene hinzugefügt haben, können Sie beginnen, Daten zu erfassen Experience Platform. Weitere Informationen erhalten Sie im Beginn in der Datenerhebungsdokumentation.

Sie können jetzt auch Datenverwendungsrichtlinien auf Basis der von Ihnen angewendeten Beschriftungen definieren. Weitere Informationen finden Sie in der Übersicht über die Datenverwendungsrichtlinien.

Weitere Informationen zum Verwalten von Datensätzen in Experience Platformfinden Sie in der Übersicht über Datensätze.

Anhang

Der folgende Abschnitt enthält weitere Informationen zum Arbeiten mit Beschriftungen mithilfe der DataSet-Dienst-API.

If-Match-Kopfzeile

Bei API-Aufrufen, die die vorhandenen Bezeichnungen eines Datensatzes (PUT und DELETE) aktualisieren, muss eine If-Match Kopfzeile mit der aktuellen Version der Entität für die Datenbeschriftung im DataSet-Dienst eingefügt werden. Um Datenkollisionen zu vermeiden, aktualisiert der Dienst die Datensatzentität nur, wenn die enthaltene If-Match Zeichenfolge mit dem neuesten vom System für diesen Datensatz generierten Version-Tag übereinstimmt.

Hinweis

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

Um die neueste Version der Entität für die Datenbeschriftung abzurufen, stellen Sie eine GET-Anforderung an den /datasets/{DATASET_ID}/labels Endpunkt. Der aktuelle Wert wird in der Antwort unter einer etag Kopfzeile zurückgegeben. Beim Aktualisieren vorhandener Datensatzbeschriftungen empfiehlt es sich, zunächst eine Suchanfrage für den Datensatz durchzuführen, um den neuesten etag Wert abzurufen, bevor dieser Wert in der If-Match Kopfzeile Ihrer nachfolgenden PUT- oder DELETE-Anforderung verwendet wird.

Auf dieser Seite