Общие сведения о протоколах и удобных методах azure SDK для .NET

Клиентские библиотеки Пакета SDK Azure предоставляют интерфейс для служб Azure, превратив вызовы методов в сообщения, отправленные через соответствующий протокол службы. Для служб REST API это означает отправку HTTP-запросов и преобразование ответов в типы среды выполнения. В этой статье вы узнаете о различных типах методов, предоставляемых клиентскими библиотеками, и изучите их шаблоны реализации.

Общие сведения о протоколах и удобных методах

Клиентская библиотека Пакета SDK Azure для .NET может предоставлять две различные категории методов для выполнения запросов к службе Azure:

• Методы протокола предоставляют тонкие оболочки вокруг базового REST API для соответствующей службы Azure. Эти методы сопоставляют примитивные входные параметры со значениями HTTP-запроса и возвращают необработанный объект ответа HTTP.
• Удобные методы предоставляют удобный уровень на уровне протокола нижнего уровня, чтобы добавить поддержку системы типов .NET и других преимуществ. Удобные методы принимают примитивы или типы моделей .NET в качестве параметров и сопоставляют их с текстом базового запроса REST API. Эти методы также обрабатывают различные сведения об управлении запросами и ответами, чтобы разработчики могли сосредоточиться на отправке и получении объектов данных вместо проблем с более низким уровнем.

Шаблоны зависимостей клиентской библиотеки Пакета SDK Azure

Методы протокола и удобства реализуют несколько разные шаблоны в зависимости от цепочки зависимостей пакета соответствующей библиотеки. Клиентская библиотека пакета SDK Azure для .NET зависит от одной из двух разных базовых библиотек:

• Azure.Core предоставляет общие примитивы, абстракции и вспомогательные средства для создания современных клиентских библиотек azure SDK. Эти библиотеки следуют рекомендациям по проектированию Пакета SDK Azure для .NET и используют имена пакетов и пространства имен, префиксированные с помощью 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 метода:

C#

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 протокола:

C#

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. Выполните обработку ответа , прочитав следующее:
   • Код состояния HTTP из объекта, чтобы определить успешность или сбой Response .
   • Данные из Response содержимого объекта в динамический тип с помощьюToDynamicFromJson. Дополнительные сведения см. в статье Об объявлении динамического JSON в библиотеке Azure Core для .NET.

Ескерім

Приведенный выше код настраивает поведение ErrorOptions.NoThrow . Этот параметр запрещает коды состояния службы, не являющиеся успешными, вызывать исключение, что означает, что код приложения должен вручную обрабатывать проверки кода состояния ответа.

Библиотеки, зависящие от System.ClientModel

Некоторые клиентские библиотеки, подключающиеся к службам, не относящихся к Azure, используют шаблоны, аналогичные библиотекам, зависящим от Azure.Core. Например, OpenAI библиотека предоставляет клиент, который подключается к службам OpenAI. Эти библиотеки основаны на библиотеке, которая System.ClientModel называется шаблонами, похожими Azure.Coreна .

Удобный метод

Рассмотрим следующий код, который используется ChatClient для вызова удобного CompleteChat метода:

C#

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 протокола:

C#

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. Выполните обработку ответа , прочитав следующее:
   • Код состояния HTTP из объекта, чтобы определить успешность или сбой PipelineResponse .
   • Данные из содержимого PipelineResponse объекта с помощью System.Text.Json API.

Ескерім

Предыдущий код настраивает поведение ClientErrorBehaviors.NoThrow для параметра RequestOptions. Этот параметр запрещает коды состояния службы, не являющиеся успешными, вызывать исключение, что означает, что код приложения должен вручную обрабатывать проверки кода состояния ответа.

Ответ System.ClientModelна основе может обрабатываться как удобная модель, если вы принимаете зависимость Azure.Core. В следующем диффе показан альтернативный подход, который соответствует тому же подходу, который показан на вкладке "Метод протокола" библиотек, зависящих от Azure.Core.

diff

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

C#

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

C#

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

Руководство по использованию протокола и удобного метода

Хотя клиентские библиотеки пакета SDK Azure для .NET предоставляют возможность использовать методы протокола или удобства, приоритеты используют удобные методы в большинстве сценариев. Удобные методы предназначены для улучшения возможностей разработки и обеспечения гибкости для разработки запросов и обработки ответов. Однако оба типа методов можно использовать в приложении по мере необходимости. При выборе типа используемого метода следует учитывать следующие критерии.

Удобные методы:

• Вы можете работать с более понятными параметрами метода и типами ответов.
• Обработка различных низкоуровневых проблем и оптимизаций для вас.

Методы протокола:

• Предоставление доступа к типам более низкого уровня, таким как RequestContext и RequestOptions, которые недоступны с помощью удобных методов.
• Включите доступ к функциям базовых ИНТЕРФЕЙСов REST API, которые не предоставляют удобные методы.
• Вы можете создавать собственные удобные методы для конечных точек службы, которые еще не имеют удобных методов. Этот подход требует понимания документации REST API службы для правильной обработки запросов и ответов.

См. также

Общие сведения о библиотеке Azure Core для .NET