Analise o conteúdo
Sugestão
Consulte a guia Texto e imagens para obter mais detalhes!
Para analisar o conteúdo de um ficheiro, pode usar a API Azure Content Understanding para o submeter ao endpoint. Pode especificar o conteúdo como uma URL (para um ficheiro alojado num local acessível à Internet) ou carregar dados binários diretamente (por exemplo, um documento .pdf, uma imagem .png, um ficheiro áudio .mp3 ou um ficheiro de vídeo .mp4). O pedido de análise inclui o analisador a ser utilizado.
A análise é uma operação assíncrona. Após submeter o pedido, recebe um ID de operação que pode usar para verificar o estado e recuperar os resultados quando a operação estiver 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 e-mail da seguinte imagem de cartão de visita digitalizada:
Utilizar o SDK Python
O SDK Python para Compreensão de Conteúdos (azure-ai-contentunderstanding) fornece uma ContentUnderstandingClient classe que simplifica a interação com o serviço. O SDK gere autenticação, formatação de pedidos e sondagens automáticas para operações assíncronas.
O seguinte código Python utiliza o SDK para submeter para análise um cartão de visita 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}")
Sugestão
O método do SDK begin_analyze devolve um objeto 'poller'. Chamar .result() no poller gere automaticamente o polling até que a operação esteja concluída, por isso não precisa de escrever o seu próprio loop de polling.
Utilizar a API REST
Também pode submeter pedidos de análise diretamente usando a API REST. A sua aplicação cliente envia chamadas HTTP para o endpoint Content Understanding do seu recurso Microsoft Foundry, passando uma chave API no cabeçalho.
O código Python seguinte submete um pedido de análise usando uma URL, e depois sonda o serviço até a operação ser concluída e os resultados serem devolvidos.
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
Pode especificar uma URL para a localização do ficheiro de conteúdo, como mostrado aqui. Para submeter dados de ficheiros binários diretamente, use a analyzeBinary operação em vez disso.
Processamento de resultados de análises
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 para o 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 reconhecimento ótico de caracteres (OCR) do documento, incluindo locais de linhas de texto, palavras individuais e parágrafos em cada página.
Utilizar o SDK Python
Ao usar o SDK, o AnalysisResult objeto fornece acesso tipado aos resultados. A contents propriedade contém uma lista de objetos de conteúdo, cada um com campos, markdown e metadados. O código seguinte mostra como extrair valores de campos de cadeia:
# (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}")
Utilizar a API REST
Ao usar a API REST, a resposta é um payload JSON que a sua aplicação tem de analisar. Eis a resposta JSON completa para a análise de cartão de negócios.
{
"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"
]
}
]
}
]
}
}
Seu aplicativo normalmente deve analisar o JSON para recuperar valores de campo. Por exemplo, o seguinte código Python extrai todos os valores das cadeias :
# (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 deste código é mostrada aqui:
ContactName: John Smith
EmailAddress: john@contoso.com