Come modellare ed esportare gli arricchimentiHow to shape and export enrichments

Le proiezioni sono l'espressione fisica dei documenti arricchiti in un archivio informazioni.Projections are the physical expression of enriched documents in a knowledge store. Un utilizzo efficace dei documenti arricchiti richiede la struttura.Effective use of enriched documents requires structure. In questo articolo si esamineranno sia la struttura che le relazioni, apprendendo come creare le proprietà di proiezione, nonché come correlare i dati tra i tipi di proiezione creati.In this article, you'll explore both structure and relationships, learning how to build out projection properties, as well as how to relate data across the projection types created.

Per creare una proiezione, i dati vengono modellati usando un' abilità di shaper per creare un oggetto personalizzato o usando la sintassi di shaping in linea all'interno di una definizione di proiezione.To create a projection, the data is shaped using either a Shaper skill to create a custom object or using the inline shaping syntax within a projection definition.

Una forma dati contiene tutti i dati progettati per il progetto, formati come una gerarchia di nodi.A data shape contains all the data intended to project, formed as a hierarchy of nodes. Questo articolo illustra diverse tecniche per il data shaping, in modo che possa essere proiettato in strutture fisiche che contribuiscono alla creazione di report, analisi o elaborazione downstream.This article shows several techniques for shaping data so that it can be projected into physical structures conducive to reporting, analysis, or downstream processing.

Gli esempi presentati in questo articolo sono reperibili in questo esempio di API REST, che è possibile scaricare ed eseguire in un client http.The examples presented in this article can be found in this REST API sample, which you can download and run in an HTTP client.

Introduzione agli esempi di proiezioneIntroduction to projection examples

Esistono tre tipi di proiezioni:There are three types of projections:

  • TabelleTables
  • OggettiObjects
  • FileFiles

Le proiezioni delle tabelle vengono archiviate nell'archiviazione tabelle di Azure.Table projections are stored in Azure Table storage. Le proiezioni di oggetti e file vengono scritte nell'archivio BLOB, in cui le proiezioni di oggetti vengono salvate come file JSON e possono contenere contenuto del documento di origine, nonché qualsiasi output o arricchimento delle competenze.Object and file projections are written to blob storage, where object projections are saved as JSON files, and can contain content from the source document as well as any skill outputs or enrichments. La pipeline di arricchimento può inoltre estrarre i file binari come le immagini, che vengono proiettati come proiezioni di file.The enrichment pipeline can also extract binaries like images, these binaries are projected as file projections. Quando un oggetto binario viene proiettato come proiezione di oggetti, solo i metadati associati vengono salvati come BLOB JSON.When a binary object is projected as an object projection, only the metadata associated with it is saved as a JSON blob.

Per comprendere l'intersezione tra la data shaping e le proiezioni, si utilizzeranno le seguenti competenze come base per esplorare varie configurazioni.To understand the intersection between data shaping and projections, we'll use the following skillset as the basis for exploring various configurations. Questo skillt elabora le immagini e il contenuto di testo non elaborati.This skillset processes raw image and text content. Le proiezioni verranno definite dal contenuto del documento e dagli output delle competenze, per gli scenari desiderati.Projections will be defined from the contents of the document and the outputs of the skills, for the desired scenarios.

Importante

Quando si sperimentano le proiezioni, è utile impostare la proprietà cache dell'indicizzatore per assicurare il controllo dei costi.When experimenting with projections, it is useful to set the indexer cache property to ensure cost control. Con la modifica delle proiezioni, l'intero documento verrà nuovamente arricchito se la cache dell'indicizzatore non è impostata.Editing projections will result in the entire document being enriched again if the indexer cache is not set. Quando viene impostata la cache e vengono aggiornate solo le proiezioni, le esecuzioni di competenze per i documenti precedentemente arricchiti non comportano alcun nuovo addebito per servizi cognitivi.When the cache is set and only the projections updated, skillset executions for previously enriched documents do not result in any new Cognitive Services charges.

