快速入門：Azure AI 內容瞭解 REST API

發行項
11/23/2024

開始使用 Azure AI Content Understanding REST API 的最新預覽版本（2024-12-01-preview）。
Azure AI Content Understanding 是一種新的以 AI 為基礎的 Azure AI 服務 ，可分析任何形式檔案（檔、影像、影片和音訊），並以使用者定義的欄位格式擷取結構化輸出。
藉由呼叫 REST API，輕鬆地將 Content Understanding 服務整合到您的工作流程和應用程式中。
本快速入門會引導您使用 Content Understanding REST API 來建立自定義分析器，並從您的輸入擷取內容和欄位。

必要條件

若要開始使用，您需要 作用中的 Azure 訂用帳戶。如果您沒有 Azure 帳戶，您可以建立免費的訂用帳戶。

擁有 Azure 訂用帳戶之後，請在 Azure 入口網站中建立 Azure AI Services 資源。此多服務資源可讓您使用一組認證來存取多個 Azure AI 服務。
- 此資源列在入口網站中的 Azure AI 服務→ Azure AI 服務底下。
  
  重要
  
  Azure 提供一個以上的資源類型，名為 Azure AI 服務。請確定您選取 Azure AI 服務底下所列的，→ Azure AI 服務，如下圖所示。如需詳細資訊，請參閱建立 Azure AI 服務資源。
在本快速入門中，我們使用 cURL 命令行工具。如果未安裝，您可以下載開發環境的版本：
- Windows
- Mac 或 Linux

建立自訂分析器

若要建立自定義分析器，您必須定義欄位架構，以描述您想要擷取的結構化數據。在下列範例中，我們會定義架構，以從發票檔擷取基本資訊。

首先，使用下列內容建立名為的 request_body.json JSON 檔案：

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

若要建立自定義分析器，您必須定義欄位架構，以描述您想要擷取的結構化數據。在下列範例中，我們會定義架構，以識別金屬板影像中的偵測。

首先，使用下列內容建立名為的 request_body.json JSON 檔案：

{
  "description": "Sample chart analyzer",
  "scenario": "image",
  "fieldSchema": {
    "fields": {
      "Title": {
        "type": "string"
      },
      "ChartType": {
        "type": "string",
        "method": "classify",
        "enum": [ "bar", "line", "pie" ]
      }
    }
  }
}

若要建立自定義分析器，您必須定義欄位架構，以描述您想要擷取的結構化數據。在下列範例中，我們會定義架構，以從呼叫文字記錄擷取基本資訊。

首先，使用下列內容建立名為的 request_body.json JSON 檔案：

{
  "description": "Sample call transcript analyzer",
  "scenario": "callCenter",
  "config": {
    "returnDetails": true,
    "locales": ["en-US"]
  },
  "fieldSchema": {
    "fields": {
      "Summary": {
        "type": "string",
        "method": "generate"
      },
      "Sentiment": {
        "type": "string",
        "method": "classify",
        "enum": [ "Positive", "Neutral", "Negative" ]
      },
      "People": {
        "type": "array",
        "description": "List of people mentioned",
        "items": {
          "type": "object",
          "properties": {
            "Name": { "type": "string" },
            "Role": { "type": "string" }
          }
        }
      }
    }
  }
}

若要建立自定義分析器，您必須定義欄位架構，以描述您想要擷取的結構化數據。在下列範例中，我們會定義架構，以從行銷影片擷取基本資訊。

首先，使用下列內容建立名為的 request_body.json JSON 檔案：

{
  "description": "Sample marketing video analyzer",
  "scenario": "videoShot",
  "fieldSchema": {
    "fields": {
      "Description": {
        "type": "string",
        "description": "Detailed summary of the video segment, focusing on product characteristics, lighting, and color palette."
      },
      "Sentiment": {
        "type": "string",
        "method": "classify",
        "enum": [ "Positive", "Neutral", "Negative" ]
      }
    }
  }
}

執行下列 cURL 命令之前，請先對 HTTP 要求進行下列變更：

將和 {key} 取代{endpoint}為您 Azure 入口網站 Azure AI Services 實例中的端點和金鑰值。
{analyzerId}取代為新分析器的名稱並建立，例如 myInvoice。

PUT 要求

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 回應

201 （Created）回應包含一個 Operation-Location 標頭，其中包含可用來追蹤此異步建立作業狀態的 URL。

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

完成時，在 URL 上執行 HTTP GET 會傳 "status": "succeeded"回。

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

分析檔案

您可以使用您建立的自定義分析器來分析檔案，以擷取架構中定義的欄位。

在執行 cURL 命令之前，請先對 HTTP 要求進行下列變更：

將和 {key} 取代{endpoint}為您 Azure 入口網站 Azure AI Services 實例中的端點和金鑰值。
將取代 {analyzerId} 為稍早建立的自定義分析器名稱。
將取代{fileUrl}為要分析之檔案的可公開存取 URL，例如 Azure 儲存體 Blob 的路徑，以及共用存取簽章（SAS）或範例 URL https://github.com/Azure-Samples/cognitive-services-REST-api-samples/raw/master/curl/form-recognizer/rest-api/invoice.pdf。

