Quickstart: REST API | Voorbeeld
Notitie
Form Recognizer versie 3.0 is momenteel beschikbaar als openbare preview. Sommige functies worden mogelijk niet ondersteund of hebben beperkte mogelijkheden.
| Form Recognizer REST API | Naslag voor Azure REST API |
Aan de slag met Azure Form Recognizer de programmeertaal C#. Azure Form Recognizer is een cloudgebaseerde, door Azure toegepaste AI-service die gebruikmaakt van machine learning voor het extraheren en analyseren van formuliervelden, tekst en tabellen uit uw documenten. U kunt eenvoudig een Form Recognizer aanroepen door onze clientbibliotheek-SDK's te integreren in uw werkstromen en toepassingen. U wordt aangeraden de gratis service te gebruiken wanneer u de technologie leert. Houd er rekening mee dat het aantal gratis pagina's beperkt is tot 500 per maand.
Ga naar onze overzichtspagina Form Recognizer meer informatie over de functies en ontwikkelingsopties.
Form Recognizer modellen
De REST API ondersteunt de volgende modellen en mogelijkheden:
- 🆕Algemeen document: tekst, tabellen, structuur, sleutel-waardeparen en benoemde entiteiten analyseren en extraheren.|
- Indeling: tabellen, lijnen, woorden en selectiemarkeringen zoals keuzerondjes en selectievakjes in formulierendocumenten analyseren en extraheren, zonder dat u een model hoeft te trainen.
- Aangepast: formuliervelden en andere inhoud uit uw aangepaste formulieren analyseren en extraheren met behulp van modellen die u hebt getraind met uw eigen formuliertypen.
- Facturen: algemene velden analyseren en extraheren uit facturen met behulp van een vooraf getraind factuurmodel.
- Ontvangstbewijzen: analyseer en extraheert algemene velden uit bonnen met behulp van een vooraf getraind ontvangstbewijsmodel.
- Id-documenten: analyseer en extraheert algemene velden uit id-documenten zoals passports of licenties voor stuurprogramma's, met behulp van een vooraf getraind model met id-documenten.
- Visitekaartjes: algemene velden analyseren en extraheren uit visitekaartjes met behulp van een vooraf getraind visitekaartjesmodel.
Document analyseren
Form Recognizer v3.0 consolideert het analysedocument en krijgt u GET-bewerkingen (Analyze Result) voor indeling, vooraf gemaakte modellen en aangepaste modellen in één paar bewerkingen door toe te wijzen aan de POST- en modelIds GET-bewerkingen:
POST /documentModels/{modelId}:analyze
GET /documentModels/{modelId}/analyzeResults/{resultId}
De volgende tabel illustreert de updates van de REST API aanroepen.
| Functie | v2.1 | v3.0 |
|---|---|---|
| Algemeen document | n.v.t. | /documentModels/prebuilt-document:analyze |
| Layout | /layout/analyze |
/documentModels/prebuilt-layout:analyze |
| Factuur | /prebuilt/invoice/analyze |
/documentModels/prebuilt-invoice:analyze |
| Ontvangst | /prebuilt/receipt/analyze |
/documentModels/prebuilt-receipt:analyze |
| Id-document | /prebuilt/idDocument/analyze |
/documentModels/prebuilt-idDocument:analyze |
| Visitekaartje | /prebuilt/businessCard/analyze |
/documentModels/prebuilt-businessCard:analyze |
| Aangepast telefoonnummer | /custom/{modelId}/analyze |
/documentModels/{modelId}:analyze |
In deze quickstart gebruikt u de volgende functies om gegevens en waarden uit formulieren en documenten te analyseren en te extraheren:
🆕 document :tekst, tabellen, structuur, sleutel-waardeparen en benoemde entiteiten analyseren en extraheren.
Indeling:tabellen, lijnen, woorden en selectiemarkeringen zoals keuzerondjes en selectievakjes in formulierendocumenten analyseren en extraheren, zonder dat u een model hoeft te trainen.
Vooraf gebouwd model:gegevens analyseren en extraheren uit algemene documenttypen, met behulp van een vooraf getraind model.
Vereisten
Azure-abonnement: Krijg een gratis abonnement
cURL moet zijn geïnstalleerd.
PowerShell versie 6.0+of een vergelijkbare opdrachtregeltoepassing.
Een Cognitive Services of Form Recognizer resource. Zodra u uw Azure-abonnement hebt, maakt u een resource voor één service of Form Recognizer voor meerdere Azure Portal om uw sleutel en eindpunt op te halen. U kunt de gratis prijscategorie (
F0) gebruiken om de service uit te proberen, en later upgraden naar een betaalde laag voor productie.
Tip
Maak een Cognitive Services als u van plan bent toegang te krijgen tot meerdere cognitieve services onder één eindpunt/sleutel. Als Form Recognizer alleen toegang hebt, maakt u een Form Recognizer resource. Houd er rekening mee dat u een resource voor één service nodig hebt als u van plan bent om Azure Active Directory gebruiken.
Nadat uw resource is geïmplementeerd, selecteert u Ga naar resource. U hebt de sleutel en het eindpunt nodig van de resource die u maakt om uw toepassing te verbinden met Form Recognizer API. U plakt uw sleutel en eindpunt later in de onderstaande code in de quickstart:
Selecteer een codevoorbeeld dat u in uw toepassing wilt kopiëren en plakken:
Belangrijk
Vergeet niet de sleutel uit uw code te verwijderen wanneer u klaar bent, en plaats deze sleutel nooit in het openbaar. Gebruik voor productie beveiligde methoden om uw referenties op te slaan en te openen. Zie het artikel Cognitive Services Beveiliging voor meer informatie.
Probeer het: Algemeen documentmodel
- Voor dit voorbeeld hebt u een formulierdocumentbestand op een URI nodig. U kunt ons voorbeeldformulierdocument gebruiken voor deze quickstart. Voordat u de opdracht uitvoert, moet u de volgende wijzigingen aanbrengen:
- Vervang
{endpoint}door het eindpunt dat u hebt verkregen met uw Form Recognizer-abonnement. - Vervang
{subscription key}door de abonnementssleutel die u uit de vorige stap hebt gekopieerd. - Vervang
{your-document-url}door de URL van een voorbeeldformulierdocument.
Aanvraag
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
U ontvangt een antwoord 202 (Success) met een Bewerkingslocatie-header. De waarde van deze header bevat een resultaat-id die u kunt gebruiken om de status van de asynchrone bewerking op te vragen en de resultaten op te halen:
https://{host}/formrecognizer/documentModels/{modelId}/analyzeResults/{resultId}?api-version=2021-09-30-preview
Algemene documentresultaten krijgen
Nadat u de Document-API analyseren hebt aangeroepen, roept u de API Resultaat analyseren op om de status van de bewerking en de geëxtraheerde gegevens op te halen. Voordat u de opdracht uitvoert, moet u de volgende wijzigingen aanbrengen:
- Vervang
{endpoint}door het eindpunt dat u hebt verkregen met uw Form Recognizer-abonnement. - Vervang
{subscription key}door de abonnementssleutel die u uit de vorige stap hebt gekopieerd. - Vervang
{resultId}door de resultaat-id uit de vorige stap.
Aanvraag
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}"
Het antwoord bekijken
U ontvangt een 200 (Success) antwoord met JSON-uitvoer. Het eerste veld, "status", geeft de status van de bewerking aan. Als de bewerking niet is voltooid, wordt de waarde van "status" "running" of "notStarted". U moet de API opnieuw aanroepen, handmatig of via een script. We raden een interval van één seconde of meer aan tussen oproepen.
Het knooppunt "analyzeResults" bevat alle herkende tekst. Tekst is ingedeeld op pagina,regels, tabellen, sleutel-waardeparen en entiteiten.
Voorbeeldantwoord
{
"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
}
]
}
]
}
}
Probeer het: Indelingsmodel
- Voor dit voorbeeld hebt u een formulierdocumentbestand op een URI nodig. U kunt ons voorbeeldformulierdocument gebruiken voor deze quickstart.
Voordat u de opdracht uitvoert, moet u de volgende wijzigingen aanbrengen:
- Vervang
{endpoint}door het eindpunt dat u hebt verkregen met uw Form Recognizer-abonnement. - Vervang
{subscription key}door de abonnementssleutel die u uit de vorige stap hebt gekopieerd. - Vervang
"{your-document-url}door een van de voorbeeld-URL's.
Aanvraag
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
U ontvangt een antwoord 202 (Success) met een Bewerkingslocatie-header. De waarde van deze header bevat een resultaat-id die u kunt gebruiken om de status van de asynchrone bewerking op te vragen en de resultaten op te halen:
https://{host}/formrecognizer/documentModels/{modelId}/analyzeResults/**{resultId}**?api-version=2021-09-30-preview
Indelingsresultaten ophalen
Nadat u de Document-API analyseren hebt aangeroepen, roept u de API Resultaat analyseren op om de status van de bewerking en de geëxtraheerde gegevens op te halen. Voordat u de opdracht uitvoert, moet u de volgende wijzigingen aanbrengen:
- Vervang
{endpoint}door het eindpunt dat u hebt verkregen met uw Form Recognizer-abonnement. - Vervang
{subscription key}door de abonnementssleutel die u uit de vorige stap hebt gekopieerd. - Vervang
{resultId}door de resultaat-id uit de vorige stap.
Aanvraag
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}"
Het antwoord bekijken
U ontvangt een 200 (Success) antwoord met JSON-uitvoer. Het eerste veld, "status", geeft de status van de bewerking aan. Als de bewerking niet is voltooid, wordt de waarde van "status" "running" of "notStarted". U moet de API opnieuw aanroepen, handmatig of via een script. We raden een interval van één seconde of meer aan tussen oproepen.
Uitproberen: vooraf gebouwd model
In dit voorbeeld wordt gedemonstreerd hoe u gegevens van bepaalde algemene documenttypen kunt analyseren met een vooraf getraind model, met behulp van een factuur als voorbeeld.
- In dit voorbeeld analyseren we een factuurdocument met behulp van een vooraf gebouwd model. U kunt ons voorbeelddocument met facturen gebruiken voor deze quickstart.
De vooraf gebouwde model-id voor facturen kiezen
U bent niet beperkt tot facturen: er zijn verschillende vooraf gebouwde modellen waaruit u kunt kiezen, die elk een eigen set ondersteunde velden hebben. Het model dat voor de analysebewerking moet worden gebruikt, is afhankelijk van het type document dat moet worden geanalyseerd. Dit zijn de model-ID's voor de vooraf gebouwde modellen die momenteel worden ondersteund door de Form Recognizer service:
- vooraf gebouwde factuur: extraheert tekst, selectiemarkeringen, tabellen, sleutel-waardeparen en sleutelgegevens van facturen.
- vooraf gebouwde businessCard: extraheert tekst- en sleutelgegevens uit visitekaartjes.
- prebuilt-idDocument: extraheert tekst- en sleutelgegevens uit stuurprogrammalicenties en internationale passports.
- vooraf gemaakt ontvangstbewijs: extraheert tekst- en sleutelgegevens uit ontvangstbewijzen.
Voordat u de opdracht uitvoert, moet u de volgende wijzigingen aanbrengen:
Vervang
{endpoint}door het eindpunt dat u hebt verkregen met uw Form Recognizer-abonnement.Vervang
{subscription key}door de abonnementssleutel die u uit de vorige stap hebt gekopieerd.Vervang
\"{your-document-url}door een voorbeeld van een factuur-URL:https://raw.githubusercontent.com/Azure-Samples/cognitive-services-REST-api-samples/master/curl/form-recognizer/sample-invoice.pdf
Aanvraag
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
U ontvangt een antwoord 202 (Success) met een Operation-Location-header. De waarde van deze header bevat een resultaat-id die u kunt gebruiken om de status van de asynchrone bewerking op te vragen en de resultaten op te halen:
https://{host}/formrecognizer/documentModels/{modelId}/analyzeResults/{resultId}?api-version=2021-09-30-preview
Factuurresultaten ophalen
Nadat u de Document-API analyseren hebt aangeroepen, roept u de API Resultaat analyseren op om de status van de bewerking en de geëxtraheerde gegevens op te halen. Voordat u de opdracht uitvoert, moet u de volgende wijzigingen aanbrengen:
- Vervang
{endpoint}door het eindpunt dat u hebt verkregen met uw Form Recognizer-abonnement. - Vervang
{subscription key}door de abonnementssleutel die u uit de vorige stap hebt gekopieerd. - Vervang
{resultId}door de resultaat-id uit de vorige stap.
Aanvraag
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}"
Het antwoord bekijken
U ontvangt een 200 (Success) antwoord met JSON-uitvoer. Het eerste veld, "status", geeft de status van de bewerking aan. Als de bewerking niet is voltooid, wordt de waarde van "status" "running" of "notStarted". U moet de API opnieuw aanroepen, handmatig of via een script. We raden een interval van één seconde of meer aan tussen oproepen.
Resultaten verbeteren
Controleer de "confidence"-waarden voor elk sleutel-/waarderesultaat onder het knooppunt "pageResults". U moet ook de betrouwbaarheidsscores in het knooppunt "readResults" bekijken; deze komen overeen met de bewerking Tekst lezen. Het vertrouwen van de leesresultaten heeft geen invloed op het vertrouwen van de resultaten van de sleutel/waarde-extractie, dus u moet beide controleren.
- Als de betrouwbaarheidsscores voor de leesbewerking laag zijn, probeert u de kwaliteit van uw invoerdocumenten te verbeteren (zie Invoervereisten).
- Als de betrouwbaarheidsscores voor de sleutel-/waarde-extractiebewerking laag zijn, controleer dan of de documenten die worden geanalyseerd van hetzelfde type zijn als de documenten die in de trainingsset worden gebruikt. Als de documenten in de trainingsset verschillend zijn, zou u ze in verschillende mappen kunnen verdelen en voor elke variant één model kunnen trainen.
De betrouwbaarheidsscores die u wilt bereiken, hangen af van uw gebruiksscenario, maar over het algemeen is het handig om u op een score van 80% of hoger te richten. Voor gevoeligere scenario's, zoals het lezen van medische dossiers of factureringsoverzichten, wordt een score van 100% aangeraden.
Aangepaste modellen beheren
Een lijst met modellen op halen
De aanvraag preview v3.0 List Models retourneert naast aangepaste modellen ook een lijst met vooraf gemaakte modellen met pagina's. Alleen modellen met de status Geslaagd zijn opgenomen. In uitvoering of mislukte modellen kunnen worden geïn opsommingen uitgevoerd via de aanvraag List Operations. Gebruik de eigenschap nextLink om toegang te krijgen tot de volgende pagina met modellen, indien van toepassing. Als u meer informatie wilt over elk geretourneerd model, met inbegrip van de lijst met ondersteunde documenten en de velden, moet u de modelId doorgeven aan de aanvraag Modelverkrijgen.
curl -v -X GET "https://{endpoint}/formrecognizer/documentModels?api-version=2021-09-30-preview"
Een specifiek model ophalen
Met de preview v3.0 Get-model wordt informatie opgehaald over een specifiek model met de status geslaagd. Voor mislukte en in uitvoering modellen gebruikt u de bewerking Get om de status van bewerkingen voor het maken van modellen en eventuele resulterende fouten bij te houden.
curl -v -X GET "https://{endpoint}/formrecognizer/documentModels/{modelId}?api-version=2021-09-30-preview" -H "Ocp-Apim-Subscription-Key: {subscription key}"
Een model verwijderen
Met de aanvraag preview v3.0-model verwijderen wordt het aangepaste model verwijderd en is de modelId niet meer toegankelijk voor toekomstige bewerkingen. Nieuwe modellen kunnen zonder conflicten worden gemaakt met dezelfde modelId.
curl -v -X DELETE "https://{endpoint}/formrecognizer/documentModels/{modelId}?api-version=2021-09-30-preview" -H "Ocp-Apim-Subscription-Key: {subscription key}"
Volgende stappen
In deze quickstart hebt u de Form Recognizer REST API preview (v3.0) gebruikt om formulieren op verschillende manieren te analyseren. Bekijk vervolgens de referentiedocumentatie voor meer informatie over Form Recognizer API.