Snabbstart: REST API | Förhandsgranska
Anteckning
Formigenkänning v3.0 finns för närvarande i offentlig förhandsversion. Vissa funktioner kanske inte stöds eller har begränsade funktioner.
| Formigenkänning REST API | Referens REST API Azure REST API Azure |
Kom igång med Azure Formigenkänning med hjälp av programmeringsspråket C#. Azure Formigenkänning är en molnbaserad Azure Applied AI-tjänst som använder maskininlärning för att extrahera och analysera formulärfält, text och tabeller från dina dokument. Du kan enkelt anropa Formigenkänning modeller genom att integrera våra klientbiblioteks-SDks i dina arbetsflöden och program. Vi rekommenderar att du använder den kostnadsfria tjänsten när du lär dig tekniken. Kom ihåg att antalet kostnadsfria sidor är begränsat till 500 per månad.
Mer information om Formigenkänning och utvecklingsalternativ finns på översiktssidan.
Formigenkänning modeller
Den REST API stöder följande modeller och funktioner:
- 🆕Allmänt dokument – Analysera och extrahera text, tabeller, struktur, nyckel/värde-par och namngivna entiteter.|
- Layout – Analysera och extrahera tabeller, linjer, ord och markeringsmarkeringar som alternativknappar och kryssrutor i formulärdokument, utan att du behöver träna en modell.
- Anpassad – Analysera och extrahera formulärfält och annat innehåll från dina anpassade formulär med hjälp av modeller som du har tränat med dina egna formulärtyper.
- Fakturor – Analysera och extrahera vanliga fält från fakturor med hjälp av en förtränad fakturamodell.
- Kvitton – Analysera och extrahera vanliga fält från kvitton med hjälp av en förtränad kvittomodell.
- ID-dokument – Analysera och extrahera vanliga fält från ID-dokument som pass eller förarlicenser med hjälp av en förtränad ID-dokumentmodell.
- Visitkort – Analysera och extrahera vanliga fält från visitkort med hjälp av en förtränad visitkortsmodell.
Analysera dokument
Formigenkänning v3.0 konsoliderar åtgärderna analysera dokument och get(analyze result) för layout, fördefinierade modeller och anpassade modeller till ett enda par åtgärder genom att tilldela till POST- och modelIds GET-åtgärderna:
POST /documentModels/{modelId}:analyze
GET /documentModels/{modelId}/analyzeResults/{resultId}
I följande tabell visas uppdateringarna för de REST API anropen.
| Funktion | v2.1 | v3.0 |
|---|---|---|
| Allmänt dokument | saknas | /documentModels/prebuilt-document:analyze |
| Layout | /layout/analyze |
/documentModels/prebuilt-layout:analyze |
| Faktura | /prebuilt/invoice/analyze |
/documentModels/prebuilt-invoice:analyze |
| Mottagandet | /prebuilt/receipt/analyze |
/documentModels/prebuilt-receipt:analyze |
| ID-dokument | /prebuilt/idDocument/analyze |
/documentModels/prebuilt-idDocument:analyze |
| Visitkort | /prebuilt/businessCard/analyze |
/documentModels/prebuilt-businessCard:analyze |
| Anpassat | /custom/{modelId}/analyze |
/documentModels/{modelId}:analyze |
I den här snabbstarten använder du följande funktioner för att analysera och extrahera data och värden från formulär och dokument:
🆕 dokument –Analysera och extrahera text, tabeller, struktur, nyckel/värde-par och namngivna entiteter.
Layout– Analysera och extrahera tabeller, linjer, ord och markeringsmarkeringar som alternativknappar och kryssrutor i formulärdokument, utan att du behöver träna en modell.
Förbyggd modell – Analyseraoch extrahera data från vanliga dokumenttyper med hjälp av en förtränad modell.
Förutsättningar
Azure-prenumeration – Skapa en kostnadsfritt
cURL installerat.
PowerShell version 6.0+eller ett liknande kommandoradsprogram.
En Cognitive Services eller Formigenkänning resurs. När du har din Azure-prenumeration kan du skapa en resurs för Formigenkänning tjänst eller flera tjänster i Azure Portal för att hämta din nyckel och slutpunkt. Du kan använda den kostnadsfria prisnivån (
F0) för att prova tjänsten och senare uppgradera till en betald nivå för produktion.
Tips
Skapa en Cognitive Services resurs om du planerar att komma åt flera kognitiva tjänster under en enda slutpunkt/nyckel. För Formigenkänning åtkomst skapar du en Formigenkänning resurs. Observera att du behöver en resurs för en enskild tjänst om du planerar att använda Azure Active Directory autentisering.
När resursen har distribuerats väljer du Gå till resurs. Du behöver nyckeln och slutpunkten från resursen som du skapar för att ansluta ditt program till Formigenkänning API. Du klistrar in nyckeln och slutpunkten i koden nedan senare i snabbstarten:
Välj ett kodexempel som du vill kopiera och klistra in i programmet:
Viktigt
Kom ihåg att ta bort nyckeln från koden när du är klar och aldrig publicera den offentligt. För produktion använder du säkra metoder för att lagra och komma åt dina autentiseringsuppgifter. Mer information finns Cognitive Services artikeln om säkerhet.
Prova: Allmän dokumentmodell
- I det här exemplet behöver du en formulärdokumentfil på en URI. Du kan använda vårt exempelformulärdokument för den här snabbstarten. Innan du kör kommandot gör du följande ändringar:
- Ersätt
{endpoint}med den slutpunkt som du fick med din Formigenkänning prenumeration. - Ersätt
{subscription key}med prenumerationsnyckeln som du kopierade från föregående steg. - Ersätt
{your-document-url}med en url till exempelformulärets dokument.
Förfrågan
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
Du får ett svar 202 (Success) som innehåller rubriken Operation-Location. Värdet för den här rubriken innehåller ett resultat-ID som du kan använda för att fråga efter status för den asynkrona åtgärden och hämta resultatet:
https://{host}/formrecognizer/documentModels/{modelId}/analyzeResults/{resultId}?api-version=2021-09-30-preview
Hämta allmänna dokumentresultat
När du har anropat API:et Analysera dokument anropar du API:et Get analyze result (Hämta analysresultat) för att hämta status för åtgärden och extraherade data. Innan du kör kommandot gör du följande ändringar:
- Ersätt
{endpoint}med den slutpunkt som du fick med din Formigenkänning prenumeration. - Ersätt
{subscription key}med prenumerationsnyckeln som du kopierade från föregående steg. - Ersätt
{resultId}med resultat-ID:t från föregående steg.
Förfrågan
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}"
Granska svaret
Du får ett svar med 200 (Success) JSON-utdata. Det första "status" fältet, , anger status för åtgärden. Om åtgärden inte slutförs blir värdet eller , och du bör anropa API:et "status" "running" "notStarted" igen, antingen manuellt eller via ett skript. Vi rekommenderar ett intervall på en sekund eller mer mellan anrop.
Noden "analyzeResults" innehåller all tolkad text. Text ordnas efter sida, rader, tabeller, nyckel/värde-par och entiteter.
Exempelsvar
{
"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: Layoutmodell
- I det här exemplet behöver du en formulärdokumentfil på en URI. Du kan använda vårt exempelformulärdokument för den här snabbstarten.
Innan du kör kommandot gör du följande ändringar:
- Ersätt
{endpoint}med den slutpunkt som du fick med din Formigenkänning prenumeration. - Ersätt
{subscription key}med prenumerationsnyckeln som du kopierade från föregående steg. - Ersätt
"{your-document-url}med en av exempel-URL:erna.
Förfrågan
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
Du får ett svar 202 (Success) som innehåller rubriken Operation-Location. Värdet för den här rubriken innehåller ett resultat-ID som du kan använda för att fråga efter status för den asynkrona åtgärden och hämta resultatet:
https://{host}/formrecognizer/documentModels/{modelId}/analyzeResults/**{resultId}**?api-version=2021-09-30-preview
Hämta layoutresultat
När du har anropat API:et Analysera dokument anropar du API:et Get analyze result (Hämta analysresultat) för att hämta status för åtgärden och extraherade data. Innan du kör kommandot gör du följande ändringar:
- Ersätt
{endpoint}med den slutpunkt som du fick med din Formigenkänning prenumeration. - Ersätt
{subscription key}med prenumerationsnyckeln som du kopierade från föregående steg. - Ersätt
{resultId}med resultat-ID:t från föregående steg.
Förfrågan
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}"
Granska svaret
Du får ett svar med 200 (Success) JSON-utdata. Det första "status" fältet, , anger status för åtgärden. Om åtgärden inte slutförs blir värdet eller , och du bör anropa API:et "status" "running" "notStarted" igen, antingen manuellt eller via ett skript. Vi rekommenderar ett intervall på en sekund eller mer mellan anrop.
Prova: Förbyggd modell
Det här exemplet visar hur du analyserar data från vissa vanliga dokumenttyper med en förtränad modell med hjälp av en faktura som exempel.
- I det här exemplet analyserar vi ett fakturadokument med hjälp av en förbyggd modell. Du kan använda vårt exempelfakturadokument för den här snabbstarten.
Välj det fördefinierade modell-ID:t för fakturan
Du är inte begränsad till fakturor – det finns flera fördefinierade modeller att välja mellan, där var och en har en egen uppsättning fält som stöds. Vilken modell som ska användas för analysåtgärden beror på vilken typ av dokument som ska analyseras. Här är modell-ID:erna för de fördefinierade modeller som stöds av Formigenkänning tjänsten:
- prebuilt-invoice: extraherar text, markeringsmarkeringar, tabeller, nyckel/värde-par och nyckelinformation från fakturor.
- prebuilt-businessCard: extraherar text och viktig information från visitkort.
- prebuilt-idDocument: extraherar text- och nyckelinformation från drivrutinslicenser och internationella pass.
- prebuilt-receipt: extraherar text- och nyckelinformation från kvitton.
Innan du kör kommandot gör du följande ändringar:
Ersätt
{endpoint}med den slutpunkt som du fick med din Formigenkänning prenumeration.Ersätt
{subscription key}med prenumerationsnyckeln som du kopierade från föregående steg.Ersätt
\"{your-document-url}med en exempelfaktura-URL:https://raw.githubusercontent.com/Azure-Samples/cognitive-services-REST-api-samples/master/curl/form-recognizer/sample-invoice.pdf
Förfrågan
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
Du får ett svar 202 (Success) som innehåller rubriken Operation-Location. Värdet för den här rubriken innehåller ett resultat-ID som du kan använda för att fråga efter status för den asynkrona åtgärden och hämta resultatet:
https://{host}/formrecognizer/documentModels/{modelId}/analyzeResults/{resultId}?api-version=2021-09-30-preview
Hämta fakturaresultat
När du har anropat API:et Analysera dokument anropar du API:et Get analyze result (Hämta analysresultat) för att hämta status för åtgärden och extraherade data. Innan du kör kommandot gör du följande ändringar:
- Ersätt
{endpoint}med den slutpunkt som du fick med din Formigenkänning prenumeration. - Ersätt
{subscription key}med prenumerationsnyckeln som du kopierade från föregående steg. - Ersätt
{resultId}med resultat-ID:t från föregående steg.
Förfrågan
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}"
Granska svaret
Du får ett svar med 200 (Success) JSON-utdata. Det första "status" fältet, , anger status för åtgärden. Om åtgärden inte slutförs blir värdet eller , och du bör anropa API:et "status" "running" "notStarted" igen, antingen manuellt eller via ett skript. Vi rekommenderar ett intervall på en sekund eller mer mellan anrop.
Förbättra resultaten
Granska värdena "confidence" för varje nyckel/värde-resultat under "pageResults" noden. Du bör också titta på förtroendepoängen i "readResults" noden, som motsvarar textläsningsåtgärden. Konfidensen för läsningsresultaten påverkar inte konfidensen för nyckel/värde-extraheringsresultaten, så du bör kontrollera båda.
- Om förtroendepoängen för läsåtgärden är låga kan du försöka förbättra kvaliteten på dina indatadokument (se Indatakrav).
- Om förtroendepoängen för nyckel-/värde-extraheringsåtgärden är låga ser du till att dokumenten som analyseras är av samma typ som dokumenten som används i träningsuppsättningen. Om dokumenten i träningsuppsättningen har variationer i utseendet kan du dela upp dem i olika mappar och träna en modell för varje variant.
Förtroendepoängen du riktar in dig på beror på ditt användningsfall, men vanligtvis är det en bra idé att rikta en poäng på 80 % eller högre. För känsligare fall, till exempel läsning av medicinska journaler eller faktureringsutdrag, rekommenderas en poäng på 100 %.
Hantera anpassade modeller
Hämta en lista över modeller
Förhandsversionen av begäran om v3.0-lista över modeller returnerar en sidindelade lista med fördefinierade modeller utöver anpassade modeller. Endast modeller med statusen lyckades ingår. Pågående eller misslyckade modeller kan räknas upp via begäran om liståtgärder. Använd egenskapen nextLink för att komma åt nästa sida med modeller, om det finns några. Om du vill ha mer information om varje returnerad modell, inklusive listan över dokument som stöds och deras fält, skickar du modelId till begäran Hämtamodell.
curl -v -X GET "https://{endpoint}/formrecognizer/documentModels?api-version=2021-09-30-preview"
Hämta en specifik modell
Förhandsversionen v3.0 Hämta modell hämtar information om en specifik modell med statusen lyckades. För misslyckade modeller och pågående modeller använder du Hämta åtgärd för att spåra status för åtgärder för modellskapande och eventuella resulterande fel.
curl -v -X GET "https://{endpoint}/formrecognizer/documentModels/{modelId}?api-version=2021-09-30-preview" -H "Ocp-Apim-Subscription-Key: {subscription key}"
Ta bort en modell
Förhandsversionen v3.0 Ta bort modellbegäran tar bort den anpassade modellen och modelId kan inte längre användas av framtida åtgärder. Nya modeller kan skapas med samma modelId utan konflikt.
curl -v -X DELETE "https://{endpoint}/formrecognizer/documentModels/{modelId}?api-version=2021-09-30-preview" -H "Ocp-Apim-Subscription-Key: {subscription key}"
Nästa steg
I den här snabbstarten använde du Formigenkänning REST API (v3.0) för att analysera formulär på olika sätt. Utforska sedan referensdokumentationen för att lära dig Formigenkänning API på djupet.