Delen via

Quickstart: Azure AI Content Understanding REST API's

  • Artikel

  • Begin met het gebruik van de nieuwste preview-versie van de Azure AI Content Understanding REST API (2024-12-01-preview).

  • Azure AI Content Understanding is een nieuwe op AI gebaseerde Azure AI-service waarmee bestanden van elke modaliteit (documenten, afbeeldingen, video's en audio) worden geanalyseerd en gestructureerde uitvoer wordt geëxtraheerd in door de gebruiker gedefinieerde veldindelingen.

  • Integreer de Content Understanding-service eenvoudig in uw werkstromen en toepassingen door onze REST API's aan te roepen.

  • In deze quickstart wordt u begeleid bij het gebruik van de REST API voor Inhoudskennis om een aangepaste analyse te maken en inhoud en velden te extraheren uit uw invoer.

Vereisten

U hebt een actief Azure-abonnement nodig om aan de slag te gaan. Als u geen Azure-account hebt, kunt u een gratis abonnement maken.

  • Zodra u uw Azure-abonnement hebt, maakt u een Azure AI Services-resource in Azure Portal. Met deze resource voor meerdere services hebt u toegang tot meerdere Azure AI-services met één set referenties.

    • Deze resource wordt vermeld onder Azure AI-services → Azure AI-services in de portal.

      Belangrijk

      Azure biedt meer dan één resourcetype met de naam Azure AI-services. Zorg ervoor dat u de service selecteert die wordt vermeld onder Azure AI-services → Azure AI-services, zoals weergegeven in de volgende afbeelding. Zie Een Azure AI Services-resource maken voor meer informatie.

      Schermopname van de resourcepagina voor meerdere services in Azure Portal.

  • In deze quickstart gebruiken we het opdrachtregelprogramma cURL. Als deze niet is geïnstalleerd, kunt u een versie voor uw ontwikkelomgeving downloaden:

Een aangepaste analyse maken

Als u een aangepaste analyse wilt maken, moet u een veldschema definiëren waarin de gestructureerde gegevens worden beschreven die u wilt extraheren. In het volgende voorbeeld definiëren we een schema voor het extraheren van basisinformatie uit een factuurdocument.

Maak eerst een JSON-bestand met de naam request_body.json met de volgende inhoud:

{
  "description": "Sample invoice analyzer",
  "scenario": "document",
  "config": {
    "returnDetails": true
  },
  "fieldSchema": {
    "fields": {
      "VendorName": {
        "type": "string",
        "method": "extract",
        "description": "Vendor issuing the invoice"
      },
      "Items": {
        "type": "array",
        "method": "extract",
        "items": {
          "type": "object",
          "properties": {
            "Description": {
              "type": "string",
              "method": "extract",
              "description": "Description of the item"
            },
            "Amount": {
              "type": "number",
              "method": "extract",
              "description": "Amount of the item"
            }
          }
        }
      }
    }
  }
}

Voordat u de volgende cURL opdrachten uitvoert, moet u de volgende wijzigingen aanbrengen in de HTTP-aanvraag:

  1. Vervang {endpoint} en door het eindpunt en {key} de sleutelwaarden van uw Azure PORTAL Azure AI Services-exemplaar.
  2. Vervang door {analyzerId} de naam van de nieuwe analyse en maak, zoals myInvoice.

PUT-aanvraag

curl -i -X PUT "{endpoint}/contentunderstanding/analyzers/{analyzerId}?api-version=2024-12-01-preview" \
  -H "Ocp-Apim-Subscription-Key: {key}" \
  -H "Content-Type: application/json" \
  -d @request_body.json

PUT-antwoord

Het antwoord 201 (Created) bevat een Operation-Location header met een URL die u kunt gebruiken om de status van deze asynchrone aanmaakbewerking bij te houden.

201 Created
Operation-Location: {endpoint}/contentunderstanding/analyzers/{analyzerId}/operations/{operationId}?api-version=2024-12-01-preview

Na voltooiing wordt een HTTP GET op de URL geretourneerd "status": "succeeded".

curl -i -X GET "{endpoint}/contentunderstanding/analyzers/{analyzerId}/operations/{operationId}?api-version=2024-12-01-preview" \
  -H "Ocp-Apim-Subscription-Key: {key}"

Een bestand analyseren

U kunt bestanden analyseren met behulp van de aangepaste analyse die u hebt gemaakt om de velden te extraheren die in het schema zijn gedefinieerd.

Voordat u de cURL-opdracht uitvoert, moet u de volgende wijzigingen aanbrengen in de HTTP-aanvraag:

  1. Vervang {endpoint} en door het eindpunt en {key} de sleutelwaarden van uw Azure PORTAL Azure AI Services-exemplaar.
  2. Vervang door {analyzerId} de naam van de aangepaste analyse die u eerder hebt gemaakt.
  3. Vervang {fileUrl} door een openbaar toegankelijke URL van het bestand dat u wilt analyseren, zoals een pad naar een Azure Storage-blob met een SAS (Shared Access Signature) of de voorbeeld-URL https://github.com/Azure-Samples/cognitive-services-REST-api-samples/raw/master/curl/form-recognizer/rest-api/invoice.pdf.

POST-aanvraag

curl -i -X POST "{endpoint}/contentunderstanding/analyzers/{analyzerId}:analyze?api-version=2024-12-01-preview" \
  -H "Ocp-Apim-Subscription-Key: {key}" \
  -H "Content-Type: application/json" \
  -d "{\"url\":\"{fileUrl}\"}"

POST-antwoord

Het antwoord 202 (Accepted) bevat een Operation-Location header met een URL die u kunt gebruiken om de status van deze asynchrone analysebewerking bij te houden.

202 Accepted
Operation-Location: {endpoint}/contentunderstanding/analyzers/{analyzerId}/results/{resultId}?api-version=2024-12-01-preview

Analyseresultaat ophalen

Gebruik de resultIdOperation-Location header die wordt geretourneerd door het vorige POST antwoord en haal het resultaat van de analyse op.

  1. Vervang {endpoint} en door het eindpunt en {key} de sleutelwaarden van uw Azure PORTAL Azure AI Services-exemplaar.
  2. Vervang door {analyzerId} de naam van de aangepaste analyse die u eerder hebt gemaakt.
  3. Vervang {resultId} door de resultId geretourneerde waarde van de POST aanvraag.

GET-aanvraag

curl -i -X GET "{endpoint}/contentunderstanding/analyzers/{analyzerId}/results/{resultId}?api-version=2024-12-01-preview" \
  -H "Ocp-Apim-Subscription-Key: {key}"

GET-antwoord

Het JSON-antwoord 200 (OK) bevat een status veld dat de status van de bewerking aangeeft. Als de bewerking niet is voltooid, is running of statusnotStarted. In dergelijke gevallen moet u de API opnieuw aanroepen, handmatig of via een script. Wacht een interval van één seconde of meer tussen aanroepen.

Voorbeeldrespons

{
  "id": "bcf8c7c7-03ab-4204-b22c-2b34203ef5db",
  "status": "Succeeded",
  "result": {
    "analyzerId": "sample_invoice_analyzer",
    "apiVersion": "2024-12-01-preview",
    "createdAt": "2024-11-13T07:15:46Z",
    "warnings": [],
    "contents": [
      {
        "markdown": "CONTOSO LTD.\n\n\n# INVOICE\n\nContoso Headquarters...",
        "fields": {
          "VendorName": {
            "type": "string",
            "valueString": "CONTOSO LTD.",
            "spans": [ { "offset": 0, "length": 12 } ],
            "confidence": 0.941,
            "source": "D(1,0.5729,0.6582,2.3353,0.6582,2.3353,0.8957,0.5729,0.8957)"
          },
          "Items": {
            "type": "array",
            "valueArray": [
              {
                "type": "object",
                "valueObject": {
                  "Description": {
                    "type": "string",
                    "valueString": "Consulting Services",
                    "spans": [ { "offset": 909, "length": 19 } ],
                    "confidence": 0.971,
                    "source": "D(1,2.3264,5.673,3.6413,5.673,3.6413,5.8402,2.3264,5.8402)"
                  },
                  "Amount": {
                    "type": "number",
                    "valueNumber": 60,
                    "spans": [ { "offset": 995, "length": 6 } ],
                    "confidence": 0.989,
                    "source": "D(1,7.4507,5.6684,7.9245,5.6684,7.9245,5.8323,7.4507,5.8323)"
                  }
                }
              }, ...
            ]
          }
        },
        "kind": "document",
        "startPageNumber": 1,
        "endPageNumber": 1,
        "unit": "inch",
        "pages": [
          {
            "pageNumber": 1,
            "angle": -0.0039,
            "width": 8.5,
            "height": 11,
            "spans": [ { "offset": 0, "length": 1650 } ],
            "words": [
              {
                "content": "CONTOSO",
                "span": { "offset": 0, "length": 7 },
                "confidence": 0.997,
                "source": "D(1,0.5739,0.6582,1.7446,0.6595,1.7434,0.8952,0.5729,0.8915)"
              }, ...
            ],
            "lines": [
              {
                "content": "CONTOSO LTD.",
                "source": "D(1,0.5734,0.6563,2.335,0.6601,2.3345,0.8933,0.5729,0.8895)",
                "span": { "offset": 0, "length": 12 }
              }, ...
            ]
          }
        ],
        "paragraphs": [
          {
            "content": "CONTOSO LTD.",
            "source": "D(1,0.5734,0.6563,2.335,0.6601,2.3345,0.8933,0.5729,0.8895)",
            "span": { "offset": 0, "length": 12 }
          }, ...
        ],
        "sections": [
          {
            "span": { "offset": 0, "length": 1649 },
            "elements": [ "/sections/1", "/sections/2" ]
          },
          {
            "span": { "offset": 0, "length": 12 },
            "elements": [ "/paragraphs/0" ]
          }, ...
        ],
        "tables": [
          {
            "rowCount": 2,
            "columnCount": 6,
            "cells": [
              {
                "kind": "columnHeader",
                "rowIndex": 0,
                "columnIndex": 0,
                "rowSpan": 1,
                "columnSpan": 1,
                "content": "SALESPERSON",
                "source": "D(1,0.5389,4.5514,1.7505,4.5514,1.7505,4.8364,0.5389,4.8364)",
                "span": { "offset": 512, "length": 11 },
                "elements": [ "/paragraphs/19" ]
              }, ...
            ],
            "source": "D(1,0.4885,4.5543,8.0163,4.5539,8.015,5.1207,0.4879,5.1209)",
            "span": { "offset": 495, "length": 228 }
          }, ...
        ]
      }
    ]
  }
}

Volgende stappen