通过

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

快速入门：在 Foundry 工具 REST API 中使用 Azure 内容理解功能

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

Prerequisites

  • 若要开始，需要 有效的 Azure 订阅。 如果没有 Azure 帐户，可免费创建一个帐户。
  • 拥有 Azure 订阅后，请在 Azure 门户中创建 Microsoft Foundry 资源 。 请务必在 受支持的区域中创建它。
  • 为内容理解资源设置默认模型部署。 默认设置将创建与用于内容理解请求的 Foundry 模型的连接。 选择下列方法之一：
    1. 转到 “内容理解设置”页
    2. 选择左上角的“+ 添加资源”按钮
    3. 选择要使用的 Foundry 资源，然后单击“下一步”，然后单击“保存”
      • 选中“如果没有可用的默认值，请确保为所需模型启用自动部署”。 确保资源已用所需的 GPT-4.1、GPT-4.1-mini 和 text-embedding-3-large 型模进行完整设置。 不同的预生成分析器需要不同的模型。
    通过执行这些步骤，可以在 Foundry 资源中设置内容理解模型和 Foundry 模型之间的连接。
  • 本指南使用 cURL 命令行工具。 如果未安装，可以 下载 适用于开发环境的相应版本。

从预建的分析器开始

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

发送文件进行分析

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

  1. 将{endpoint}和{key}替换为 Azure 门户中您 Foundry 实例的相应值。

POST 请求

此示例使用 prebuilt-invoice 分析器从发票文档中提取结构化数据。

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"}]
      }'

POST 响应

响应标头包括一个 Operation-Location 字段，用于检索异步分析作的结果。

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

重要

从响应标头复制 Operation-Location URL。 在下一步中，你将使用此 URL 检索分析结果。

获取分析结果

使用Operation-Location中 POST，并检索分析结果。

GET 请求

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

GET 响应

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

{
  "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
    }
  }
}

后续步骤

了解如何调用分析作后，请详细了解如何为用例生成 自定义分析器 。

  • Last updated on