Guida introduttiva: Api REST | Anteprima

Nota

riconoscimento modulo versione 3.0 è attualmente in anteprima pubblica. Alcune funzionalità potrebbero non essere supportate o avere funzionalità limitate.

| | | REST | |

Introduzione ad Azure riconoscimento modulo il linguaggio di programmazione C#. Azure riconoscimento modulo è un servizio di intelligenza artificiale applicato di Azure basato sul cloud che usa Machine Learning per estrarre e analizzare campi modulo, testo e tabelle dai documenti. È possibile chiamare facilmente riconoscimento modulo modelli integrando gli SDK della libreria client nei flussi di lavoro e nelle applicazioni. È consigliabile usare il servizio gratuito mentre si acquisisce familiarità con questa tecnologia. Tenere presente che il numero di pagine gratuite è limitato a 500 al mese.

Per altre informazioni sulle funzionalità riconoscimento modulo e sulle opzioni di sviluppo, visitare la pagina Panoramica.

riconoscimento modulo modelli

L'API REST supporta i modelli e le funzionalità seguenti:

  • 🆕 Documento generale: analizzare ed estrarre testo, tabelle, struttura, coppie chiave-valore ed entità denominate.|
  • Layout: consente di analizzare ed estrarre tabelle, righe, parole e segni di selezione, ad esempio pulsanti di opzione e caselle di controllo nei documenti dei moduli, senza la necessità di eseguire il training di un modello.
  • Personalizzato: analizzare ed estrarre campi modulo e altro contenuto dai moduli personalizzati, usando modelli di cui è stato fatto il training con i propri tipi di modulo.
  • Fatture: analizzare ed estrarre campi comuni dalle fatture usando un modello di fattura con training preliminare.
  • Ricevute: analizzare ed estrarre campi comuni dalle ricevute usando un modello di ricevuta con training preliminare.
  • Documenti ID: analizzare ed estrarre campi comuni dai documenti ID, ad esempio passaporti o licenze del driver, usando un modello di documenti ID con training preliminare.
  • Biglietti da visita: analizzare ed estrarre i campi comuni dai biglietti da visita usando un modello di biglietti da visita con training preliminare.

Analizzare il documento

riconoscimento modulo v3.0 consolida il documento di analisi e ottiene operazioni GET (Analyze Result) per layout, modelli predefiniti e modelli personalizzati in un'unica coppia di operazioni assegnando alle operazioni modelIds POST e GET:

POST /documentModels/{modelId}:analyze

GET /documentModels/{modelId}/analyzeResults/{resultId}

La tabella seguente illustra gli aggiornamenti alle chiamate API REST.

Funzionalità v2.1 v3.0
Documento generale n/d /documentModels/prebuilt-document:analyze
Layout /layout/analyze /documentModels/prebuilt-layout:analyze
Fattura /prebuilt/invoice/analyze /documentModels/prebuilt-invoice:analyze
Ricevuta /prebuilt/receipt/analyze /documentModels/prebuilt-receipt:analyze
Documento ID /prebuilt/idDocument/analyze /documentModels/prebuilt-idDocument:analyze
Biglietto da visita /prebuilt/businessCard/analyze /documentModels/prebuilt-businessCard:analyze
Personalizzato /custom/{modelId}/analyze /documentModels/{modelId}:analyze

In questa guida introduttiva si useranno le funzionalità seguenti per analizzare ed estrarre dati e valori da moduli e documenti:

  • 🆕 documento Generale:analizzare ed estrarre testo, tabelle, struttura, coppie chiave-valore ed entità denominate.

  • Layout:consente di analizzare ed estrarre tabelle, righe, parole e segni di selezione, ad esempio pulsanti di opzione e caselle di controllo nei documenti dei moduli, senza la necessità di eseguire il training di un modello.

  • Modello predefinito:analizzare ed estrarre dati da tipi di documento comuni usando un modello con training preliminare.

Prerequisiti

  • Sottoscrizione di Azure: creare un account gratuito

  • cURL installato.

  • PowerShell versione 6.0+o un'applicazione della riga di comando simile.

  • Una risorsa riconoscimento modulo cognitiva. Dopo aver creato la sottoscrizione di Azure, creare una risorsa di riconoscimento modulo a servizio singolo o multi-portale di Azure per ottenere la chiave e l'endpoint. È possibile usare il piano tariffario gratuito (F0) per provare il servizio ed eseguire in un secondo momento l'aggiornamento a un livello a pagamento per la produzione.

