DokumentationExperience PlatformHandbuch zum Experience-Datenmodell (XDM)

CSV-Vorlage zum Schema-Konversions-API-Endpunkt

Last update: Tue Jul 16 2024 00:00:00 GMT+0000 (Coordinated Universal Time)
  • Themen:

Erstellt für:

  • Entwickler

Mit dem Endpunkt /rpc/csv2schema in der API Schema Registry können Sie automatisch ein XDM-Schema (Experience-Datenmodell) erstellen, indem Sie eine CSV-Datei als Vorlage verwenden. Mithilfe dieses Endpunkts können Sie Vorlagen erstellen, um Schemafelder per Massenimport zu importieren und die manuelle API- oder UI-Arbeit zu reduzieren.

Erste Schritte

Der Endpunkt /rpc/csv2schema ist Teil der Schema Registry API. Bevor Sie fortfahren, lesen Sie bitte das Erste Schritte-Handbuch , um Links zur zugehörigen Dokumentation zu erhalten, eine Anleitung zum Lesen der Beispiel-API-Aufrufe in diesem Dokument und wichtige Informationen zu erforderlichen Kopfzeilen, die für das erfolgreiche Aufrufen von Adobe Experience Platform-APIs benötigt werden.

Der Endpunkt /rpc/csv2schema ist Teil der Remote-Prozeduraufrufe (RPCs), die von Schema Registry unterstützt werden. Im Gegensatz zu anderen Endpunkten in der Schema Registry-API erfordern RPC-Endpunkte keine zusätzlichen Kopfzeilen wie Accept oder Content-Type und verwenden keine CONTAINER_ID. Stattdessen müssen sie den Namespace /rpc verwenden, wie in den API-Aufrufen unten dargestellt.

CSV-Dateianforderungen

Um diesen Endpunkt zu nutzen, müssen Sie zunächst eine CSV-Datei mit entsprechenden Spaltenüberschriften und entsprechenden Werten erstellen. Einige Spalten sind erforderlich, während der Rest optional ist. In der folgenden Tabelle werden diese Spalten und ihre Rolle bei der Schemaerstellung beschrieben.

CSV-Kopfzeilenposition
CSV-Headername
Erforderlich/Optional
Beschreibung
1
isIgnored
Optional
Wenn eingeschlossen und auf true gesetzt, zeigt an, dass das Feld nicht bereit zum API-Upload ist und ignoriert werden sollte.
2
isCustom
Erforderlich
Gibt an, ob das Feld ein benutzerdefiniertes Feld ist oder nicht.
3
fieldGroupId
Optional
Die ID der Feldergruppe, der ein benutzerdefiniertes Feld zugeordnet werden soll.
4
fieldGroupName
(Siehe Beschreibung)
Der Name der Feldergruppe, mit der dieses Feld verknüpft werden soll.

Optional für benutzerdefinierte Felder, die keine vorhandenen Standardfelder erweitern. Wenn das Feld leer gelassen wird, weist das System automatisch einen Namen zu.

Erforderlich für Standardfelder oder benutzerdefinierte Felder, die Standardfeldgruppen erweitern, was zur Abfrage von fieldGroupId verwendet wird.
5
fieldPath
Erforderlich
Der vollständige Pfad für die XED-Punktnotation für das Feld. Um alle Felder aus einer Standardfeldgruppe (wie unter fieldGroupName angegeben) einzuschließen, setzen Sie den Wert auf ALL.
6
displayName
Optional
Der Titel oder Anzeigename für das Feld. Kann auch ein Alias für den Titel sein, sofern vorhanden.
7
fieldDescription
Optional
Eine Beschreibung für das Feld. Kann auch ein Alias für die Beschreibung sein, sofern vorhanden.
8
dataType
(Siehe Beschreibung)
Gibt den grundlegenden Datentyp für das Feld an. Erforderlich für alle benutzerdefinierten Felder.