{
    "name": "azureblob-skillset",
    "description": "Skillset created from the portal. skillsetName: azureblob-skillset; contentField: merged_content; enrichmentGranularity: document; knowledgeStoreStorageAccount: confdemo;",
    "skills": [
        {
            "@odata.type": "#Microsoft.Skills.Text.EntityRecognitionSkill",
            "name": "#1",
            "description": null,
            "context": "/document/merged_content",
            "categories": [
                "Person",
                "Quantity",
                "Organization",
                "URL",
                "Email",
                "Location",
                "DateTime"
            ],
            "defaultLanguageCode": "en",
            "minimumPrecision": null,
            "includeTypelessEntities": null,
            "inputs": [
                {
                    "name": "text",
                    "source": "/document/merged_content"
                },
                {
                    "name": "languageCode",
                    "source": "/document/language"
                }
            ],
            "outputs": [
                {
                    "name": "persons",
                    "targetName": "people"
                },
                {
                    "name": "organizations",
                    "targetName": "organizations"
                },
                {
                    "name": "locations",
                    "targetName": "locations"
                },
                {
                    "name": "entities",
                    "targetName": "entities"
                }
            ]
        },
        {
            "@odata.type": "#Microsoft.Skills.Text.KeyPhraseExtractionSkill",
            "name": "#2",
            "description": null,
            "context": "/document/merged_content",
            "defaultLanguageCode": "en",
            "maxKeyPhraseCount": null,
            "inputs": [
                {
                    "name": "text",
                    "source": "/document/merged_content"
                },
                {
                    "name": "languageCode",
                    "source": "/document/language"
                }
            ],
            "outputs": [
                {
                    "name": "keyPhrases",
                    "targetName": "keyphrases"
                }
            ]
        },
        {
            "@odata.type": "#Microsoft.Skills.Text.LanguageDetectionSkill",
            "name": "#3",
            "description": null,
            "context": "/document",
            "inputs": [
                {
                    "name": "text",
                    "source": "/document/merged_content"
                }
            ],
            "outputs": [
                {
                    "name": "languageCode",
                    "targetName": "language"
                }
            ]
        },
        {
            "@odata.type": "#Microsoft.Skills.Text.MergeSkill",
            "name": "#4",
            "description": null,
            "context": "/document",
            "insertPreTag": " ",
            "insertPostTag": " ",
            "inputs": [
                {
                    "name": "text",
                    "source": "/document/content"
                },
                {
                    "name": "itemsToInsert",
                    "source": "/document/normalized_images/*/text"
                },
                {
                    "name": "offsets",
                    "source": "/document/normalized_images/*/contentOffset"
                }
            ],
            "outputs": [
                {
                    "name": "mergedText",
                    "targetName": "merged_content"
                }
            ]
        },
        {
            "@odata.type": "#Microsoft.Skills.Vision.OcrSkill",
            "name": "#5",
            "description": null,
            "context": "/document/normalized_images/*",
            "textExtractionAlgorithm": "printed",
            "lineEnding": "Space",
            "defaultLanguageCode": "en",
            "detectOrientation": true,
            "inputs": [
                {
                    "name": "image",
                    "source": "/document/normalized_images/*"
                }
            ],
            "outputs": [
                {
                    "name": "text",
                    "targetName": "text"
                },
                {
                    "name": "layoutText",
                    "targetName": "layoutText"
                }
            ]
        }
    ],
    "cognitiveServices": {
        "@odata.type": "#Microsoft.Azure.Search.CognitiveServicesByKey",
        "description": "DemosCS",
        "key": "<COGNITIVE SERVICES KEY>"
    },
    "knowledgeStore": null
}

Utilizzando questo insieme di competenze, con il relativo valore null knowledgeStore come base, nel primo esempio viene compilato l' knowledgeStore oggetto, configurato con proiezioni che consentono di creare strutture di dati tabulari che è possibile utilizzare in altri scenari.Using this skillset, with its null knowledgeStore as the basis, our first example fills in the knowledgeStore object, configured with projections that create tabular data structures we can use in other scenarios.

Proiezione in tabelleProjecting to tables

La proiezione per le tabelle in archiviazione di Azure è utile per la creazione di report e l'analisi tramite strumenti come Power BI.Projecting to tables in Azure Storage is useful for reporting and analysis using tools like Power BI. Power BI possibile leggere dalle tabelle e individuare le relazioni in base alle chiavi generate durante la proiezione.Power BI can read from tables and discover relationships based on the keys that are generated during projection. Se si sta provando a creare un dashboard, i dati correlati verranno semplificati dall'attività.If you're trying to build a dashboard, having related data will simplify that task.