Suggerimento

Creare una risorsa Servizi cognitivi se si prevede di accedere a più servizi cognitivi con un singolo endpoint/chiave. Per riconoscimento modulo solo l'accesso, creare una risorsa riconoscimento modulo locale. Si noti che è necessaria una risorsa a servizio singolo se si intende usare Azure Active Directory autenticazione.

  • Dopo la distribuzione della risorsa, selezionare Vai alla risorsa. La chiave e l'endpoint della risorsa creata sono necessari per connettere l'applicazione all'API riconoscimento modulo dati. La chiave e l'endpoint verranno incollati nel codice seguente più avanti nella guida introduttiva:

    Screenshot: keys and endpoint location in the Azure portal.

Selezionare un esempio di codice da copiare e incollare nell'applicazione:

Importante

Al termine, ricordarsi di rimuovere la chiave dal codice e non renderlo mai pubblico. Per la produzione, usare metodi sicuri per archiviare e accedere alle credenziali. Per altre informazioni, vedere l'articolo sulla sicurezza di Servizi cognitivi.

Prova:modello di documento generale

  • Per questo esempio è necessario un file di documento del modulo in un URI. È possibile usare il documento del modulo di esempio per questa guida introduttiva. Prima di eseguire il comando, apportare queste modifiche:
  1. Sostituire {endpoint} con l'endpoint ottenuto con la sottoscrizione di riconoscimento modulo.
  2. Sostituire {subscription key} con la chiave di sottoscrizione copiata nel passaggio precedente.
  3. Sostituire {your-document-url} con un URL del documento modulo di esempio.

Richiesta

curl -v -i POST "https://{endpoint}/formrecognizer/documentModels/prebuilt-document:analyze?api-version=2021-09-30-preview" -H "Content-Type: application/json" -H "Ocp-Apim-Subscription-Key: {subscription key}" --data-ascii "{'urlSource': '{your-document-url}'}"

Operation-Location

Si riceverà una risposta 202 (Success) che include un'intestazione 202 (Success). Il valore di questa intestazione contiene un ID risultato che è possibile usare per eseguire query sullo stato dell'operazione asincrona e ottenere i risultati:

https://{host}/formrecognizer/documentModels/{modelId}/analyzeResults/{resultId}?api-version=2021-09-30-preview

Ottenere i risultati generali del documento

Dopo aver chiamato l'API Analizza documento, chiamare l'API Ottenere i risultati dell'analisi per ottenere lo stato dell'operazione e i dati estratti. Prima di eseguire il comando, apportare queste modifiche:

  1. Sostituire {endpoint} con l'endpoint ottenuto con la sottoscrizione di riconoscimento modulo.
  2. Sostituire {subscription key} con la chiave di sottoscrizione copiata nel passaggio precedente.
  3. Sostituire {resultId} con l'ID risultato del passaggio precedente.

Richiesta

curl -v -X GET "https://{endpoint}/formrecognizer/documentModels/prebuilt-document/analyzeResults/{resultId}?api-version=2021-09-30-preview" -H "Ocp-Apim-Subscription-Key: {subscription key}"

Esaminare i risultati

Si riceverà una risposta 200 (Success) con un output JSON. Il primo campo, "status", indica lo stato dell'operazione. Se l'operazione non è stata completata, il valore di "status" sarà "running" o "notStarted" e si dovrà chiamare nuovamente l'API, manualmente o tramite uno script. Si consiglia di attendere almeno un secondo tra le chiamate.

Il nodo "analyzeResults" contiene tutto il testo riconosciuto. Il testo è organizzato per pagina, righe, tabelle, coppie chiave-valore ed entità.

Risposta di esempio

