Panoramica del contratto dati

Questo articolo spiega come condividere i dati con Raccomandazioni intelligenti in modo da poterli abilitare e fornire raccomandazioni significative.

La corrispondente API per le raccomandazioni intelligenti per i contratti dati descritti è l'API Raccomandazioni intelligenti.

Scarica l'ultimo file model.json per i contratti dati di Raccomandazioni intelligenti: model.json.

Prerequisiti

Per l'integrazione dei dati, Raccomandazioni intelligenti utilizza Microsoft Azure Data Lake Storage. Questo articolo descrive la struttura logica dei dati che Raccomandazioni intelligenti prevede di utilizzare dal tuo account Azure Data Lake Storage.

Per consentire a Raccomandazioni intelligenti di trovare facilmente i tuoi dati all'interno dell'account Azure Data Lake Storage, devi creare una cartella dedicata all'interno dell'account Azure Data Lake Storage e fornire il percorso della cartella (cartella radice di Raccomandazioni intelligenti) a Raccomandazioni intelligenti.

Per informazioni sull'onboarding e sulla creazione dell'account Data Lake Storage, vai a Distribuire Raccomandazioni intelligenti o consulta la Guida rapida.

Contratti dati

Contratti dati sono un insieme di definizioni e vincoli per la struttura dei dati utilizzati da Raccomandazioni intelligenti. Per consentire a Raccomandazioni intelligenti di acquisire i dati condivisi con essa e fornire suggerimenti, è necessario rispettare i contratti dati come descritto in questo articolo.

File JSON del modello

I contratti dati di Raccomandazioni intelligenti sono logicamente suddivisi in un set di entità dati. Ciascuna entità di dati comprende zero o più file CSV di input, anch'essi chiamati partizioni. Un file di testo JSON separato denominato model.json descrive il set di entità di dati. Il file JSON del modello è preconfigurato e può essere aggiunto immediatamente alla cartella radice di Raccomandazioni intelligenti.

Scaricare il modello predefinito

Scarica l'ultimo file modello predefinito per i contratti dati di Raccomandazioni intelligenti: model.json.

[!NOTE]

Il file model.json deve essere incluso nella cartella radice di Raccomandazioni intelligenti in aggiunta ai file di entità di dati. Puoi imparare ad apportare modifiche al model.json nella sezione Modificare il file predefinito del Contratto dati.

Modificare il file predefinito

Non è consigliabile modificare il file JSON del modello fornito finché non acquisisci familiarità con il servizio Raccomandazioni intelligenti e solo quando utilizzi una delle seguenti funzionalità:

• Formato degli input numerici. L'attributo cultura specifica cosa utilizza Raccomandazioni intelligenti come formato di input per i valori numerici. Il separatore decimale può essere un punto (.) o una virgola (,) a seconda delle culture. Per utilizzare un separatore decimale diverso da un punto (.), specifica la cultura appropriata nell'attributo cultura.

  Nota

  Se stai usando una virgola (,) come separatore decimale, dovrai eseguire correttamente l'escape di ogni valore decimale nel file CSV di input. Per ulteriori informazioni su come eseguire l'escape dei caratteri nei file di input CSV, vai alla sezione Formato dei dati.

• Posizioni esplicite delle partizioni. Per specificare le posizioni esplicite dei file di partizione dell'entità dati, è possibile utilizzare l'attributo partizioni. Per impostazione predefinita, il valore dell'attributo partizioni è null, il che significa che Raccomandazioni intelligenti cerca automaticamente i file di partizione dell'entità dati rilevanti. Per altre informazioni, vai a Formato dei dati. L'attributo partizioni è una matrice di partizioni. Ogni partizione contiene i seguenti attributi:

  • nome: una rappresentazione di stringa della partizione, non utilizzata da Raccomandazioni intelligenti per nessuna logica specifica.
  • posizione: URI completo del file di dati di partizione (CSV). L'URI deve essere accessibile a Raccomandazioni intelligenti (sola lettura), che potrebbe richiedere di fornire le autorizzazioni appropriate per Raccomandazioni intelligenti. Per ulteriori informazioni su come consentire a Raccomandazioni intelligenti di accedere ai dati, vai a Configurare Azure Data Lake Storage.
  • fileFormatSettings: contiene l'attributo seguente:
    • columnsHeaders: un valore booleano che specifica se i dati della partizione contengono una riga di intestazione. Le righe di intestazione vengono automaticamente eliminate da Raccomandazioni intelligenti quando i dati di input vengono inseriti. Il valore predefinito è falso, che significa senza intestazioni.

