Partager via


Démarrage rapide : Utiliser Azure Content Understanding dans l’API REST Des outils Foundry

Ce guide de démarrage rapide vous montre comment utiliser l’API REST Content Understanding pour obtenir des données structurées à partir de contenu modal dans des fichiers document, image, audio et vidéo.

Prérequis

  • Pour commencer, vous avez besoin d’un abonnement Azure actif. Si vous ne possédez pas de compte Azure, créez un compte gratuit.
  • Une fois que vous avez votre abonnement Azure, créez une ressource Microsoft Foundry dans le Portail Azure. Veillez à le créer dans une région prise en charge.
  • Configurez les déploiements de modèles par défaut pour votre ressource Content Understanding. La définition par défaut crée une connexion aux modèles Foundry que vous utilisez pour les requêtes Content Understanding. Choisissez l’une des méthodes suivantes :
    1. Accédez à la page des paramètres Content Understanding
    2. Sélectionnez le bouton « + Ajouter une ressource » en haut à gauche
    3. Sélectionnez la ressource Foundry que vous souhaitez utiliser, puis cliquez sur Suivant, puis Enregistrez
      • Veillez à laisser « Activer le redéploiement automatique pour les modèles requis si aucune valeur par défaut n’est disponible ». Cela garantit que votre ressource est entièrement configurée avec les modèles GPT-4.1, GPT-4.1-mini et text-embedding-3-large requis. Différents analyseurs prédéfinis nécessitent différents modèles.
    En effectuant ces étapes, vous configurez une connexion entre les modèles Content Understanding et Foundry dans votre ressource Foundry.
  • Dans ce guide, nous utilisons l’outil en ligne de commande cURL. S’il n’est pas installé, vous pouvez télécharger la version appropriée pour votre environnement de développement.

Commencez avec un analyseur préconfiguré

Les analyseurs définissent la façon dont votre contenu est traité et les insights extraits. Nous offrons des analyseurs prédéfinis pour les cas d’usage courants. Vous pouvez personnaliser des analyseurs prédéfinis pour mieux répondre à vos besoins et cas d’usage spécifiques. Ce guide de démarrage rapide utilise des analyseurs de facture, d’image, d’audio et de vidéo prédéfinis pour vous aider à commencer.

Envoyer un fichier à des fins d’analyse

Avant d’exécuter la commande cURL suivante, apportez les modifications suivantes à la requête HTTP :

  1. Remplacez {endpoint} et {key} par les valeurs correspondantes de votre instance Foundry dans le portail Azure.

requête POST

Cet exemple utilise l’analyseur prebuilt-invoice pour extraire des données structurées à partir d’un document de facture.

curl -i -X POST "{endpoint}/contentunderstanding/analyzers/prebuilt-invoice:analyze?api-version=2025-11-01" \
  -H "Ocp-Apim-Subscription-Key: {key}" \
  -H "Content-Type: application/json" \
  -d '{
        "inputs":[{"url": "https://github.com/Azure-Samples/azure-ai-content-understanding-python/raw/refs/heads/main/data/invoice.pdf"}]
      }'  

Réponse POST

L’en-tête de réponse inclut un Operation-Location champ que vous utilisez pour récupérer les résultats de l’opération d’analyse asynchrone.

HTTP/1.1 202 Accepted
Transfer-Encoding: chunked
Content-Type: application/json
request-id: aaa-bbb-ccc-ddd
x-ms-request-id: aaa-bbb-ccc-ddd
Operation-Location: {endpoint}/contentunderstanding/analyzerResults/{request-id}?api-version=2025-11-01
api-supported-versions: 2024-12-01-preview,2025-05-01-preview,2025-11-01
x-envoy-upstream-service-time: 800
apim-request-id: {request-id}
Strict-Transport-Security: max-age=31536000; includeSubDomains; preload
x-content-type-options: nosniff
x-ms-region: West US
Date: Fri, 31 Oct 2025 05:30:17 GMT
Connection: close

Important

Copiez l’URL d’emplacement de l’opération à partir de l’en-tête de réponse. Vous allez utiliser cette URL à l’étape suivante pour récupérer les résultats de l’analyse.