{
    "status": "succeeded",
    "createdDateTime": "2021-09-28T16:52:51Z",
    "lastUpdatedDateTime": "2021-09-28T16:53:08Z",
    "analyzeResult": {
        "apiVersion": "2021-09-30-preview",
        "modelId": "prebuilt-document",
        "stringIndexType": "textElements",
        "content": "content extracted",
        "pages": [
            {
                "pageNumber": 1,
                "angle": 0,
                "width": 8.4722,
                "height": 11,
                "unit": "inch",
                "words": [
                    {
                        "content": "Case",
                        "boundingBox": [
                            1.3578,
                            0.2244,
                            1.7328,
                            0.2244,
                            1.7328,
                            0.3502,
                            1.3578,
                            0.3502
                        ],
                        "confidence": 1,
                        "span": {
                            "offset": 0,
                            "length": 4
                        }
                    }

                ],
                "lines": [
                    {
                        "content": "Case",
                        "boundingBox": [
                            1.3578,
                            0.2244,
                            3.2879,
                            0.2244,
                            3.2879,
                            0.3502,
                            1.3578,
                            0.3502
                        ],
                        "spans": [
                            {
                                "offset": 0,
                                "length": 22
                            }
                        ]
                    }
                ]
            }
        ],
        "tables": [
            {
                "rowCount": 8,
                "columnCount": 3,
                "cells": [
                    {
                        "kind": "columnHeader",
                        "rowIndex": 0,
                        "columnIndex": 0,
                        "rowSpan": 1,
                        "columnSpan": 1,
                        "content": "Applicant's Name:",
                        "boundingRegions": [
                            {
                                "pageNumber": 1,
                                "boundingBox": [
                                    1.9198,
                                    4.277,
                                    3.3621,
                                    4.2715,
                                    3.3621,
                                    4.5034,
                                    1.9198,
                                    4.5089
                                ]
                            }
                        ],
                        "spans": [
                            {
                                "offset": 578,
                                "length": 17
                            }
                        ]
                    }
                ],
                "spans": [
                    {
                        "offset": 578,
                        "length": 300
                    },
                    {
                        "offset": 1358,
                        "length": 10
                    }
                ]
            }
        ],
        "keyValuePairs": [
            {
                "key": {
                    "content": "Case",
                    "boundingRegions": [
                        {
                            "pageNumber": 1,
                            "boundingBox": [
                                1.3578,
                                0.2244,
                                1.7328,
                                0.2244,
                                1.7328,
                                0.3502,
                                1.3578,
                                0.3502
                            ]
                        }
                    ],
                    "spans": [
                        {
                            "offset": 0,
                            "length": 4
                        }
                    ]
                },
                "value": {
                    "content": "A Case",
                    "boundingRegions": [
                        {
                            "pageNumber": 1,
                            "boundingBox": [
                                1.8026,
                                0.2276,
                                3.2879,
                                0.2276,
                                3.2879,
                                0.3502,
                                1.8026,
                                0.3502
                            ]
                        }
                    ],
                    "spans": [
                        {
                            "offset": 5,
                            "length": 17
                        }
                    ]
                },
                "confidence": 0.867
            }
        ],
        "entities": [
            {
                "category": "Person",
                "content": "Jim Smith",
                "boundingRegions": [
                    {
                        "pageNumber": 1,
                        "boundingBox": [
                            3.4672,
                            4.3255,
                            5.7118,
                            4.3255,
                            5.7118,
                            4.4783,
                            3.4672,
                            4.4783
                        ]
                    }
                ],
                "confidence": 0.93,
                "spans": [
                    {
                        "offset": 596,
                        "length": 21
                    }
                ]
            }
        ],
        "styles": [
            {
                "isHandwritten": true,
                "confidence": 0.95,
                "spans": [
                    {
                        "offset": 565,
                        "length": 12
                    },
                    {
                        "offset": 3493,
                        "length": 1
                    }
                ]
            }
        ]
    }
}

Prova:modello di layout

  • Per questo esempio è necessario un file di documento del modulo in un URI. È possibile usare il documento del modulo di esempio per questa guida introduttiva.

Prima di eseguire il comando, apportare queste modifiche:

  1. Sostituire {endpoint} con l'endpoint ottenuto con la sottoscrizione di riconoscimento modulo.
  2. Sostituire {subscription key} con la chiave di sottoscrizione copiata nel passaggio precedente.
  3. Sostituire "{your-document-url} con uno degli URL di esempio.

Richiesta

