다음을 통해 공유

Image Analysis 4.0 API 호출

  • 아티클

이 문서에서는 Image Analysis 4.0 API를 호출하여 이미지의 시각적 기능에 대한 정보를 반환하는 방법을 보여 줍니다. 또한 반환된 정보를 구문 분석하는 방법도 보여 줍니다.

필수 조건

이 가이드에서는 사용자가 빠른 시작 페이지에 언급된 단계를 따랐다고 가정합니다. 이것은 다음을 의미합니다.

  • Computer Vision 리소스를 생성하고 키와 엔드포인트 URL을 얻었습니다.
  • 적절한 SDK 패키지가 설치되어 있고 실행 중인 quickstart 애플리케이션이 있습니다. 여기에서 코드 예제를 기반으로 이 빠른 시작 애플리케이션을 수정할 수 있습니다.

클라이언트 만들기 및 인증

이미지 분석 서비스에 대해 인증하려면 Computer Vision 키와 엔드포인트 URL이 필요합니다. 이 가이드에서는 키와 엔드포인트를 사용하여 환경 변수 VISION_KEY 및 VISION_ENDPOINT를 정의했다고 가정합니다.

Important

API 키를 사용하는 경우 Azure Key Vault와 같은 다른 위치에 안전하게 저장합니다. API 키를 코드에 직접 포함하지 말고, 공개적으로 게시하지 마세요.

AI 서비스 보안에 대한 자세한 내용은 Azure AI 서비스에 대한 요청 인증을 참조하세요.

먼저 ImageAnalysisClient 개체를 만듭니다. 예시:

string endpoint = Environment.GetEnvironmentVariable("VISION_ENDPOINT");
string key = Environment.GetEnvironmentVariable("VISION_KEY");

// Create an Image Analysis client.
ImageAnalysisClient client = new ImageAnalysisClient(
    new Uri(endpoint),
    new AzureKeyCredential(key));

분석할 이미지를 선택하세요

공개적으로 액세스할 수 있는 이미지 URL을 제공하거나 이진 데이터를 SDK에 전달하여 이미지를 선택할 수 있습니다. 지원되는 이미지 형식은 이미지 요구 사항을 참조하세요.

이미지 URL

분석하려는 이미지의 Uri 개체를 만듭니다.

Uri imageURL = new Uri("https://aka.ms/azsdk/image-analysis/sample.jpg");

이미지 버퍼

또는 BinaryData 개체를 통해 이미지 데이터를 SDK에 전달할 수 있습니다. 예를 들어 분석하려는 로컬 이미지 파일에서 읽습니다.

using FileStream stream = new FileStream("sample.jpg", FileMode.Open);
BinaryData imageData = BinaryData.FromStream(stream);

시각적 기능 선택

Analysis 4.0 API를 통해 모든 서비스의 이미지 분석 기능에 액세스할 수 있습니다. 자체 사용 사례에 따라 수행할 작업을 선택합니다. 각 기능의 설명은 개요를 참조하세요. 이 섹션의 예제에는 사용 가능한 모든 시각적 기능이 추가되어 있지만 실제 사용에 필요한 기능 수는 더 적을 수 있습니다.

Important

시각적 기능 Captions 및 DenseCaptions은/는 특정 Azure 지역에서만 지원됩니다. 지역 가용성 참조

VisualFeatures visualFeatures =
    VisualFeatures.Caption |
    VisualFeatures.DenseCaptions |
    VisualFeatures.Objects |
    VisualFeatures.Read |
    VisualFeatures.Tags |
    VisualFeatures.People |
    VisualFeatures.SmartCrops;

분석 옵션 선택

ImageAnalysisOptions 개체를 사용하여 Analyze Image API 호출의 다양한 옵션을 지정합니다.

  • 언어: 반환되는 데이터의 언어를 지정할 수 있습니다. 언어는 선택 사항이며 기본값은 영어입니다. 지원되는 언어 코드 목록과 각 언어에 지원되는 시각적 기능은 언어 지원을 참조하세요.
  • 성 중립 캡션: 캡션 또는 조밀 캡션을 추출하는 경우(VisualFeatures.Caption 또는 VisualFeatures.DenseCaptions사용) 성 중립적 캡션을 요청할 수 있습니다. 성 중립적 캡션은 선택 사항이며, 기본값은 성별 캡션입니다. 예를 들어, 영어에서 성 중립적 캡션을 선택하면 woman 또는 man과 같은 용어는 person으로 대체되고 boy 또는 girl은 child로 대체됩니다.
  • 가로 세로 비율 자르기: 가로 세로 비율은 대상 자르기 너비를 높이로 나누어 계산됩니다. 지원되는 값은 0.75에서 1.8(포함)입니다. 이 속성 설정은 VisualFeatures.SmartCrops가 시각적 기능 목록의 일부로 선택된 경우에만 관련됩니다. VisualFeatures.SmartCrops를 선택했지만 가로 세로 비율을 지정하지 않은 경우 서비스는 적합하다고 판단하는 가로 세로 비율이 포함된 자르기 제안 하나를 반환합니다. 이 경우 가로 세로 비율은 0.5에서 2.0(포함) 사이입니다.
ImageAnalysisOptions options = new ImageAnalysisOptions { 
    GenderNeutralCaption = true,
    Language = "en",
    SmartCropsAspectRatios = new float[] { 0.9F, 1.33F }};

Analyze API 호출

이 섹션에서는 서비스에 대한 분석 호출을 수행하는 방법을 보여 줍니다.

여기에 표시된 대로 ImageAnalysisClient 개체에서 분석 메서드를 호출합니다. 이 호출은 동기식이며, 서비스가 결과를 반환하거나 오류가 발생할 때까지 실행이 차단됩니다. 또는 비차단 AnalyzeAsync 메서드를 호출할 수 있습니다.

위의 섹션에서 만든 입력 개체를 사용합니다. URL 대신 이미지 버퍼에서 분석하려면 메서드 호출의 imageURL을 imageData 변수로 바꿉니다.

ImageAnalysisResult result = client.Analyze(
    imageURL,
    visualFeatures,
    options);

서비스에서 결과 가져오기

다음 코드는 다양한 분석 작업의 결과를 구문 분석하는 방법을 보여 줍니다.

Console.WriteLine("Image analysis results:");

// Print caption results to the console
Console.WriteLine(" Caption:");
Console.WriteLine($"   '{result.Caption.Text}', Confidence {result.Caption.Confidence:F4}");

// Print dense caption results to the console
Console.WriteLine(" Dense Captions:");
foreach (DenseCaption denseCaption in result.DenseCaptions.Values)
{
    Console.WriteLine($"   '{denseCaption.Text}', Confidence {denseCaption.Confidence:F4}, Bounding box {denseCaption.BoundingBox}");
}

// Print object detection results to the console
Console.WriteLine(" Objects:");
foreach (DetectedObject detectedObject in result.Objects.Values)
{
    Console.WriteLine($"   '{detectedObject.Tags.First().Name}', Bounding box {detectedObject.BoundingBox.ToString()}");
}