Viene ora creato un dashboard per visualizzare le frasi chiave estratte dai documenti come un cloud di Word.Let's build a dashboard to visualize the key phrases extracted from documents as a word cloud. Per creare la struttura di dati corretta, aggiungere una competenza shaper al skillt per creare una forma personalizzata con i dettagli e le frasi chiave specifici del documento.To create the right data structure, add a Shaper skill to the skillset to create a custom shape that has the document-specific details and key phrases. La forma personalizzata verrà chiamata pbiShape sul document nodo radice.The custom shape will be called pbiShape on the document root node.

Nota

Le proiezioni di tabella sono tabelle di archiviazione di Azure, regolate dai limiti di archiviazione imposti da archiviazione di Azure.Table projections are Azure Storage tables, governed by the storage limits imposed by Azure Storage. Per altre informazioni, vedere limiti di archiviazione tabelle.For more information, see table storage limits. È utile tenere presente che la dimensione dell'entità non può superare 1 MB e una singola proprietà non può essere maggiore di 64 KB.It is useful to know that the entity size cannot exceed 1 MB and a single property can be no bigger than 64 KB. Questi vincoli rendono le tabelle una soluzione efficace per l'archiviazione di un numero elevato di entità di piccole dimensioni.These constraints make tables a good solution for storing a large number of small entities.

Uso di un'abilità di shaper per creare una forma personalizzataUsing a Shaper skill to create a custom shape

Creare una forma personalizzata che è possibile proiettare nell'archivio tabelle.Create a custom shape that you can project into table storage. Senza una forma personalizzata, una proiezione può fare riferimento solo a un singolo nodo (una proiezione per output).Without a custom shape, a projection can only reference a single node (one projection per output). La creazione di una forma personalizzata aggrega vari elementi in un nuovo intero logico che può essere proiettato come una singola tabella oppure sezionato e distribuito in una raccolta di tabelle.Creating a custom shape aggregates various elements into a new logical whole that can be projected as a single table, or sliced and distributed across a collection of tables.

In questo esempio, la forma personalizzata combina i metadati e le entità identificate e le frasi chiave.In this example, the custom shape combines metadata and identified entities and key phrases. L'oggetto viene chiamato pbiShape ed è associato a un elemento padre /document .The object is called pbiShape and is parented under /document.

Importante

Uno degli scopi di data shaping è garantire che tutti i nodi di arricchimento siano espressi in formato JSON ben formato, necessario per la proiezione nell'archivio delle informazioni.One purpose of shaping is to ensure that all enrichment nodes are expressed in well-formed JSON, which is required for projecting into knowledge store. Ciò vale soprattutto quando un albero di arricchimento contiene nodi che non sono JSON ben formati, ad esempio quando un arricchimento è associato a una primitiva come una stringa.This is especially true when an enrichment tree contains nodes that are not well-formed JSON (for example, when an enrichment is parented to a primitive like a string).

Si notino gli ultimi due nodi, KeyPhrases e Entities .Notice the last two nodes, KeyPhrases and Entities. Questi vengono inclusi in un oggetto JSON valido con sourceContext .These are wrapped into a valid JSON object with the sourceContext. Questa operazione è necessaria perché keyphrases e entities sono arricchimenti sulle primitive e devono essere convertiti in JSON valido prima di poter essere proiettati.This is required as keyphrases and entities are enrichments on primitives and need to be converted to valid JSON before they can be projected.

{
    "@odata.type": "#Microsoft.Skills.Util.ShaperSkill",
    "name": "ShaperForTables",
    "description": null,
    "context": "/document",
    "inputs": [
        {
            "name": "metadata_storage_content_type",
            "source": "/document/metadata_storage_content_type",
            "sourceContext": null,
            "inputs": []
        },
        {
            "name": "metadata_storage_name",
            "source": "/document/metadata_storage_name",
            "sourceContext": null,
            "inputs": []
        },
        {
            "name": "metadata_storage_path",
            "source": "/document/metadata_storage_path",
            "sourceContext": null,
            "inputs": []
        },
        {
            "name": "metadata_content_type",
            "source": "/document/metadata_content_type",
            "sourceContext": null,
            "inputs": []
        },
        {
            "name": "keyPhrases",
            "source": null,
            "sourceContext": "/document/merged_content/keyphrases/*",
            "inputs": [
                {
                    "name": "KeyPhrases",
                    "source": "/document/merged_content/keyphrases/*"
                }

            ]
        },
        {
            "name": "Entities",
            "source": null,
            "sourceContext": "/document/merged_content/entities/*",
            "inputs": [
                {
                    "name": "Entities",
                    "source": "/document/merged_content/entities/*/name"
                }

            ]
        }
    ],
    "outputs": [
        {
            "name": "output",
            "targetName": "pbiShape"
        }
    ]
}

