.NET용 Azure SDK 프로토콜 및 편리한 메서드 개요

Azure SDK 클라이언트 라이브러리는 메서드 호출을 해당 서비스 프로토콜을 통해 전송된 메시지로 변환하여 Azure 서비스에 대한 인터페이스를 제공합니다. 즉, REST API 서비스의 경우 HTTP 요청을 보내고 응답을 런타임 형식으로 변환합니다. 이 문서에서는 클라이언트 라이브러리에서 제공하는 다양한 형식의 메서드에 대해 알아보고 해당 구현 패턴을 살펴보겠습니다.

프로토콜 및 편리한 메서드 이해

.NET용 Azure SDK 클라이언트 라이브러리는 Azure 서비스에 요청하기 위해 두 가지 범주의 메서드를 노출할 수 있습니다.

• 프로토콜 메서드는 해당 Azure 서비스에 대한 기본 REST API 주위에 씬(thin) 래퍼를 제공합니다. 이러한 메서드는 기본 입력 매개 변수를 HTTP 요청 값에 매핑하고 원시 HTTP 응답 개체를 반환합니다.
• 편리한 메서드는 하위 수준 프로토콜 계층 위에 편의 계층을 제공하여 .NET 형식 시스템에 대한 지원과 기타 이점을 추가합니다. 편리한 메서드는 기본 요소 또는 .NET 모델 형식을 매개 변수로 받아들이고 이를 기본 REST API 요청의 본문에 매핑합니다. 또한 이러한 방법은 요청 및 응답 관리의 다양한 세부 정보를 처리하여 개발자가 하위 수준의 문제 대신 데이터 개체를 보내고 받는 데 집중할 수 있도록 합니다.

Azure SDK 클라이언트 라이브러리 종속성 패턴

프로토콜 및 편리한 메서드는 각 라이브러리의 기본 패키지 종속성 체인을 기반으로 약간 다른 패턴을 구현합니다. .NET용 Azure SDK 클라이언트 라이브러리는 두 가지 기본 라이브러리 중 하나에 따라 달라집니다.

• Azure.Core는 최신 Azure SDK 클라이언트 라이브러리를 빌드하기 위한 공유 기본 요소, 추상화 및 도우미를 제공합니다. 이러한 라이브러리는 .NET용 Azure SDK 디자인 지침을 따르며 Azure.Storage.Blobs와 같이 Azure 접두사가 붙은 패키지 이름과 네임스페이스를 사용합니다.
• System.ClientModel은 .NET 서비스 클라이언트 라이브러리를 위한 공유 기본 요소, 추상화 및 도우미를 제공하는 핵심 라이브러리입니다. 다양한 플랫폼 및 서비스에 대한 라이브러리를 빌드를 돕기 위해 설계된 범용 도구 집합이 System.ClientModel 라이브러리이며, 반면에 Azure.Core 라이브러리는 Azure 클라이언트 라이브러리에 대한 빌드를 위해 특별히 설계되었습니다.

참고 항목

Azure.Core 라이브러리 자체도 다양한 클라이언트 구성 요소에 대해 System.ClientModel에 따라 달라집니다. 이 문서의 컨텍스트에서 메서드 패턴의 주요 차별화 요소는 클라이언트 라이브러리가 전이적 종속성을 통하지 않고 Azure.Core 또는 System.ClientModel에 직접 종속되는지 여부를 나타냅니다.

프로토콜 및 편리한 메서드에서 사용하는 일부 요청 및 응답 유형에 대해, Azure.Core 또는 System.ClientModel에 라이브러리가 종속되는지 여부에 따라 다음 표에서 비교합니다.

요청 또는 응답 문제	Azure.Core	System.ClientModel
요청 본문	RequestContent	BinaryContent
고급 요청 옵션	RequestContext	RequestOptions
원시 HTTP 응답	Response	PipelineResponse
출력 모델이 있는 반환 형식	Response<T>	ClientResult<T>

앞의 섹션에서는 이러한 개념의 구현 예를 제공합니다.

프로토콜 및 편리한 메서드 예

