Analisar conteúdo
Para analisar o conteúdo de um arquivo, você pode usar a API de Compreensão de Conteúdo do Azure para enviá-lo ao ponto de extremidade. Você pode especificar o conteúdo como uma URL (para um arquivo hospedado em um local acessível pela Internet) ou carregar dados de arquivo binário diretamente (por exemplo, um documento .pdf, uma imagem .png, um arquivo de áudio .mp3 ou um arquivo de vídeo .mp4). A solicitação de análise inclui o analisador a ser usado.
A análise é uma operação assíncrona. Depois de enviar a solicitação, você recebe uma ID de operação que pode ser usada para verificar o status e recuperar os resultados quando a operação for concluída.
Por exemplo, suponha que você queira usar o analisador de cartão de visita discutido anteriormente para extrair o nome e o endereço de email da seguinte imagem de cartão de visita digitalizada:
Usar o SDK do Python
O SDK do Python para Compreensão de Conteúdo (azure-ai-contentunderstanding) fornece uma ContentUnderstandingClient classe que simplifica a interação com o serviço. O SDK manipula autenticação, formatação de solicitação e sondagem automática para operações assíncronas.
O seguinte código Python usa o SDK para enviar um cartão de visita para análise e recuperar os resultados:
from azure.ai.contentunderstanding import ContentUnderstandingClient
from azure.ai.contentunderstanding.models import AnalysisInput
from azure.core.credentials import AzureKeyCredential
# Authenticate the client
endpoint = "<YOUR_ENDPOINT>"
credential = AzureKeyCredential("<YOUR_API_KEY>")
client = ContentUnderstandingClient(endpoint=endpoint, credential=credential)
# Analyze the business card using the custom analyzer
analyzer_name = "business_card_analyser"
poller = client.begin_analyze(
analyzer_id=analyzer_name,
inputs=[AnalysisInput(url="https://host.com/business-card.png")]
)
# Wait for the operation to complete and get the results
result = poller.result()
# Extract field values from the results
content = result.contents[0]
if content.fields:
for field_name, field_data in content.fields.items():
if field_data.type == "string":
print(f"{field_name}: {field_data.value}")
Dica
O método do begin_analyze SDK retorna um objeto poller. Chamar .result() no poller lida automaticamente com a sondagem até que a operação seja concluída, portanto, você não precisa escrever seu próprio loop de sondagem.
Usando a API REST
Você também pode enviar solicitações de análise diretamente usando a API REST. Seu aplicativo cliente envia chamadas HTTP ao endpoint de Compreensão de Conteúdo para o recurso Microsoft Foundry, passando uma chave de API no cabeçalho.
O código Python a seguir envia uma solicitação de análise usando uma URL e, em seguida, sonda o serviço até que a operação seja concluída e os resultados sejam retornados.
import json
import requests
## Use a POST request to submit the file URL to the analyzer
analyzer_name = "business_card_analyser"
headers = {
"Ocp-Apim-Subscription-Key": "<YOUR_API_KEY>",
"Content-Type": "application/json"}
url = f"{<YOUR_ENDPOINT>}/contentunderstanding/analyzers/{analyzer_name}:analyze?api-version=2025-11-01"
request_body = {
"inputs": [
{
"url": "https://host.com/business-card.png"
}
]
}
response = requests.post(url, headers=headers, json=request_body)
# Get the response and extract the ID assigned to the analysis operation
response_json = response.json()
id_value = response_json.get("id")
# Use a GET request to check the status of the analysis operation
result_url = f"{<YOUR_ENDPOINT>}/contentunderstanding/analyzerResults/{id_value}?api-version=2025-11-01"
result_response = requests.get(result_url, headers=headers)
# Keep polling until the analysis is complete
status = result_response.json().get("status")
while status == "Running":
result_response = requests.get(result_url, headers=headers)
status = result_response.json().get("status")
# Get the analysis results
if status == "Succeeded":
result_json = result_response.json()
Observação
Você pode especificar uma URL para o local do arquivo de conteúdo, conforme mostrado aqui. Para enviar dados de arquivo binário diretamente, use a operação analyzeBinary.
Resultados da análise de processamento
Os resultados dependem de:
- O tipo de conteúdo que o analisador foi projetado para analisar (por exemplo, documento, vídeo, imagem ou áudio).
- O esquema do analisador.
- O conteúdo do arquivo que foi analisado.
Por exemplo, a resposta do analisador de cartão de visita baseado em documento ao analisar o cartão de visita descrito anteriormente contém:
- Os campos extraídos
- O layout de OCR (reconhecimento óptico de caracteres) do documento, incluindo locais de linhas de texto, palavras individuais e parágrafos em cada página.
Usar o SDK do Python
Ao usar o SDK, o AnalysisResult objeto fornece acesso digitado aos resultados. A contents propriedade contém uma lista de objetos de conteúdo, cada um com campos, markdown e metadados. O código a seguir mostra como extrair valores de campos de strings:
# (continued from previous SDK code example)
content = result.contents[0]
if content.fields:
for field_name, field_data in content.fields.items():
if field_data.type == "string":
print(f"{field_name}: {field_data.value}")
Usando a API REST
Ao usar a API REST, a resposta é um conteúdo JSON que seu aplicativo deve analisar. Aqui está a resposta JSON completa da análise do cartão de visita:
{
"id": "00000000-0000-0000-0000-a00000000000",
"status": "Succeeded",
"result": {
"analyzerId": "biz_card_analyser_2",
"apiVersion": "2025-11-01",
"createdAt": "2025-05-16T03:51:46Z",
"warnings": [],
"contents": [
{
"markdown": "John Smith\nEmail: john@contoso.com\n",
"fields": {
"ContactName": {
"type": "string",
"valueString": "John Smith",
"spans": [
{
"offset": 0,
"length": 10
}
],
"confidence": 0.994,
"source": "D(1,69,234,333,234,333,283,69,283)"
},
"EmailAddress": {
"type": "string",
"valueString": "john@contoso.com",
"spans": [
{
"offset": 18,
"length": 16
}
],
"confidence": 0.998,
"source": "D(1,179,309,458,309,458,341,179,341)"
}
},
"kind": "document",
"startPageNumber": 1,
"endPageNumber": 1,
"unit": "pixel",
"pages": [
{
"pageNumber": 1,
"angle": 0.03410444,
"width": 1000,
"height": 620,
"spans": [
{
"offset": 0,
"length": 35
}
],
"words": [
{
"content": "John",
"span": {
"offset": 0,
"length": 4
},
"confidence": 0.992,
"source": "D(1,69,234,181,234,180,283,69,283)"
},
{
"content": "Smith",
"span": {
"offset": 5,
"length": 5
},
"confidence": 0.998,
"source": "D(1,200,234,333,234,333,282,200,283)"
},
{
"content": "Email:",
"span": {
"offset": 11,
"length": 6
},
"confidence": 0.995,
"source": "D(1,75,310,165,309,165,340,75,340)"
},
{
"content": "john@contoso.com",
"span": {
"offset": 18,
"length": 16
},
"confidence": 0.977,
"source": "D(1,179,309,458,311,458,340,179,341)"
}
],
"lines": [
{
"content": "John Smith",
"source": "D(1,69,234,333,233,333,282,69,282)",
"span": {
"offset": 0,
"length": 10
}
},
{
"content": "Email: john@contoso.com",
"source": "D(1,75,309,458,309,458,340,75,340)",
"span": {
"offset": 11,
"length": 23
}
}
]
}
],
"paragraphs": [
{
"content": "John Smith Email: john@contoso.com",
"source": "D(1,69,233,458,233,458,340,69,340)",
"span": {
"offset": 0,
"length": 34
}
}
],
"sections": [
{
"span": {
"offset": 0,
"length": 34
},
"elements": [
"/paragraphs/0"
]
}
]
}
]
}
}
Normalmente, seu aplicativo deve analisar o JSON para recuperar valores de campo. Por exemplo, o código Python a seguir extrai todos os valores de cadeia de caracteres:
# (continued from previous code example)
# Iterate through the fields and extract the names and type-specific values
contents = result_json["result"]["contents"]
for content in contents:
if "fields" in content:
fields = content["fields"]
for field_name, field_data in fields.items():
if field_data['type'] == "string":
print(f"{field_name}: {field_data['valueString']}")
A saída desse código é mostrada aqui:
ContactName: John Smith
EmailAddress: john@contoso.com