curl -v -i POST "https://{endpoint}/formrecognizer/documentModels/prebuilt-layout:analyze?api-version=2021-09-30-preview" -H "Content-Type: application/json" -H "Ocp-Apim-Subscription-Key: {subscription key}" --data-ascii "{'urlSource': '{your-document-url}'}"

Operation-Location

Si riceverà una risposta 202 (Success) che include un'intestazione 202 (Success). Il valore di questa intestazione contiene un ID risultato che è possibile usare per eseguire query sullo stato dell'operazione asincrona e ottenere i risultati:

https://{host}/formrecognizer/documentModels/{modelId}/analyzeResults/**{resultId}**?api-version=2021-09-30-preview

Ottenere i risultati del layout

Dopo aver chiamato l'API Analizza documento, chiamare l'API Ottenere i risultati dell'analisi per ottenere lo stato dell'operazione e i dati estratti. Prima di eseguire il comando, apportare queste modifiche:

  1. Sostituire {endpoint} con l'endpoint ottenuto con la sottoscrizione di riconoscimento modulo.
  2. Sostituire {subscription key} con la chiave di sottoscrizione copiata nel passaggio precedente.
  3. Sostituire {resultId} con l'ID risultato del passaggio precedente.

Richiesta

curl -v -X GET "https://{endpoint}/formrecognizer/documentModels/prebuilt-layout/analyzeResults/{resultId}?api-version=2021-09-30-preview" -H "Ocp-Apim-Subscription-Key: {subscription key}"

Esaminare i risultati

Si riceverà una risposta 200 (Success) con un output JSON. Il primo campo, "status", indica lo stato dell'operazione. Se l'operazione non è stata completata, il valore di "status" sarà "running" o "notStarted" e si dovrà chiamare nuovamente l'API, manualmente o tramite uno script. Si consiglia di attendere almeno un secondo tra le chiamate.

Prova:modello predefinito

Questo esempio illustra come analizzare i dati di determinati tipi di documento comuni con un modello con training preliminare, usando come esempio una fattura.

  • Per questo esempio si analizza un documento di fattura usando un modello predefinito. Per questa guida introduttiva è possibile usare il documento di esempio della fattura.
Scegliere l'ID modello predefinito della fattura

Non si è limitati alle fatture: è possibile scegliere tra diversi modelli predefiniti, ognuno dei quali ha un proprio set di campi supportati. Il modello da usare per l'operazione di analisi dipende dal tipo di documento da analizzare. Di seguito sono disponibili gli ID modello per i modelli predefiniti attualmente supportati dal riconoscimento modulo servizio:

  • prebuilt-invoice:estrae testo, segni di selezione, tabelle, coppie chiave-valore e informazioni chiave dalle fatture.
  • prebuilt-businessCard:estrae testo e informazioni chiave dai biglietti da visita.
  • prebuilt-idDocument:estrae testo e informazioni chiave dalle licenze del driver e dai passaporti internazionali.
  • prebuilt-receipt:estrae testo e informazioni chiave dalle ricevute.

Prima di eseguire il comando, apportare queste modifiche:

  1. Sostituire {endpoint} con l'endpoint ottenuto con la sottoscrizione di riconoscimento modulo.

  2. Sostituire {subscription key} con la chiave di sottoscrizione copiata nel passaggio precedente.

  3. Sostituire \"{your-document-url} con un URL di fattura di esempio:

    https://raw.githubusercontent.com/Azure-Samples/cognitive-services-REST-api-samples/master/curl/form-recognizer/sample-invoice.pdf
    

Richiesta

curl -v -i POST "https://{endpoint}/formrecognizer/documentModels/prebuilt-invoice:analyze?api-version=2021-09-30-preview" -H "Content-Type: application/json" -H "Ocp-Apim-Subscription-Key: {subscription key}" --data-ascii "{'urlSource': '{your-document-url}'}"

Operation-Location

Si riceverà una risposta 202 (Success) che include un'intestazione 202 (Success). Il valore di questa intestazione contiene un ID risultato che è possibile usare per eseguire query sullo stato dell'operazione asincrona e ottenere i risultati:

https://{host}/formrecognizer/documentModels/{modelId}/analyzeResults/{resultId}?api-version=2021-09-30-preview

Ottenere i risultati delle fatture