// Print text (OCR) analysis results to the console
Console.WriteLine(" Read:");
foreach (DetectedTextBlock block in result.Read.Blocks)
    foreach (DetectedTextLine line in block.Lines)
    {
        Console.WriteLine($"   Line: '{line.Text}', Bounding Polygon: [{string.Join(" ", line.BoundingPolygon)}]");
        foreach (DetectedTextWord word in line.Words)
        {
            Console.WriteLine($"     Word: '{word.Text}', Confidence {word.Confidence.ToString("#.####")}, Bounding Polygon: [{string.Join(" ", word.BoundingPolygon)}]");
        }
    }

// Print tags results to the console
Console.WriteLine(" Tags:");
foreach (DetectedTag tag in result.Tags.Values)
{
    Console.WriteLine($"   '{tag.Name}', Confidence {tag.Confidence:F4}");
}

// Print people detection results to the console
Console.WriteLine(" People:");
foreach (DetectedPerson person in result.People.Values)
{
    Console.WriteLine($"   Person: Bounding box {person.BoundingBox.ToString()}, Confidence {person.Confidence:F4}");
}

// Print smart-crops analysis results to the console
Console.WriteLine(" SmartCrops:");
foreach (CropRegion cropRegion in result.SmartCrops.Values)
{
    Console.WriteLine($"   Aspect ratio: {cropRegion.AspectRatio}, Bounding box: {cropRegion.BoundingBox}");
}

// Print metadata
Console.WriteLine(" Metadata:");
Console.WriteLine($"   Model: {result.ModelVersion}");
Console.WriteLine($"   Image width: {result.Metadata.Width}");
Console.WriteLine($"   Image hight: {result.Metadata.Height}");

문제 해결

예외 처리

.NET SDK를 사용하여 이미지 분석과 상호 작용할 때 200(성공) 상태 코드가 없는 서비스의 응답은 예외를 throw합니다. 예를 들어 URL이 손상되어 액세스할 수 없는 이미지를 분석하려고 하면 잘못된 요청을 나타내는 400 상태가 반환되고 해당 예외가 throw됩니다.

다음 코드 조각에서 오류는 예외를 catch하고 오류에 대한 추가 정보를 표시하여 적절히 처리됩니다.

var imageUrl = new Uri("https://some-host-name.com/non-existing-image.jpg");

try
{
    var result = client.Analyze(imageUrl, VisualFeatures.Caption);
}
catch (RequestFailedException e)
{
    if (e.Status != 200)
    {
        Console.WriteLine("Error analyzing image.");
        Console.WriteLine($"HTTP status code {e.Status}: {e.Message}");
    }
    else
    {
        throw;
    }
}

SDK 로깅을 사용하는 방법에 대한 자세한 내용은 여기에서 자세히 알아볼 수 있습니다.

필수 조건

이 가이드에서는 사용자가 빠른 시작의 단계를 따랐다고 가정합니다. 이것은 다음을 의미합니다.

  • Computer Vision 리소스를 만들고 키 및 엔드포인트 URL을 획득했습니다.
  • 적절한 SDK 패키지를 설치했으며 작동하는 빠른 시작 응용 프로그램이 있습니다. 여기에서 코드 예제를 기반으로 이 빠른 시작 애플리케이션을 수정할 수 있습니다.

클라이언트 만들기 및 인증

이미지 분석 서비스에 대해 인증하려면 Computer Vision 키와 엔드포인트 URL이 필요합니다. 이 가이드에서는 키와 엔드포인트를 사용하여 환경 변수 VISION_KEY 및 VISION_ENDPOINT를 정의했다고 가정합니다.

Important

API 키를 사용하는 경우 Azure Key Vault와 같은 다른 위치에 안전하게 저장합니다. API 키를 코드에 직접 포함하지 말고, 공개적으로 게시하지 마세요.

AI 서비스 보안에 대한 자세한 내용은 Azure AI 서비스에 대한 요청 인증을 참조하세요.

먼저 생성자 중 하나를 사용하여 ImageAnalysisClient 개체를 생성합니다. 예시:

client = ImageAnalysisClient(
    endpoint=endpoint,
    credential=AzureKeyCredential(key)
)

분석할 이미지를 선택하세요

공개적으로 액세스할 수 있는 이미지 URL을 제공하거나 이미지 데이터를 SDK의 입력 버퍼로 읽어 이미지를 선택할 수 있습니다. 지원되는 이미지 형식은 이미지 요구 사항을 참조하세요.

이미지 URL

사용할 수 있는 샘플 이미지 URL은 다음과 같습니다.

# Define image URL
image_url = "https://learn.microsoft.com/azure/ai-services/computer-vision/media/quickstarts/presentation.png"

이미지 버퍼

또는 이미지를 bytes 개체로 전달할 수 있습니다. 예를 들어 분석하려는 로컬 이미지 파일에서 읽습니다.

# Load image to analyze into a 'bytes' object
with open("sample.jpg", "rb") as f:
    image_data = f.read()

시각적 기능 선택

Analysis 4.0 API를 통해 모든 서비스의 이미지 분석 기능에 액세스할 수 있습니다. 자체 사용 사례에 따라 수행할 작업을 선택합니다. 각 기능의 설명은 개요를 참조하세요. 이 섹션의 예제에는 사용 가능한 모든 시각적 기능이 추가되어 있지만 실제 사용에 필요한 기능 수는 더 적을 수 있습니다.

Important

시각적 기능 캡션 및 DenseCaptions는 특정 Azure 지역에서만 지원됩니다. 지역 가용성을 참조하세요.

visual_features =[
        VisualFeatures.TAGS,
        VisualFeatures.OBJECTS,
        VisualFeatures.CAPTION,
        VisualFeatures.DENSE_CAPTIONS,
        VisualFeatures.READ,
        VisualFeatures.SMART_CROPS,
        VisualFeatures.PEOPLE,
    ]

옵션을 사용하여 analyze_from_url 메서드 호출

다음 코드는 위에서 선택한 기능과 아래에 정의된 기타 옵션을 사용하여 클라이언트에 대해 analyze_from_url 메서드를 호출합니다. URL 대신 이미지 버퍼에서 분석하려면 image_data=image_data를 첫 번째 인수로 사용하여 analyze 메서드를 대신 호출합니다.

# Analyze all visual features from an image stream. This will be a synchronously (blocking) call.
result = client.analyze_from_url(
    image_url=image_url,
    visual_features=visual_features,
    smart_crops_aspect_ratios=[0.9, 1.33],
    gender_neutral_caption=True,
    language="en"
)

스마트 자르기 가로 세로 비율 선택

가로 세로 비율은 대상 자르기 너비를 높이로 나누어 계산됩니다. 지원되는 값은 0.75에서 1.8(포함)입니다. 이 속성 설정은 VisualFeatures.SMART_CROPS가 시각적 기능 목록의 일부로 선택된 경우에만 관련됩니다. VisualFeatures.SMART_CROPS를 선택했지만 가로 세로 비율을 지정하지 않은 경우 서비스는 적합하다고 판단하는 가로 세로 비율이 포함된 자르기 제안 하나를 반환합니다. 이 경우 가로 세로 비율은 0.5에서 2.0(포함) 사이입니다.

성 중립적 캡션을 선택하세요.

캡션 또는 조밀 캡션을 추출하는 경우(VisualFeatures.CAPTION 또는 VisualFeatures.DENSE_CAPTIONS 사용) 성 중립적 캡션을 요청할 수 있습니다. 성 중립적 캡션은 선택 사항이며, 기본값은 성별 캡션입니다. 예를 들어, 영어에서 성 중립적 캡션을 선택하면 woman 또는 man과 같은 용어는 person으로 대체되고 boy 또는 girl은 child로 대체됩니다.

언어 지정

반환된 데이터의 언어를 지정할 수 있습니다. 언어는 선택 사항이며 기본값은 영어입니다. 지원되는 언어 코드 목록과 각 언어에 지원되는 시각적 기능은 언어 지원을 참조하세요.

서비스에서 결과 가져오기

다음 코드는 analyze_from_url 또는 analyze 작업의 결과를 구문 분석하는 방법을 보여 줍니다.

# Print all analysis results to the console
print("Image analysis results:")

if result.caption is not None:
    print(" Caption:")
    print(f"   '{result.caption.text}', Confidence {result.caption.confidence:.4f}")

if result.dense_captions is not None:
    print(" Dense Captions:")
    for caption in result.dense_captions.list:
        print(f"   '{caption.text}', {caption.bounding_box}, Confidence: {caption.confidence:.4f}")

if result.read is not None:
    print(" Read:")
    for line in result.read.blocks[0].lines:
        print(f"   Line: '{line.text}', Bounding box {line.bounding_polygon}")
        for word in line.words:
            print(f"     Word: '{word.text}', Bounding polygon {word.bounding_polygon}, Confidence {word.confidence:.4f}")

if result.tags is not None:
    print(" Tags:")
    for tag in result.tags.list:
        print(f"   '{tag.name}', Confidence {tag.confidence:.4f}")

if result.objects is not None:
    print(" Objects:")
    for object in result.objects.list:
        print(f"   '{object.tags[0].name}', {object.bounding_box}, Confidence: {object.tags[0].confidence:.4f}")

if result.people is not None:
    print(" People:")
    for person in result.people.list:
        print(f"   {person.bounding_box}, Confidence {person.confidence:.4f}")

if result.smart_crops is not None:
    print(" Smart Cropping:")
    for smart_crop in result.smart_crops.list:
        print(f"   Aspect ratio {smart_crop.aspect_ratio}: Smart crop {smart_crop.bounding_box}")

print(f" Image height: {result.metadata.height}")
print(f" Image width: {result.metadata.width}")
print(f" Model version: {result.model_version}")

문제 해결

예외

analyze 메서드는 서비스의 비성공 HTTP 상태 코드 응답에 HttpResponseError 예외를 발생시킵니다. 예외의 status_code는 HTTP 응답 상태 코드입니다. 예외의 error.message에는 문제를 진단할 수 있는 자세한 메시지가 포함되어 있습니다.

try:
    result = client.analyze( ... )
except HttpResponseError as e:
    print(f"Status code: {e.status_code}")
    print(f"Reason: {e.reason}")
    print(f"Message: {e.error.message}")

예를 들어 잘못된 인증 키를 제공하는 경우:

Status code: 401
Reason: PermissionDenied
Message: Access denied due to invalid subscription key or wrong API endpoint. Make sure to provide a valid key for an active subscription and use a correct regional API endpoint for your resource.

또는 존재하지 않거나 액세스할 수 없는 이미지 URL을 제공하는 경우:

Status code: 400
Reason: Bad Request
Message: The provided image url is not accessible.

로깅

클라이언트는 표준 Python 로깅 라이브러리를 사용합니다. SDK는 문제 해결에 유용할 수 있는 HTTP 요청 및 응답 세부 정보를 로그합니다. stdout에 로그하려면 다음을 추가합니다.

import sys
import logging

# Acquire the logger for this client library. Use 'azure' to affect both
# 'azure.core` and `azure.ai.vision.imageanalysis' libraries.
logger = logging.getLogger("azure")

# Set the desired logging level. logging.INFO or logging.DEBUG are good options.
logger.setLevel(logging.INFO)

# Direct logging output to stdout (the default):
handler = logging.StreamHandler(stream=sys.stdout)
# Or direct logging output to a file:
# handler = logging.FileHandler(filename = 'sample.log')
logger.addHandler(handler)

# Optional: change the default logging format. Here we add a timestamp.
formatter = logging.Formatter("%(asctime)s:%(levelname)s:%(name)s:%(message)s")
handler.setFormatter(formatter)

기본적으로 로그는 URL 쿼리 문자열의 값, 일부 HTTP 요청 및 응답 헤더의 값(키를 보유하고 있는 Ocp-Apim-Subscription-Key 포함), 요청 및 응답 페이로드를 수정합니다. 수정 없는 로그를 만들려면 ImageAnalysisClient를 만들 때 또는 클라이언트에서 analyze를 호출할 때 메서드 인수 logging_enable = True를 설정합니다.

# Create an Image Analysis client with none redacted log
client = ImageAnalysisClient(
    endpoint=endpoint,
    credential=AzureKeyCredential(key),
    logging_enable=True
)

로그 수준 logging.DEBUG에 대해서만 수정되지 않은 로그가 생성됩니다. 보안이 손상되지 않도록 수정되지 않은 로그를 보호해야 합니다. 자세한 내용은 Python용 Azure 라이브러리에서 로깅 구성을 참조하세요.

필수 조건

이 가이드에서는 사용자가 빠른 시작 페이지의 단계를 따랐다고 가정합니다. 이것은 다음을 의미합니다.

  • Computer Vision 리소스를 생성하고 키와 엔드포인트 URL을 얻었습니다.
  • 적절한 SDK 패키지가 설치되어 있고 실행 중인 quickstart 애플리케이션이 있습니다. 여기에서 코드 예제를 기반으로 이 빠른 시작 애플리케이션을 수정할 수 있습니다.

클라이언트 만들기 및 인증

이미지 분석 서비스에 인증하려면 Computer Vision 키와 엔드포인트 URL이 필요합니다. 이 가이드에서는 키와 엔드포인트를 사용하여 환경 변수 VISION_KEY 및 VISION_ENDPOINT를 정의했다고 가정합니다.

Important

API 키를 사용하는 경우 Azure Key Vault와 같은 다른 위치에 안전하게 저장합니다. API 키를 코드에 직접 포함하지 말고, 공개적으로 게시하지 마세요.

AI 서비스 보안에 대한 자세한 내용은 Azure AI 서비스에 대한 요청 인증을 참조하세요.

먼저 ImageAnalysisClient 개체를 만듭니다. 예시:

String endpoint = System.getenv("VISION_ENDPOINT");
String key = System.getenv("VISION_KEY");

if (endpoint == null || key == null) {
    System.out.println("Missing environment variable 'VISION_ENDPOINT' or 'VISION_KEY'.");
    System.out.println("Set them before running this sample.");
    System.exit(1);
}

// Create a synchronous Image Analysis client.
ImageAnalysisClient client = new ImageAnalysisClientBuilder()
    .endpoint(endpoint)
    .credential(new KeyCredential(key))
    .buildClient();

분석할 이미지를 선택하세요

공개적으로 액세스할 수 있는 이미지 URL을 제공하거나 이미지 데이터를 SDK의 입력 버퍼로 읽어 이미지를 선택할 수 있습니다. 지원되는 이미지 형식은 이미지 요구 사항을 참조하세요.

이미지 URL

분석하려는 이미지의 공개적으로 액세스할 수 있는 URL을 포함할 imageUrl 문자열을 만듭니다.

String imageUrl = "https://learn.microsoft.com/azure/ai-services/computer-vision/media/quickstarts/presentation.png";

이미지 버퍼

또는 BinaryData 개체를 사용하여 이미지를 메모리 버퍼로 전달할 수 있습니다. 예를 들어 분석하려는 로컬 이미지 파일에서 읽습니다.

BinaryData imageData = BinaryData.fromFile(new File("sample.png").toPath());

시각적 기능 선택

Analysis 4.0 API를 통해 모든 서비스의 이미지 분석 기능에 액세스할 수 있습니다. 자체 사용 사례에 따라 수행할 작업을 선택합니다. 각 기능의 설명은 개요를 참조하세요. 이 섹션의 예제에는 사용 가능한 모든 시각적 기능이 추가되어 있지만 실제 사용에 필요한 기능 수는 더 적을 수 있습니다.

Important

시각적 기능 캡션 및 DenseCaptions는 특정 Azure 지역에서만 지원됩니다. 지역 가용성을 참조하세요.

// visualFeatures: Select one or more visual features to analyze.
List<VisualFeatures> visualFeatures = Arrays.asList(
            VisualFeatures.SMART_CROPS,
            VisualFeatures.CAPTION,
            VisualFeatures.DENSE_CAPTIONS,
            VisualFeatures.OBJECTS,
            VisualFeatures.PEOPLE,
            VisualFeatures.READ,
            VisualFeatures.TAGS);

분석 옵션 선택

ImageAnalysisOptions 개체를 사용하여 분석 API 호출의 다양한 옵션을 지정합니다.

  • 언어: 반환되는 데이터의 언어를 지정할 수 있습니다. 언어는 선택 사항이며 기본값은 영어입니다. 지원되는 언어 코드 목록과 각 언어에 지원되는 시각적 기능은 언어 지원을 참조하세요.
  • 성 중립 캡션: 캡션 또는 조밀 캡션을 추출하는 경우(VisualFeatures.CAPTION 또는 VisualFeatures.DENSE_CAPTIONS사용) 성 중립적 캡션을 요청할 수 있습니다. 성 중립적 캡션은 선택 사항이며, 기본값은 성별 캡션입니다. 예를 들어, 영어에서 성 중립적 캡션을 선택하면 woman 또는 man과 같은 용어는 person으로 대체되고 boy 또는 girl은 child로 대체됩니다.
  • 가로 세로 비율 자르기: 가로 세로 비율은 대상 자르기 너비를 높이로 나누어 계산됩니다. 지원되는 값은 0.75에서 1.8(포함)입니다. 이 속성 설정은 VisualFeatures.SMART_CROPS가 시각적 기능 목록의 일부로 선택된 경우에만 관련됩니다. VisualFeatures.SMART_CROPS를 선택했지만 가로 세로 비율을 지정하지 않은 경우 서비스는 적합하다고 판단하는 가로 세로 비율이 포함된 자르기 제안 하나를 반환합니다. 이 경우 가로 세로 비율은 0.5에서 2.0(포함) 사이입니다.
// Specify analysis options (or set `options` to null for defaults)
ImageAnalysisOptions options = new ImageAnalysisOptions()
    .setLanguage("en")
    .setGenderNeutralCaption(true)
    .setSmartCropsAspectRatios(Arrays.asList(0.9, 1.33, 1.78));

analyzeFromUrl 메서드 호출

이 섹션에서는 서비스에 대한 분석 호출을 수행하는 방법을 보여 줍니다.

여기에 표시된 대로 ImageAnalysisClient 개체에서 analyzeFromUrl 메서드를 호출합니다. 이 호출은 동기식이며, 서비스가 결과를 반환하거나 오류가 발생할 때까지 차단합니다. 또는 ImageAnalysisAsyncClient 개체를 대신 사용하고 비차단 메서드인 analyzeFromUrl 메서드를 호출할 수 있습니다.

URL 대신 이미지 버퍼에서 분석하려면 imageData를 첫 번째 인수로 제공하여 analyze 메서드를 대신 호출합니다.

try {
    // Analyze all visual features from an image URL. This is a synchronous (blocking) call.
    ImageAnalysisResult result = client.analyzeFromUrl(
        imageUrl,
        visualFeatures,
        options);

    printAnalysisResults(result);

} catch (HttpResponseException e) {
    System.out.println("Exception: " + e.getClass().getSimpleName());
    System.out.println("Status code: " + e.getResponse().getStatusCode());
    System.out.println("Message: " + e.getMessage());
} catch (Exception e) {
    System.out.println("Message: " + e.getMessage());
}

서비스에서 결과 가져오기

다음 코드는 analyzeFromUrl 또는 analyze 작업의 결과를 구문 분석하는 방법을 보여 줍니다.

// Print all analysis results to the console
public static void printAnalysisResults(ImageAnalysisResult result) {

    System.out.println("Image analysis results:");

    if (result.getCaption() != null) {
        System.out.println(" Caption:");
        System.out.println("   \"" + result.getCaption().getText() + "\", Confidence "
            + String.format("%.4f", result.getCaption().getConfidence()));
    }

    if (result.getDenseCaptions() != null) {
        System.out.println(" Dense Captions:");
        for (DenseCaption denseCaption : result.getDenseCaptions().getValues()) {
            System.out.println("   \"" + denseCaption.getText() + "\", Bounding box "
                + denseCaption.getBoundingBox() + ", Confidence " + String.format("%.4f", denseCaption.getConfidence()));
        }
    }

    if (result.getRead() != null) {
        System.out.println(" Read:");
        for (DetectedTextLine line : result.getRead().getBlocks().get(0).getLines()) {
            System.out.println("   Line: '" + line.getText()
                + "', Bounding polygon " + line.getBoundingPolygon());
            for (DetectedTextWord word : line.getWords()) {
                System.out.println("     Word: '" + word.getText()
                    + "', Bounding polygon " + word.getBoundingPolygon()
                    + ", Confidence " + String.format("%.4f", word.getConfidence()));
            }
        }
    }

    if (result.getTags() != null) {
        System.out.println(" Tags:");
        for (DetectedTag tag : result.getTags().getValues()) {
            System.out.println("   \"" + tag.getName() + "\", Confidence " + String.format("%.4f", tag.getConfidence()));
        }
    }

    if (result.getObjects() != null) {
        System.out.println(" Objects:");
        for (DetectedObject detectedObject : result.getObjects().getValues()) {
            System.out.println("   \"" + detectedObject.getTags().get(0).getName() + "\", Bounding box "
                + detectedObject.getBoundingBox() + ", Confidence " + String.format("%.4f", detectedObject.getTags().get(0).getConfidence()));
        }
    }

    if (result.getPeople() != null) {
        System.out.println(" People:");
        for (DetectedPerson person : result.getPeople().getValues()) {
            System.out.println("   Bounding box "
                + person.getBoundingBox() + ", Confidence " + String.format("%.4f", person.getConfidence()));
        }
    }

    if (result.getSmartCrops() != null) {
        System.out.println(" Crop Suggestions:");
        for (CropRegion cropRegion : result.getSmartCrops().getValues()) {
            System.out.println("   Aspect ratio "
                + cropRegion.getAspectRatio() + ": Bounding box " + cropRegion.getBoundingBox());
        }
    }

    System.out.println(" Image height = " + result.getMetadata().getHeight());
    System.out.println(" Image width = " + result.getMetadata().getWidth());
    System.out.println(" Model version = " + result.getModelVersion());
}

문제 해결

예외

analyze 메서드는 서비스가 비성공 HTTP 상태 코드로 응답할 때 HttpResponseException 을 throw합니다. 예외의 getResponse().getStatusCode()는 HTTP 응답 상태 코드를 보유하고 있습니다. 예외의 getMessage()에는 문제를 진단할 수 있는 자세한 메시지가 포함되어 있습니다.

try {
    ImageAnalysisResult result = client.analyze(...)
} catch (HttpResponseException e) {
    System.out.println("Exception: " + e.getClass().getSimpleName());
    System.out.println("Status code: " + e.getResponse().getStatusCode());
    System.out.println("Message: " + e.getMessage());
} catch (Exception e) {
    System.out.println("Message: " + e.getMessage());
}

예를 들어 잘못된 인증 키를 제공하는 경우:

Exception: ClientAuthenticationException
Status code: 401
Message: Status code 401, "{"error":{"code":"401","message":"Access denied due to invalid subscription key or wrong API endpoint. Make sure to provide a valid key for an active subscription and use a correct regional API endpoint for your resource."}}"

또는 인식되지 않는 형식으로 이미지를 제공하는 경우:

Exception: HttpResponseException
Status code: 400
Message: Status code 400, "{"error":{"code":"InvalidRequest","message":"Image format is not valid.","innererror":{"code":"InvalidImageFormat","message":"Input data is not a valid image."}}}"

HTTP 요청/응답 로깅 사용

통신을 통해 이미지 분석 서비스로 전송된 HTTP 요청 또는 수신된 응답을 검토하면 문제 해결에 유용할 수 있습니다. 이미지 분석 클라이언트 라이브러리는 임시 디버깅을 위한 기본 제공 콘솔 로깅 프레임워크를 지원합니다. 또한 SLF4J 인터페이스를 사용하여 고급 로깅도 지원합니다. 자세한 내용은 Java용 Azure SDK의 로깅 구성을 참조하세요.

아래 섹션에서는 기본 제공 프레임워크를 사용하여 콘솔 로깅을 사용하도록 설정하는 방법을 설명합니다.

환경 변수 설정을 통해

다음 두 환경 변수를 설정하여 전체 애플리케이션의 HTTP 요청 및 응답에 콘솔 로깅을 사용하도록 설정할 수 있습니다. 이 변경 내용은 HTTP 요청 및 응답 로깅을 지원하는 모든 Azure 클라이언트에 영향을 줍니다.

  • 환경 변수 AZURE_LOG_LEVEL을 debug로 설정
  • 환경 변수 AZURE_HTTP_LOG_DETAIL_LEVEL을 다음 값 중 하나로 설정
값 로깅 수준
none HTTP 요청/응답 로깅 사용하지 않음
basic URL, HTTP 메서드, 요청 완료 시간만 로그합니다.
headers BASIC의 모든 항목 및 모든 요청 및 응답 헤더를 로그합니다.
body BASIC의 모든 항목 및 모든 요청 및 응답 본문을 로그합니다.
body_and_headers 헤더 및 본문의 모든 항목을 로그합니다.

httpLogOptions 설정을 통해

단일 클라이언트에 HTTP 요청 및 응답의 콘솔 로깅을 사용하려면

  • 환경 변수 AZURE_LOG_LEVEL을 debug로 설정
  • ImageAnalysisClient를 빌드할 때 httpLogOptions 호출을 추가
ImageAnalysisClient client = new ImageAnalysisClientBuilder()
    .endpoint(endpoint)
    .credential(new KeyCredential(key))
    .httpLogOptions(new HttpLogOptions().setLogLevel(HttpLogDetailLevel.BODY_AND_HEADERS))
    .buildClient();

열거형 HttpLogDetailLevel은 지원되는 로깅 수준을 정의합니다.

기본적으로 로깅할 때 특정 HTTP 헤더 및 쿼리 매개 변수 값이 수정됩니다. 로그해도 안전한 헤더 및 쿼리 매개 변수를 지정하여 이 기본값을 재정의할 수 있습니다.

ImageAnalysisClient client = new ImageAnalysisClientBuilder()
    .endpoint(endpoint)
    .credential(new KeyCredential(key))
    .httpLogOptions(new HttpLogOptions().setLogLevel(HttpLogDetailLevel.BODY_AND_HEADERS)
        .addAllowedHeaderName("safe-to-log-header-name")
        .addAllowedQueryParamName("safe-to-log-query-parameter-name"))
    .buildClient();

예를 들어 HTTP 요청의 수정되지 않은 전체 로그를 얻으려면 다음을 적용합니다.

    .httpLogOptions(new HttpLogOptions().setLogLevel(HttpLogDetailLevel.BODY_AND_HEADERS)
        .addAllowedHeaderName("Ocp-Apim-Subscription-Key")
        .addAllowedQueryParamName("features")
        .addAllowedQueryParamName("language")
        .addAllowedQueryParamName("gender-neutral-caption")
        .addAllowedQueryParamName("smartcrops-aspect-ratios")
        .addAllowedQueryParamName("model-version"))

수정되지 않은 HTTP 응답을 얻으려면 위에 더 추가합니다. 수정되지 않은 로그를 공유하는 경우 구독 키와 같은 비밀이 포함되어 있지 않은지 확인합니다.

필수 조건

이 가이드에서는 사용자가 빠른 시작에 언급된 단계를 따랐다고 가정합니다. 이것은 다음을 의미합니다.

  • Computer Vision 리소스를 생성하고 키와 엔드포인트 URL을 얻었습니다.
  • 적절한 SDK 패키지가 설치되어 있고 실행 중인 quickstart 애플리케이션이 있습니다. 여기에서 코드 예제를 기반으로 이 빠른 시작 애플리케이션을 수정할 수 있습니다.

클라이언트 만들기 및 인증

이미지 분석 서비스에 대해 인증하려면 Computer Vision 키와 엔드포인트 URL이 필요합니다. 이 가이드에서는 키와 엔드포인트를 사용하여 환경 변수 VISION_KEY 및 VISION_ENDPOINT를 정의했다고 가정합니다.

Important

API 키를 사용하는 경우 Azure Key Vault와 같은 다른 위치에 안전하게 저장합니다. API 키를 코드에 직접 포함하지 말고, 공개적으로 게시하지 마세요.

AI 서비스 보안에 대한 자세한 내용은 Azure AI 서비스에 대한 요청 인증을 참조하세요.

먼저 ImageAnalysisClient 개체를 만듭니다. 예시:

// Load the .env file if it exists
require("dotenv").config();

const endpoint = process.env['VISION_ENDPOINT'] || '<your_endpoint>';
const key = process.env['VISION_KEY'] || '<your_key>';

const credential = new AzureKeyCredential(key);
const client = createClient(endpoint, credential);

분석할 이미지를 선택하세요

공개적으로 액세스할 수 있는 이미지 URL을 제공하거나 이미지 데이터를 SDK의 입력 버퍼로 읽어 이미지를 선택할 수 있습니다. 지원되는 이미지 형식은 이미지 요구 사항을 참조하세요.

이미지 URL

사용할 수 있는 샘플 이미지 URL은 다음과 같습니다.

const imageUrl = 'https://learn.microsoft.com/azure/ai-services/computer-vision/media/quickstarts/presentation.png';

이미지 버퍼

또는 이미지를 데이터 배열로 전달할 수 있습니다. 예를 들어 분석하려는 로컬 이미지 파일에서 읽습니다.

const imagePath = '../sample.jpg';
const imageData = fs.readFileSync(imagePath);

시각적 기능 선택

Analysis 4.0 API를 통해 모든 서비스의 이미지 분석 기능에 액세스할 수 있습니다. 자체 사용 사례에 따라 수행할 작업을 선택합니다. 각 기능의 설명은 개요를 참조하세요. 이 섹션의 예제에는 사용 가능한 모든 시각적 기능이 추가되어 있지만 실제 사용에 필요한 기능 수는 더 적을 수 있습니다.

Important

시각적 기능 캡션 및 DenseCaptions는 특정 Azure 지역에서만 지원됩니다. 을 참조하세요.

const features = [
  'Caption',
  'DenseCaptions',
  'Objects',
  'People',
  'Read',
  'SmartCrops',
  'Tags'
];

옵션을 사용하여 Analyze API 호출

다음 코드는 위에서 선택한 기능과 다음에 정의된 기타 옵션을 사용하여 Analyze Image API를 호출합니다. URL 대신 이미지 버퍼에서 분석하려면 메서드 호출의 imageURL을 imageData로 바꿉니다.

const result = await client.path('/imageanalysis:analyze').post({
  body: {
      url: imageUrl
  },
  queryParameters: {
      features: features,
      'language': 'en',
      'gender-neutral-captions': 'true',
      'smartCrops-aspect-ratios': [0.9, 1.33]
  },
  contentType: 'application/json'
});

스마트 자르기 가로 세로 비율 선택

가로 세로 비율은 대상 자르기 너비를 높이로 나누어 계산됩니다. 지원되는 값은 0.75에서 1.8(포함)입니다. 이 속성 설정은 VisualFeatures.SmartCrops가 시각적 기능 목록의 일부로 선택된 경우에만 관련됩니다. VisualFeatures.SmartCrops를 선택했지만 가로 세로 비율을 지정하지 않은 경우 서비스는 적합하다고 판단하는 가로 세로 비율이 포함된 자르기 제안 하나를 반환합니다. 이 경우 가로 세로 비율은 0.5에서 2.0(포함) 사이입니다.

성 중립적 캡션을 선택하세요.

캡션 또는 조밀 캡션을 추출하는 경우(VisualFeatures.Caption 또는 VisualFeatures.DenseCaptions 사용) 성 중립적 캡션을 요청할 수 있습니다. 성 중립적 캡션은 선택 사항이며, 기본값은 성별 캡션입니다. 예를 들어, 영어에서 성 중립적 캡션을 선택하면 woman 또는 man과 같은 용어는 person으로 대체되고 boy 또는 girl은 child로 대체됩니다.

언어 지정

반환된 데이터의 언어를 지정할 수 있습니다. 언어는 선택 사항이며 기본값은 영어입니다. 지원되는 언어 코드 목록과 각 언어에 지원되는 시각적 기능은 언어 지원을 참조하세요.

서비스에서 결과 가져오기

다음 코드는 다양한 분석 작업의 결과를 구문 분석하는 방법을 보여 줍니다.

const iaResult = result.body;

console.log(`Model Version: ${iaResult.modelVersion}`);
console.log(`Image Metadata: ${JSON.stringify(iaResult.metadata)}`);
if (iaResult.captionResult) {
  console.log(`Caption: ${iaResult.captionResult.text} (confidence: ${iaResult.captionResult.confidence})`);
}
if (iaResult.denseCaptionsResult) {
  iaResult.denseCaptionsResult.values.forEach(denseCaption => console.log(`Dense Caption: ${JSON.stringify(denseCaption)}`));
}
if (iaResult.objectsResult) {
  iaResult.objectsResult.values.forEach(object => console.log(`Object: ${JSON.stringify(object)}`));
}
if (iaResult.peopleResult) {
  iaResult.peopleResult.values.forEach(person => console.log(`Person: ${JSON.stringify(person)}`));
}
if (iaResult.readResult) {
  iaResult.readResult.blocks.forEach(block => console.log(`Text Block: ${JSON.stringify(block)}`));
}
if (iaResult.smartCropsResult) {
  iaResult.smartCropsResult.values.forEach(smartCrop => console.log(`Smart Crop: ${JSON.stringify(smartCrop)}`));
}
if (iaResult.tagsResult) {
  iaResult.tagsResult.values.forEach(tag => console.log(`Tag: ${JSON.stringify(tag)}`));
}

문제 해결

로깅

로깅을 사용하도록 설정하면 실패에 대한 유용한 정보를 파악하는 데 도움이 될 수 있습니다. HTTP 요청 및 응답 로그를 보려면 AZURE_LOG_LEVEL 환경 변수를 info로 설정합니다. 또는 @azure/logger에서 setLogLevel을 호출하여 런타임에 로깅을 사용하도록 설정할 수 있습니다.

const { setLogLevel } = require("@azure/logger");

setLogLevel("info");

로그를 사용하는 방법에 대한 자세한 내용은 @azure/logger package docs를 참조하세요.

필수 조건

이 가이드에서는 귀하가 빠른 시작 페이지에 언급된 단계를 성공적으로 수행했다고 가정합니다. 이것은 다음을 의미합니다.

  • Computer Vision 리소스를 생성하고 키와 엔드포인트 URL을 얻었습니다.
  • 서비스에 대한 curl.exe 호출을 성공적으로 수행했습니다(또는 대체 도구를 사용했습니다). 여기의 예를 기반으로 curl.exe 호출을 수정합니다.

서비스에 대한 인증

이미지 분석 서비스에 대해 인증하려면 Computer Vision 키와 엔드포인트 URL이 필요합니다.

Important

API 키를 사용하는 경우 Azure Key Vault와 같은 다른 위치에 안전하게 저장합니다. API 키를 코드에 직접 포함하지 말고, 공개적으로 게시하지 마세요.

AI 서비스 보안에 대한 자세한 내용은 Azure AI 서비스에 대한 요청 인증을 참조하세요.

SDK 예시에서는 키와 엔드포인트를 사용하여 환경 변수 VISION_KEY 및 VISION_ENDPOINT를 정의했다고 가정합니다.

인증은 HTTP 요청 헤더 Ocp-Apim-Subscription-Key를 추가하고 이를 비전 키에 설정하여 수행됩니다. URL <endpoint>/computervision/imageanalysis:analyze?api-version=2024-02-01에 대한 호출이 이루어집니다. 여기서 <endpoint>는 고유한 컴퓨터 비전 엔드포인트 URL입니다. 분석 옵션에 따라 쿼리 문자열을 추가합니다.

분석할 이미지를 선택하세요

이 가이드의 코드는 URL에서 참조하는 원격 이미지를 사용합니다. 이미지 분석 기능의 전체 기능을 보기 위해 다양한 이미지를 직접 시도할 수 있습니다.

이미지 URL

원격 이미지를 분석하는 경우 {"url":"https://learn.microsoft.com/azure/cognitive-services/computer-vision/images/windows-kitchen.jpg"} 같이 요청 본문의 형식을 지정하여 이미지 URL을 지정합니다. Content-Type은 application/json이어야 합니다.

Image file

로컬 이미지를 분석하려면 HTTP 요청 본문에 이진 이미지 데이터를 넣습니다. Content-Type은 application/octet-stream 또는 multipart/form-data이어야 합니다.

분석 옵션 선택

표준 모델 사용시 시각적 특징 선택

Analysis 4.0 API를 통해 모든 서비스의 이미지 분석 기능에 액세스할 수 있습니다. 자체 사용 사례에 따라 수행할 작업을 선택합니다. 각 기능의 설명은 개요를 참조하세요. 이 섹션의 예제에는 사용 가능한 모든 시각적 기능이 추가되어 있지만 실제 사용에 필요한 기능 수는 더 적을 수 있습니다.

시각적 기능 '캡션' 및 'DenseCaptions'는 특정 Azure 지역에서만 지원됩니다. 지역 가용성을 참조하세요.

참고 항목

REST API는 스마트 작물 및 스마트 작물 가로 세로 비율라는 용어를 사용합니다. SDK에서는 자르기 제안 및 가로 세로 비율 자르기라는 용어를 사용합니다. 둘 다 동일한 서비스 작업을 나타냅니다. 마찬가지로 REST API는 광학 인식(OCR)을 사용하여 이미지에서 텍스트를 감지할 때 읽기라는 용어를 사용하는 반면, SDK는 동일한 작업에 텍스트라는 용어를 사용합니다.

Analysis 4.0 API의 URL 쿼리 매개 변수를 설정하여 사용하려는 기능을 지정할 수 있습니다. 매개 변수는 쉼표로 구분된 여러 값을 가질 수 있습니다.

URL 매개 변수 값 설명
features read 이미지에서 보이는 텍스트를 읽고 구조화된 JSON 데이터로 출력합니다.
features caption 지원되는 언어를 사용하여 완전한 문장으로 이미지 콘텐츠를 설명합니다.
features denseCaptions 최대 10개의 눈에 띄는 이미지 영역에 대한 자세한 캡션을 생성합니다.
features smartCrops 관심 영역을 유지하면서 이미지를 원하는 가로 세로 비율로 자르는 직사각형 좌표를 찾습니다.
features objects 이미지 내에서 대략적인 위치를 포함한 다양한 개체를 감지합니다. Objects 인수는 영어로만 사용할 수 있습니다.
features tags 이미지 콘텐츠와 관련된 단어의 자세한 목록으로 이미지에 태그를 지정합니다.
features people 대략적 위치를 포함하여 이미지에 표시되는 사람을 검색합니다.

채워진 URL은 다음과 같이 표시됩니다.

<endpoint>/computervision/imageanalysis:analyze?api-version=2024-02-01&features=tags,read,caption,denseCaptions,smartCrops,objects,people

사용자 지정 모델 사용 시 모델명 설정

사용자 지정 학습된 모델을 사용하여 이미지 분석을 수행할 수도 있습니다. 모델을 만들고 학습하려면 사용자 지정 이미지 분석 모델 만들기를 참조하세요. 모델이 학습되면 모델 이름만 있으면 됩니다. 사용자 지정 모델을 사용하는 경우 시각적 기능을 지정할 필요가 없습니다.

사용자 지정 모델을 사용하려면 기능 쿼리 매개 변수를 사용하지 마세요. 대신 여기에 표시된 대로 model-name 매개 변수를 모델 이름으로 설정하세요. MyCustomModelName을 사용자 지정 모델 이름으로 바꾸세요.

<endpoint>/computervision/imageanalysis:analyze?api-version=2023-02-01&model-name=MyCustomModelName

언어 지정

반환된 데이터의 언어를 지정할 수 있습니다. 언어는 선택 사항이며 기본값은 영어입니다. 지원되는 언어 코드 목록과 각 언어에 지원되는 시각적 기능은 언어 지원을 참조하세요.

언어 옵션은 표준 모델을 사용하는 경우에만 적용됩니다.

다음 URL 쿼리 매개 변수는 언어를 지정합니다. 기본값은 en입니다.

URL 매개 변수 값 설명
language en 영어
language es 스페인어
language ja 일본어
language pt 포르투갈어
language zh 중국어(간체)

채워진 URL은 다음과 같이 표시됩니다.

<endpoint>/computervision/imageanalysis:analyze?api-version=2024-02-01&features=caption&language=en

성 중립적 캡션을 선택하세요.

캡션이나 조밀한 캡션을 추출하는 경우 성 중립적 캡션을 요청할 수 있습니다. 성 중립적 캡션은 선택 사항이며, 기본값은 성별 캡션입니다. 예를 들어, 영어에서 성 중립적 캡션을 선택하면 woman 또는 man과 같은 용어는 person으로 대체되고 boy 또는 girl은 child로 대체됩니다.

성 중립적 캡션 옵션은 표준 모델을 사용하는 경우에만 적용됩니다.

값이 true 또는 false(기본값)인 선택적 쿼리 문자열 gender-neutral-caption을 추가합니다.

채워진 URL은 다음과 같이 표시됩니다.

<endpoint>/computervision/imageanalysis:analyze?api-version=2024-02-01&features=caption&gender-neutral-caption=true

스마트 자르기 가로 세로 비율 선택

가로 세로 비율은 대상 자르기 너비를 높이로 나누어 계산됩니다. 지원되는 값은 0.75에서 1.8(포함)입니다. 이 속성 설정은 VisualFeatures.SmartCrops가 시각적 기능 목록의 일부로 선택된 경우에만 관련됩니다. VisualFeatures.SmartCrops를 선택했지만 가로 세로 비율을 지정하지 않은 경우 서비스는 적합하다고 판단하는 가로 세로 비율이 포함된 자르기 제안 하나를 반환합니다. 이 경우 가로 세로 비율은 0.5에서 2.0(포함) 사이입니다.

스마트 자르기 화면 비율은 표준 모델을 사용하는 경우에만 적용됩니다.

하나 이상의 가로 세로 비율을 쉼표로 구분하여 선택적 쿼리 문자열 smartcrops-aspect-ratios을(를) 추가합니다.

채워진 URL은 다음과 같이 표시됩니다.

<endpoint>/computervision/imageanalysis:analyze?api-version=2024-02-01&features=smartCrops&smartcrops-aspect-ratios=0.8,1.2

서비스에서 결과 가져오기

표준 모델을 사용하여 결과 얻기

이 섹션에서는 표준 모델을 사용하여 서비스에 대한 분석 호출을 수행하고 결과를 얻는 방법을 보여줍니다.

이 서비스는 200 HTTP 응답을 반환하며 본문에는 반환된 데이터가 JSON 문자열 형식으로 포함됩니다. 다음 텍스트는 JSON 응답의 예제입니다.

{
    "modelVersion": "string",
    "captionResult": {
      "text": "string",
      "confidence": 0.0
    },
    "denseCaptionsResult": {
      "values": [
        {
          "text": "string",
          "confidence": 0.0,
          "boundingBox": {
            "x": 0,
            "y": 0,
            "w": 0,
            "h": 0
          }
        }
      ]
    },
    "metadata": {
      "width": 0,
      "height": 0
    },
    "tagsResult": {
      "values": [
        {
          "name": "string",
          "confidence": 0.0
        }
      ]
    },
    "objectsResult": {
      "values": [
        {
          "id": "string",
          "boundingBox": {
            "x": 0,
            "y": 0,
            "w": 0,
            "h": 0
          },
          "tags": [
            {
              "name": "string",
              "confidence": 0.0
            }
          ]
        }
      ]
    },
    "readResult": {
      "blocks": [
        {
          "lines": [
            {
              "text": "string",
              "boundingPolygon": [
                {
                  "x": 0,
                  "y": 0
                },
                {
                    "x": 0,
                    "y": 0
                },
                {
                    "x": 0,
                    "y": 0
                },
                {
                    "x": 0,
                    "y": 0
                }
              ],
              "words": [
                {
                  "text": "string",
                  "boundingPolygon": [
                    {
                        "x": 0,
                        "y": 0
                    },
                    {
                        "x": 0,
                        "y": 0
                    },
                    {
                        "x": 0,
                        "y": 0
                    },
                    {
                        "x": 0,
                        "y": 0
                    }
                  ],
                  "confidence": 0.0
                }
              ]
            }
          ]
        }
      ]
    },
    "smartCropsResult": {
      "values": [
        {
          "aspectRatio": 0.0,
          "boundingBox": {
            "x": 0,
            "y": 0,
            "w": 0,
            "h": 0
          }
        }
      ]
    },
    "peopleResult": {
      "values": [
        {
          "boundingBox": {
            "x": 0,
            "y": 0,
            "w": 0,
            "h": 0
          },
          "confidence": 0.0
        }
      ]
    }
  }

오류 코드

오류가 발생하면 이미지 분석 서비스 응답에 오류 코드와 오류 메시지가 포함된 JSON 페이로드가 포함됩니다. 또한 내부 오류 코드 및 메시지 형식의 다른 세부 정보도 포함될 수 있습니다. 예시:

{
    "error":
    {
        "code": "InvalidRequest",
        "message": "Analyze query is invalid.",
        "innererror":
        {
            "code": "NotSupportedVisualFeature",
            "message": "Specified feature type is not valid"
        }
    }
}

다음은 일반적인 오류와 그 원인 목록입니다. 목록 항목은 다음 형식으로 표시됩니다.

  • HTTP 응답 코드
    • JSON 응답의 오류 코드 및 메시지
      • [선택 사항] JSON 응답의 내부 오류 코드 및 메시지

일반적인 오류 목록:

  • 400 Bad Request
    • InvalidRequest - Image URL is badly formatted or not accessible; 이미지 URL이 유효하고 공개적으로 액세스할 수 있는지 확인하세요.
    • InvalidRequest - The image size is not allowed to be zero or larger than 20971520 bytes; 이미지를 압축하거나 크기를 조정하여 이미지 크기를 줄이고 요청을 다시 제출하세요.
    • InvalidRequest - The feature 'Caption' is not supported in this region; 이 기능은 특정 Azure 지역에서만 지원됩니다. 지원되는 Azure 지역 목록은 빠른 시작 필수 조건을 참조하세요.
    • InvalidRequest - The provided image content type ... is not supported; 요청의 HTTP 헤더 Content-Type이 허용되는 형식이 아닙니다.
      • 이미지 URL의 경우 Content-Type은 application/json이어야 합니다.
      • 이진 이미지 데이터의 경우 Content-Type은 application/octet-stream 또는 multipart/form-data이어야 합니다.
    • InvalidRequest - Either 'features' or 'model-name' needs to be specified in the query parameter;
    • InvalidRequest - Image format is not valid
      • InvalidImageFormat - Image format is not valid; 지원되는 이미지 형식은 이미지 요구 사항 섹션을 참조하세요.
    • InvalidRequest - Analyze query is invalid
      • NotSupportedVisualFeature - Specified feature type is not valid; 기능 쿼리 문자열에 유효한 값이 있는지 확인하세요.
      • NotSupportedLanguage - The input language is not supported; 다음 표에 따라 언어 쿼리 문자열에 선택한 시각적 기능에 대한 유효한 값이 있는지 확인하세요.
      • BadArgument - 'smartcrops-aspect-ratios' aspect ratio is not in allowed range [0.75 to 1.8]
  • 401 PermissionDenied
    • 401 - Access denied due to invalid subscription key or wrong API endpoint. Make sure to provide a valid key for an active subscription and use a correct regional API endpoint for your resource;
  • 404 Resource Not Found
    • 404 - Resource not found; 서비스가 model-name 쿼리 문자열에서 제공한 이름을 기반으로 사용자 지정 모델을 찾을 수 없습니다.

다음 단계