클라이언트 라이브러리 프로토콜과 편리한 메서드에서 사용되는 코딩 패턴과 형식은 라이브러리가 Azure.Core 또는 System.ClientModel에 종속되는지 여부에 따라 약간 다릅니다. 차이점은 주로 요청 및 응답 데이터를 처리하는 데 사용되는 .NET 형식에 영향을 미칩니다.

Azure.Core에 의존하는 라이브러리

최신 디자인 지침을 준수하는 Azure SDK 클라이언트 라이브러리는 Azure.Core 라이브러리에 의존합니다. 예를 들어, Azure.AI.ContentSafety 라이브러리는 Azure.Core 라이브러리에 종속되며 프로토콜과 편리한 메서드를 모두 노출하는 ContentSafetyClient 클래스를 제공합니다.

편리한 메서드

다음 코드는 ContentSafetyClient를 사용하여 AnalyzeText 편리한 메서드를 호출합니다.

using Azure.AI.ContentSafety;
using Azure.Identity;

// Create the client
ContentSafetyClient client = new(
    new Uri("https://contentsafetyai.cognitiveservices.azure.com/"),
    new DefaultAzureCredential());

// Call the convenience method
AnalyzeTextResult result = client.AnalyzeText("What is Microsoft Azure?");

// Display the results
foreach (TextCategoriesAnalysis item in result.CategoriesAnalysis)
{
    Console.WriteLine($"{item.Category}: {item.Severity}");
}

앞의 코드는 다음과 같은 Azure.Core 편리한 메서드 패턴을 보여 줍니다.

• 표준 C# 기본 요소 또는 모델 형식을 매개 변수로 사용합니다.
• 작업 결과를 나타내는 친숙한 C# 형식을 반환합니다.

프로토콜 메서드

다음 코드는 ContentSafetyClient를 사용하여 AnalyzeText 프로토콜 메서드를 호출합니다.

using Azure;
using Azure.AI.ContentSafety;
using Azure.Core;
using Azure.Core.Serialization;
using Azure.Identity;

// Create the client
ContentSafetyClient client = new(
    new Uri("https://contentsafetyai.cognitiveservices.azure.com/"),
    new DefaultAzureCredential());

// Create the prompt
RequestContent prompt = RequestContent.Create(new
{
    text = "What is Microsoft Azure?",
});

// Call the protocol method
Response response = client.AnalyzeText(
    prompt,
    new RequestContext
    {
        ErrorOptions = ErrorOptions.NoThrow,
    });

// Any non-200 response code from Azure AI Content Safety AnalyzeText REST API isn't considered a success response.
// See REST API details at https://azure-ai-content-safety-api-docs.developer.azure-api.net/api-details#api=content-safety-service-2023-10-01&operation=TextOperations_AnalyzeText
if (response.Status != 200)
{
    throw new RequestFailedException(response);
}

// With this dynamic instance, you can use response content like a convenience model. As convenience APIs are added
// to the library, this approach helps you evolve code from protocol to convenience with minimal code changes.
dynamic content = response.Content.ToDynamicFromJson(JsonPropertyNames.CamelCase);

// Display the results
foreach (var item in content.CategoriesAnalysis)
{
    Console.WriteLine($"{item.Category}: {item.Severity}");
}

앞의 코드는 다음과 같은 Azure.Core 프로토콜 메서드 패턴을 보여 줍니다.

1. 요청 본문에 대한 RequestContent 개체를 사용하여 요청을 만듭니다.
2. RequestContext 개체를 사용하여 요청 옵션을 구성하고 프로토콜 메서드를 호출합니다.
3. 다음을 읽어 응답을 처리합니다.
   • 성공 또는 실패를 결정하기 위한 Response 개체의 HTTP 상태 코드입니다.
   • ToDynamicFromJson을(를) 사용하여 Response 개체 콘텐츠에서 동적 유형으로 데이터를 변환합니다. .NET용 Azure Core 라이브러리에서 동적 JSON 발표를 참조하여 자세한 내용을 확인하세요.

참고 항목

