Rychlý start: REST API | Náhled

Článek
11/24/2021
9 min ke čtení

Poznámka

Rozpoznávání formulářů verze 3.0 je aktuálně ve verzi Public Preview. Některé funkce nemusí být podporované nebo mají omezené možnosti.

| Rozpoznávání formulářů REST API | Referenční informace REST API Azure |

Začínáme s Azure Rozpoznávání formulářů s využitím programovacího jazyka C#. Azure Rozpoznávání formulářů je cloudová služba Azure Applied AI Service, která pomocí strojového učení extrahuje a analyzuje pole formuláře, text a tabulky z vašich dokumentů. Můžete snadno volat Rozpoznávání formulářů integrací našich klientských knihoven SDK do vašich pracovních postupů a aplikací. Doporučujeme používat bezplatnou službu, když se s technologií učíte. Nezapomeňte, že počet bezplatných stránek je omezený na 500 za měsíc.

Další informace o funkcích Rozpoznávání formulářů a možnostech vývoje najdete na naší stránce Přehled.

Rozpoznávání formulářů modelů

Následující REST API podporuje následující modely a možnosti:

🆕Obecné – analýza a extrakce textu, tabulek, struktury, párů klíč-hodnota a pojmenovaných entit.|
Rozložení – analyzujte a extrahujte tabulky, řádky, slova a značky výběru, jako jsou přepínače a zaškrtávací políčka ve formulářích dokumentů, aniž byste trénovali model.
Vlastní– analyzujte a extrahujte pole formuláře a další obsah z vlastních formulářů pomocí modelů, které jste natrénovali s vlastními typy formulářů.
Faktury – Analyzujte a extrahujte běžná pole z faktur pomocí předem natrénovaných modelů faktur.
Účtenky – analyzujte a extrahujte běžná pole z účtenek pomocí předem natrénovaných modelů účtenek.
Dokumenty ID – analyzujte a extrahujte běžná pole z dokumentů ID, jako jsou pasy nebo licence řidičů, pomocí předem natrénovaných modelů dokumentů ID.
Vizitky – Analyzujte a extrahujte běžná pole z vizitků pomocí předem natrénovaných modelů s vizitkou.

Analýza dokumentu

Rozpoznávání formulářů v3.0 konsoliduje analýzu dokumentu a získání operací analýzy výsledků (GET) pro rozložení, předem sestavené modely a vlastní modely do jedné dvojice operací přiřazením k operacím POST a  modelIds GET:

POST /documentModels/{modelId}:analyze

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

Následující tabulka znázorňuje aktualizace volání REST API dat.

Funkce	v2.1	v3.0
Obecný dokument	Není k dispozici	`/documentModels/prebuilt-document:analyze`
Layout	`/layout/analyze`	`/documentModels/prebuilt-layout:analyze`
Faktura	`/prebuilt/invoice/analyze`	`/documentModels/prebuilt-invoice:analyze`
Příjmu	`/prebuilt/receipt/analyze`	`/documentModels/prebuilt-receipt:analyze`
Dokument ID	`/prebuilt/idDocument/analyze`	`/documentModels/prebuilt-idDocument:analyze`
Vizitka	`/prebuilt/businessCard/analyze`	`/documentModels/prebuilt-businessCard:analyze`
Vlastní	`/custom/{modelId}/analyze`	`/documentModels/{modelId}:analyze`

V tomto rychlém startu použijete následující funkce k analýze a extrahování dat a hodnot z formulářů a dokumentů:

🆕 obecný dokument– analýza a extrahování textu, tabulek, struktury, párů klíč-hodnota a pojmenovaných entit
Rozložení– analyzujte a extrahujte tabulky, řádky, slova a značky výběru, jako jsou přepínače a zaškrtávací políčka ve formulářích dokumentů, aniž byste trénovali model.
Předem připravený model –analýza a extrahování dat z běžných typů dokumentů pomocí předem vytrénovaných modelů

Požadavky

Předplatné Azure – Vytvořte si ho zdarma.
Nainstalovaný cURL.
PowerShell verze 6.0 nebonovější nebo podobná aplikace příkazového řádku.
Prostředek Cognitive Services nebo Rozpoznávání formulářů. Jakmile máte předplatné Azure, vytvořte prostředek služby s jednou nebo více Rozpoznávání formulářů ve službě Azure Portal a získejte svůj klíč a koncový bod. K vyzkoušejí služby můžete použít bezplatnou cenovou úroveň ( ) a později upgradovat F0 na placenou úroveň pro produkční prostředí.

Tip

Pokud plánujete Cognitive Services více kognitivních služeb v rámci jednoho koncového bodu nebo klíče, vytvořte nový prostředek. Pro Rozpoznávání formulářů přístup vytvořte prostředek Rozpoznávání formulářů. Upozorňujeme, že pokud chcete použít ověřování pomocí služby , budete potřebovat Azure Active Directory službu.