POST 要求

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 回應

202 （Accepted）回應包含 Operation-Location 標頭，其中包含可用來追蹤此異步分析作業狀態的 URL。

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

取得分析結果

resultId使用上POST一個回應所傳回標頭中的 Operation-Location ，並擷取分析的結果。

將和 {key} 取代{endpoint}為您 Azure 入口網站 Azure AI Services 實例中的端點和金鑰值。
將取代 {analyzerId} 為稍早建立的自定義分析器名稱。
取代為{resultId}resultId從要求傳回的 POST 。

GET 要求

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

GET 回應

200 （OK） JSON 回應包含一個 status 欄位，指出作業的狀態。如果工作未完成，則的值 status 為 running 或 notStarted。在這種情況下，您應該手動或透過腳本再次呼叫 API。在呼叫之間等候一秒或多個間隔。

範例回覆

{
  "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 }
          }, ...
        ]
      }
    ]
  }
}

{
  "id": "12fd421b-b545-4d63-93a5-01284081bbe1",
  "status": "Succeeded",
  "result": {
    "analyzerId": "sample_chart_analyzer",
    "apiVersion": "2024-12-01-preview",
    "createdAt": "2024-11-09T08:41:00Z",
    "warnings": [],
    "contents": [
      {
        "markdown": "![image](image)\n",
        "fields": {
          "Title": {
            "type": "string",
            "valueString": "Weekly Work Hours Distribution"
          },
          "ChartType": {
            "type": "string",
            "valueString": "pie"
          }
        },
        "kind": "document",
        "startPageNumber": 1,
        "endPageNumber": 1,
        "unit": "pixel",
        "pages": [
          {
            "pageNumber": 1,
            "width": 1283,
            "height": 617
          }
        ]
      }
    ]
  }
}

{
  "id": "247c369c-1aa5-4f92-b033-a8e4318e1c02",
  "status": "Succeeded",
  "result": {
    "analyzerId": "sample_chart_analyzer",
    "apiVersion": "2024-12-01-preview",
    "createdAt": "2024-11-09T08:42:58Z",
    "warnings": [],
    "contents": [
      {
        "kind": "audioVisual",
        "startTimeMs": 0,
        "endTimeMs": 32182,
        "markdown": "```WEBVTT\n\n00:00.080 --> 00:00.640\n<v Agent>Good day...",
        "fields": {
          "Sentiment": {
            "type": "string",
            "valueString": "Positive"
          },
          "Summary": {
            "type": "string",
            "valueString": "Maria Smith contacted Contoso to inquire about her current point balance. Agent John Doe confirmed her identity and informed her that she has 599 points. Maria did not require any further information and the call ended on a positive note."
          },
          "People": {
            "type": "array",
            "valueArray": [
              {
                "type": "object",
                "valueObject": {
                  "Name": {
                    "type": "string",
                    "valueString": "Maria Smith"
                  },
                  "Role": {
                    "type": "string",
                    "valueString": "Customer"
                  }
                }
              }, ...
            ]
          }
        },
        "transcriptPhrases": [
          {
            "speaker": "Agent 1",
            "startTimeMs": 80,
            "endTimeMs": 640,
            "text": "Good day.",
            "confidence": 0.932,
            "words": [
              {
                "startTimeMs": 80,
                "endTimeMs": 280,
                "text": "Good"
              }, ...
            ],
            "locale": "en-US"
          }, ...
        ]
      }
    ]
  }
}

{
  "id": "204fb777-e961-4d6d-a6b1-6e02c773d72c",
  "status": "Succeeded",
  "result": {
    "analyzerId": "sample_marketing_video_analyzer",
    "apiVersion": "2024-12-01-preview",
    "createdAt": "2024-11-09T08:57:21Z",
    "warnings": [],
    "contents": [
      {
        "kind": "audioVisual",
        "startTimeMs": 0,
        "endTimeMs": 2800,
        "width": 540,
        "height": 960,
        "markdown": "# Shot 0:0.0 => 0:1.800\n\n## Transcript\n\n```\n\nWEBVTT\n\n0:0.80 --> 0:10.560\n<v Speaker>When I was planning my trip...",
        "fields": {
          "sentiment": {
            "type": "string",
            "valueString": "Neutral"
          },
          "description": {
            "type": "string",
            "valueString": "The video begins with a view from a glass floor, showing a person's feet in white sneakers standing on it. The scene captures a downward view of a structure, possibly a tower, with a grid pattern on the floor and a clear view of the ground below. The lighting is bright, suggesting a sunny day, and the colors are dominated by the orange of the structure and the gray of the floor."
          }
        }
      },
      ...
    ]
  }
}

下一步

在本快速入門中，您已瞭解如何呼叫 REST API 來建立自定義分析器。如需用戶體驗，請嘗試 Azure AI Foundry 入口網站。

共用方式為

快速入門：Azure AI 內容瞭解 REST API

必要條件

建立自訂分析器

PUT 要求

PUT 回應

分析檔案

POST 要求

POST 回應

取得分析結果

GET 要求

GET 回應

範例回覆

下一步

意見反應

其他資源