Erstellen und Testen einer Nachrichtenumwandlungsvorlage

Letzte Aktualisierung: 2023-09-08
  • Erstellt für:
  • Developer
    User
    Admin
    Leader

Übersicht

Als Teil des Destination SDK bietet Adobe Entwickler-Tools, mit denen Sie Ihr Ziel konfigurieren und testen können. Auf dieser Seite wird beschrieben, wie Sie eine Nachrichtenumwandlungsvorlage erstellen und testen. Informationen zum Testen Ihres Ziels finden Sie unter Testen der Zielkonfiguration.

Zum Erstellen und Testen einer Nachrichtenumwandlungsvorlage zwischen dem Zielschema in Adobe Experience Platform und dem von Ihrem Ziel unterstützten Nachrichtenformat können Sie das Authoring-Tool für Vorlagen verwenden, das weiter unten beschrieben wird. Weitere Informationen zur Datenumwandlung zwischen Quell- und Zielschema finden Sie im Dokument zu Nachrichtenformaten.

Die folgende Abbildung zeigt, wie das Erstellen und Testen einer Nachrichtenumwandlungsvorlage in den Zielkonfigurations-Workflow in Destination SDK passt:

Abbildung, wo der Schritt „Vorlage erstellen“ in den Zielkonfigurations-Workflow passt

Gründe für das Erstellen und Testen einer Nachrichtenumwandlungsvorlage

Einer der ersten Schritte bei der Erstellung Ihres Ziels in Destination SDK besteht darin, darüber nachzudenken, wie das Datenformat für Zielgruppenzugehörigkeit, Identitäten und Profilattribute transformiert wird, wenn die Daten von Adobe Experience Plattform in Ihr Ziel exportiert werden. Informationen zur Transformation zwischen dem Adobe-XDM-Schema und Ihrem Zielschema finden Sie in Dokument zu Nachrichtenformaten.

Damit die Transformation erfolgreich ist, müssen Sie eine Umwandlungsvorlage wie im folgenden Beispiel angeben: Erstellen einer Vorlage zum Senden von Segmenten, Identitäten und Profilattributen.

Adobe bietet ein Vorlagenwerkzeug, mit dem Sie die Nachrichtenvorlage erstellen und testen können, mit der Daten aus dem Adobe-XDM-Format in das von Ihrem Ziel unterstützte Format umgewandelt werden. Das Tool verfügt über zwei API-Endpunkte, die Sie verwenden können:

  • Verwenden Sie die Beispiel-Vorlagen-API um eine Beispielvorlage zu erhalten.
  • Verwenden Sie die Render-Vorlagen-API, um die Beispielvorlage zu rendern, damit Sie das Ergebnis mit dem erwarteten Datenformat Ihres Ziels vergleichen können. Nachdem Sie die exportierten Daten mit dem von Ihrem Ziel erwarteten Datenformat verglichen haben, können Sie die Vorlage bearbeiten. Auf diese Weise entsprechen die exportierten Daten, die Sie generieren, dem von Ihrem Ziel erwarteten Datenformat.

Schritte, die vor der Erstellung der Vorlage abzuschließen sind

Bevor Sie bereit sind, die Vorlage zu erstellen, führen Sie die folgenden Schritte aus:

  1. Erstellen Sie eine Ziel-Server-Konfiguration. Die Vorlage, die Sie generieren, unterscheidet sich je nach dem Wert, den Sie für den Parameter maxUsersPerRequest angeben.
    • Wenn ein API-Aufruf an das Ziel ein einzelnes Profil sowie die zugehörigen Segmentqualifikationen, Identitäten und Profilattribute enthalten soll, muss maxUsersPerRequest=1 verwendet werden.
    • Wenn ein API-Aufruf an das Ziel mehrere Profile sowie deren Segmentqualifikationen, Identitäten und Profilattribute enthalten soll, muss maxUsersPerRequest mit einem Wert größer als 1 verwendet werden.
  2. Erstellen Sie eine Zielkonfiguration und fügen Sie die ID der Ziel-Server-Konfiguration in destinationDelivery.destinationServerId hinzu.
  3. Rufen Sie die ID der Zielkonfiguration ab, die Sie gerade erstellt haben, sodass Sie sie im Tool zur Vorlagenerstellung verwenden können.
  4. Sie müssen verstehen, welche Funktionen und Filter Sie in der Nachrichtenumwandlungsvorlage verwenden können.

Verwendung der Beispielvorlagen-API und der Render-Vorlagen-API zum Erstellen einer Vorlage für Ihr Ziel

TIPP

Bevor Sie die Nachrichtenumwandlungsvorlage erstellen und bearbeiten, können Sie zunächst den Endpunkt der Render-Vorlagen-API mit einer einfachen Vorlage aufrufen, die Ihre Rohprofile exportiert, ohne Umwandlungen vorzunehmen. Die Syntax für die einfache Vorlage lautet:
"template": "{% for profile in input.profiles %}{{profile|raw}}{% endfor %}}"

Der Prozess zum Abrufen und Testen der Vorlage ist iterativ. Wiederholen Sie die folgenden Schritte, bis die exportierten Profile dem erwarteten Datenformat Ihres Ziels entsprechen.

  1. Als erstes rufen Sie eine Beispielvorlage ab.
  2. Verwenden Sie die Beispielvorlage als Ausgangspunkt, um einen eigenen Entwurf zu erstellen.
  3. Rufen Sie den Endpunkt der Render-Vorlagen-API mit Ihrer eigenen Vorlage auf. Adobe generiert Beispielprofile basierend auf Ihrem Schema und gibt das Ergebnis oder etwaige aufgetretene Fehler zurück.
  4. Vergleichen Sie die exportierten Daten mit dem von Ihrem Ziel erwarteten Datenformat. Bearbeiten Sie bei Bedarf die Vorlage.
  5. Wiederholen Sie diesen Vorgang, bis die exportierten Profile dem erwarteten Datenformat Ihres Ziels entsprechen.

