Compartilhar via


Visão geral do contrato de dados

Este artigo explica como compartilhar dados com o Recomendações Inteligentes para que você possa habilitá-lo e fornecer recomendações significativas.

A API correspondente do Recomendações Inteligentes para os contratos de dados descritos é a API do Recomendações Inteligentes.

Baixe o arquivo model.json mais recente para contratos de dados do Recomendações Inteligentes: model.json.

Pré-requisitos

Para integração de dados, as Recomendações Inteligentes usam o Microsoft Azure Data Lake Storage. Este artigo descreve a estrutura lógica dos dados que as Recomendações Inteligentes esperam consumir da sua conta do Azure Data Lake Storage.

Para permitir que o Recomendações Inteligentes encontre facilmente seus dados na conta do Azure Data Lake Storage, você deve criar uma pasta dedicada na conta do Azure Data Lake Storage e fornecer o caminho da pasta (pasta raiz do Recomendações Inteligentes) ao Recomendações Inteligentes.

Para obter informações sobre como integrar e criar sua conta do Data Lake Storage, acesse Implantar o Recomendações Inteligentes ou acessar nosso Guia de início rápido.

Contratos de dados

Contratos de dados são um conjunto de definições e restrições para a estrutura dos dados que as Recomendações Inteligentes consomem. Para permitir que o Recomendações Inteligentes ingira os dados compartilhados com ele e forneça recomendações, você precisa aderir aos contratos de dados conforme descrito neste artigo.

Arquivo JSON de modelo

Os contratos de dados do Recomendações Inteligentes são divididos logicamente em um conjunto de entidades de dados. Cada entidade de dados compreende zero ou mais arquivos CSV de entrada, também chamados de partições. Um arquivo de texto JSON separado chamado model.json descreve o conjunto de entidades de dados. O arquivo JSON do modelo é pré-configurado e pode ser adicionado imediatamente à pasta raiz do Recomendações Inteligentes.

Baixar o modelo padrão

Baixe o arquivo JSON de modelo padrão mais recente para contratos de dados do Recomendações Inteligentes: model.json.

[!OBSERVAÇÃO]

O arquivo model.json deve ser incluído na pasta Raiz de Recomendações Inteligentes, além dos Arquivos de Entidade de Dados. Você pode aprender sobre como fazer ajustes no model.json na seção Modificar o arquivo padrão deste Contrato de Dados.

Modificar o arquivo padrão

Modificar o arquivo JSON do modelo fornecido não é recomendado até que você se familiarize com o serviço Recomendações Inteligentes e somente ao usar um dos seguintes recursos:

  • Formato de entradas numéricas. O atributo cultura especifica o que o Recomendações Inteligentes usará como o formato de entrada para valores numéricos. O separador decimal pode ser um ponto (.) ou uma vírgula (,) em diferentes culturas. Para usar um separador decimal diferente de um ponto (.), especifique a cultura apropriada no atributo cultura.

    Observação

    Se você estiver usando uma vírgula (,) como um separador decimal, será necessário escapar adequadamente cada valor decimal no arquivo CSV de entrada. Para obter mais informações sobre como escapar caracteres em arquivos de entrada CSV, vá para a seção Formato de dados.

  • Locais explícitos de partições. Para especificar locais explícitos dos arquivos de partições de entidades de dados, você pode usar o atributo partições. Por padrão, o valor do atributo partições é nulo, o que significa que o Recomendações Inteligentes procurará automaticamente os arquivos de partições de entidades de dados relevantes. Para obter mais informações, vá para 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 cadeia de caracteres da partição, não usada pelo Recomendações Inteligentes para nenhuma lógica específica.
    • local: URI completo para o arquivo de dados da partição (CSV). O URI precisa estar acessível ao Recomendações Inteligentes (somente leitura), o que pode exigir que você forneça as permissões adequadas a ele. Para obter mais informações sobre como conceder ao Recomendações Inteligentes acesso aos dados, vá para Configurar o Azure Data Lake Storage.
    • fileFormatSettings: contém o seguinte atributo:
      • columnsHeaders: um valor booliano que especifica se os dados da partição contêm uma linha de cabeçalho. O Recomendações Inteligentes descarta automaticamente as linhas do cabeçalho quando os dados de entrada são ingeridos. O valor padrão é falso, ou seja, sem cabeçalhos.

