Bearbeiten von Zielverbindungen mithilfe der Flow Service-API

In diesem Tutorial werden die Schritte zum Bearbeiten verschiedener Komponenten einer Zielverbindung beschrieben. Erfahren Sie, wie Sie Authentifizierungsdaten, den Exportspeicherort und mehr mithilfe der Flow Service API aktualisieren.

Erste Schritte get-started

Für dieses Tutorial benötigen Sie eine gültige Datenfluss-ID. Wenn Sie keine gültige Datenfluss-ID haben, wählen Sie Ihr Ziel aus dem Zielkatalog und führen Sie die Schritte aus, die Herstellen einer Verbindung mit dem Ziel und Aktivieren von Daten beschrieben sind, bevor Sie dieses Tutorial ausführen.

Dieses Tutorial setzt außerdem ein Grundverständnis der folgenden Komponenten von Adobe Experience Platform voraus:

Die folgenden Abschnitte enthalten zusätzliche Informationen, die Sie benötigen, um Ihren Datenfluss mithilfe der Flow Service-API erfolgreich aktualisieren 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 gather-values-for-required-headers

Um Experience Platform-APIs aufzurufen, müssen Sie zunächst das Authentifizierungs-Tutorial abschließen. Im Rahmen des Authentifizierungs-Tutorials werden die Werte für die einzelnen erforderlichen Kopfzeilen in allen Experience Platform-API-Aufrufen bereitgestellt, wie unten dargestellt:

Alle Ressourcen in Experience Platform, einschließlich der Ressourcen, die zu Flow Service gehören, sind in bestimmten virtuellen Sandboxes isoliert. Bei allen Anfragen an Experience Platform-APIs ist eine Kopfzeile erforderlich, die den Namen der Sandbox angibt, in der der Vorgang ausgeführt werden soll:

Für alle Anfragen mit einer Payload (POST, PUT, PATCH) ist eine zusätzliche Kopfzeile vom Typ „Medien“ erforderlich:

Nachschlagen von Datenflussdetails look-up-dataflow-details

Der erste Schritt bei der Bearbeitung Ihrer Zielverbindung besteht darin, Datenflussdetails mit Ihrer Fluss-ID abzurufen. Sie können die aktuellen Details eines vorhandenen Datenflusses anzeigen, indem Sie eine GET-Anfrage an den /flows-Endpunkt stellen.

TIP

Sie können die Experience Platform-Benutzeroberfläche verwenden, um die gewünschte Datenfluss-ID eines Ziels abzurufen. Gehen Sie Ziele > Durchsuchen, wählen Sie den gewünschten Zieldatenfluss aus und suchen Sie die Ziel-ID in der rechten Leiste. Die Ziel-ID ist der Wert, den Sie als Fluss-ID im nächsten Schritt verwenden werden.

API-Format

GET /flows/{FLOW_ID}

Anfrage

Mit der folgenden Anfrage werden Informationen zu Ihrer Fluss-ID abgerufen.

curl -X GET \
    'https://platform.adobe.io/data/foundation/flowservice/flows/226fb2e1-db69-4760-b67e-9e671e05abfc' \
    -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

Bei einer erfolgreichen Antwort werden die aktuellen Details Ihres Datenflusses zurückgegeben, einschließlich der Version, der eindeutigen Kennung (id) und anderer relevanter Informationen. Am relevantesten für dieses Tutorial sind die Zielverbindungs- und Basisverbindungs-IDs, die in der folgenden Antwort hervorgehoben sind. Sie werden diese IDs in den nächsten Abschnitten verwenden, um verschiedene Komponenten der Zielverbindung zu aktualisieren.