Aggiungere la capacità di shaper sopra indicata al skillt.Add the above Shaper skill to the skillset.

    "name": "azureblob-skillset",
    "description": "A friendly description of the skillset goes here.",
    "skills": [
        {
            Shaper skill goes here
            }
        ],
    "cognitiveServices":  "A key goes here",
    "knowledgeStore": []
}  

Ora che sono disponibili tutti i dati necessari per proiettare le tabelle, aggiornare l'oggetto knowledgeStore con le definizioni della tabella.Now that we have all the data needed to project to tables, update the knowledgeStore object with the table definitions. In questo esempio sono disponibili tre tabelle, definite impostando le tableName proprietà, source e generatedKeyName .In this example, we have three tables, defined by setting the tableName, source and generatedKeyName properties.

"knowledgeStore" : {
    "storageConnectionString": "DefaultEndpointsProtocol=https;AccountName=<Acct Name>;AccountKey=<Acct Key>;",
    "projections": [
        {
            "tables": [
                {
                    "tableName": "pbiDocument",
                    "generatedKeyName": "Documentid",
                    "source": "/document/pbiShape"
                },
                {
                    "tableName": "pbiKeyPhrases",
                    "generatedKeyName": "KeyPhraseid",
                    "source": "/document/pbiShape/keyPhrases/*"
                },
                {
                    "tableName": "pbiEntities",
                    "generatedKeyName": "Entityid",
                    "source": "/document/pbiShape/Entities/*"
                }
            ],
            "objects": [],
            "files": []
        }
    ]
}

È possibile elaborare il lavoro attenendosi alla procedura seguente:You can process your work by following these steps:

  1. Impostare la storageConnectionString proprietà su una stringa di connessione dell'account di archiviazione per utilizzo generico V2 valida.Set the storageConnectionString property to a valid V2 general purpose storage account connection string.

  2. Aggiornare il skillt inviando la richiesta PUT.Update the skillset by issuing the PUT request.

  3. Dopo aver aggiornato le competenze, eseguire l'indicizzatore.After updating the skillset, run the indexer.

È ora disponibile una proiezione funzionante con tre tabelle.You now have a working projection with three tables. L'importazione di queste tabelle in Power BI dovrebbe comportare Power BI l'individuazione automatica delle relazioni.Importing these tables into Power BI should result in Power BI auto-discovering the relationships.

Prima di passare all'esempio successivo, è possibile esaminare gli aspetti della proiezione della tabella per comprendere i meccanismi di sezionamento e di correlazione dei dati.Before moving on to the next example, let's revisit aspects of the table projection to understand the mechanics of slicing and relating data.

AffettareSlicing

Il sezionamento è una tecnica che suddivide un'intera forma consolidata in parti costituenti.Slicing is a technique that subdivides a whole consolidated shape into constituent parts. Il risultato è costituito da tabelle separate ma correlate che è possibile utilizzare singolarmente.The outcome consists of separate but related tables that you can work with individually.

Nell'esempio pbiShape è la forma consolidata (o il nodo di arricchimento).In the example, pbiShape is the consolidated shape (or enrichment node). Nella definizione della proiezione, pbiShape viene sezionato in tabelle aggiuntive, che consente di estrarre parti della forma, keyPhrases e Entities .In the projection definition, pbiShape is sliced into additional tables, which enables you to pull out parts of the shape, keyPhrases and Entities. In Power BI, questo è utile perché più entità e frasi chiave sono associate a ogni documento e si ottengono maggiori informazioni se è possibile visualizzare le entità e le frasi chiave come dati categorizzati.In Power BI, this is useful as multiple entities and keyPhrases are associated with each document, and you will get more insights if you can see entities and keyPhrases as categorized data.

Il sezionamento genera in modo implicito una relazione tra le tabelle padre e figlio, usando nella generatedKeyName tabella padre per creare una colonna con lo stesso nome nella tabella figlio.Slicing implicitly generates a relationship between the parent and child tables, using the generatedKeyName in the parent table to create a column with the same name in the child table.

Relazioni di denominazioneNaming relationships

