Anzeigen von Datensatzdaten mit Data Access API
In diesem Schritt-für-Schritt-Tutorial erfahren Sie, wie Sie in einem Datensatz gespeicherte Daten mithilfe des Data Access API in Adobe Experience Platform. In diesem Dokument werden einige der einzigartigen Funktionen der Data Access API, z. B. Paging und teilweise Downloads.
Erste Schritte
Dieses Tutorial setzt ein grundlegendes Verständnis dafür voraus, wie man einen Datensatz erstellt und füllt. Siehe Tutorial zur Erstellung von Datensätzen für weitere Informationen.
Die folgenden Abschnitte enthalten zusätzliche Informationen, die Sie benötigen, um die Platform-APIs erfolgreich aufrufen zu können.
Lesen von Beispiel-API-Aufrufen reading-sample-api-calls
In diesem Tutorial wird anhand von Beispielen für API-Aufrufe die korrekte Formatierung von Anfragen aufgezeigt. Dazu gehören Pfade, erforderliche Kopfzeilen und ordnungsgemäß formatierte Anfrage-Payloads. Außerdem wird ein Beispiel für eine von der API im JSON-Format zurückgegebene Antwort bereitgestellt. Informationen zu den Konventionen, die in der Dokumentation für Beispiel-API-Aufrufe verwendet werden, finden Sie im Abschnitt zum Lesen von Beispiel-API-Aufrufen im Handbuch zur Fehlerbehebung für Experience Platform
Sammeln von Werten für erforderliche Kopfzeilen
So rufen Sie an Platform APIs verwenden, müssen Sie zunächst die Authentifizierungs-Tutorial. Durch Abschluss des Authentifizierungs-Tutorials werden die Werte für die einzelnen erforderlichen Header in allen Experience Platform-API-Aufrufen bereitgestellt, wie unten dargestellt:
- Authorization: Bearer
{ACCESS_TOKEN}
- x-api-key:
{API_KEY}
- x-gw-ims-org-id:
{ORG_ID}
Alle Ressourcen in Experience Platform sind auf bestimmte virtuelle Sandboxes beschränkt. Alle Anfragen an Platform APIs erfordern eine Kopfzeile, die den Namen der Sandbox angibt, in der der Vorgang ausgeführt wird:
- x-sandbox-name:
{SANDBOX_NAME}
Bei allen Anfragen mit einer Payload (POST, PUT, PATCH) ist eine zusätzliche Kopfzeile erforderlich:
- Content-Type: application/json
Sequenzdiagramm
Dieses Tutorial folgt den Schritten, die im unten stehenden Sequenzdiagramm beschrieben sind und die die Kernfunktionalität der Data Access API.
Um Informationen zu Batches und Dateien abzurufen, verwenden Sie die Catalog API. Verwenden Sie zum Zugreifen auf und Herunterladen dieser Dateien über HTTP als vollständige oder teilweise Downloads je nach Größe der Datei die Data Access API.
Suchen Sie die Daten
Bevor Sie mit der Verwendung des Data Access API müssen Sie den Speicherort der Daten identifizieren, auf die Sie zugreifen möchten. Im Catalog API gibt es zwei Endpunkte, mit denen Sie die Metadaten eines Unternehmens durchsuchen und die Kennung eines Batches oder einer Datei abrufen können, auf den/die Sie zugreifen möchten:
GET /batches
: Gibt eine Liste der Batches unter Ihrer Organisation zurück.GET /dataSetFiles
: Gibt eine Liste der Dateien unter Ihrer Organisation zurück.
Für eine umfassende Liste von Endpunkten im Catalog API, siehe API-Referenz.
Abrufen einer Liste von Batches unter Ihrer Organisation
Verwenden der Catalog API können Sie eine Liste von Batches unter Ihrem Unternehmen zurückgeben:
API-Format
GET /batches
Anfrage
curl -X GET 'https://platform.adobe.io/data/foundation/catalog/batches/' \
-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
Die Antwort enthält ein -Objekt, das alle Batches auflistet, die mit der Organisation verbunden sind, wobei jeder Wert der obersten Ebene einen Batch darstellt. Die einzelnen Batch-Objekte enthalten die Details für diesen Batch. Die folgende Antwort wurde aus Platzgründen minimiert.
{
"{BATCH_ID_1}": {
"imsOrg": "{ORG_ID}",
"created": 1516640135526,
"createdClient": "{CREATED_CLIENT}",
"createdUser": "{CREATED_BY}",
"updatedUser": "{CREATED_BY}",
"updated": 1516640135526,
"status": "processing",
"version": "1.0.0",
"availableDates": {}
},
"{BATCH_ID_2}": {
...
}
}
Filtern der Batch-Liste filter-batches-list
Filter sind oft erforderlich, um einen bestimmten Batch zu finden, um relevante Daten für einen bestimmten Anwendungsfall abzurufen. Parameter können zu einer GET /batches
Anfrage zum Filtern der zurückgegebenen Antwort. Die nachstehende Anfrage gibt alle Batches zurück, die nach einem bestimmten Zeitpunkt innerhalb eines bestimmten Datensatzes erstellt wurden und nach dem Zeitpunkt der Erstellung sortiert wurden.
API-Format
GET /batches?createdAfter={START_TIMESTAMP}&dataSet={DATASET_ID}&sort={SORT_BY}
{START_TIMESTAMP}
{DATASET_ID}
{SORT_BY}
desc:created
sortiert die Objekte nach Erstellungsdatum in absteigender Reihenfolge.Anfrage
curl -X GET 'https://platform.adobe.io/data/foundation/catalog/batches?createdAfter=1521053542579&dataSet=5cd9146b21dae914b71f654f&orderBy=desc:created' \
-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
{ "{BATCH_ID_3}": {
"imsOrg": "{ORG_ID}",
"relatedObjects": [
{
"id": "5c01a91863540f14cd3d0439",
"type": "dataSet"
},
{
"id": "00998255b4a148a2bfd4804c2f327324",
"type": "batch"
}
],
"status": "success",
"metrics": {
"recordsFailed": 0,
"recordsWritten": 2,
"startTime": 1550791835809,
"endTime": 1550791994636
},
"errors": [],
"created": 1550791457173,
"createdClient": "{CLIENT_CREATED}",
"createdUser": "{CREATED_BY}",
"updatedUser": "{CREATED_BY}",
"updated": 1550792060301,
"version": "1.0.116"
},
"{BATCH_ID_4}": {
"imsOrg": "{ORG_ID}",
"status": "success",
"relatedObjects": [
{
"type": "batch",
"id": "00aff31a9ae84a169d69b886cc63c063"
},
{
"type": "dataSet",
"id": "5bfde8c5905c5a000082857d"
}
],
"metrics": {
"startTime": 1544571333876,
"endTime": 1544571358291,
"recordsRead": 4,
"recordsWritten": 4
},
"errors": [],
"created": 1544571077325,
"createdClient": "{CLIENT_CREATED}",
"createdUser": "{CREATED_BY}",
"updatedUser": "{CREATED_BY}",
"updated": 1544571368776,
"version": "1.0.3"
}
}
Eine vollständige Liste der Parameter und Filter finden Sie im Referenz zur Catalog API.
Liste aller Dateien abrufen, die zu einem bestimmten Batch gehören
Nachdem Sie nun über die Kennung des Batches verfügen, auf den Sie zugreifen möchten, können Sie die Data Access API zum Abrufen einer Liste von Dateien, die zu diesem Batch gehören.
API-Format
GET /batches/{BATCH_ID}/files
{BATCH_ID}
Anfrage
curl -X GET 'https://platform.adobe.io/data/foundation/export/batches/5c6f332168966814cd81d3d3/files' \
-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
{
"data": [
{
"dataSetFileId": "8dcedb36-1cb2-4496-9a38-7b2041114b56-1",
"dataSetViewId": "5cc6a9b60d4a5914b7940a7f",
"version": "1.0.0",
"created": "1558522305708",
"updated": "1558522305708",
"isValid": false,
"_links": {
"self": {
"href": "https://platform.adobe.io:443/data/foundation/export/files/8dcedb36-1cb2-4496-9a38-7b2041114b56-1"
}
}
}
],
"_page": {
"limit": 100,
"count": 1
}
}
}
data._links.self.href
Die Antwort enthält ein Daten-Array, das alle Dateien innerhalb des angegebenen Batches auflistet. Die Dateien werden durch ihre Datei-ID referenziert, die sich unter der dataSetFileId
-Feld.
Zugriff auf eine Datei mit einer Datei-ID access-file-with-file-id
Sobald Sie über eine eindeutige Datei-ID verfügen, können Sie die Data Access API für den Zugriff auf spezifische Details zur Datei, einschließlich Name, Größe in Byte und Link zum Herunterladen.
API-Format
GET /files/{FILE_ID}
{FILE_ID}
Anfrage
curl -X GET 'https://platform.adobe.io/data/foundation/export/files/8dcedb36-1cb2-4496-9a38-7b2041114b56-1' \
-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}'
Je nachdem, ob die Datei-ID auf eine einzelne Datei oder ein Verzeichnis verweist, kann das zurückgegebene Datenarray einen einzelnen Eintrag oder eine Liste von Dateien enthalten, die zu diesem Verzeichnis gehören. Jedes Dateielement enthält Details wie den Namen der Datei, die Größe in Byte und einen Link zum Herunterladen der Datei.
1. Fall: Datei-ID verweist auf eine einzelne Datei
Antwort
{
"data": [
{
"name": "{FILE_NAME}.parquet",
"length": "249058",
"_links": {
"self": {
"href": "https://platform.adobe.io/data/foundation/export/files/{FILE_ID_1}?path={FILE_NAME_1}.parquet"
}
}
}
],
"_page": {
"limit": 100,
"count": 1
}
}
{FILE_NAME}.parquet
_links.self.href
2. Fall: Datei-ID verweist auf ein Verzeichnis
Antwort
{
"data": [
{
"dataSetFileId": "{FILE_ID_2}",
"dataSetViewId": "460590b01ba38afd1",
"version": "1.0.0",
"created": "150151267347",
"updated": "150151267347",
"isValid": true,
"_links": {
"self": {
"href": "https://platform.adobe.io/data/foundation/export/files/{FILE_ID_2}"
}
}
},
{
"dataSetFileId": "{FILE_ID_3}",
"dataSetViewId": "460590b01ba38afd1",
"version": "1.0.0",
"created": "150151267685",
"updated": "150151267685",
"isValid": true,
"_links": {
"self": {
"href": "https://platform.adobe.io/data/foundation/export/files/{FILE_ID_3}"
}
}
}
],
"_page": {
"limit": 100,
"count": 2
}
}
data._links.self.href
Diese Antwort gibt einen Ordner mit zwei separaten Dateien mit IDs zurück {FILE_ID_2}
und {FILE_ID_3}
. In diesem Szenario müssen Sie der URL jeder Datei folgen, um auf die Datei zuzugreifen.
Abrufen der Metadaten einer Datei
Sie können die Metadaten einer Datei abrufen, indem Sie eine HEAD-Anfrage stellen. Dadurch werden die Metadaten-Header der Datei zurückgegeben, einschließlich der Größe in Byte und des Dateiformats.
API-Format
HEAD /files/{FILE_ID}?path={FILE_NAME}
{FILE_ID}
{FILE_NAME}
Anfrage
curl -I 'https://platform.adobe.io/data/foundation/export/files/8dcedb36-1cb2-4496-9a38-7b2041114b56-1?path=profiles.parquet' \
-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
Die Antwortheader enthalten die Metadaten der abgefragten Datei, darunter:
Content-Length
: Gibt die Größe der Payload in Byte anContent-Type
: Gibt den Dateityp an.
Dateiinhalt aufrufen
Sie können auch über die Data Access API.
API-Format
GET /files/{FILE_ID}?path={FILE_NAME}
{FILE_ID}
{FILE_NAME}
Anfrage
curl -X GET 'https://platform.adobe.io/data/foundation/export/files/8dcedb36-1cb2-4496-9a38-7b2041114b56-1?path=profiles.parquet' \
-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 den Inhalt der Datei zurück.
Herunterladen von partiellen Inhalten einer Datei download-partial-file-contents
Um einen bestimmten Byte-Bereich aus einer Datei herunterzuladen, geben Sie eine Bereichsüberschrift während einer GET /files/{FILE_ID}
Anfrage an die Data Access API. Wenn der Bereich nicht angegeben ist, lädt die API standardmäßig die gesamte Datei herunter.
Das HEAD-Beispiel im vorheriger Abschnitt gibt die Größe einer bestimmten Datei in Byte an.
API-Format
GET /files/{FILE_ID}?path={FILE_NAME}
{FILE_ID}
{FILE_NAME}
Anfrage
curl -X GET 'https://platform.adobe.io/data/foundation/export/files/8dcedb36-1cb2-4496-9a38-7b2041114b56-1?path=profiles.parquet' \
-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 'Range: bytes=0-99'
Range: bytes=0-99
Antwort
Der Antworttext enthält die ersten 100 Byte der Datei (wie durch die "Bereich"-Kopfzeile in der Anfrage angegeben) zusammen mit dem HTTP-Status 206 (Teilinhalt). Die Antwort enthält auch die folgenden Kopfzeilen:
- Content-Length: 100 (die Anzahl der zurückgegebenen Bytes)
- Inhaltstyp: application/parquet (eine Parquet-Datei wurde angefordert, daher ist der Typ des Antwortinhalts
parquet
) - Inhaltsbereich: Byte 0-99/249058 (der angeforderte Bereich (0-99) von der Gesamtzahl der Byte (249058))
API-Antwort-Paginierung konfigurieren configure-response-pagination
Antworten innerhalb der Data Access API wird paginiert. Standardmäßig beträgt die maximale Anzahl von Einträgen pro Seite 100. Sie können das Standardverhalten mit Paging-Parametern ändern.
limit
: Mit dem Parameter "limit" können Sie die Anzahl der Einträge pro Seite entsprechend Ihren Anforderungen angeben.start
: Der Versatz kann durch den Abfrageparameter "start"festgelegt werden.&
: Sie können ein kaufmännisches Und-Zeichen verwenden, um mehrere Parameter in einem einzelnen Aufruf zu kombinieren.
API-Format
GET /batches/{BATCH_ID}/files?start={OFFSET}
GET /batches/{BATCH_ID}/files?limit={LIMIT}
GET /batches/{BATCH_ID}/files?start={OFFSET}&limit={LIMIT}
{BATCH_ID}
{OFFSET}
{LIMIT}
Anfrage
curl -X GET 'https://platform.adobe.io/data/foundation/export/batches/5c102cac7c7ebc14cd6b098e/files?start=0&limit=1' \
-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:
Die Antwort enthält eine "data"
Array mit einem einzelnen Element, wie durch den Anforderungsparameter angegeben limit=1
. Dieses Element ist ein Objekt, das die Details der ersten verfügbaren Datei enthält, wie in der start=0
-Parameter in der Anfrage (denken Sie daran, dass bei einer Nummerierung mit 0 das erste Element "0"ist).
Die _links.next.href
-Wert den Link zur nächsten Antwortseite enthält, auf der Sie sehen können, dass die Variable start
-Parameter wurde erweitert auf start=1
.
{
"data": [
{
"dataSetFileId": "{FILE_ID_1}",
"dataSetViewId": "5a9f264c2aa0cf01da4d82fa",
"version": "1.0.0",
"created": "1521053793635",
"updated": "1521053793635",
"isValid": false,
"_links": {
"self": {
"href": "https://platform.adobe.io/data/foundation/export/files/{FILE_ID_1}"
}
}
}
],
"_page": {
"limit": 1,
"count": 6
},
"_links": {
"next": {
"href": "https://platform.adobe.io/data/foundation/export/batches/5c102cac7c7ebc14cd6b098e/files?start=1&limit=1"
},
"page": {
"href": "https://platform.adobe.io/data/foundation/export/batches/5c102cac7c7ebc14cd6b098e/files?start=0&limit=1",
"templated": true
}
}
}