Dopo aver chiamato l'API Analizza documento, chiamare l'API Ottenere i risultati dell'analisi per ottenere lo stato dell'operazione e i dati estratti. Prima di eseguire il comando, apportare queste modifiche:

  1. Sostituire {endpoint} con l'endpoint ottenuto con la sottoscrizione di riconoscimento modulo.
  2. Sostituire {subscription key} con la chiave di sottoscrizione copiata nel passaggio precedente.
  3. Sostituire {resultId} con l'ID risultato del passaggio precedente.

Richiesta

curl -v -X GET "https://{endpoint}/formrecognizer/documentModels/prebuilt-invoice/analyzeResults/{resultId}?api-version=2021-09-30-preview" -H "Ocp-Apim-Subscription-Key: {subscription key}"

Esaminare i risultati

Si riceverà una risposta 200 (Success) con un output JSON. Il primo campo, "status", indica lo stato dell'operazione. Se l'operazione non è stata completata, il valore di "status" sarà "running" o "notStarted" e si dovrà chiamare nuovamente l'API, manualmente o tramite uno script. Si consiglia di attendere almeno un secondo tra le chiamate.

Migliorare i risultati

Esaminare i valori di "confidence" per ogni risultato di chiave-valore nel nodo "pageResults". È inoltre consigliabile esaminare i punteggi di attendibilità nel nodo "readResults", che corrispondono all'operazione di lettura del testo. L'attendibilità dei risultati della lettura non influisce su quella dei risultati dell'estrazione di coppie chiave-valore, quindi è necessario controllare entrambi.

  • Se i punteggi di attendibilità dell'operazione di lettura sono bassi, provare a migliorare la qualità dei documenti di input. Vedere Requisiti di input.
  • Se i punteggi di attendibilità per l'operazione di estrazione di coppie chiave-valore sono bassi, assicurarsi che i documenti da analizzare siano dello stesso tipo di quelli usati nel set di training. Se i documenti del set di training hanno aspetti diversi, è consigliabile dividerli in cartelle diverse ed eseguire il training di un modello per ogni variante.

I punteggi di attendibilità obiettivo dipendono dal caso d'uso, ma in genere è consigliabile avere come obiettivo un punteggio di almeno l'80%. Per i casi più sensibili, come la lettura di record medici o gli estratti conto, è consigliabile un punteggio del 100%.

Gestire i modelli personalizzati

Ottenere un elenco di modelli

La richiesta di anteprima dei modelli di elenco v3.0 restituisce un elenco di modelli predefiniti, oltre ai modelli personalizzati. Sono inclusi solo i modelli con stato operazione riuscita. I modelli in corso o non riusciti possono essere enumerati tramite la richiesta Elenca operazioni. Usare la proprietà nextLink per accedere alla pagina successiva dei modelli, se presente. Per ottenere altre informazioni su ogni modello restituito, incluso l'elenco di documenti supportati e i relativi campi, passare modelId alla richiesta Get Model.

curl -v -X GET "https://{endpoint}/formrecognizer/documentModels?api-version=2021-09-30-preview"

Ottenere un modello specifico

Il modello Get di anteprima v3.0 recupera informazioni su un modello specifico con stato operazione riuscita. Per i modelli non riusciti e in corso, usare l'operazione Get per tenere traccia dello stato delle operazioni di creazione del modello ed eventuali errori risultanti.

curl -v -X GET "https://{endpoint}/formrecognizer/documentModels/{modelId}?api-version=2021-09-30-preview" -H "Ocp-Apim-Subscription-Key: {subscription key}"

Eliminare un modello

La richiesta di eliminazione del modello di anteprima v3.0 rimuove il modello personalizzato e modelId non è più accessibile dalle operazioni future. È possibile creare nuovi modelli usando lo stesso modelId senza conflitti.

curl -v -X DELETE "https://{endpoint}/formrecognizer/documentModels/{modelId}?api-version=2021-09-30-preview" -H "Ocp-Apim-Subscription-Key: {subscription key}"

Passaggi successivi

In questa guida introduttiva è stata usata l'anteprima riconoscimento modulo API REST (v3.0) per analizzare i moduli in modi diversi. Esaminare quindi la documentazione di riferimento per altre informazioni sull'API riconoscimento modulo più approfondita.