Visão geral dos métodos de conveniência e protocolo do SDK do Azure para .NET

Artigo
10/04/2024

As bibliotecas de clientes do SDK do Azure fornecem uma interface para os serviços do Azure traduzindo chamadas de método em mensagens enviadas por meio do respectivo protocolo de serviço. Para serviços de API REST, isso significa enviar solicitações HTTP e converter as respostas em tipos de runtime. Neste artigo, você aprenderá sobre os diferentes tipos de métodos expostos pelas bibliotecas de cliente e explorará seus padrões de implementação.

Entender os métodos de protocolo e conveniência

Uma biblioteca de clientes do SDK do Azure para .NET pode expor duas categorias diferentes de métodos para fazer solicitações a um serviço do Azure:

Os métodos de protocolo fornecem um wrapper fino em torno da API REST subjacente para um serviço do Azure correspondente. Esses métodos mapeiam parâmetros de entrada primitivos para valores de solicitação HTTP e retornam um objeto de resposta HTTP bruto.
Os métodos de conveniência fornecem uma camada de conveniência sobre a camada de protocolo de nível inferior para adicionar suporte ao sistema de tipos .NET e outros benefícios. Métodos de conveniência aceitam primitivos ou tipos de modelo .NET como parâmetros e mapeiam-os para o corpo de uma solicitação de API REST subjacente. Esses métodos também lidam com vários detalhes do gerenciamento de solicitações e respostas para permitir que os desenvolvedores se concentrem no envio e recebimento de objetos de dados, em vez de preocupações de nível inferior.

Padrões de dependência da biblioteca de clientes do SDK do Azure

Os métodos de protocolo e conveniência implementam padrões ligeiramente diferentes com base na cadeia de dependência de pacote subjacente da respectiva biblioteca. Uma biblioteca de clientes do SDK do Azure para .NET depende de uma das duas bibliotecas fundamentais diferentes:

Azure.Core fornece primitivos compartilhados, abstrações e auxiliares para a criação de bibliotecas de clientes modernas do SDK do Azure. Essas bibliotecas seguem as diretrizes de design do SDK do Azure para .NET e usam nomes de pacote e namespaces prefixados com o Azure, como Azure.Storage.Blobs.
System.ClientModel é uma biblioteca principal que fornece primitivos compartilhados, abstrações e auxiliares para bibliotecas de clientes do serviço .NET. A biblioteca System.ClientModel é um conjunto de ferramentas de uso geral projetado para ajudar a criar bibliotecas para várias plataformas e serviços, enquanto a biblioteca Azure.Core foi projetada especificamente para criar bibliotecas de cliente do Azure.

Observação

A biblioteca Azure.Core em si também depende de System.ClientModel para vários blocos de construção do cliente. No contexto deste artigo, o diferencial chave para padrões de método é se uma biblioteca de clientes depende de Azure.Core ou System.ClientModel diretamente, em vez de por meio de uma dependência transitiva.

A tabela a seguir compara alguns dos tipos de solicitação e resposta usados por métodos de protocolo e conveniência, com base em se a biblioteca depende de Azure.Core ou System.ClientModel.

Solicitar uma preocupação de resposta	Azure.Core	System.ClientModel
Corpo da solicitação	RequestContent	BinaryContent
Opções avançadas de solicitação	RequestContext	RequestOptions
Resposta HTTP bruta	Response	PipelineResponse
Tipo de retorno com o modelo de saída	Response<T>	ClientResult<T>

As seções adiante fornecem exemplos de implementação desses conceitos.

Exemplos de protocolo e método de conveniência

Os padrões e tipos de codificação usados pelo protocolo de biblioteca de clientes e métodos de conveniência variam ligeiramente de acordo com se a biblioteca depende de Azure.Core ou System.ClientModel. As diferenças influenciam principalmente os tipos .NET usados para lidar com dados de solicitação e resposta.

Bibliotecas que dependem do Azure.Core

As bibliotecas de clientes do SDK do Azure que aderirem às diretrizes de design mais recentes dependem da biblioteca Azure.Core. Por exemplo, a biblioteca Azure.AI.ContentSafety depende da biblioteca Azure.Core e fornece uma classe ContentSafetyClient que expõe métodos de protocolo e conveniência.

Método de conveniência
Método de protocolo

O código a seguir usa ContentSafetyClient para chamar o método de conveniência 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}");
}

O código anterior demonstra os seguintes padrões de método de conveniência Azure.Core:

Usa um tipo de modelo ou primitivo C# padrão como um parâmetro.
Retorna um tipo C# amigável que representa o resultado da operação.

O código a seguir usa ContentSafetyClient para chamar o método de protocolo 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}");
}

O código anterior demonstra os seguintes padrões de método de protocolo Azure.Core:

Crie a solicitação, usando um objeto RequestContent para o corpo da solicitação.
Chame o método de protocolo, usando um objeto RequestContext para configurar opções de solicitação.
Manipule a resposta lendo:
- O código de status HTTP do objeto Response para determinar o sucesso ou a falha.
- Dados do conteúdo do objeto Response em um tipo dinâmico usando ToDynamicFromJson. Para obter mais informações, consulte Anunciando JSON dinâmico na biblioteca principal do Azure para .NET.

Observação

O código anterior configura o comportamento ErrorOptions.NoThrow. Essa opção impede que códigos de status de respostas de serviço sem êxito gerem uma exceção, o que significa que o código do aplicativo deve lidar manualmente com as verificações de código de status de resposta.

Bibliotecas que dependem de System.ClientModel

Algumas bibliotecas de clientes que se conectam a serviços que não são do Azure usam padrões semelhantes às bibliotecas que dependem de Azure.Core. Por exemplo, a biblioteca de OpenAI fornece um cliente que se conecta aos serviços OpenAI. Essas bibliotecas são baseadas em uma biblioteca chamada System.ClientModel que tem padrões semelhantes a Azure.Core.

Método de conveniência
Método de protocolo

Considere o seguinte código que usa um ChatClient para chamar o método de conveniência 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}");

O código anterior demonstra os seguintes padrões de método de conveniência System.ClientModel:

Usa um tipo de modelo ou primitivo C# padrão como um parâmetro.
Retorna um tipo ClientResult amigável que representa o resultado da operação.

O código a seguir usa ChatClient para chamar o método de protocolo 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)}");

O código anterior demonstra os seguintes padrões de método de protocolo System.ClientModel:

Crie a solicitação, usando um objeto BinaryContent para o corpo da solicitação.
Chame o método de protocolo, usando um objeto RequestOptions para configurar opções de solicitação.
Manipule a resposta lendo:
- O código de status HTTP do objeto PipelineResponse para determinar o sucesso ou a falha.
- Dados do conteúdo do objeto PipelineResponse usando APIs System.Text.Json.

Observação

O código anterior configura o comportamento ClientErrorBehaviors.NoThrow para o RequestOptions. Essa opção impede que códigos de status de respostas de serviço sem êxito gerem uma exceção, o que significa que o código do aplicativo deve lidar manualmente com as verificações de código de status de resposta.

Uma resposta baseada em System.ClientModel pode ser processada como um modelo de conveniência, se você assumir uma dependência do Azure.Core. A comparação a seguir mostra essa abordagem alternativa, que segue a mesma abordagem demonstrada na guia Método de protocolo de Bibliotecas que dependem do 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}");

Tratar exceções

Quando uma chamada de serviço falha, o cliente de serviço lança uma exceção que expõe o código do status HTTP e os detalhes da resposta do serviço, se estiverem disponíveis. Uma biblioteca dependente de System.ClientModel lança um ClientResultException, enquanto uma biblioteca dependente de Azure.Core lança um RequestFailedException.

Exceções de System.ClientModel
Exceções do Azure.Core

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

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

Diretriz de uso do protocolo e método de conveniência

Embora o SDK do Azure para bibliotecas de clientes .NET forneça a opção de usar métodos de protocolo ou conveniência, priorize o uso de métodos de conveniência na maioria dos cenários. Os métodos de conveniência são projetados para melhorar a experiência de desenvolvimento e fornecer flexibilidade para criar solicitações e lidar com respostas. No entanto, ambos os tipos de método podem ser usados em seu aplicativo conforme necessário. Considere os seguintes critérios ao decidir que tipo de método usar.

Métodos de conveniência:

Permite que você trabalhe com tipos de resposta e parâmetros de método mais amigáveis.
Lida com várias preocupações e otimizações de baixo nível para você.

Métodos de protocolo:

Fornece acesso a tipos de nível inferior, como RequestContext e RequestOptions, que não estão disponíveis por meio de métodos de conveniência.
Habilita o acesso aos recursos das APIs REST subjacentes que os métodos de conveniência não expõem.
Permite que você crie seus próprios métodos de conveniência em torno de pontos de extremidade de serviço que ainda não têm métodos de conveniência. Essa abordagem requer entender a documentação da API REST do serviço para lidar com solicitações e respostas corretamente.

Confira também

Noções básicas sobre a biblioteca do Azure Core para .NET

Compartilhar via

Visão geral dos métodos de conveniência e protocolo do SDK do Azure para .NET

Entender os métodos de protocolo e conveniência

Padrões de dependência da biblioteca de clientes do SDK do Azure

Exemplos de protocolo e método de conveniência

Bibliotecas que dependem do Azure.Core

Bibliotecas que dependem de System.ClientModel

Tratar exceções

Diretriz de uso do protocolo e método de conveniência

Confira também

Recursos adicionais