Omówienie zestawu Azure SDK dla protokołu .NET i metod wygody

Biblioteki klienckie zestawu Azure SDK udostępniają interfejs usług platformy Azure, tłumacząc wywołania metod na komunikaty wysyłane za pośrednictwem odpowiedniego protokołu usługi. W przypadku usług interfejsu API REST oznacza to wysyłanie żądań HTTP i konwertowanie odpowiedzi na typy środowiska uruchomieniowego. W tym artykule poznasz różne typy metod udostępnianych przez biblioteki klienckie i poznasz ich wzorce implementacji.

Omówienie metod protokołu i wygody

Biblioteka kliencka zestawu Azure SDK dla platformy .NET może uwidaczniać dwie różne kategorie metod, aby wysyłać żądania do usługi platformy Azure:

• Metody protokołu zapewniają cienką otokę podstawowego interfejsu API REST dla odpowiedniej usługi platformy Azure. Te metody mapowania pierwotnych parametrów wejściowych na wartości żądania HTTP i zwracają nieprzetworzonego obiektu odpowiedzi HTTP.
• Metody wygody zapewniają wygodną warstwę w warstwie protokołu niższego poziomu, aby dodać obsługę systemu typu .NET i innych korzyści. Metody wygody akceptują typy modeli pierwotnych lub .NET jako parametry i mapują je na treść bazowego żądania interfejsu API REST. Te metody obsługują również różne szczegóły zarządzania żądaniami i odpowiedziami, aby umożliwić deweloperom skoncentrowanie się na wysyłaniu i odbieraniu obiektów danych zamiast problemów niższego poziomu.

Wzorce zależności biblioteki klienta zestawu Azure SDK

Metody protokołu i wygody implementują nieco różne wzorce na podstawie bazowego łańcucha zależności pakietu odpowiedniej biblioteki. Biblioteka klienta zestawu Azure SDK dla platformy .NET zależy od jednej z dwóch różnych podstawowych bibliotek:

• Platforma Azure.Core udostępnia udostępnione elementy pierwotne, abstrakcji i pomocników do tworzenia nowoczesnych bibliotek klienckich zestawu Azure SDK. Te biblioteki są zgodne z wytycznymi projektowania zestawu Azure SDK dla platformy .NET i używają nazw pakietów i przestrzeni nazw poprzedzonych prefiksem platformy Azure, takich jak Azure.Storage.Blobs.
• System.ClientModel to podstawowa biblioteka, która udostępnia udostępnione elementy pierwotne, abstrakcji i pomocników bibliotek klienckich usługi .NET. Biblioteka System.ClientModel jest zestawem narzędzi ogólnego przeznaczenia przeznaczonym do tworzenia bibliotek dla różnych platform i usług, natomiast Azure.Core biblioteka została specjalnie zaprojektowana do tworzenia bibliotek klienckich platformy Azure.

Uwaga

Sama Azure.Core biblioteka zależy również od System.ClientModel różnych bloków konstrukcyjnych klienta. W kontekście tego artykułu kluczową różnicą dla wzorców metod jest to, czy biblioteka klienta zależy od, czy System.ClientModel bezpośrednioAzure.Core, a nie przez zależność przechodnią.

W poniższej tabeli porównaliśmy niektóre typy żądań i odpowiedzi używane przez metody protokołu i wygody, na podstawie tego, czy biblioteka zależy od, czy System.ClientModel.Azure.Core

Żądanie lub odpowiedź — problem	Azure.Core	System.ClientModel
Treść żądania	RequestContent	BinaryContent
Zaawansowane opcje żądania	RequestContext	RequestOptions
Nieprzetworzona odpowiedź HTTP	Response	PipelineResponse
Zwracany typ z modelem danych wyjściowych	Response<T>	ClientResult<T>

Sekcje z wyprzedzeniem zawierają przykłady implementacji tych pojęć.

Przykłady metod protokołu i wygody

Wzorce kodowania i typy używane przez protokół biblioteki klienta i metody wygody różnią się nieznacznie w zależności od tego, czy biblioteka zależy od , czy System.ClientModel.Azure.Core Różnice mają wpływ głównie na typy platformy .NET używane do obsługi danych żądań i odpowiedzi.

Biblioteki zależne od platformy Azure.Core

Biblioteki klienckie zestawu Azure SDK przestrzegają najnowszych wytycznych dotyczących projektowania, zależą od Azure.Core biblioteki. Na przykład Azure.AI.ContentSafety biblioteka zależy od Azure.Core biblioteki i udostępnia klasę ContentSafetyClient , która uwidacznia zarówno metody protokołu, jak i wygody.

Metoda wygody

Poniższy kod używa elementu , ContentSafetyClient aby wywołać metodę wygody 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}");
}

Powyższy kod przedstawia następujące Azure.Core wzorce metod wygody:

• Używa standardowego typu pierwotnego lub modelu języka C# jako parametru.
• Zwraca przyjazny typ języka C#, który reprezentuje wynik operacji.

Metoda protokołu

Poniższy kod używa klasy a ContentSafetyClient do wywołania AnalyzeText metody protokołu:

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