앞의 코드는 ErrorOptions.NoThrow 동작을 구성합니다. 이 옵션은 성공하지 않은 서비스 응답 상태 코드가 예외를 throw하는 것을 방지합니다. 즉, 앱 코드가 응답 상태 코드 검사를 수동으로 처리해야 합니다.

System.ClientModel에 따라 다른 라이브러리

Azure 이외의 서비스에 연결하는 일부 클라이언트 라이브러리는 Azure.Core에 따라 다른 라이브러리와 유사한 패턴을 사용합니다. 예를 들어, OpenAI 라이브러리는 OpenAI 서비스에 연결하는 클라이언트를 제공합니다. 이러한 라이브러리는 Azure.Core와 유사한 패턴을 가진 System.ClientModel이라는 라이브러리를 기반으로 합니다.

편리한 메서드

ChatClient를 사용하여 CompleteChat 편리한 메서드를 호출하는 다음 코드를 고려해 보세요.

using OpenAI.Chat;

// Create the client
ChatClient client = new(
    model: "gpt-4o-mini",
    credential: Environment.GetEnvironmentVariable("OPENAI_API_KEY")!);

// Call the convenience method
ChatCompletion completion = client.CompleteChat("What is Microsoft Azure?");

// Display the results
Console.WriteLine($"[{completion.Role}]: {completion}");

앞의 코드는 다음과 같은 System.ClientModel 편리한 메서드 패턴을 보여 줍니다.

• 표준 C# 기본 요소 또는 모델 형식을 매개 변수로 사용합니다.
• 작업 결과를 나타내는 ClientResult 형식을 반환합니다.

프로토콜 메서드

다음 코드는 ChatClient를 사용하여 CompleteChat 프로토콜 메서드를 호출합니다.

using OpenAI.Chat;
using System.ClientModel;
using System.ClientModel.Primitives;
using System.Text.Json;

// Create the client
ChatClient client = new(
    model: "gpt-4o-mini",
    credential: Environment.GetEnvironmentVariable("OPENAI_API_KEY")!);

// Create the request content
BinaryData input = BinaryData.FromBytes("""
    {
        "model": "gpt-4o-mini",
        "messages": [
           {
               "role": "user",
               "content": "What is Microsoft Azure?"
           }
        ]
    }
    """u8.ToArray());
using BinaryContent content = BinaryContent.Create(input);

var requestOptions = new RequestOptions();

requestOptions.AddHeader("CustomHeader", "CustomHeaderValue");
requestOptions.ErrorOptions = ClientErrorBehaviors.NoThrow;

// Call the protocol method
ClientResult result = client.CompleteChat(
    content,
    requestOptions
);

PipelineResponse response = result.GetRawResponse();

// Any non-200 response code from CompleteChat endpoint isn't considered a success response.
if (response.Status != 200)
{
    throw new ClientResultException(response);
}

using JsonDocument output = JsonDocument.Parse(response.Content);
JsonElement message = output.RootElement
    .GetProperty("choices"u8)[0]
    .GetProperty("message"u8);