Ecco un esempio dell'attributo partizioni:

"partitions": [
        {
            "name": "Partition1",
            "location": "https://myStorageAcount.blob.core.windows.net/intelligent-recommnedations-container/intelligent-recommendations-root-folder/partition1.csv",
            "fileFormatSettings": {
                "columnHeaders": true
            }
        }
    ]

Procedure consigliate per l'aggiornamento dei dati d input

Evita una situazione in cui i dati vengono modellati e aggiornati contemporaneamente, in quanto può portare alla modellazione di dati da versioni miste di set di dati e risultati di raccomandazioni indesiderati. Alcune procedure consigliate per l'aggiornamento dei dati d input sono:

1. Scrivi tutte le entità di dati in una cartella diversa. Questa cartella non deve trovarsi nello stesso contenitore o account di archiviazione in cui si trovano i dati di input correnti. Assicurati di fornire le autorizzazioni di Raccomandazioni intelligenti per leggere i dati dal contenitore dei dati di input aggiornati. Per ulteriori informazioni, vedi Configurare Azure Data Lake Storage.
2. Per ciascuna delle entità di dati che stai utilizzando, aggiungi l'attributo "partitions" al tuo file Json del modello. Per ogni partizione, aggiorna l'attributo "location" in modo che punti alla nuova posizione dei dati. Una spiegazione su come aggiungere e modificare l'attributo "partitions" è disponibile qui
3. Puoi eliminare i vecchi dati se non sono più in uso. Consigliamo di eliminare i vecchi dati dopo la durata stimata del ciclo di modellazione (almeno 36 ore), con un po' di buffer per evitare che i dati vengano eliminati durante la modellazione.
4. Ripeti i passaggi 1-3 ogni volta che vuoi aggiornare i dati di input.

Entità dati

Una entità di dati è un insieme di uno o più file di testo di dati, ciascuno con un elenco di colonne (chiamato anche attributi) e righe contenenti i valori dei dati effettivi.

Raccomandazioni intelligenti definisce gruppi logici di entità di dati, ciascuno con il proprio scopo. Le entità dei dati sono considerate facoltative (se non diversamente specificato), il che significa che i loro dati possono essere vuoti (o del tutto mancanti).

I seguenti gruppi di entità di dati sono definiti da Raccomandazioni intelligenti:

Formato dati

Raccomandazioni intelligenti prevede che tutti i file di input delle partizioni delle entità dati siano conformi al formato seguente:

• Il contenuto all'interno del file di input della partizione deve essere in formato CSV (file di testo delimitato da virgole), utilizzando solo il testo codificato UTF-8.

• Ogni file CSV deve includere tutti i campi specificati nel contratto dati dell'entità dati pertinente. Inoltre, i campi devono essere visualizzati secondo l'ordine descritto nel contratto.

• I file CSV dovrebbero contenere solo voci di dati, secondo RFC 4180.

Di seguito sono riportati alcuni esempi comuni di comportamento del formato dati CSV in diversi casi:

• Ciascun campo può essere racchiuso o meno tra virgolette doppie.

  Ad esempio: aaa, "bbb", ccc

• I campi contenenti interruzioni di riga (CRLF), virgolette doppie e virgole devono essere racchiusi tra virgolette doppie.

  Ad esempio: aaa, “bbCRLFb”, “c, cc”

• Una doppia virgoletta che compare all'interno di un campo deve essere preceduta da un'altra doppia virgoletta.

  Ad esempio: aaa, “b””bb”, ccc

Nel caso in cui non hai dichiarato esplicitamente l'attributo partizioni (nel file JSON del modello) per un'entità di dati, Raccomandazioni intelligenti cerca i file di partizione dell'entità di dati all'interno di una sottocartella (nella cartella radice di Raccomandazioni intelligenti) che ha lo stesso nome dell'entità di dati.