Le generatedKeyName referenceKeyName proprietà e vengono usate per correlare i dati tra tabelle o persino tra tipi di proiezione.The generatedKeyName and referenceKeyName properties are used to relate data across tables or even across projection types. Ogni riga nella tabella/proiezione figlio ha una proprietà che punta all'elemento padre.Each row in the child table/projection has a property pointing back to the parent. Il nome della colonna o della proprietà nell'elemento figlio è referenceKeyName dall'elemento padre.The name of the column or property in the child is the referenceKeyName from the parent. Quando referenceKeyName non viene specificato, il servizio ne imposta il valore predefinito su generatedKeyName dall'elemento padre.When the referenceKeyName is not provided, the service defaults it to the generatedKeyName from the parent.

Power BI si basa su queste chiavi generate per individuare le relazioni all'interno delle tabelle.Power BI relies on these generated keys to discover relationships within the tables. Se è necessario che la colonna della tabella figlio sia denominata in modo diverso, impostare la referenceKeyName proprietà nella tabella padre.If you need the column in the child table named differently, set the referenceKeyName property on the parent table. Un esempio consiste nell'impostare l' generatedKeyName ID As nella tabella pbiDocument e referenceKeyName come DocumentID.One example would be to set the generatedKeyName as ID on the pbiDocument table and the referenceKeyName as DocumentID. Ciò comporterebbe la colonna nelle tabelle pbiEntities e pbiKeyPhrases contenente l'ID documento denominato DocumentID.This would result in the column in the pbiEntities and pbiKeyPhrases tables containing the document ID being named DocumentID.

Proiezione in oggettiProjecting to objects

Le proiezioni di oggetti non hanno le stesse limitazioni delle proiezioni di tabella e sono più adatte per la proiezione di documenti di grandi dimensioni.Object projections do not have the same limitations as table projections and are better suited for projecting large documents. In questo esempio, l'intero documento viene inviato come proiezione di oggetti.In this example, the entire document is sent as an object projection. Le proiezioni di oggetti sono limitate a una singola proiezione in un contenitore e non possono essere sezionate.Object projections are limited to a single projection in a container and cannot be sliced.

Per definire una proiezione di oggetti, usare la objects matrice nelle proiezioni.To define an object projection, use the objects array in the projections. È possibile generare una nuova forma usando l'abilità dell'shaper o usare il data shaping in linea della proiezione dell'oggetto.You can generate a new shape using the Shaper skill or use inline shaping of the object projection. Mentre nell'esempio Tables è stato illustrato l'approccio per la creazione di una forma e un sezionamento, in questo esempio viene illustrato l'utilizzo di shaping in linea.While the tables example demonstrated the approach of creating a shape and slicing, this example demonstrates the use of inline shaping.

Il data shaping è la possibilità di creare una nuova forma nella definizione degli input di una proiezione.Inline shaping is the ability to create a new shape in the definition of the inputs to a projection. Il data shaping crea un oggetto anonimo che è identico a quello prodotto da un'abilità shaper (in questo caso pbiShape ).Inline shaping creates an anonymous object that is identical to what a Shaper skill would produce (in our case, pbiShape). Il data shaping è utile se si definisce una forma che non si prevede di riutilizzare.Inline shaping is useful if you are defining a shape that you do not plan to reuse.

La proprietà proiezioni è una matrice.The projections property is an array. In questo esempio viene aggiunta una nuova istanza di proiezione alla matrice, in cui la definizione knowledgeStore contiene proiezioni inline.This example adds a new projection instance to the array, where the knowledgeStore definition contains inline projections. Quando si usano le proiezioni inline, è possibile omettere la capacità dell'shaper.When using inline projections, you can omit the Shaper skill.

"knowledgeStore" : {
        "storageConnectionString": "DefaultEndpointsProtocol=https;AccountName=<Acct Name>;AccountKey=<Acct Key>;",
        "projections": [
             {
                "tables": [ ],
                "objects": [
                    {
                        "storageContainer": "sampleobject",
                        "source": null,
                        "generatedKeyName": "myobject",
                        "sourceContext": "/document",
                        "inputs": [
                            {
                                "name": "metadata_storage_name",
                                "source": "/document/metadata_storage_name"
                            },
                            {
                                "name": "metadata_storage_path",
                                "source": "/document/metadata_storage_path"
                            },
                            {
                                "name": "content",
                                "source": "/document/content"
                            },
                            {
                                "name": "keyPhrases",
                                "source": "/document/merged_content/keyphrases/*"
                            },
                            {
                                "name": "entities",
                                "source": "/document/merged_content/entities/*/name"
                            },
                            {
                                "name": "ocrText",
                                "source": "/document/normalized_images/*/text"
                            },
                            {
                                "name": "ocrLayoutText",
                                "source": "/document/normalized_images/*/layoutText"
                            }
                        ]

                    }
                ],
                "files": []
            }
        ]
    }