Veja um exemplo 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
            }
        }
    ]

Práticas recomendadas para atualizar seus dados de entrada

Evite uma situação em que os dados estejam sendo modelados e atualizados ao mesmo tempo, pois isso pode levar à modelagem de dados de versões de conjuntos de dados mistos e resultados de recomendação indesejados. Algumas das melhores práticas para atualizar seus dados de entrada são as seguintes:

  1. Grave todas as entidades de dados em uma pasta diferente. Essa pasta não precisa estar localizada no mesmo contêiner ou conta de armazenamento em que seus dados de entrada atuais estão localizados. Certifique-se de fornecer permissões do Recomendação Inteligente para ler dados do contêiner de seus dados de entrada atualizados. Para obter mais informações, acesse Configurar Azure Data Lake Storage.
  2. Para cada uma das entidades de dados que você está usando, adicione o atributo 'partições' ao seu arquivo Json de Modelo. Para cada partição, atualize o atributo 'location' para que ele aponte para o novo local de dados. Uma explicação sobre como adicionar e editar o atributo 'partitions' pode ser encontrada aqui
  3. Você pode excluir os dados antigos, se eles não estiverem mais em uso. Recomendamos excluir os dados antigos após a duração estimada do ciclo de modelagem (pelo menos 36 horas), com algum buffer para evitar que os dados sejam excluídos durante a modelagem.
  4. Repita as etapas 1 a 3 toda vez que quiser atualizar seus dados de entrada.

Entidades de dados

Uma entidade de dados é um conjunto de um ou mais arquivos de texto de dados, cada um com uma lista de colunas (também chamadas de atributos) e linhas contendo os valores de dados reais.

O Recomendações Inteligentes define grupos lógicos de entidades de dados, cada um com sua própria finalidade. As entidades de dados são consideradas opcionais (a menos que explicitamente indicado de outra forma), o que significa que seus dados podem estar vazios (ou totalmente ausentes).

O Intelligent Recommendations define os seguintes grupos de entidades de dados:

Agrupar Entidades de dados
Entidades de dados de catálogo Itens e variações
Categorias de item
Imagens de item e de variação
Filtros de item e de variação
Disponibilidades de item e de variação
Entidades de dados de interações Interações
Entidades de dados de configuração de recomendações Configuração de recomendações
Entidades de dados de usuários recusados Usuários recusados
Entidades de dados de enriquecimento de recomendações Enriquecimento de recomendações semeadas
Enriquecimento de recomendações
Entidades de dados de mapeamentos de imagem para item Inventário de imagens
Mapeamentos de imagem para item
Entidades de dados de listas externas Listas de recomendações externas
Itens de recomendações externas

Formato dos dados

O Recomendações Inteligentes espera que todos os arquivos de entrada da partição de entidades de dados estejam em conformidade com o seguinte formato:

  • O conteúdo do arquivo de entrada da partição deve estar no formato de arquivos de texto delimitados por vírgulas (CSV), usando apenas texto codificado em UTF-8.

  • Cada arquivo CSV deve incluir todos os campos especificados no contrato de dados da entidade de dados relevante. Além disso, os campos devem ser exibidos de acordo com a ordem descrita no contrato.

  • Os arquivos CSV devem conter apenas entradas de dados, de acordo com RFC 4180.

Aqui estão alguns exemplos comuns de comportamento do formato de dados CSV em diferentes casos:

  • Cada campo pode ou não estar entre aspas duplas.

    Por exemplo: aaa, “bbb”, ccc

  • Campos que contêm quebras de linha (CRLF), aspas duplas e vírgulas devem ser colocados entre aspas duplas.

    Por exemplo: aaa, “bbCRLFb”, “c, cc”

  • Uma aspa dupla que aparece dentro de um campo deve ser escapada antecedendo-a com outra aspa dupla.

    Por exemplo: aaa, “b””bb”, ccc

No caso de você não declarar explicitamente o atributo partições (no arquivo JSON de modelo) para uma entidade de dados, o Recomendações Inteligentes pesquisará os arquivos de partição da entidade de dados em uma subpasta (na pasta raiz do Recomendações Inteligentes) que tenha o mesmo nome da entidade de dados.

Nesse caso, todos os arquivos de entrada da partição na subpasta de entidades de dados devem ter uma extensão de arquivo CSV, como MyData.csv, e não devem conter uma linha de dados de cabeçalhos.

