通过

你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

快速入门：使用 Azure AI 内容理解 REST API

  • 本快速入门介绍如何使用 内容理解 REST API 从文档、图像、音频和视频文件中的多模式内容获取结构化数据。

  • 试用 Azure AI Foundry 上的无代码内容理解功能

Prerequisites

  • 若要开始，需要 有效的 Azure 订阅。 如果没有 Azure 帐户，可免费创建一个帐户。
  • 拥有 Azure 订阅后，请在 Azure 门户中创建 Azure AI Foundry 资源 。 请务必在 受支持的区域中创建它。
    • 此资源在门户中的AI Foundry>AI Foundry类别下列出。 Azure 门户中 AI Foundry 资源页的屏幕截图。
  • 本指南使用 cURL 命令行工具。 如果未安装，可以 下载 适用于开发环境的相应版本。

从预建的分析器开始

分析器定义内容的处理方式和提取的见解。 我们为常见用例提供 预生成分析器 。 可以 自定义预生成分析器 ，以更好地满足特定需求和用例。 本快速入门使用预生成的文档、图像、音频和视频分析器来帮助你入门。

发送文件进行分析

运行以下 cURL 命令之前，请对 HTTP 请求进行以下更改：

  1. 将 {endpoint} 和 {key} 替换为 Azure 门户中 Azure AI Foundry 实例的相应值。
  2. 将 {analyzerId} 替换为 prebuilt-documentAnalyzer。 此分析器从文档中提取文本和布局元素，如段落、节和表格。
  3. 将 {fileUrl} 替换为要分析的文件的可公开访问 URL，例如具有共享访问签名 (SAS) 或使用示例 URL https://github.com/Azure-Samples/azure-ai-content-understanding-python/raw/refs/heads/main/data/invoice.pdf 的 Azure 存储 Blob 的路径。

POST 请求

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

POST 响应

响应包括一个 request-id，用于检索异步分析操作的结果。 此外， Operation-Location 标头还提供用于访问分析结果的直接 URL。

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-05-01-preview
api-supported-versions: 2024-12-01-preview,2025-05-01-preview,2025-10-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

获取分析结果

使用request-id中 POST，并检索分析结果。

  1. 在 Azure 门户的 Azure AI Foundry 实例中，将 {endpoint} 和 {key} 替换为终结点和密钥值。
  2. 将{request-id}替换为request-id响应中的POST，或使用Operation-Location响应头中的完整URL。

GET 请求

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

GET 响应

200 (OK) JSON 响应包括一个指示操作状态的 status 字段。 如果操作未完成，则 status 的值为 Running 或 NotStarted。 在这种情况下，应手动或通过脚本再次发送 GET 请求。 两次调用之间等待一秒或更长时间。

{
  "id": "<request-id>",
  "status": "Succeeded",
  "result": {
    "analyzerId": "prebuilt-documentAnalyzer",
    "apiVersion": "2025-05-01-preview",
    "createdAt": "YYYY-MM-DDTHH:MM:SSZ",
    "warnings": [],
    "contents": [
      {
        "markdown": "CONTOSO LTD.\n\n\n# INVOICE\n\nContoso Headquarters\n123 456th St...",
        "fields": {
          "Summary": {
            "type": "string",
            "valueString": "This document is an invoice issued by Contoso Ltd. to Microsoft Corporation for services rendered during the period of 10/14/2019 to 11/14/2019..."
          }
        },
        "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.998,
                "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 }
          },
          {
            "role": "title",
            "content": "INVOICE",
            "source": "D(1,7.0515,0.5614,8.0064,0.5628,8.006,0.791,7.0512,0.7897)",
            "span": { "offset": 15, "length": 9 }
          }, ...
        ],
        "sections": [
          {
            "span": { "offset": 0, "length": 1649 },
            "elements": [ "/sections/1", "/sections/2" ]
          }, ...
        ],
        "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 }
          }, ...
        ]
      }
    ]
  },
  "usage": {
		"documentPages": 1,
		"tokens": {
			"contextualization": 1000,
			"input": 1866,
			"output": 87
		}
	}
}

后续步骤

详细了解如何为用例 创建自定义分析器 。