{
   "items":[
      {
         "id":"226fb2e1-db69-4760-b67e-9e671e05abfc",
         "createdAt":"{CREATED_AT}",
         "updatedAt":"{UPDATED_BY}",
         "createdBy":"{CREATED_BY}",
         "updatedBy":"{UPDATED_BY}",
         "createdClient":"{CREATED_CLIENT}",
         "updatedClient":"{UPDATED_CLIENT}",
         "sandboxId":"{SANDBOX_ID}",
         "sandboxName":"prod",
         "imsOrgId":"{ORG_ID}",
         "name":"2021 winter campaign",
         "description":"ACME company holiday campaign for high fidelity customers",
         "flowSpec":{
            "id":"71471eba-b620-49e4-90fd-23f1fa0174d8",
            "version":"1.0"
         },
         "state":"enabled",
         "version":"\"8b0351ca-0000-0200-0000-61c4d6700000\"",
         "etag":"\"8b0351ca-0000-0200-0000-61c4d6700000\"",
         "sourceConnectionIds":[
            "5e45582a-5336-4ea1-9ec9-d0004a9f344a"
         ],
         "targetConnectionIds":[
            "8ce3dc63-3766-4220-9f61-51d2f8f14618"
         ],
         "inheritedAttributes":{
            "sourceConnections":[
               {
                  "id":"5e45582a-5336-4ea1-9ec9-d0004a9f344a",
                  "connectionSpec":{
                     "id":"8a9c3494-9708-43d7-ae3f-cda01e5030e1",
                     "version":"1.0"
                  },
                  "baseConnection":{
                     "id":"0a82f29f-b457-47f7-bb30-33856e2ae5aa",
                     "connectionSpec":{
                        "id":"8a9c3494-9708-43d7-ae3f-cda01e5030e1",
                        "version":"1.0"
                     }
                  },
                  "typeInfo":{
                     "type":"ProfileFragments",
                     "id":"ups"
                  }
               }
            ],
            "targetConnections":[
               {
                  "id":"8ce3dc63-3766-4220-9f61-51d2f8f14618",
                  "connectionSpec":{
                     "id":"0b23e41a-cb4a-4321-a78f-3b654f5d7d97",
                     "version":"1.0"
                  },
                  "baseConnection":{
                     "id":"7fbf542b-83ed-498f-8838-8fde0c4d4d69",
                     "connectionSpec":{
                        "id":"0b23e41a-cb4a-4321-a78f-3b654f5d7d97",
                        "version":"1.0"
                     }
                  }
               }
            ]
         },
         "transformations":[
            "shortened for brevity"
         ]
      }
   ]

Bearbeiten der Zielverbindungskomponenten (Speicherort und andere Komponenten) patch-target-connection

Die Komponenten einer Zielverbindung unterscheiden sich je nach Ziel. Beispielsweise können Sie für Amazon S3 Ziele den Bucket und den Pfad aktualisieren, in den Dateien exportiert werden. Für Pinterest Ziele können Sie Ihre Pinterest Advertiser ID aktualisieren und für Google Customer Match können Sie Ihre Pinterest Account ID aktualisieren.

Um Komponenten einer Zielverbindung zu aktualisieren, führen Sie eine PATCH-Anfrage an den Endpunkt /targetConnections/{TARGET_CONNECTION_ID} aus und geben Sie dabei Ihre Zielverbindungs-ID, die Version und die neuen Werte an, die Sie verwenden möchten. Denken Sie daran, dass Sie im vorherigen Schritt Ihre Zielverbindungs-ID erhalten haben, als Sie einen vorhandenen Datenfluss zu Ihrem gewünschten Ziel überprüft haben.

Im Folgenden finden Sie einige Beispiele für die Aktualisierung von Parametern in der Zielverbindungsspezifikation für verschiedene Zieltypen. Die allgemeine Regel zum Aktualisieren der Parameter für jedes Ziel lautet jedoch wie folgt:

Abrufen der Datenfluss-ID der Verbindung > Abrufen der Zielverbindungs-ID > PATCH der Zielverbindung mit aktualisierten Werten für die gewünschten Parameter.

API-Format

PATCH /targetConnections/{TARGET_CONNECTION_ID}

curl -X PATCH \
    'https://platform.adobe.io/data/foundation/flowservice/targetConnections/b2cb1407-3114-441c-87ea-2c1a3c84d0b0' \
    -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 'If-Match: "1a0037e4-0000-0200-0000-602e06f60000"' \
    -d '[
  {
    "op": "replace",
    "path": "/params",
    "value": {
      "bucketName": "newBucketName",
      "path": "updatedPath"
    }
  }
]'

{
    "id": "b2cb1407-3114-441c-87ea-2c1a3c84d0b0",
    "etag": "\"50014cc8-0000-0200-0000-6036eb720000\""
}

curl -X PATCH \
    'https://platform.adobe.io/data/foundation/flowservice/targetConnections/b2cb1407-3114-441c-87ea-2c1a3c84d0b0' \
    -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 'If-Match: "1a0037e4-0000-0200-0000-602e06f60000"' \
    -d '[
  {
    "op": "add",
    "path": "/params/appendSegmentId",
    "value": true
  }
]'

