Descrição geral do contrato de dados
Este artigo explica como partilhar dados com o Intelligent Recommendations para que o possa ativar e fornecer recomendações significativas.
A API Intelligent Recommendations correspondente para os contratos de dados descritos é a API Intelligent Recommendations.
Transfira o ficheiro model.json mais recente para contratos de dados do Intelligent Recommendations: model.json.
Pré-requisitos
Para a integração de dados, o Intelligent Recommendations utiliza o Microsoft Azure Data Lake Storage. Este artigo descreve a estrutura lógica dos dados que o Intelligent Recommendations espera consumir da sua conta do Azure Data Lake Storage.
Para permitir que o Intelligent Recommendations encontre facilmente os seus dados na conta do Azure Data Lake Storage, tem de criar uma pasta dedicada na conta do Azure Data Lake Storage e fornecer o caminho da pasta (pasta raiz do Intelligent Recommendations) para o Intelligent Recommendations.
Para obter informações sobre a inclusão e a criação da sua conta do Data Lake Storage, aceda a Implementar o Intelligent Recommendations ou visite o nosso Guia de Início Rápido.
Dados do contrato
Os Contratos de dados são um conjunto de definições e de restrições para a estrutura dos dados que o Intelligent Recommendations consome. Para permitir que o Intelligent Recommendations efetue a ingestão dos dados partilhados com ele e fornecer recomendações, é necessário que adira aos contratos de dados, conforme descrito neste artigo.
Ficheiro do modelo JSON
Os contratos de dados do Intelligent Recommendations estão logicamente divididos num conjunto de entidades de dados. Cada entidade de dados é composta por zero ou mais ficheiros CSV de entrada, também denominados partições. Um ficheiro de texto JSON separado denominado model.json descreve o conjunto de entidades de dados. O ficheiro model JSON está pré-configurado e pode ser imediatamente adicionado à pasta raiz do Intelligent Recommendations.
Transferir o modelo predefinido
Transfira o ficheiro JSON de modelo predefinido mais recente para contratos de dados do Intelligent Recommendations: model.json.
[!NOTA]
O ficheiro model.json é obrigatório que seja incluído na pasta Raiz do Intelligent Recommendations, para além dos Ficheiros de Entidade de Dados. Poderá aprender a fazer ajustes ao model.json na secção Modificar o ficheiro predefinido deste Contrato de Dados.
Modificar o ficheiro predefinido
Não é recomendado modificar o ficheiro JSON de modelo fornecido até que se familiarize com o serviço Intelligent Recommendations, e apenas quando utilizar uma das seguintes caraterísticas:
Formato de entradas numéricas. O atributo cultura especifica o que o Intelligent Recommendations utiliza como o formato de entrada para valores numéricos. O separador decimal pode ser um ponto (.) ou uma vírgula (,) em culturas diferentes. Para utilizar um separador decimal que não seja um ponto (.), especifique a cultura apropriada no atributo cultura.
Nota
Se estiver a utilizar uma vírgula (,) como separador decimal, terá de sair escapar adequadamente cada valor decimal no ficheiro CSV de entrada. Para mais informações sobre como escapar de carateres em ficheiros de entrada CSV, aceda à secção Formato de dados.
Localizações de partições explícitas. Para especificar localizações explícitas dos ficheiros de partição da entidade de dados, pode utilizar o atributo partições. Por predefinição, o valor do atributo partições é nulo, o que significa que o Intelligent Recommendations pesquisa automaticamente pelos ficheiros de partição de entidade de dados relevantes. Para mais informações, consulte Formato de dados. O atributo partições é uma matriz de partições. Cada partição contém os seguintes atributos:
- nome: uma representação de cadeias da partição, não utilizada pelo Intelligent Recommendations para qualquer lógica específica.
- localização: o URI completo para o ficheiro de dados de partição (CSV). O URI tem de estar acessível para o Intelligent Recommendations (só de leitura), o que poderá requerer que forneça as permissões adequadas para o Intelligent Recommendations. Para mais informações sobre como dar acesso ao Intelligent Recommendations a dados, aceda a Configurar o Azure Data Lake Storage.
- fileFormatSettings: contém o atributo seguinte:
- columnsHeaders: um valor booleano que especifica se os dados de partição contêm uma linha de cabeçalhos. O Intelligent Recommendations descarta automaticamente as linhas de cabeçalhos quando os dados de entrada são ingeridos. O valor predefinido é false, ou seja, sem cabeçalhos.
Eis uma amostra do atributo partições:
"partitions": [
{
"name": "Partition1",
"location": "https://myStorageAcount.blob.core.windows.net/intelligent-recommnedations-container/intelligent-recommendations-root-folder/partition1.csv",
"fileFormatSettings": {
"columnHeaders": true
}
}
]
Melhores práticas para atualizar os seus dados de entrada
Evite uma situação em que os dados estão a ser modelados e atualizados ao mesmo tempo, porque poderá levar à modelação de dados de versões de conjuntos de dados mistas e resultados de recomendações indesejáveis. Seguem-se algumas melhores práticas para atualizar os seus dados de entrada:
- Escreva todas as entidades de dados numa pasta diferente. Esta pasta não tem de estar localizada no mesmo contentor ou conta de armazenamento em que os seus dados de entrada atuais estão localizados. Certifique-se de que fornece permissões para ler dados ao Intelligent Recommendation a partir do contentor dos seus dados de entrada atualizados. Para mais informações, aceda a Configurar o Azure Data Lake Storage.
- Para cada uma das entidades de dados que está a utilizar, adicione o atributo "partitions" ao seu ficheiro Model Json. Para cada partição, atualize o atributo "location" de modo a que aponte para a nova localização dos dados. Pode encontrar aqui uma explicação sobre como adicionar e editar o atributo "partitions"
- Pode eliminar os dados antigos se já não estiverem em utilização. Recomendamos a eliminação de dados antigos após a duração do ciclo de modelação estimada (pelo menos 36 horas), com alguma memória intermédia para evitar que dados sejam eliminados durante a modelação.
- Repita os passos 1 a 3 sempre que pretender atualizar os dados de entrada.
Entidades de dados
Uma entidade de dados é um conjunto de um ou mais ficheiros de texto de dados, cada um com uma lista de colunas (também denominados atributos) e linhas que contêm os valores reais dos dados.
O Intelligent Recommendations define grupos lógicos de entidades de dados, cada um com o seu próprio propósito. As entidades de dados são consideradas opcionais (a menos que tenha sido explicitamente indicado o contrário), o que significa que os respetivos dados podem estar vazios (ou totalmente em falta).
O Intelligent Recommendations define os seguintes grupos de entidades de dados:
Formato dos dados
O Intelligent Recommendations espera que todos os ficheiros de entrada de partição de entidades de dados estejam em conformidade com o seguinte formato:
O conteúdo existente no ficheiro de entrada de partição deverá estar no formato de ficheiros de texto delimitado por vírgulas (CSV), utilizando apenas codificado por UTF-8.
Cada ficheiro CSV deve incluir todos os campos especificados no contrato de dados da entidade de dados relevante. Além disso, os campos deverão ser apresentados de acordo com a ordem descrita nesse contrato.
Os ficheiros CSV só devem conter entradas de dados, de acordo com o RFC 4180.
Eis alguns exemplos comuns do comportamento do formato de dados CSV em diferentes casos:
Cada campo pode ou não estar entre aspas.
Por exemplo: aaa, “bbb”, ccc
Os campos que contenham quebras de linha (CRLF), aspas e vírgulas, têm de estar entre aspas.
Por exemplo: aaa, “bbCRLFb”, “c, cc”
Aspas que aparecem no interior de um campo têm de ter caráter de escape precedido por outra aspa.
Por exemplo: aaa, “b””bb”, ccc
No caso de não ter afirmado explicitamente o atributo partitions (no ficheiro model JSON) para uma entidade de dados, o Intelligent Recommendations pesquisa os ficheiros de partição da entidade de dados dentro de uma subpasta (sob a pasta raiz do Intelligent Recommendations) que tenha o mesmo nome que a entidade de dados.
Neste caso, todos os ficheiros de entrada da partição na subpasta da entidade de dados deverão ter uma extensão de ficheiro CSV, tal como MyData.csv e não devem conter uma linha de dados de cabeçalhos.
O Intelligent Recommendations pesquisa e agrega dados de todos os ficheiros que utilizam a extensão CSV, ao mesmo tempo que ignora o nome do ficheiro propriamente dito.
Exemplo da estrutura da pasta do Intelligent Recommendations
Eis um exemplo de captura de ecrã de uma estrutura de pastas raiz do Intelligent Recommendations. Os CSVs não precisam de corresponder aos nomes das Pastas:
Entidades de dados obrigatórias para cada cenário de recomendações
Os Cenários de Recomendações podem basear-se em entidades de dados diferentes para funcionarem corretamente. Para ver uma tabela completa de cenários de mapeamento e entidades de dados, consulte a nossa Tabela de Mapeamento de Entidades de Dados.
Requisitos e limitações do conteúdo de dados
Todos os conteúdos das entidades de dados têm de respeitar os seguintes requisitos e limitações.
Qualquer linha de dados que não respeite estes requisitos é tratada como especificado na coluna Comportamento de Valor Inválido para a entidade de dados e atributos relevantes:
Todos os IDs de itens e de variantes de itens têm de estar em conformidade com exatamente uma destas restrições (não pode misturam formatos de IDs de itens de ambas as opções):
- O comprimento tem de ser 16 carateres ou menos e conter apenas os seguintes carateres: A-Z, 0-9, _, -, ~,.
- No formato GUID — uma cadeia de exatamente 36 carateres que contém carateres hexadecimais e travessões; por exemplo, 12345678-1234-5678-90ab-1234567890ab. Se pretender utilizar este formato GUID, adicione uma entrada à entidade de dados Reco_Config com os seguintes dados: Key=ItemIdAsGuid, Value=True (ou seja, ItemIdAsGuid,True). Caso contrário, o Intelligent Recommendations não consegue gerar recomendações.
Os IDs de variantes de itens devem ser exclusivos globalmente (em todos os itens e variantes de itens).
O ID da variante do item deve ficar vazio para as linhas de dados que representam dados sobre um item mestre ou um item autónomo.
Os IDs de itens e os IDs de variantes de itens não são sensíveis às maiúsculas e minúsculas, o que significa que:
- Os IDs ABCD1234, abcd1234 e AbCd1234 são todos considerados iguais.
- Nas respostas à API de recomendações, os IDs devolvidos estão todos em maiúsculas.
Os atributos de cadeia têm um limite de comprimento. Os valores de cadeia que excedem o respetivo limite são cortados (os carateres em excesso são removidos) ou a linha de dados completa é removida (o comportamento exato está listado na tabela de entidades de dados para cada atributo).
Todos os valores de DateTime devem estar em UTC, no seguinte formato: aaaa-MM-ddTHH:mm:ss.fffZ.
Todas as cadeias, exceto o título do item e a descrição do item, não são sensíveis às maiúsculas e minúsculas. Por exemplo, os nomes de filtros Cor e cor são considerados o mesmo, e o valor de filtro Vermelho é o mesmo que o valor de filtro vermelho.
Para qualquer atributo não obrigatório que esteja vazio, é utilizado o valor predefinido (se for especificado um valor predefinido).
Os valores booleanos devem ser true ou false e não são sensíveis às maiúsculas e minúsculas (o que significa que true é considerado o mesmo que True).
Alterações à versão anterior
Eis a lista de alterações ao contrato de dados entre a versão 1.3 e a versão 1.4:
| Entidade de Dados | Resumo das Alterações |
|---|---|
| Reco_ItemCategories | A entidade de dados é agora suportada e pode ser não vazia. |
| Reco_ItemAndVariantFilters | FilterName suporta nome de filtro personalizado.Os filtros suportam agora a filtragem de múltiplos valores (mais do que um valor de filtro). |
| Reco_ItemAndVariantAvailabilities | Canal e Catálogo suportam agora qualquer valor de cadeia (não apenas 0). |
| Reco_Interactions | Canal e Catálogo suportam agora qualquer valor de cadeia (não apenas 0). |
| Reco_ImagesInventory | Nova entidade de dados. |
| Reco_ImageToItemMappings | Nova entidade de dados. |
Consulte também
API do Intelligent RecommendationsGuia de Início Rápido: Configurar e executar o Intelligent Recommendations com dados de amostraCódigos de Estado da APITabela de mapeamento de entidades de dadosEntidades de dados de catálogoEntidades de dados de interaçõesEntidades de dados de configuração de recomendaçõesEntidades de dados de listas externasOpted-out users data entitiesEntidades de dados de utilizadores que optaram ativamente por não participarEntidades de dados de mapeamento de imagem para item