Documentazione Experience Platform Guida di Experience Data Model (XDM)

Endpoint API di conversione da modello CSV a schema

Ultimo aggiornamento: 16 luglio 2024

Argomenti:

Creato per:

Sviluppatore

L'endpoint /rpc/csv2schema nell'API Schema Registry consente di creare automaticamente uno schema Experience Data Model (XDM) utilizzando un file CSV come modello. Utilizzando questo endpoint, puoi creare modelli per importare in blocco i campi dello schema e ridurre il lavoro manuale dell’API o dell’interfaccia utente.

Introduzione

L'endpoint /rpc/csv2schema fa parte dell'Schema Registry API. Prima di continuare, consulta la guida introduttiva per i collegamenti alla documentazione correlata, una guida alla lettura delle chiamate API di esempio in questo documento e per le informazioni importanti sulle intestazioni necessarie per effettuare correttamente le chiamate a qualsiasi API Adobe Experience Platform.

L'endpoint /rpc/csv2schema fa parte delle chiamate di procedura remota (RPC) supportate da Schema Registry. A differenza di altri endpoint nell'API Schema Registry, gli endpoint RPC non richiedono intestazioni aggiuntive come Accept o Content-Type e non utilizzano un CONTAINER_ID. Devono invece utilizzare lo spazio dei nomi /rpc, come dimostrato nelle chiamate API riportate di seguito.

Requisiti del file CSV

Per utilizzare questo endpoint, devi innanzitutto creare un file CSV con le intestazioni di colonna appropriate e i valori corrispondenti. Alcune colonne sono obbligatorie, mentre le altre sono facoltative. La tabella seguente descrive queste colonne e il loro ruolo nella costruzione dello schema.

Posizione intestazione CSV	Nome intestazione CSV	Obbligatorio/facoltativo	Descrizione
1	`isIgnored`	Facoltativo	Se incluso e impostato su `true`, indica che il campo non è pronto per il caricamento API e deve essere ignorato.
2	`isCustom`	Obbligatorio	Indica se il campo è personalizzato o meno.
3	`fieldGroupId`	Facoltativo	ID del gruppo di campi a cui deve essere associato un campo personalizzato.
4	`fieldGroupName`	(Vedi descrizione)	Nome del gruppo di campi a cui associare il campo. Facoltativo per i campi personalizzati che non estendono i campi standard esistenti. Se non specificato, il sistema assegnerà automaticamente il nome. Obbligatorio per campi standard o campi personalizzati che estendono gruppi di campi standard, utilizzato per eseguire query su `fieldGroupId`.
5	`fieldPath`	Obbligatorio	Percorso completo di notazione con punti XED per il campo. Per includere tutti i campi di un gruppo di campi standard (come indicato in `fieldGroupName`), impostare il valore su `ALL`.
6	`displayName`	Facoltativo	Titolo o nome visualizzato descrittivo del campo. Può anche essere un alias per il titolo, se presente.
7	`fieldDescription`	Facoltativo	Descrizione del campo. Può anche essere un alias per la descrizione, se presente.
8	`dataType`	(Vedi descrizione)	Indica il tipo di dati di base per il campo. Obbligatorio per tutti i campi personalizzati. Se `dataType` è impostato su `object`, è necessario definire anche `properties` o `$ref` per la stessa riga, ma non entrambi.
9	`isRequired`	Facoltativo	Indica se il campo è obbligatorio per l’acquisizione dei dati.
10	`isArray`	Facoltativo	Indica se il campo è una matrice dei relativi `dataType` indicati.
11	`isIdentity`	Facoltativo	Indica se il campo è un campo di identità.
12	`identityNamespace`	Obbligatorio se `isIdentity` è true	Spazio dei nomi identità per il campo identità.
13	`isPrimaryIdentity`	Facoltativo	Indica se il campo è l’identità primaria dello schema.
14	`minimum`	Facoltativo	(Solo per campi numerici) Il valore minimo per il campo.
15	`maximum`	Facoltativo	(Solo per campi numerici) Il valore massimo per il campo.
16	`enum`	Facoltativo	Elenco di valori enum per il campo, espressi come matrice (esempio: `[value1,value2,value3]`).
17	`stringPattern`	Facoltativo	(Solo per i campi stringa) Pattern regex che il valore stringa deve corrispondere per passare la convalida durante l’acquisizione dei dati.
18	`format`	Facoltativo	(Solo per i campi stringa) Il formato del campo stringa.
19	`minLength`	Facoltativo	(Solo per i campi stringa) La lunghezza minima del campo stringa.
20	`maxLength`	Facoltativo	(Solo per i campi stringa) La lunghezza massima del campo stringa.
21	`properties`	(Vedi descrizione)	Obbligatorio se `dataType` è impostato su `object` e `$ref` non è definito. Definisce il corpo dell'oggetto come stringa JSON (esempio: `{"myField": {"type": "string"}}`).
22	`$ref`	(Vedi descrizione)	Obbligatorio se `dataType` è impostato su `object` e `properties` non è definito. Definisce il `$id` dell'oggetto di riferimento per il tipo di oggetto (ad esempio `https://ns.adobe.com/xdm/context/person`).
23	`comment`	Facoltativo	Quando `isIgnored` è impostato su `true`, questa colonna viene utilizzata per fornire le informazioni di intestazione dello schema.

Consulta il seguente modello CSV per determinare come formattare il file CSV.

Creare un payload di esportazione da un file CSV

Dopo aver configurato il modello CSV, puoi inviare il file all'endpoint /rpc/csv2schema e convertirlo in un payload di esportazione.

Formato API

POST /rpc/csv2schema

Richiesta

Il payload della richiesta deve utilizzare i dati del modulo come formato. I campi modulo richiesti sono mostrati di seguito.

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."'

Proprietà	Descrizione
`csv-file`	Percorso del modello CSV memorizzato nel computer locale.
`schema-class-id`	`$id` della classe XDM che questo schema utilizzerà.
`schema-name`	Un nome visualizzato per lo schema.
`schema-description`	Descrizione dello schema.

Risposta

In caso di esito positivo, la risposta restituisce un payload di esportazione generato dal file CSV. Il payload assume la forma di un array e ogni elemento dell’array è un oggetto che rappresenta un componente XDM dipendente per lo schema. Seleziona la sezione seguente per visualizzare un esempio completo di payload di esportazione generato da un file CSV.

Esempio di payload di risposta

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

Endpoint API di conversione da modello CSV a schema

Introduzione

Requisiti del file CSV

Creare un payload di esportazione da un file CSV

Importare il payload dello schema