Azure SDK for .NET 协议和便捷方法概述

Azure SDK 客户端库通过将方法调用转换为通过相应服务协议发送的消息，提供 Azure 服务的接口。 对于 REST API 服务，这意味着发送 HTTP 请求并将响应转换为运行时类型。 在本文中，你将了解客户端库公开的各种方法类型，并探索其实现模式。

了解协议和便捷方法

Azure SDK for .NET 客户端库可以公开两种不同类别的方法，以向 Azure 服务发出请求：

• 协议方法为相应的 Azure 服务提供基础 REST API 的精简包装器。 这些方法将基元输入参数映射到 HTTP 请求值并返回原始 HTTP 响应对象。
• 便捷方法基于较低级别的协议层提供一个便捷层，以支持 .NET 类型系统和其他优势。 便捷方法接受基元或 .NET 模型类型作为参数，并将其映射到基础 REST API 请求的正文。 这些方法还处理请求和响应管理的各种细节，使开发人员能够专注于发送和接收数据对象，而不是处理较低级别的关注点。

Azure SDK 客户端库依赖项模式

协议和便捷方法基于各自库的基础包依赖链实现了略有不同的模式。 Azure SDK for .NET 客户端库依赖于两个不同的基础库之一：

• Azure.Core 提供了用于构建新式 Azure SDK 客户端库的共享基元、抽象和帮助程序。 这些库遵循适用于 .NET 的 Azure SDK 设计指南并使用以 Azure 为前缀的包名称和命名空间，例如 Azure.Storage.Blobs。
• 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 行为。 此选项阻止非成功服务响应状态代码引发异常，这意味着应用代码应手动处理响应状态代码检查。

依赖于 System.ClientModel 的库

连接到非 Azure 服务的一些客户端库使用的模式与依赖于 Azure.Core 的库类似。 例如，OpenAI 库提供连接到 OpenAI 服务的客户端。 这些库基于一个名为 System.ClientModel 的库，其模式类似于 Azure.Core。

便捷方法

请考虑使用 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 行为。 此选项阻止非成功服务响应状态代码引发异常，这意味着应用代码应手动处理响应状态代码检查。

如果在 Azure.Core 上采用依赖项，则可以像简便模型一样处理基于 System.ClientModel 的响应。 以下差异显示了此替代方法，该方法遵循依赖于 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 状态代码和服务响应的详细信息（如果可用）。 依赖于 System.ClientModel 的库引发 ClientResultException，而依赖于 Azure.Core 的库则引发 RequestFailedException。

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}");
}

协议和便捷方法使用指导

尽管 Azure SDK for .NET 客户端库提供了使用协议方法或便捷方法的选项，但在大多数情况下，优先使用便捷方法。 便捷方法设计用于改善开发体验，并为编写请求和处理响应提供了灵活性。 但是，可以根据需要在应用中使用这两种方法类型。 在决定使用哪种类型的方法时，请考虑以下条件。

便捷方法：

• 使你能够使用更友好的方法参数和响应类型。
• 为你处理各种低级别问题和优化。

协议方法：

• 提供对较低级别的类型（例如 RequestContext 和 RequestOptions）的访问，这些类型无法通过便捷方法使用。
• 用于访问便捷方法未公开的底层 REST API 的功能。
• 使你能够围绕尚未具有便捷方法的服务终结点创建自己的便捷方法。 使用此方法时需要了解服务的 REST API 文档以便正确处理请求和响应。

另请参阅

了解适用于 .NET 的 Azure Core 库