Proiezione in un fileProjecting to file

Le proiezioni di file sono immagini estratte dal documento di origine o output di arricchimento che possono essere proiettate dal processo di arricchimento.File projections are images that are either extracted from the source document or outputs of enrichment that can be projected out of the enrichment process. Le proiezioni di file, simili alle proiezioni degli oggetti, vengono implementate come BLOB in archiviazione di Azure e contengono l'immagine.File projections, similar to object projections, are implemented as blobs in Azure Storage, and contain the image.

Per generare una proiezione di file, usare la files matrice nell'oggetto di proiezione.To generate a file projection, use the files array in the projection object. Questo esempio proietta tutte le immagini estratte dal documento in un contenitore denominato samplefile .This example projects all images extracted from the document to a container called samplefile.

"knowledgeStore" : {
        "storageConnectionString": "DefaultEndpointsProtocol=https;AccountName=<Acct Name>;AccountKey=<Acct Key>;",
        "projections": [
            {
                "tables": [ ],
                "objects": [ ],
                "files": [
                    {
                        "storageContainer": "samplefile",
                        "source": "/document/normalized_images/*"
                    }
                ]
            }
        ]
    }

Proiezione a più tipiProjecting to multiple types

Uno scenario più complesso potrebbe richiedere di proiettare contenuto tra tipi di proiezione.A more complex scenario might require you to project content across projection types. Se, ad esempio, è necessario proiettare alcuni dati come frasi chiave ed entità nelle tabelle, salvare i risultati OCR del testo e del testo di layout come oggetti, quindi proiettare le immagini come file.For example, if you need to project some data like key phrases and entities to tables, save the OCR results of text and layout text as objects, and then project the images as files.

Questo esempio aggiorna le competenze con le modifiche seguenti:This example updates the skillset with the following changes:

  1. Creare una tabella con una riga per ogni documento.Create a table with a row for each document.
  2. Creare una tabella correlata alla tabella Document con ogni frase chiave identificata come riga in questa tabella.Create a table related to the document table with each key phrase identified as a row in this table.
  3. Creare una tabella correlata alla tabella Document con ogni entità identificata come riga in questa tabella.Create a table related to the document table with each entity identified as a row in this table.
  4. Creare una proiezione di oggetti con il testo del layout per ogni immagine.Create an object projection with the layout text for each image.
  5. Creare una proiezione di file, proiettando ogni immagine estratta.Create a file projection, projecting each extracted image.
  6. Creare una tabella di riferimento incrociato che contiene riferimenti alla tabella del documento, proiezione dell'oggetto con il testo del layout e proiezione del file.Create a cross reference table that contains references to the document table, object projection with the layout text and the file projection.

Queste modifiche vengono riflesse nella definizione knowledgeStore più in basso.These changes are reflected in the knowledgeStore definition further down.

Data Shaping per la proiezione incrociataShape data for cross-projection

Per ottenere le forme necessarie per queste proiezioni, iniziare aggiungendo una nuova abilità shaper che crea un oggetto con forma denominato crossProjection .To get the shapes needed for these projections, start by adding a new Shaper skill that creates a shaped object called crossProjection.

{
    "@odata.type": "#Microsoft.Skills.Util.ShaperSkill",
    "name": "ShaperForCross",
    "description": null,
    "context": "/document",
    "inputs": [
        {
            "name": "metadata_storage_name",
            "source": "/document/metadata_storage_name",
            "sourceContext": null,
            "inputs": []
        },
        {
            "name": "keyPhrases",
            "source": null,
            "sourceContext": "/document/merged_content/keyphrases/*",
            "inputs": [
                {
                    "name": "KeyPhrases",
                    "source": "/document/merged_content/keyphrases/*"
                }

            ]
        },
        {
            "name": "entities",
            "source": null,
            "sourceContext": "/document/merged_content/entities/*",
            "inputs": [
                {
                    "name": "Entities",
                    "source": "/document/merged_content/entities/*/name"
                }

            ]
        },
        {
            "name": "images",
            "source": null,
            "sourceContext": "/document/normalized_images/*",
            "inputs": [
                {
                    "name": "image",
                    "source": "/document/normalized_images/*"
                },
                {
                    "name": "layoutText",
                    "source": "/document/normalized_images/*/layoutText"
                },
                {
                    "name": "ocrText",
                    "source": "/document/normalized_images/*/text"
                }
                ]
        }
 
    ],
    "outputs": [
        {
            "name": "output",
            "targetName": "crossProjection"
        }
    ]
}