Powyższy kod przedstawia następujące Azure.Core wzorce metod protokołu:

1. Utwórz żądanie przy użyciu RequestContent obiektu dla treści żądania.
2. Wywołaj metodę protokołu przy użyciu obiektu w celu skonfigurowania RequestContext opcji żądania.
3. Obsłuż odpowiedź , odczytując:
   • Kod stanu HTTP z Response obiektu w celu określenia powodzenia lub niepowodzenia.
   • Dane z Response zawartości obiektu do typu dynamicznego przy użyciu polecenia ToDynamicFromJson. Aby uzyskać więcej informacji, zobacz Ogłoszenie dynamicznego kodu JSON w bibliotece Azure Core dla platformy .NET.

Uwaga

Powyższy kod konfiguruje zachowanie ErrorOptions.NoThrow . Ta opcja uniemożliwia zgłaszanie wyjątku przez kody stanu odpowiedzi usługi bez powodzenia, co oznacza, że kod aplikacji powinien ręcznie obsługiwać sprawdzanie kodu stanu odpowiedzi.

Biblioteki zależne od modelu System.ClientModel

Niektóre biblioteki klienckie łączące się z usługami spoza platformy Azure używają wzorców podobnych do bibliotek, które zależą od Azure.Coreprogramu . Na przykład OpenAI biblioteka udostępnia klienta, który łączy się z usługami OpenAI. Te biblioteki są oparte na bibliotece o nazwie System.ClientModel , która ma wzorce podobne do Azure.Core.

Metoda wygody

Rozważ następujący kod, który używa elementu , ChatClient aby wywołać metodę wygody 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}");

Powyższy kod przedstawia następujące System.ClientModel wzorce metod wygody:

• Używa standardowego typu pierwotnego lub modelu języka C# jako parametru.
• ClientResult Zwraca typ reprezentujący wynik operacji.

Metoda protokołu

Poniższy kod używa klasy a ChatClient do wywołania CompleteChat metody protokołu:

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

Powyższy kod przedstawia następujące System.ClientModel wzorce metod protokołu:

1. Utwórz żądanie przy użyciu BinaryContent obiektu dla treści żądania.
2. Wywołaj metodę protokołu przy użyciu obiektu w celu skonfigurowania RequestOptions opcji żądania.
3. Obsłuż odpowiedź , odczytując:
   • Kod stanu HTTP z PipelineResponse obiektu w celu określenia powodzenia lub niepowodzenia.
   • Dane z PipelineResponse zawartości obiektu przy użyciu System.Text.Json interfejsów API.

Uwaga

Powyższy kod konfiguruje zachowanie ClientErrorBehaviors.NoThrow dla elementu RequestOptions. Ta opcja uniemożliwia zgłaszanie wyjątku przez kody stanu odpowiedzi usługi bez powodzenia, co oznacza, że kod aplikacji powinien ręcznie obsługiwać sprawdzanie kodu stanu odpowiedzi.

System.ClientModelOdpowiedź oparta na modelu wygody może być przetwarzana, jeśli korzystasz z zależności od Azure.Coreelementu . Poniższa różnica pokazuje to alternatywne podejście, które jest zgodne z tym samym podejściem przedstawionym na karcie Metoda protokołu bibliotek, które zależą od platformy 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}");

Obsługa wyjątków

Gdy wywołanie usługi zakończy się niepowodzeniem, klient usługi zgłasza wyjątek, który uwidacznia kod stanu HTTP i szczegóły odpowiedzi usługi, jeśli są dostępne. Biblioteka zależna System.ClientModelzgłasza element ClientResultException, podczas gdy Azure.Corebiblioteka zależna zgłasza element RequestFailedException.

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

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

Wskazówki dotyczące użycia metod protokołu i wygody

Mimo że zestaw Azure SDK dla bibliotek klienckich platformy .NET udostępnia opcję używania metod protokołu lub wygody, priorytetyzują korzystanie z metod wygody w większości scenariuszy. Metody wygody zostały zaprojektowane tak, aby usprawnić środowisko programistyczne i zapewnić elastyczność tworzenia żądań i obsługi odpowiedzi. Jednak oba typy metod mogą być używane w aplikacji zgodnie z potrzebami. Podczas podejmowania decyzji o typie metody do użycia należy wziąć pod uwagę następujące kryteria.

Metody wygodne:

• Umożliwia pracę z bardziej przyjaznymi typami parametrów metody i odpowiedzi.
• Obsługa różnych problemów niskiego poziomu i optymalizacji dla Ciebie.

Metody protokołu:

• Zapewnij dostęp do typów niższego poziomu, takich jak RequestContext i RequestOptions, które nie są dostępne za pośrednictwem metod wygody.
• Włącz dostęp do funkcji podstawowych interfejsów API REST, które nie są uwidaczniane przez metody wygodne.
• Umożliwia tworzenie własnych metod wygody wokół punktów końcowych usługi, które nie mają jeszcze metod wygody. Takie podejście wymaga zrozumienia dokumentacji interfejsu API REST usługi w celu poprawnego obsługi żądań i odpowiedzi.

Zobacz też

Omówienie biblioteki Azure Core dla platformy .NET