Modelo CSV para endpoint da API de conversão de esquema
Última atualização: 16 de julho de 2024
Criado para:
- Desenvolvedor
O ponto de extremidade /rpc/csv2schema na API Schema Registry permite criar automaticamente um esquema do Experience Data Model (XDM) usando um arquivo CSV como modelo. Usando esse endpoint, é possível criar modelos para importar campos de esquema em massa e reduzir o trabalho manual da API ou da interface do usuário.
Introdução
O ponto de extremidade /rpc/csv2schema faz parte da Schema Registry API. Antes de continuar, consulte o guia de introdução para obter links para a documentação relacionada, um guia para ler as chamadas de API de exemplo neste documento e informações importantes sobre os cabeçalhos necessários para fazer chamadas com êxito para qualquer API do Adobe Experience Platform.
O ponto de extremidade /rpc/csv2schema faz parte das chamadas de procedimento remoto (RPCs) para as quais o Schema Registry oferece suporte. Ao contrário de outros pontos de extremidade na API Schema Registry, os pontos de extremidade RPC não exigem cabeçalhos adicionais como Accept ou Content-Type e não usam CONTAINER_ID. Em vez disso, eles devem usar o namespace /rpc, conforme demonstrado nas chamadas de API abaixo.
Requisitos do arquivo CSV
Para usar esse endpoint, primeiro crie um arquivo CSV com cabeçalhos de coluna apropriados e valores correspondentes. Algumas colunas são necessárias, enquanto o restante é opcional. A tabela abaixo descreve essas colunas e sua função na construção do schema.
| Posição do cabeçalho do CSV | Nome do cabeçalho CSV | Obrigatório/Opcional | Descrição |
|---|---|---|---|
| 1 | isIgnored | Opcional | Quando incluído e definido como true, indica que o campo não está pronto para o carregamento da API e deve ser ignorado. |
| 2 | isCustom | Obrigatório | Indica se o campo é personalizado ou não. |
| 3 | fieldGroupId | Opcional | A ID do grupo de campos ao qual um campo personalizado deve ser associado. |
| 4 | fieldGroupName | (Consulte a descrição) | O nome do grupo de campos ao qual associar este campo. Opcional para campos personalizados que não estendem campos padrão existentes. Se deixado em branco, o sistema atribuirá o nome automaticamente. Obrigatório para campos padrão ou campos personalizados que estendem grupos de campos padrão, que são usados para consultar o fieldGroupId. |
| 5 | fieldPath | Obrigatório | O caminho completo da notação de pontos XED para o campo. Para incluir todos os campos de um grupo de campos padrão (conforme indicado em fieldGroupName), defina o valor como ALL. |
| 6 | displayName | Opcional | O título ou nome de exibição amigável do campo. Também pode ser um alias para o título, se existir. |
| 7 | fieldDescription | Opcional | Uma descrição para o campo. Também pode ser um alias para a descrição, se existir. |
| 8 | dataType | (Consulte a descrição) | Indica o tipo de dados básico do campo. Obrigatório para todos os campos personalizados. Se dataType estiver definido como object, properties ou $ref também precisará ser definido para a mesma linha, mas não ambos. |
| 9 | isRequired | Opcional | Indica se o campo é necessário para assimilação de dados. |
| 10 | isArray | Opcional | Indica se o campo é uma matriz de seu dataType indicado. |
| 11 | isIdentity | Opcional | Indica se o campo é um campo de identidade. |
| 12 | identityNamespace | Obrigatório se isIdentity for verdadeiro | O namespace de identidade do campo de identidade. |
| 13 | isPrimaryIdentity | Opcional | Indica se o campo é a identidade principal do esquema. |
| 14 | minimum | Opcional | (Somente para campos numéricos) O valor mínimo do campo. |
| 15 | maximum | Opcional | (Somente para campos numéricos) O valor máximo do campo. |
| 16 | enum | Opcional | Uma lista de valores de enumeração para o campo, expressa como uma matriz (por exemplo, [value1,value2,value3]). |
| 17 | stringPattern | Opcional | (Somente para campos de sequência) Um padrão regex que o valor da sequência de caracteres deve corresponder para passar pela validação durante a assimilação de dados. |
| 18 | format | Opcional | (Somente para campos de sequência de caracteres) O formato do campo de sequência. |
| 19 | minLength | Opcional | (Somente para campos de sequência de caracteres) O comprimento mínimo do campo de sequência de caracteres. |
| 20 | maxLength | Opcional | (Somente para campos de sequência de caracteres) O comprimento máximo do campo de sequência de caracteres. |
| 21 | properties | (Consulte a descrição) | Necessário se dataType estiver definido como object e $ref não estiver definido. Isso define o corpo do objeto como uma sequência JSON (por exemplo, {"myField": {"type": "string"}}). |
| 22 | $ref | (Consulte a descrição) | Necessário se dataType estiver definido como object e properties não estiver definido. Isso define o $id do objeto referenciado para o tipo de objeto (por exemplo, https://ns.adobe.com/xdm/context/person). |
| 23 | comment | Opcional | Quando isIgnored está definido como true, esta coluna é usada para fornecer as informações do cabeçalho do esquema. |
Consulte o seguinte modelo CSV para determinar como seu arquivo CSV deve ser formatado.
Criar uma carga de exportação de um arquivo CSV
Após configurar seu modelo CSV, você pode enviar o arquivo para o endpoint /rpc/csv2schema e convertê-lo em uma carga de exportação.
Formato da API
POST /rpc/csv2schema
Solicitação
A carga da solicitação deve usar dados de formulário como formato. Os campos de formulário obrigatórios são mostrados abaixo.
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."'
| Propriedade | Descrição |
|---|---|
csv-file | O caminho para o modelo CSV armazenado no computador local. |
schema-class-id | O $id da classe XDM que este esquema empregará. |
schema-name | Um nome de exibição para o esquema. |
schema-description | Uma descrição para o esquema. |
Resposta
Uma resposta bem-sucedida retorna uma carga útil de exportação gerada pelo arquivo CSV. A carga assume a forma de uma matriz e cada item da matriz é um objeto que representa um componente XDM dependente do esquema. Selecione a seção abaixo para ver um exemplo completo de uma carga útil de exportação gerada de um arquivo CSV.
Exemplo de carga de resposta
[
{
"$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
}
]
Importar a carga do esquema
Depois de gerar a carga de exportação do arquivo CSV, você pode enviar essa carga para o ponto de extremidade /rpc/import para gerar o esquema.
Consulte o manual de endpoint de importação para obter detalhes sobre como gerar esquemas a partir de cargas de exportação.
recommendation-more-help
62e9ffd9-1c74-4cef-8f47-0d00af32fc07