Definire la tabella, l'oggetto e le proiezioni di fileDefine table, object, and file projections

Dall'oggetto crossProjection consolidato, sezionare l'oggetto in più tabelle, acquisire l'output OCR come BLOB e quindi salvare l'immagine come file (anche nell'archivio BLOB).From the consolidated crossProjection object, slice the object into multiple tables, capture the OCR output as blobs, and then save the image as files (also in Blob storage).

"knowledgeStore" : {
        "storageConnectionString": "DefaultEndpointsProtocol=https;AccountName=<Acct Name>;AccountKey=<Acct Key>;",
        "projections": [
             {
                "tables": [
                    {
                        "tableName": "crossDocument",
                        "generatedKeyName": "Id",
                        "source": "/document/crossProjection"
                    },
                    {
                        "tableName": "crossEntities",
                        "generatedKeyName": "EntityId",
                        "source": "/document/crossProjection/entities/*"
                    },
                    {
                        "tableName": "crossKeyPhrases",
                        "generatedKeyName": "KeyPhraseId",
                        "source": "/document/crossProjection/keyPhrases/*"
                    },
                    {
                        "tableName": "crossReference",
                        "generatedKeyName": "CrossId",
                        "source": "/document/crossProjection/images/*"
                    }
                     
                ],
                "objects": [
                    {
                        "storageContainer": "crossobject",
                        "generatedKeyName": "crosslayout",
                        "source": null,
                        "sourceContext": "/document/crossProjection/images/*/layoutText",
                        "inputs": [
                            {
                                "name": "OcrLayoutText",
                                "source": "/document/crossProjection/images/*/layoutText"
                            }
                        ]
                    }
                ],
                "files": [
                    {
                        "storageContainer": "crossimages",
                        "generatedKeyName": "crossimages",
                        "source": "/document/crossProjection/images/*/image"
                    }
                ]
            }
        ]
    }

Per le proiezioni di oggetti è necessario un nome di contenitore per ogni proiezione, le proiezioni di oggetti o le proiezioni di file non possono condividere un contenitore.Object projections require a container name for each projection, object projections or file projections cannot share a container.

Relazioni tra la tabella, l'oggetto e le proiezioni di fileRelationships among table, object, and file projections

In questo esempio viene evidenziata anche un'altra funzionalità delle proiezioni.This example also highlights another feature of projections. Definendo più tipi di proiezioni all'interno dello stesso oggetto di proiezione, esiste una relazione espressa all'interno e tra i diversi tipi (tabelle, oggetti, file).By defining multiple types of projections within the same projection object, there is a relationship expressed within and across the different types (tables, objects, files). In questo modo è possibile iniziare con una riga di tabella per un documento e trovare tutto il testo OCR per le immagini all'interno del documento nella proiezione dell'oggetto.This allows you to start with a table row for a document and find all the OCR text for the images within that document in the object projection.

Se non si desidera che i dati siano correlati, definire le proiezioni in oggetti di proiezione diversi.If you do not want the data related, define the projections in different projection objects. Il frammento di codice seguente, ad esempio, comporterà la correlazione tra le tabelle, ma senza le relazioni tra le tabelle e le proiezioni dell'oggetto (testo OCR).For example, the following snippet will result in the tables being related, but without relationships between the tables and the object (OCR text) projections.

I gruppi di proiezione sono utili quando si desidera proiettare gli stessi dati in forme diverse per esigenze diverse.Projection groups are useful when you want to project the same data in different shapes for different needs. Ad esempio, un gruppo di proiezione per il dashboard Power BI e un altro gruppo di proiezione per l'acquisizione dei dati usati per eseguire il training di un modello di apprendimento automatico incluso in un'abilità personalizzata.For example, a projection group for the Power BI dashboard, and another projection group for capturing data used to train a machine learning model wrapped in a custom skill.

Quando si compilano proiezioni di tipi diversi, vengono generate prima le proiezioni di file e oggetti e i percorsi vengono aggiunti alle tabelle.When building projections of different types, file and object projections are generated first, and the paths are added to the tables.

"knowledgeStore" : {
        "storageConnectionString": "DefaultEndpointsProtocol=https;AccountName=<Acct Name>;AccountKey=<Acct Key>;",
        "projections": [
            {
                "tables": [
                    {
                        "tableName": "unrelatedDocument",
                        "generatedKeyName": "Documentid",
                        "source": "/document/pbiShape"
                    },
                    {
                        "tableName": "unrelatedKeyPhrases",
                        "generatedKeyName": "KeyPhraseid",
                        "source": "/document/pbiShape/keyPhrases"
                    }
                ],
                "objects": [
                    
                ],
                "files": []
            }, 
            {
                "tables": [],
                "objects": [
                    {
                        "storageContainer": "unrelatedocrtext",
                        "source": null,
                        "sourceContext": "/document/normalized_images/*/text",
                        "inputs": [
                            {
                                "name": "ocrText",
                                "source": "/document/normalized_images/*/text"
                            }
                        ]
                    },
                    {
                        "storageContainer": "unrelatedocrlayout",
                        "source": null,
                        "sourceContext": "/document/normalized_images/*/layoutText",
                        "inputs": [
                            {
                                "name": "ocrLayoutText",
                                "source": "/document/normalized_images/*/layoutText"
                            }
                        ]
                    }
                ],
                "files": []
            }
        ]
    }

Problemi comuniCommon Issues

Quando si definisce una proiezione, si verificano alcuni problemi comuni che possono causare risultati imprevisti.When defining a projection, there are a few common issues that can cause unanticipated results. Verificare la presenza di questi problemi se l'output nell'archivio informazioni non è quello previsto.Check for these issues if the output in knowledge store isn't what you expect.

  • Impossibile definire il data shaping in JSON valido.Not shaping string enrichments into valid JSON. Quando le stringhe sono arricchite, ad esempio merged_content arricchite con frasi chiave, la proprietà arricchita viene rappresentata come elemento figlio di merged_content all'interno dell'albero di arricchimento.When strings are enriched, for example merged_content enriched with key phrases, the enriched property is represented as a child of merged_content within the enrichment tree. La rappresentazione predefinita non è JSON ben formato.The default representation is not well-formed JSON. Quindi, in fase di proiezione, assicurarsi di trasformare l'arricchimento in un oggetto JSON valido con un nome e un valore.So at projection time, make sure to transform the enrichment into a valid JSON object with a name and a value.

  • Omettere l'oggetto /* alla fine di un percorso di origine.Omitting the /* at the end of a source path. Se l'origine di una proiezione è /document/pbiShape/keyPhrases , la matrice di frasi chiave viene proiettata come un singolo oggetto/riga.If the source of a projection is /document/pbiShape/keyPhrases, the key phrases array is projected as a single object/row. Impostare invece il percorso di origine su /document/pbiShape/keyPhrases/* per produrre una singola riga o un oggetto per ogni frase chiave.Instead, set the source path to /document/pbiShape/keyPhrases/* to yield a single row or object for each of the key phrases.

  • Errori di sintassi del percorso.Path syntax errors. I selettori di percorso distinguono tra maiuscole e minuscole e possono causare la mancata presenza di avvisi di input se non si usa il caso esatto del selettore.Path selectors are case-sensitive and can lead to missing input warnings if you do not use the exact case for the selector.

Passaggi successiviNext steps

Gli esempi in questo articolo illustrano i modelli comuni per la creazione di proiezioni.The examples in this article demonstrate common patterns on how to create projections. Ora che si dispone di una conoscenza approfondita dei concetti, è preferibile creare proiezioni per uno scenario specifico.Now that you have a good understanding of the concepts, you are better equipped to build projections for your specific scenario.

Quando si esplorano nuove funzionalità, prendere in considerazione l'arricchimento incrementale come passaggio successivo.As you explore new features, consider incremental enrichment as your next step. L'arricchimento incrementale è basato sulla memorizzazione nella cache, che consente di riutilizzare eventuali arricchimenti che non sono altrimenti interessati da una modifica di competenze.Incremental enrichment is based on caching, which lets you reuse any enrichments that are not otherwise affected by a skillset modification. Questa operazione è particolarmente utile per le pipeline che includono OCR e analisi delle immagini.This is especially useful for pipelines that include OCR and image analysis.

Per una panoramica sulle proiezioni, vedere altre informazioni sulle funzionalità, ad esempio gruppi e sezionamento, e su come definirle in un insieme di competenzeFor an overview on projections, learn more about capabilities like groups and slicing, and how you define them in a skillset