// Display the results
Console.WriteLine($@"[{message.GetProperty("role"u8)}]:
    {message.GetProperty("content"u8)}");

앞의 코드는 다음과 같은 System.ClientModel 프로토콜 메서드 패턴을 보여 줍니다.

1. 요청 본문에 대한 BinaryContent 개체를 사용하여 요청을 만듭니다.
2. RequestOptions 개체를 사용하여 요청 옵션을 구성하고 프로토콜 메서드를 호출합니다.
3. 다음을 읽어 응답을 처리합니다.
   • 성공 또는 실패를 결정하기 위한 PipelineResponse 개체의 HTTP 상태 코드입니다.
   • System.Text.Json API를 사용하여 PipelineResponse 개체 콘텐츠의 데이터를 변환합니다.

참고 항목

앞의 코드는 RequestOptions에 대한 ClientErrorBehaviors.NoThrow 동작을 구성합니다. 이 옵션은 성공하지 않은 서비스 응답 상태 코드가 예외를 throw하는 것을 방지합니다. 즉, 앱 코드가 응답 상태 코드 검사를 수동으로 처리해야 합니다.

System.ClientModel 기반의 응답을 편리한 모델처럼 처리하기 위해 Azure.Core 종속성을 사용할 수 있습니다. Azure.Core에 의존하는 라이브러리의 프로토콜 메서드 탭에서 설명한 것과 동일한 접근 방식을 따르는 대안적인 접근 방식을 다음과 같은 차이를 통해 보여 줍니다.

PipelineResponse response = result.GetRawResponse();

- using JsonDocument output = JsonDocument.Parse(response.Content);
- JsonElement message = output.RootElement
-     .GetProperty("choices"u8)[0]
-     .GetProperty("message"u8);

- Console.WriteLine($@"[{message.GetProperty("role"u8)}]:
-     {message.GetProperty("content"u8)}");

+ dynamic output = response.Content.ToDynamicFromJson(
+     JsonPropertyNames.CamelCase);
+ var message = output.Choices[0].Message;
+ Console.WriteLine($"[{message.Role}]: {message.Content}");

예외 처리

서비스 호출이 실패하면 서비스 클라이언트는 HTTP 상태 코드와 서비스 응답의 세부 정보를 노출하는 예외를 throw합니다(사용 가능한 경우). System.ClientModel-dependent 라이브러리는 ClientResultException을 throw하고 Azure.Core-dependent 라이브러리는 RequestFailedException을 throw합니다.

System.ClientModel 예외

using Azure.AI.ContentSafety;
using Azure.Identity;
using Azure;

// Create the client
ContentSafetyClient client = new(
    new Uri("https://contentsafetyai.cognitiveservices.azure.com/"),
    new DefaultAzureCredential());

try
{
    // Call the convenience method
    AnalyzeTextResult result = client.AnalyzeText("What is Microsoft Azure?");

    // Display the results
    foreach (TextCategoriesAnalysis item in result.CategoriesAnalysis)
    {
        Console.WriteLine($"{item.Category}: {item.Severity}");
    }
} 
catch (RequestFailedException ex)
{
    Console.WriteLine($"Error: {ex.Message}");
}

Azure.Core 예외

using OpenAI.Chat;
using System.ClientModel;

// Create the client
ChatClient client = new(
    model: "gpt-4o-mini",
    credential: Environment.GetEnvironmentVariable("OPENAI_API_KEY")!);

try
{
    // Call the convenience method
    ChatCompletion completion = client.CompleteChat("What is Microsoft Azure?");

    // Display the results
    Console.WriteLine($"[{completion.Role}]: {completion}");
}
catch (ClientResultException ex)
{
    Console.WriteLine($"Error: {ex.Message}");
}

프로토콜 및 편리한 메서드 사용 지침

.NET용 Azure SDK 클라이언트 라이브러리는 프로토콜 또는 편리한 메서드를 사용하는 옵션을 제공하지만 대부분의 시나리오에서는 편리한 메서드 사용에 우선 순위를 둡니다. 편리한 메서드는 개발 환경을 개선하고 요청 작성 및 응답 처리에 유연성을 제공하도록 설계되었습니다. 그러나 필요에 따라 앱에서 두 메서드 형식을 모두 사용할 수 있습니다. 다음과 같은 기준을 고려하여 사용할 메서드 유형을 결정하세요.

편리한 메서드:

• 보다 친숙한 메서드 매개 변수 및 응답 형식을 사용하여 작업할 수 있습니다.
• 다양한 하위 수준 문제와 최적화를 처리합니다.

프로토콜 메서드:

• 편리한 메서드를 통해 사용할 수 없는 RequestContext 및 RequestOptions와 같은 하위 수준 형식에 대한 액세스를 제공합니다.
• 편리한 메서드가 노출되지 않는 기본 REST API 기능에 대한 액세스를 사용하도록 설정합니다.
• 아직 편리한 메서드가 없는 서비스 엔드포인트에 대해 고유한 편리한 메서드를 만들 수 있습니다. 이 방식을 사용하려면 요청과 응답을 올바르게 처리하기 위해 서비스의 REST API 설명서를 이해해야 합니다.

참고 항목

.NET용 Azure Core 라이브러리 이해