O Recomendações Inteligentes pesquisa e agrega dados de todos os arquivos que usam a extensão CSV, ignorando o próprio nome do arquivo.

Exemplo de estrutura de pastas do Recomendações Inteligentes

Veja aqui um exemplo de captura de tela de uma estrutura da pasta raiz do Recomendações Inteligentes. Os CSVs não precisam corresponder aos nomes das pastas:

Estrutura de exemplo de uma pasta raiz do Recomendações Inteligentes.

Entidades de dados necessárias para cada cenário de recomendações

Os Cenários de Recomendações podem depender de diferentes entidades de dados para funcionar corretamente. Para ver uma tabela completa de cenários de mapeamento e entidades de dados, consulte 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 devem respeitar os seguintes requisitos e limitações.

Qualquer linha de dados que não respeitar esses requisitos será tratada conforme especificado na coluna Comportamento de Valor Inválido para a entidade de dados e os atributos relevantes:

  • Todas as IDs de itens e variantes de itens devem obedecer exatamente a uma destas restrições (não é possível misturar formatos de IDs de itens de ambas as opções):

    • O tamanho deve ser de 16 caracteres ou menos e conter apenas os seguintes caracteres: A-Z, 0-9, _, -, ~,.
    • No formato GUID – uma cadeia de caracteres de exatamente 36 caracteres contendo caracteres hexadecimais e traços; por exemplo, 12345678-1234-5678-90ab-1234567890ab. Se você quiser usar o 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 Recomendações Inteligentes não gerará recomendações.
  • As IDs de variantes de itens devem ser globalmente exclusivas (em todos os itens e variantes de itens).

  • A ID da variante de item deve ser deixada em branco para linhas de dados que representam dados sobre um mestre do item ou um item autônomo.

  • As IDs de itens e as IDs de variantes de itens não diferenciam maiúsculas de minúsculas, o que significa que:

    • As IDs ABCD1234, abcd1234 e AbCd1234 são consideradas iguais.
    • Nas respostas da API de recomendações, as IDs retornadas estão todas em letras maiúsculas.
  • Os atributos de cadeia de caracteres têm um limite de tamanho. Os valores de cadeia de caracteres que excedem seu limite serão reduzidos (os caracteres em excesso serão removidos) ou a linha de dados inteira será descartada (o comportamento exato é listado na tabela de entidades de dados para cada atributo).

  • Todos os valores DateTime devem estar em UTC, no seguinte formato: aaaa-MM-ddTHH:mm:ss.fffZ.

  • Todas as cadeias de caracteres, exceto os itens título e descrição não diferenciam maiúsculas de minúsculas. Por exemplo, os nomes de filtros Cor e cor são considerados iguais, e o valor de filtro Vermelho é igual ao valor de filtro vermelho.

  • Para qualquer atributo não obrigatório que esteja vazio, o valor padrão será usado (se um valor padrão for especificado).

  • Os valores boolianos devem ser verdadeiro ou falso e não diferenciam maiúsculas de minúsculas (o que significa que verdadeiro é considerado o mesmo que Verdadeiro).

Alterações da versão anterior

Aqui está a lista de alterações do 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 tem suporte e pode não ficar vazia.
Reco_ItemAndVariantFilters FilterName dá suporte a nomes de filtro personalizados.
Os filtros agora oferecem suporte à filtragem de vários valores (mais de um valor de filtro).
Reco_ItemAndVariantAvailabilities Canal e Catálogo agora oferecem suporte a qualquer valor de cadeia de caracteres (não apenas 0).
Reco_Interactions Canal e Catálogo agora oferecem suporte a qualquer valor de cadeia de caracteres (não apenas 0).
Reco_ImagesInventory Nova entidade de dados.
Reco_ImageToItemMappings Nova entidade de dados.

Confira também

API do Recomendações Inteligentes
Guia de Início Rápido: configurar e executar o Recomendações Inteligentes com dados de exemplo
Códigos de status da API
Tabela Mapeamento de entidades de dados
Entidades de dados de catálogo
Entidades de dados de interações
Entidades de dados de configuração de recomendações
Entidades de dados de listas externas
Entidades de dados de usuários recusados
Entidades de dados de enriquecimento de recomendações
Entidades de dados de mapeamentos de imagem para item