Introducción a los métodos de uso y protocolo de .NET para el SDK de Azure para .NET

Article
10/03/2024

Las bibliotecas cliente del SDK de Azure proporcionan una interfaz a los servicios de Azure mediante la traducción de llamadas de método a mensajes enviados a través del protocolo de servicio correspondiente. En el caso de los servicios de API de REST, esto significa enviar solicitudes HTTP y convertir las respuestas en tipos de tiempo de ejecución. En este artículo, obtendrá información sobre los distintos tipos de métodos expuestos por las bibliotecas cliente y explorará sus patrones de implementación.

Descripción del protocolo y los métodos de conveniencia

Una biblioteca cliente de Azure SDK para .NET puede exponer dos categorías diferentes de métodos para realizar solicitudes a un servicio de Azure:

Los métodos de protocolo proporcionan un contenedor fino alrededor de la API de REST subyacente para un servicio de Azure correspondiente. Estos métodos asignan parámetros de entrada primitivos a valores de solicitud HTTP y devuelven un objeto de respuesta HTTP sin procesar.
Los métodos prácticos proporcionan una capa de comodidad sobre la capa de protocolo de nivel inferior para agregar compatibilidad con el sistema de tipos de .NET y otras ventajas. Los métodos de conveniencia aceptan primitivos o tipos de modelo de .NET como parámetros y los asignan al cuerpo de una solicitud de API de REST subyacente. Estos métodos también controlan varios detalles de la administración de solicitudes y respuestas para permitir a los desarrolladores centrarse en el envío y recepción de objetos de datos, en lugar de problemas de nivel inferior.

Patrones de dependencia de la biblioteca cliente del SDK de Azure

Los métodos de protocolo y prácticos implementan patrones ligeramente diferentes en función de la cadena de dependencias del paquete subyacente de la biblioteca respectiva. Una biblioteca cliente del SDK de Azure para .NET depende de una de las dos bibliotecas fundamentales diferentes:

Azure.Core proporciona primitivos compartidos, abstracciones y asistentes para crear bibliotecas cliente modernas del SDK de Azure. Estas bibliotecas siguen las directrices de diseño del SDK de Azure para .NET y usan nombres de paquete y espacios de nombres prefijos con Azure, como Azure.Storage.Blobs.
System.ClientModel es una biblioteca principal que proporciona primitivos compartidos, abstracciones y asistentes para las bibliotecas cliente del servicio .NET. La biblioteca System.ClientModel es un conjunto de herramientas de uso general diseñado para crear bibliotecas en diversas plataformas y servicios, mientras que la biblioteca Azure.Core está diseñada específicamente para crear bibliotecas cliente de Azure.

Nota:

La propia biblioteca Azure.Core también depende de System.ClientModel para varios bloques de creación de cliente. En el contexto de este artículo, el diferenciador clave para los patrones de método es si una biblioteca cliente depende de Azure.Core o System.ClientModel directamente, en lugar de a través de una dependencia transitiva.

En la tabla siguiente se comparan algunos de los tipos de solicitud y respuesta utilizados por los métodos de protocolo y de uso, en función de si la biblioteca depende de Azure.Core o de System.ClientModel.

Solicitud o problema de respuesta	Azure.Core	System.ClientModel
Cuerpo de la solicitud	RequestContent	BinaryContent
Opciones avanzadas de solicitud	RequestContext	RequestOptions
Respuesta HTTP sin formato	Response	PipelineResponse
Tipo devuelto con el modelo de salida	Response<T>	ClientResult<T>

En las secciones anteriores se proporcionan ejemplos de implementación de estos conceptos.

Ejemplos de métodos de protocolo y prácticos

Los patrones de codificación y los tipos usados por el protocolo de biblioteca cliente y los métodos de conveniencia varían ligeramente en función de si la biblioteca depende de Azure.Core o System.ClientModel. Las diferencias influyen principalmente en los tipos de .NET que se usan para controlar los datos de solicitud y respuesta.

Bibliotecas que dependen de Azure.Core

Las bibliotecas cliente del SDK de Azure que se adhieren a las directrices de diseño más recientes dependen de la biblioteca Azure.Core. Por ejemplo, la biblioteca Azure.AI.ContentSafety depende de la biblioteca Azure.Core y proporciona una clase ContentSafetyClient que expone métodos de protocolo y práctico.

Método práctico
Método de protocolo

El código siguiente usa un ContentSafetyClient para llamar al método práctico 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}");
}

El código anterior muestra los siguientes patrones de método práctico Azure.Core:

Usa un tipo primitivo o de modelo estándar de C# como parámetro.
Devuelve un tipo de C# descriptivo que representa el resultado de la operación.

El código siguiente usa un ContentSafetyClient para llamar al 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}");
}

En el código anterior se muestran los siguientes patrones de método de protocolo Azure.Core:

Cree la solicitud mediante un objeto RequestContent para el cuerpo de la solicitud.
Invoque el método de protocolo mediante un objeto RequestContext para configurar las opciones de solicitud.
Controle la respuesta leyendo:
- Código de estado HTTP del objeto Response para determinar si se ha realizado correctamente o no.
- Datos del contenido del objeto Response en un tipo dinámico mediante ToDynamicFromJson. Para obtener más información, consulte Anuncio de JSON dinámico en la biblioteca de Azure Core para .NET.

Nota:

En el código anterior se configura el comportamiento de ErrorOptions.NoThrow . Esta opción impide que los códigos de estado de las respuestas de servicio que no se realicen correctamente inicien una excepción, lo que significa que el código de la aplicación debe controlar manualmente las comprobaciones de código de estado de respuesta.

Bibliotecas que dependen de System.ClientModel

Algunas bibliotecas cliente que se conectan a servicios que no son de Azure usan patrones similares a las bibliotecas que dependen de Azure.Core. Por ejemplo, la biblioteca OpenAI proporciona un cliente que se conecta a los servicios de OpenAI. Estas bibliotecas se basan en una biblioteca denominada System.ClientModel que tiene patrones similares a Azure.Core.

Método práctico
Método de protocolo

Tenga en cuenta el código siguiente que usa un ChatClient para llamar al método práctico 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}");

El código anterior muestra los siguientes patrones de método práctico System.ClientModel:

Usa un tipo primitivo o de modelo estándar de C# como parámetro.
Devuelve un tipo ClientResult que representa el resultado de la operación.

El código siguiente usa un ChatClient para llamar al 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)}");

En el código anterior se muestran los siguientes patrones de método de protocolo System.ClientModel:

Cree la solicitud mediante un objeto BinaryContent para el cuerpo de la solicitud.
Invoque el método de protocolo mediante un objeto RequestOptions para configurar las opciones de solicitud.
Controle la respuesta leyendo:
- Código de estado HTTP del objeto PipelineResponse para determinar si se ha realizado correctamente o no.
- Datos del contenido del objeto PipelineResponse mediante System.Text.Json API.

Nota:

El código anterior configura el comportamiento ClientErrorBehaviors.NoThrow para RequestOptions. Esta opción impide que los códigos de estado de las respuestas de servicio que no se realicen correctamente inicien una excepción, lo que significa que el código de la aplicación debe controlar manualmente las comprobaciones de código de estado de respuesta.

Una respuesta basada en System.ClientModel se puede procesar como un modelo de uso si se toma una dependencia en Azure.Core. La diferencia siguiente refleja este modo alternativo, que sigue el mismo método que se muestra en la pestaña Método de protocolo de Bibliotecas que dependen de 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}");

Administrar excepciones

Cuando se produce un error en una llamada de servicio, el cliente de servicio produce una excepción que expone el código de estado HTTP y los detalles de la respuesta del servicio, si está disponible. Una System.ClientModelbiblioteca dependiente produce un ClientResultException, mientras que una Azure.Corebiblioteca dependiente produce un RequestFailedException.

Excepciones de System.ClientModel
Excepciones de 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}");
}

Guía de uso de métodos de protocolo y prácticos

Aunque las bibliotecas cliente de Azure SDK para .NET proporcionan la opción de usar métodos de protocolo o prácticos, priorice el uso de métodos de conveniencia en la mayoría de los escenarios. Los métodos prácticos están diseñados para mejorar la experiencia de desarrollo y proporcionan flexibilidad para crear solicitudes y controlar respuestas. Sin embargo, ambos tipos de método se pueden usar en la aplicación según sea necesario. Tenga en cuenta los siguientes criterios a la hora de decidir qué tipo de método utilizar.

Métodos prácticos:

Le permite trabajar con tipos de parámetros de método y respuesta más descriptivos.
Controle diversos problemas y optimizaciones de bajo nivel para usted.

Métodos de protocolo:

Proporcione acceso a tipos de nivel inferior, como RequestContext y RequestOptions, que no están disponibles a través de métodos prácticos.
Habilite el acceso a las características de las API de REST subyacentes que los métodos de conveniencia no exponen.
Le permite crear sus propios métodos prácticos en torno a los puntos de conexión de servicio que aún no tienen métodos de conveniencia. Este enfoque requiere comprender la documentación de la API de REST del servicio para controlar las solicitudes y respuestas correctamente.

Consulte también

Descripción de la biblioteca de Azure Core para .NET

Comparteix a través de

Introducción a los métodos de uso y protocolo de .NET para el SDK de Azure para .NET

Descripción del protocolo y los métodos de conveniencia

Patrones de dependencia de la biblioteca cliente del SDK de Azure

Ejemplos de métodos de protocolo y prácticos

Bibliotecas que dependen de Azure.Core

Bibliotecas que dependen de System.ClientModel

Administrar excepciones

Guía de uso de métodos de protocolo y prácticos

Consulte también

Recursos addicionals