Wenn dataType auf object gesetzt ist, müssen entweder properties oder $ref auch für dieselbe Zeile definiert werden, aber nicht für beide.
9
isRequired
Optional
Gibt an, ob das Feld für die Datenerfassung erforderlich ist.
10
isArray
Optional
Gibt an, ob das Feld ein Array des angegebenen dataType ist.
11
isIdentity
Optional
Gibt an, ob das Feld ein Identitätsfeld ist.
12
identityNamespace
Erforderlich, wenn isIdentity wahr ist
Der Identitäts-Namespace für das Identitätsfeld.
13
isPrimaryIdentity
Optional
Gibt an, ob das Feld die primäre Identität für das Schema ist.
14
minimum
Optional
(Nur für numerische Felder) Der Mindestwert für das Feld.
15
maximum
Optional
(Nur für numerische Felder) Der Maximalwert für das Feld.
16
enum
Optional
Eine Liste der Enum-Werte für das Feld, ausgedrückt als Array (z. B. [value1,value2,value3]).
17
stringPattern
Optional
(Nur für Zeichenfolgenfelder) Ein Regex-Muster, mit dem der Zeichenfolgenwert übereinstimmen muss, um die Validierung während der Datenerfassung zu bestehen.
18
format
Optional
(Nur für Zeichenfolgenfelder) Das Format für das Zeichenfolgenfeld.
19
minLength
Optional
(Nur für Zeichenfolgenfelder) Die Mindestlänge des Zeichenfolgenfelds.
20
maxLength
Optional
(Nur für Zeichenfolgenfelder) Die maximale Länge des Zeichenfolgenfelds.
21
properties
(Siehe Beschreibung)
Erforderlich, wenn dataType auf object und $ref nicht definiert ist. Dadurch wird der Objekttext als JSON-Zeichenfolge definiert (z. B. {"myField": {"type": "string"}}).
22
$ref
(Siehe Beschreibung)
Erforderlich, wenn dataType auf object und properties nicht definiert ist. Dadurch wird der $id des referenzierten Objekts für den Objekttyp (z. B. https://ns.adobe.com/xdm/context/person) definiert.
23
comment
Optional
Wenn isIgnored auf true gesetzt ist, wird diese Spalte verwendet, um die Kopfzeileninformationen des Schemas bereitzustellen.

In der folgenden CSV-Vorlage erfahren Sie, wie Ihre CSV-Datei formatiert werden soll.

Export-Payload aus einer CSV-Datei erstellen

Nachdem Sie Ihre CSV-Vorlage eingerichtet haben, können Sie die Datei an den /rpc/csv2schema -Endpunkt senden und in eine Export-Payload konvertieren.

API-Format

POST /rpc/csv2schema

Anfrage

Die Anfrage-Payload muss Formulardaten als Format verwenden. Die erforderlichen Formularfelder sind unten dargestellt.

curl -X POST \
  https://platform.adobe.io/data/foundation/schemaregistry/rpc/csv2schema \
  -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}' \
  -F 'csv-file=@"/Users/userName/Documents/sample-csv-template.csv"' \
  -F 'schema-class-id="https://ns.adobe.com/xdm/context/profile"' \
  -F 'schema-name="Example Schema"' \
  -F 'schema-description="Example schema description."'
Eigenschaft
Beschreibung
csv-file
Der Pfad zur CSV-Vorlage, die auf Ihrem lokalen Computer gespeichert ist.
schema-class-id
Die $id der XDM class , die dieses Schema verwendet.
schema-name
Ein Anzeigename für das Schema.
schema-description
Eine Beschreibung für das Schema.

Antwort

Eine erfolgreiche Antwort gibt eine Export-Payload zurück, die aus der CSV-Datei generiert wurde. Die Payload hat die Form eines Arrays, und jedes Array-Element ist ein Objekt, das eine abhängige XDM-Komponente für das Schema darstellt. Wählen Sie den folgenden Abschnitt aus, um ein vollständiges Beispiel einer Export-Payload anzuzeigen, die aus einer CSV-Datei generiert wurde.