In questo caso, tutti i file di input della partizione all'interno della sottocartella dell'entità dati dovrebbero avere un'estensione di file CSV, ad esempio MyData.csv e non dovrebbe contenere una riga di dati di intestazione.

Raccomandazioni intelligenti cerca e aggrega i dati da tutti i file che utilizzano l'estensione CSV, ignorando il nome file stesso.

Esempio di struttura della cartella Raccomandazioni intelligenti

Ecco un esempio di screenshot di una struttura di cartelle radice di Raccomandazioni intelligenti. I CSV non devono per forza corrispondere ai nomi delle cartelle:

Entità di dati obbligatorie per ogni scenario di raccomandazioni

Gli scenari di raccomandazioni possono basarsi su diverse entità di dati per funzionare correttamente. Per vedere una tabella completa di mapping di scenari ed entità di dati, vedi la Tabella di mapping delle entità di dati.

Requisiti e limitazioni del contenuto di dati

Tutti i contenuti delle entità dati devono rispettare i seguenti requisiti e limitazioni.

Qualsiasi riga di dati che non rispetti questi requisiti viene trattata come specificato nella colonna Comportamento valore non valido per l'entità dati e gli attributi rilevanti:

• Tutti gli ID articolo e le varianti articolo devono rispettare esattamente una di queste restrizioni (non è possibile combinare i formati ID articolo di entrambe le opzioni):

  • La lunghezza deve essere di 16 caratteri o meno e contenere solo i seguenti caratteri: A-Z, 0-9, _, -, ~,.
  • In formato GUID una stringa di esattamente 36 caratteri contenente caratteri esadecimali e trattini; ad esempio, 12345678-1234-5678-90ab-1234567890ab. Se vuoi usare questo formato GUID, aggiungi una voce all'entità di dati Reco_Config con i seguenti dati: Key=ItemIdAsGuid, Valore=Vero (questo è ItemIdAsGuid, True). In caso contrario, Raccomandazioni intelligenti non genererà le raccomandazioni.

• Gli ID delle varianti dell'articolo devono essere univoci a livello globale (per tutti gli articoli e le varianti dell'articolo).

• L'ID variante articolo deve essere lasciato vuoto per le righe di dati che rappresentano i dati su un'anagrafica articolo o un articolo autonomo.

• Gli ID articolo e gli ID variante articolo non fanno distinzione tra maiuscole e minuscole, il che significa che:

  • Gli ID ABCD1234, abcd1234 e AbCd1234 sono tutti considerati uguali.
  • Nelle risposte API dei consigli, gli ID restituiti sono tutti in maiuscolo.

• Gli attributi di stringa hanno un limite di lunghezza. I valori di stringa che superano il limite vengono troncati (i caratteri in eccesso vengono rimossi) oppure l'intera riga di dati viene eliminata (il comportamento esatto è elencato nella tabella dell'entità dei dati per ciascun attributo).

• Tutti i valori DateTime devono essere in formato UTC, nel seguente formato: aaaa-MM-ggTHH:mm:ss.fffZ.

• Tutte le stringhe, tranne l'articolo titolo e l'articolo descrizione, non fanno distinzione tra maiuscole e minuscole. Ad esempio, i nomi dei filtri Colore e colore sono considerati uguali e il valore del filtro Rosso è uguale al valore del filtro rosso.

• Per qualsiasi attributo non obbligatorio vuoto, viene utilizzato il valore predefinito (se viene specificato un valore predefinito).

• I valori booleani dovrebbero essere entrambi vero o falso e non fanno distinzione tra maiuscole e minuscole (il che significa che vero è considerato uguale a Vero).

Modifiche rispetto alla versione precedente

Ecco l'elenco delle modifiche al contratto dati tra la versione 1.3 e la versione 1.4:

Vedi anche

API di Raccomandazioni intelligenti
Guida rapida: impostare ed eseguire Raccomandazioni intelligenti con dati di esempio
Codici di stato API
Tabella dei mapping di entità di dati
Entità catalogo dati
Entità di dati di interazioni
Entità di dati configurazione raccomandazioni
Entità di dati elenchi esterni
Entità dati utenti rifiuto esplicito
Entità di dati di arricchimento raccomandazioni
Entità di dati di mapping da immagine a articolo