Abrufen einer Beispielvorlage mit der Beispielvorlagen-API

HINWEIS

Eine vollständige API-Referenzdokumentation finden Sie unter Abrufen von Beispielvorlagen-API-Vorgängen.

Fügen Sie dem Aufruf eine Ziel-ID hinzu, wie unten dargestellt, und die Antwort gibt ein Vorlagenbeispiel zurück, das der Ziel-ID entspricht.

curl --location --request GET 'https://platform.adobe.io/data/core/activation/authoring/testing/template/sample/5114d758-ce71-43ba-b53e-e2a91d67b67f' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'x-api-key: {API_KEY}' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-gw-ims-org-id: {ORG_ID}' \
--header 'x-sandbox-name: {SANDBOX_NAME}' \

Wenn die von Ihnen angegebene Ziel-ID einer Zielkonfiguration mit Aggregation nach bestem Bemühen und maxUsersPerRequest=1 in der Aggregationsrichtlinie entspricht, gibt die Anfrage eine Beispielvorlage zurück, die der folgenden ähnelt:

{#- THIS is an example template for a single profile -#}
{#- A '-' at the beginning or end of a tag removes all whitespace on that side of the tag. -#}
{
    "identities": [
    {%- for idMapEntry in input.profile.identityMap -%}
    {%- set namespace = idMapEntry.key -%}
        {%- for identity in idMapEntry.value %}
        {
            "type": "{{ namespace }}",
            "id": "{{ identity.id }}"
        }{%- if not loop.last -%},{%- endif -%}
        {%- endfor -%}{%- if not loop.last -%},{%- endif -%}
    {% endfor %}
    ],
    "AdobeExperiencePlatformSegments": {
        "add": [
        {%- for segment in input.profile.segmentMembership.ups | added %}
            "{{ segment.key }}"{%- if not loop.last -%},{%- endif -%}
        {% endfor %}
        ],
        "remove": [
        {#- Alternative syntax for filtering audiences by status: -#}
        {% for segment in removedSegments(input.profile.segmentMembership.ups) %}
            "{{ segment.key }}"{%- if not loop.last -%},{%- endif -%}
        {% endfor %}
        ]
    }
}

Wenn die von Ihnen angegebene Ziel-ID einer Ziel-Server-Vorlage mit konfigurierbarer Aggregation oder Aggregation nach bestem Bemühen mit maxUsersPerRequest größer als 1 entspricht, gibt die Anfrage eine Beispielvorlage zurück, die der folgenden ähnelt:

{#- THIS is an example template for multiple profiles -#}
{#- A '-' at the beginning or end of a tag removes all whitespace on that side of the tag. -#}
{
    "profiles": [
    {%- for profile in input.profiles %}
        {
            "identities": [
            {%- for idMapEntry in profile.identityMap -%}
            {%- set namespace = idMapEntry.key -%}
                {%- for identity in idMapEntry.value %}
                {
                    "type": "{{ namespace }}",
                    "id": "{{ identity.id }}"
                }{%- if not loop.last -%},{%- endif -%}
                {%- endfor -%}{%- if not loop.last -%},{%- endif -%}
            {% endfor %}
            ],
            "AdobeExperiencePlatformSegments": {
                "add": [
                {%- for segment in profile.segmentMembership.ups | added %}
                    "{{ segment.key }}"{%- if not loop.last -%},{%- endif -%}
                {% endfor %}
                ],
                "remove": [
                {#- Alternative syntax for filtering audiences by status: -#}
                {% for segment in removedSegments(profile.segmentMembership.ups) %}
                    "{{ segment.key }}"{%- if not loop.last -%},{%- endif -%}
                {% endfor %}
                ]
            }
        }{%- if not loop.last -%},{%- endif -%}
    {% endfor %}
    ]
}

Escape-Zeichen für Ihre Vorlage

Bevor Sie die Vorlage zum Rendern von Profilen verwenden, die dem erwarteten Format Ihres Ziels entsprechen, müssen Sie die Vorlage mit einem Escape-Zeichen versehen, wie in der folgenden Bildschirmaufzeichnung dargestellt.

Video, das zeigt, wie eine Vorlage mithilfe eines Online-Tools zum Maskieren von Zeichen mit Escapezeichen versehen wird

Sie können ein Online-Tool zum Maskieren von Zeichen verwenden. In der obigen Demo wird die JSON Escape-Formatierung verwendet.

Render-Vorlagen-API

Nach Erstellung einer Nachrichtenumwandlungsvorlage mit der Beispielvorlagen-APIkönnen Sie die Vorlage rendern, um exportierte Daten auf dieser Basis zu generieren. Auf diese Weise können Sie überprüfen, ob die Profile, die Adobe Experience Platform in Ihr Ziel exportieren würde, dem erwarteten Format Ihres Ziels entsprechen.

Beispiele für Aufrufe, die Sie tätigen können, finden Sie in der API-Referenz:

Bearbeiten Sie die Vorlage und rufen Sie den Endpunkt der Render-Vorlagen-API auf, bis die exportierten Profile dem erwarteten Datenformat Ihres Ziels entsprechen.

Fügen Sie Ihre mit Escape-Zeichen versehene Vorlage zur Ziel-Server-Konfiguration hinzu

Wenn Sie mit der Nachrichtenumwandlungsvorlage zufrieden sind, fügen Sie sie zu Ihrer Ziel-Server-Konfigurationin httpTemplate.requestBody.value hinzu.

Auf dieser Seite