Beispiel für Antwort-Payload
code language-json 
[
    {
        "$id": "https://ns.adobe.com/ddgxdmint/mixins/68397e9293a6904b3006311fb46c9573a8aaad49780dd65a",
        "$schema": "http://json-schema.org/draft-06/schema#",
        "type": "object",
        "meta:xdmType": "object",
        "meta:resourceType": "mixins",
        "title": "Generated field group 68397e9293a6904b3006311fb46c9573a8aaad49780dd65a",
        "description": "Generated field group 68397e9293a6904b3006311fb46c9573a8aaad49780dd65a",
        "meta:intendedToExtend": [
            "https://ns.adobe.com/xdm/context/profile"
        ],
        "required": [
            "_ddgxdmint"
        ],
        "properties": {
            "_ddgxdmint": {
                "properties": {
                    "customField1": {
                        "type": "string",
                        "title": "my custom field1",
                        "description": "Sample custom field1"
                    },
                    "customField2": {
                        "properties": {
                            "customerField22": {
                                "type": "string",
                                "title": "my custom field22",
                                "description": "Sample custom field22"
                            }
                        },
                        "type": "object",
                        "required": [
                            "customerField22"
                        ]
                    },
                    "customField3": {
                        "type": "number",
                        "title": "my custom field3",
                        "description": "Sample custom field3",
                        "minimum": 0,
                        "maximum": 10
                    },
                    "customField4": {
                        "type": "string",
                        "title": "my custom field4",
                        "description": "Sample custom field4",
                        "enum": [
                            "one",
                            "two",
                            "three"
                        ]
                    },
                    "customField5": {
                        "type": "array",
                        "title": "my custom field5",
                        "description": "Sample custom field5",
                        "items": {
                            "type": "string"
                        }
                    },
                    "customField6": {
                        "type": "string",
                        "title": "my custom field6",
                        "description": "Sample custom field6",
                        "format": "date"
                    }
                },
                "type": "object",
                "required": [
                    "customField1",
                    "customField2"
                ]
            }
        }
    },
    {
        "$id": "https://ns.adobe.com/ddgxdmint/mixins/7d4edf1a4c2b8c97d31f9931a10618e0b7341cefc97edad6",
        "$schema": "http://json-schema.org/draft-06/schema#",
        "type": "object",
        "meta:xdmType": "object",
        "meta:resourceType": "mixins",
        "title": "SampleFieldGroup",
        "description": "Generated field group 7d4edf1a4c2b8c97d31f9931a10618e0b7341cefc97edad6",
        "meta:intendedToExtend": [
            "https://ns.adobe.com/xdm/context/profile"
        ],
        "properties": {
            "_ddgxdmint": {
                "properties": {
                    "customField7": {
                        "type": "object",
                        "title": "my custom field7",
                        "description": "Sample custom field7",
                        "properties": {
                            "myField": {
                                "type": "string"
                            }
                        }
                    },
                    "customField8": {
                        "type": "array",
                        "title": "my custom field8",
                        "description": "Sample custom field8",
                        "items": {
                            "type": "object",
                            "$ref": "https://ns.adobe.com/xdm/context/person"
                        }
                    }
                },
                "type": "object"
            }
        }
    },
    {
        "$id": "https://ns.adobe.com/ddgxdmint/mixins/6420020c79930a4c3aa7c9fd03b218e0e85c9a7d9990ecf",
        "$schema": "http://json-schema.org/draft-06/schema#",
        "type": "object",
        "meta:xdmType": "object",
        "meta:resourceType": "mixins",
        "title": "Demographic Details:Generated field group 6420020c79930a4c3aa7c9fd03b218e0e85c9a7d9990ecf",
        "description": "Generated field group 6420020c79930a4c3aa7c9fd03b218e0e85c9a7d9990ecf",
        "meta:intendedToExtend": [
            "https://ns.adobe.com/xdm/context/profile"
        ],
        "meta:extends": [
            "https://ns.adobe.com/xdm/context/profile-person-details"
        ],
        "allOf": [
            {
                "properties": {
                    "person": {
                        "properties": {
                            "name": {
                                "properties": {
                                    "_ddgxdmint": {
                                        "properties": {
                                            "nickName": {
                                                "type": "string"
                                            }
                                        },
                                        "type": "object",
                                        "required": [
                                            "nickName"
                                        ]
                                    }
                                },
                                "type": "object",
                                "required": [
                                    "_ddgxdmint"
                                ]
                            }
                        },
                        "type": "object",
                        "required": [
                            "name"
                        ]
                    }
                },
                "required": [
                    "person"
                ]
            },
            {
                "$ref": "https://ns.adobe.com/xdm/context/profile-person-details"
            }
        ]
    },
    {
        "$id": "https://ns.adobe.com/ddgxdmint/mixins/39e6bb291e5b9072878c5c80c0ff5a325df79385ed10d241",
        "$schema": "http://json-schema.org/draft-06/schema#",
        "type": "object",
        "meta:xdmType": "object",
        "meta:resourceType": "mixins",
        "title": "Loyalty Details:Generated field group 39e6bb291e5b9072878c5c80c0ff5a325df79385ed10d241",
        "description": "Generated field group 39e6bb291e5b9072878c5c80c0ff5a325df79385ed10d241",
        "meta:intendedToExtend": [
            "https://ns.adobe.com/xdm/context/profile"
        ],
        "meta:extends": [
            "https://ns.adobe.com/xdm/mixins/profile/profile-loyalty-details"
        ],
        "allOf": [
            {
                "properties": {
                    "loyalty": {
                        "properties": {
                            "_ddgxdmint": {
                                "properties": {
                                    "joinDate": {
                                        "type": "string"
                                    }
                                },
                                "type": "object"
                            }
                        },
                        "type": "object"
                    }
                }
            },
            {
                "$ref": "https://ns.adobe.com/xdm/mixins/profile/profile-loyalty-details"
            }
        ]
    },
    {
        "$id": "https://ns.adobe.com/ddgxdmint/schemas/632cb76723ce2fd3876385168c03eb5201c5997f3f367a2f",
        "$schema": "http://json-schema.org/draft-06/schema#",
        "type": "object",
        "meta:xdmType": "object",
        "meta:resourceType": "schemas",
        "title": "My Sample Schema",
        "description": "My Sample Schema",
        "meta:extends": [
            "https://ns.adobe.com/xdm/context/profile"
        ],
        "allOf": [
            {
                "$ref": "https://ns.adobe.com/xdm/context/profile"
            },
            {
                "$ref": "https://ns.adobe.com/ddgxdmint/mixins/68397e9293a6904b3006311fb46c9573a8aaad49780dd65a"
            },
            {
                "$ref": "https://ns.adobe.com/ddgxdmint/mixins/7d4edf1a4c2b8c97d31f9931a10618e0b7341cefc97edad6"
            },
            {
                "$ref": "https://ns.adobe.com/ddgxdmint/mixins/6420020c79930a4c3aa7c9fd03b218e0e85c9a7d9990ecf",
                "meta:refProperty": [
                    "/person/name/firstName",
                    "/person/name/lastName",
                    "/person/name/_ddgxdmint/nickName"
                ]
            },
            {
                "$ref": "https://ns.adobe.com/ddgxdmint/mixins/39e6bb291e5b9072878c5c80c0ff5a325df79385ed10d241"
            }
        ]
    },
    {
        "@type": "xdm:alternateDisplayInfo",
        "meta:resourceType": "descriptors",
        "xdm:sourceSchema": "https://ns.adobe.com/ddgxdmint/schemas/632cb76723ce2fd3876385168c03eb5201c5997f3f367a2f",
        "xdm:sourceVersion": 1,
        "xdm:sourceProperty": "/person/name/firstName",
        "xdm:title": {
            "en_us": "My first name"
        }
    },
    {
        "@type": "xdm:descriptorIdentity",
        "meta:resourceType": "descriptors",
        "xdm:sourceSchema": "https://ns.adobe.com/ddgxdmint/schemas/632cb76723ce2fd3876385168c03eb5201c5997f3f367a2f",
        "xdm:sourceVersion": 1,
        "xdm:sourceProperty": "/_ddgxdmint/customField1",
        "xdm:namespace": "email",
        "xdm:property": "xdm:code",
        "xdm:isPrimary": true
    }
]

Importieren der Schema-Payload

Nachdem Sie die Export-Payload aus der CSV-Datei generiert haben, können Sie diese Payload an den /rpc/import -Endpunkt senden, um das Schema zu generieren.

Weitere Informationen zum Generieren von Schemas aus Export-Payloads finden Sie im Import-Endpunkthandbuch .

recommendation-more-help
62e9ffd9-1c74-4cef-8f47-0d00af32fc07