Po nasazení prostředku vyberte Přejít k prostředku. Klíč a koncový bod z prostředku, který vytvoříte, potřebujete pro připojení aplikace k Rozpoznávání formulářů API. Klíč a koncový bod vložíte do kódu níže v pozdější části tohoto rychlého startu:

Vyberte vzorový kód, který chcete zkopírovat a vložit do aplikace:

Obecný dokument
Layout
Předem připravený model

Důležité

Až budete hotovi, nezapomeňte klíč z kódu odebrat a nikdy ho veřejně ne zveřejníte. V produkčním prostředí použijte zabezpečené metody pro ukládání přihlašovacích údajů a přístup k přihlašovacím údajům. Další informace najdete Cognitive Services zabezpečení sítě.

Vyzkoušet: Obecný model dokumentu

V tomto příkladu budete potřebovat soubor dokumentu formuláře s identifikátorem URI. Pro tento rychlý start můžete použít náš ukázkový dokument formuláře. Před spuštěním příkazu proveďte tyto změny:

Nahraďte {endpoint} koncovým bodem, který jste získali pomocí Rozpoznávání formulářů předplatného.
Nahraďte {subscription key} klíčem předplatného, který jste zkopíroval v předchozím kroku.
Nahraďte {your-document-url} adresou URL dokumentu ukázkového formuláře.

Žádost

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

Obdržíte 202 (Success) odpověď, která obsahuje hlavičku Operation-Location. Hodnota této hlavičky obsahuje ID výsledku, které můžete použít k dotazování stavu asynchronní operace a získání výsledků:

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

Získání obecných výsledků dokumentů

Jakmile zavoláte rozhraní API pro analýzu dokumentu, zavolejte rozhraní API Get analyze result a získejte stav operace a extrahovaných dat. Před spuštěním příkazu proveďte tyto změny:

Nahraďte {endpoint} koncovým bodem, který jste získali pomocí Rozpoznávání formulářů předplatného.
Nahraďte {subscription key} klíčem předplatného, který jste zkopíroval v předchozím kroku.
Nahraďte {resultId} ID výsledku z předchozího kroku.

Žádost

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}"

Prozkoumání odpovědi

Obdržíte odpověď s 200 (Success) výstupem JSON. První pole "status" označuje stav operace. Pokud operace není dokončená, hodnota bude nebo a rozhraní API byste měli volat znovu, a to buď ručně, nebo "status" "running" prostřednictvím "notStarted" skriptu. Mezi voláními doporučujeme interval jedné sekundy nebo více.

Uzel "analyzeResults" obsahuje veškerý rozpoznaný text. Text je uspořádaný podle stránek, řádků, tabulek, párů klíč-hodnota a entit.

Ukázková odpověď

{
    "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
                    }
                ]
            }
        ]
    }
}

Vyzkoušet: Model rozložení

V tomto příkladu budete potřebovat soubor dokumentu formuláře s identifikátorem URI. Pro tento rychlý start můžete použít náš ukázkový dokument formuláře.

Před spuštěním příkazu proveďte tyto změny:

Nahraďte {endpoint} koncovým bodem, který jste získali pomocí Rozpoznávání formulářů předplatného.
Nahraďte {subscription key} klíčem předplatného, který jste zkopíroval v předchozím kroku.
Nahraďte "{your-document-url} jednou z příkladových adres URL.

Žádost

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

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

Získání výsledků rozložení

Nahraďte {endpoint} koncovým bodem, který jste získali pomocí Rozpoznávání formulářů předplatného.
Nahraďte {subscription key} klíčem předplatného, který jste zkopíroval v předchozím kroku.
Nahraďte {resultId} ID výsledku z předchozího kroku.

Žádost

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}"

Prozkoumání odpovědi

Vyzkoušet: Předem připravený model

Tato ukázka ukazuje, jak analyzovat data z určitých běžných typů dokumentů s předem natrénovaný model a jako příklad použít fakturu.

V tomto příkladu analyzujeme dokument faktury pomocí předem sestavených modelů. Pro tento rychlý start můžete použít náš ukázkový dokument faktury.

Volba ID modelu předem sestavené faktury

Nejste omezeni na faktury – existuje několik předem připravených modelů, ze kterých si můžete vybrat, z nichž každý má vlastní sadu podporovaných polí. Model, který se má použít pro operaci analýzy, závisí na typu dokumentu, který se má analyzovat. Tady jsou ID modelů pro předem sestavené modely, které aktuálně podporuje Rozpoznávání formulářů služby:

prebuilt-invoice: Extrahuje text, značky výběru, tabulky, páry klíč-hodnota a klíčové informace z faktur.
prebuilt-businessCard: Extrahuje textové a klíčové informace z vizitek.
prebuilt-idDocument: Extrahuje textové a klíčové informace z řidičský průkazů a mezinárodních pasů.
prebuilt-receipt: Extrahuje z účtenek textové a klíčové informace.

Před spuštěním příkazu proveďte tyto změny:

Nahraďte {endpoint} koncovým bodem, který jste získali pomocí Rozpoznávání formulářů předplatného.
Nahraďte {subscription key} klíčem předplatného, který jste zkopíroval v předchozím kroku.

Nahraďte \"{your-document-url} ukázkovou adresou URL faktury:

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

Žádost

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

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

Získání výsledků faktury

Nahraďte {endpoint} koncovým bodem, který jste získali pomocí Rozpoznávání formulářů předplatného.
Nahraďte {subscription key} klíčem předplatného, který jste zkopíroval v předchozím kroku.
Nahraďte {resultId} ID výsledku z předchozího kroku.

Žádost

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}"

Prozkoumání odpovědi

Vylepšení výsledků

Prověřte "confidence" hodnoty pro každý výsledek klíč/hodnota pod "pageResults" uzlem. Měli byste se také podívat na skóre spolehlivosti v "readResults" uzlu, který odpovídá operaci čtení textu. Spolehlivost výsledků čtení neovlivňuje spolehlivost výsledků extrakce klíč/hodnota, proto byste měli zaškrtnout obě.

Pokud jsou skóre spolehlivosti pro operaci čtení nízká, zkuste zlepšit kvalitu vstupních dokumentů (viz požadavky na vstup).
Pokud jsou skóre spolehlivosti pro operaci extrakce klíč/hodnota nízká, zajistěte, aby analyzované dokumenty byly stejného typu jako dokumenty používané v sadě školení. Pokud se v dokumentech v sadě školení nacházejí změny, zvažte jejich rozdělení do různých složek a školení jednoho modelu pro každou variaci.

Hodnocení spolehlivosti bude záviset na vašem případu použití, ale obecně je dobrým zvykem zaměřit se na skóre 80% nebo vyšší. Pro citlivější případy, jako je čtení lékařských záznamů nebo výpisů faktur, se doporučuje skóre 100%.

Správa vlastních modelů

Získání seznamu modelů

Požadavek na seznam  modelů verze Preview v3.0 vrátí kromě vlastních modelů stránkovaný seznam předem připravených modelů. Jsou zahrnuty pouze modely se stavem úspěch. Probíhající nebo neúspěšné modely je možné vyčíslovat prostřednictvím požadavku List Operations (Vypište operace). Pomocí vlastnosti nextLink můžete získat přístup k další stránce modelů, pokud je k dispozici. Pokud chcete získat další informace o každém vráceném modelu, včetně seznamu podporovaných dokumentů a jejich polí, předejte modelId požadavku Get Model.

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

Získání konkrétního modelu

Verze Preview v3.0 Získání modelu načte informace o konkrétním modelu se stavem Úspěch. Pro neúspěšné a probíhající modely použijte operaci Get ke sledování stavu operací vytvoření modelu a všech výsledných chyb.

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

Odstranění modelu

Požadavek na odstranění modelu verze Preview v3.0 odebere vlastní model a budoucí operace už nebudou mít přístup k modelu modelId. Nové modely je možné vytvořit pomocí stejného id modelu bez konfliktu.

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

Další kroky

V tomto rychlém startu jste použili Rozpoznávání formulářů REST API Preview (v3.0) k různým způsobům analýzy formulářů. Dále si projděte referenční dokumentaci, ve které se dozvíte Rozpoznávání formulářů api do hloubky.

REST API preview (v3.0) – referenční dokumentace

Rychlý start: REST API | Náhled

Ohodnoťte vaše zkušenosti

Rozpoznávání formulářů modelů

Analýza dokumentu

Požadavky

Vyberte vzorový kód, který chcete zkopírovat a vložit do aplikace:

Vyzkoušet: Obecný model dokumentu

Žádost

Operation-Location

Získání obecných výsledků dokumentů

Žádost

Prozkoumání odpovědi

Ukázková odpověď

Vyzkoušet: Model rozložení

Žádost

Operation-Location

Získání výsledků rozložení

Žádost

Prozkoumání odpovědi

Vyzkoušet: Předem připravený model

Volba ID modelu předem sestavené faktury

Žádost

Operation-Location

Získání výsledků faktury

Žádost

Prozkoumání odpovědi

Vylepšení výsledků

Správa vlastních modelů

Získání seznamu modelů

Získání konkrétního modelu

Odstranění modelu

Další kroky