{
    "id": "b2cb1407-3114-441c-87ea-2c1a3c84d0b0",
    "etag": "\"50014cc8-0000-0200-0000-6036eb720000\""
}

curl -X PATCH \
    'https://platform.adobe.io/data/foundation/flowservice/targetConnections/b2cb1407-3114-441c-87ea-2c1a3c84d0b0' \
    -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 'If-Match: "1a0037e4-0000-0200-0000-602e06f60000"' \
    -d '[
  {
    "op": "replace",
    "path": "/params",
    "value": {
      "advertiser_id": "1234567890"
    }
  }
]'

{
    "id": "b2cb1407-3114-441c-87ea-2c1a3c84d0b0",
    "etag": "\"50014cc8-0000-0200-0000-6036eb720000\""
}

Bearbeiten von Basisverbindungskomponenten (Authentifizierungsparameter und andere Komponenten) patch-base-connection

Bearbeiten Sie die Basisverbindung, wenn Sie die Anmeldeinformationen eines Ziels aktualisieren möchten. Die Komponenten einer Basisverbindung unterscheiden sich je nach Ziel. Beispielsweise können Sie für Amazon S3 Ziele den Zugriffsschlüssel und den geheimen Schlüssel für Ihren Amazon S3 Speicherort aktualisieren.

Um Komponenten einer Basisverbindung zu aktualisieren, führen Sie eine PATCH-Anfrage an den /connections-Endpunkt durch und geben Sie dabei Ihre Basisverbindungs-ID, die Version und die neuen Werte an, die Sie verwenden möchten.

Denken Sie daran, dass Sie Ihre Basisverbindungs-ID in einem vorherigen Schritt erhalten haben, als Sie einen vorhandenen Datenfluss zu Ihrem gewünschten Ziel für die baseConnection überprüft haben.

Im Folgenden finden Sie einige Beispiele für die Aktualisierung von Parametern in der Basisverbindungsspezifikation für verschiedene Zieltypen. Die allgemeine Regel zum Aktualisieren der Parameter für jedes Ziel lautet jedoch wie folgt:

Abrufen der Datenfluss-ID der Verbindung > Abrufen der Basisverbindungs-ID > PATCH der Basisverbindung mit aktualisierten Werten für die gewünschten Parameter.

API-Format

PATCH /connections/{BASE_CONNECTION_ID}

curl -X PATCH \
    'https://platform.adobe.io/data/foundation/flowservice/targetConnections/b2cb1407-3114-441c-87ea-2c1a3c84d0b0' \
    -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 'If-Match: "1a0037e4-0000-0200-0000-602e06f60000"' \
    -d '[
  {
    "op": "add",
    "path": "/auth/params",
    "value": {
      "accessId": "exampleAccessId",
      "secretKey": "exampleSecretKey"
    }
  }
]'

{
    "id": "b2cb1407-3114-441c-87ea-2c1a3c84d0b0",
    "etag": "\"50014cc8-0000-0200-0000-6036eb720000\""
}

curl -X PATCH \
    'https://platform.adobe.io/data/foundation/flowservice/targetConnections/b2cb1407-3114-441c-87ea-2c1a3c84d0b0' \
    -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 'If-Match: "1a0037e4-0000-0200-0000-602e06f60000"' \
    -d '[
  {
    "op": "add",
    "path": "/auth/params",
    "value": {
      "connectionString": "updatedString"
    }
  }
]'

{
    "id": "b2cb1407-3114-441c-87ea-2c1a3c84d0b0",
    "etag": "\"50014cc8-0000-0200-0000-6036eb720000\""
}

Umgang mit API-Fehlern api-error-handling

Die API-Endpunkte in diesem Tutorial folgen den allgemeinen Grundsätzen von Experience Platform API-Fehlermeldungen. Weitere Informationen Interpretieren von Fehlerantworten finden Sie unterAPI-Status-Codes undFehler in der Anfragekopfzeile im Handbuch zur Fehlerbehebung bei Experience Platform .

Nächste Schritte next-steps

In diesem Tutorial haben Sie gelernt, wie Sie verschiedene Komponenten einer Zielverbindung mithilfe der Flow Service-API aktualisieren können. Weitere Informationen zu Zielen finden Sie unter Ziele - Übersicht.