Obtenir le résultat d’analyse

Utilisez le Operation-Location de la réponse POST et récupérez le résultat de l’analyse.

Requête GET

curl -i -X GET "{endpoint}/contentunderstanding/analyzerResults/{request-id}?api-version=2025-11-01" \
  -H "Ocp-Apim-Subscription-Key: {key}"

Réponse GET

La réponse JSON (OK) 200 inclut un champ status indiquant l’état de l’opération. Si l’opération n’est pas terminée, la valeur de status est Running ou NotStarted. Dans ce cas, vous devez renvoyer la GET requête, manuellement ou via un script. Attendez une seconde ou plus entre chaque appel.

{
  "id": "ce05fb5a-579e-4f0b-afb5-3532bcddeaee",
  "status": "Succeeded",
  "result": {
    "analyzerId": "prebuilt-invoice",
    "apiVersion": "2025-11-01",
    "createdAt": "2025-11-13T20:04:55Z",
    "warnings": [],
    "contents": [
      {
        "path": "input1",
        "markdown": "CONTOSO LTD.\n\n\n# INVOICE\n\nContoso Headquarters\n123 456th St\nNew York, NY, 10001\n\nINVOICE: INV-100\n\nINVOICE DATE: 11/15/2019\n\nDUE DATE: 12/15/2019\n\nCUSTOMER NAME: MICROSOFT CORPORATION...",
        "fields": {
          "AmountDue": {
            "type": "object",
            "valueObject": {
              "Amount": {
                "type": "number",
                "valueNumber": 610,
                "spans": [
                  {
                    "offset": 1522,
                    "length": 7
                  }
                ],
                "confidence": 0.773,
                "source": "D(1,7.3628,8.0459,7.9272,8.0459,7.9272,8.2070,7.3628,8.2070)"
              },
              "CurrencyCode": {
                "type": "string",
                "valueString": "USD"
              }
            }
          },
          "BalanceForward": {
            "type": "object",
            "valueObject": {
              "Amount": {
                "type": "number",
                "valueNumber": 500,
                "spans": [
                  {
                    "offset": 1474,
                    "length": 7
                  }
                ],
                "confidence": 0.901,
                "source": "D(1,7.3628,7.7445,7.9278,7.7467,7.9272,7.9092,7.3622,7.9070)"
              },
              "CurrencyCode": {
                "type": "string",
                "valueString": "USD"
              }
            }
          },
          "BillingAddress": {
            "type": "string",
            "valueString": "123 Bill St, Redmond WA, 98052",
            "spans": [
              {
                "offset": 325,
                "length": 12
              },
              "..."
            ],
            "confidence": 0.712,
            "source": "D(1,0.5805,3.9471,1.2858,3.9478,1.2856,4.1115,0.5803,4.1108);..."
          },
          "BillingAddressRecipient": {
            "type": "string",
            "valueString": "Microsoft Finance",
            "spans": [
              {
                "offset": 307,
                "length": 17
              }
            ],
            "confidence": 0.815,
            "source": "D(1,0.5734,3.7392,1.8060,3.7521,1.8043,3.9201,0.5717,3.9072)"
          },
          "CountryRegion": {
            "type": "string",
            "valueString": "USA"
          },
          "CustomerAddress": {
            "type": "string",
            "valueString": "123 Other St, Redmond WA, 98052",
            "spans": [
              "..."
            ],
            "confidence": 0.744,
            "source": "..."
          },
          "CustomerAddressRecipient": {
            "type": "string",
            "valueString": "Microsoft Corp",
            "spans": [
              "..."
            ],
            "confidence": 0.437,
            "source": "..."
          },
          "CustomerId": {
            "type": "string",
            "valueString": "CID-12345",
            "spans": [
              "..."
            ],
            "confidence": 0.936,
            "source": "..."
          },
          "CustomerName": {
            "type": "string",
            "valueString": "MICROSOFT CORPORATION",
            "spans": [
              "..."
            ],
            "confidence": 0.46,
            "source": "..."
          },
          "CustomerTaxId": {
            "type": "string",
            "confidence": 0.912
          },
          "DueDate": {
            "type": "date",
            "valueDate": "2019-12-15",
            "spans": [
              "..."
            ],
            "confidence": 0.97,
            "source": "..."
          },
          "InvoiceDate": {
            "type": "date",
            "valueDate": "2019-11-15",
            "spans": [
              "..."
            ],
            "confidence": 0.939,
            "source": "..."
          },
          "InvoiceId": {
            "type": "string",
            "valueString": "INV-100",
            "spans": [
              "..."
            ],
            "confidence": 0.733,
            "source": "..."
          },
          "LineItems": {
            "type": "array",
            "valueArray": [
              {
                "type": "object",
                "valueObject": {
                  "Date": {
                    "type": "date",
                    "valueDate": "2021-03-04",
                    "spans": [
                      "..."
                    ],
                    "confidence": 0.894,
                    "source": "..."
                  },
                  "Description": {
                    "type": "string",
                    "valueString": "Consulting Services",
                    "spans": [
                      "..."
                    ],
                    "confidence": 0.589,
                    "source": "..."
                  },
                  "ProductCode": {
                    "type": "string",
                    "valueString": "A123",
                    "spans": [
                      "..."
                    ],
                    "confidence": 0.879,
                    "source": "..."
                  },
                  "Quantity": {
                    "type": "number",
                    "valueNumber": 2,
                    "spans": [
                      "..."
                    ],
                    "confidence": 0.939,
                    "source": "..."
                  },
                  "QuantityUnit": {
                    "type": "string",
                    "valueString": "hours",
                    "spans": [
                      "..."
                    ],
                    "confidence": 0.85,
                    "source": "..."
                  },
                  "TaxAmount": {
                    "type": "object",
                    "valueObject": {
                      "Amount": {
                        "type": "number",
                        "valueNumber": 6,
                        "spans": [
                          "..."
                        ],
                        "confidence": 0.522,
                        "source": "..."
                      },
                      "CurrencyCode": {
                        "type": "string",
                        "valueString": "USD"
                      }
                    }
                  },
                  "TaxRate": {
                    "type": "number",
                    "confidence": 0.915
                  },
                  "TotalAmount": {
                    "type": "object",
                    "valueObject": {
                      "Amount": {
                        "type": "number",
                        "valueNumber": 60,
                        "spans": [
                          "..."
                        ],
                        "confidence": 0.972,
                        "source": "..."
                      },
                      "CurrencyCode": {
                        "type": "string",
                        "valueString": "USD"
                      }
                    }
                  },
                  "UnitPrice": {
                    "type": "object",
                    "valueObject": {
                      "Amount": {
                        "type": "number",
                        "valueNumber": 30,
                        "spans": [
                          "..."
                        ],
                        "confidence": 0.97,
                        "source": "..."
                      },
                      "CurrencyCode": {
                        "type": "string",
                        "valueString": "USD"
                      }
                    }
                  }
                }
              },
              "... (2 additional line items)"
            ]
          }
          /*additional fields omitted*/
        },
        "kind": "document",
        "startPageNumber": 1,
        "endPageNumber": 1,
        "unit": "inch",
        "pages": [
          {
            "pageNumber": 1,
            "angle": 0,
            "width": 8.5,
            "height": 11,
            "words": [
              "... (words omitted for brevity)"
            ],
            "selectionMarks": [],
            "lines": [
              "... (lines omitted for brevity)"
            ],
            "barcodes": [],
            "formulas": []
          }
        ],
        "tables": [
          "... (tables omitted for brevity)"
        ],
        "keyValuePairs": [
          "... (key-value pairs omitted for brevity)"
        ],
        "analyzerId": "prebuilt-invoice",
        "mimeType": "application/pdf"
      }
    ]
  },
  "usage": {
    "documentStandardPages": 1,
    "contextualizationTokens": 2345,
    "tokens": {
      "gpt-4.1-mini-input": 1234,
      "gpt-4.1-mini-output": 567
    }
  }
}

Étape suivante

Maintenant que vous savez comment appeler l’opération d’analyse, apprenez-en davantage sur la création d’analyseurs personnalisés pour votre cas d’usage.