Vue d’ensemble du protocole .NET et des méthodes pratiques du kit de développement logiciel (SDK) Azure pour .NET

Les bibliothèques clientes du SDK Azure fournissent une interface aux services Azure en convertissant les appels de méthode en messages envoyés via le protocole de service respectif. Pour les services d’API REST, cela signifie envoyer des requêtes HTTP et convertir les réponses en types d’exécution. Dans cet article, vous allez découvrir les différents types de méthodes exposées par les bibliothèques clientes et explorer leurs modèles d’implémentation.

Comprendre les méthodes de protocole et les méthodes pratiques

Une bibliothèque cliente Azure SDK pour .NET peut exposer deux catégories différentes de méthodes pour effectuer des requêtes auprès d’un service Azure :

• Les méthodes de protocole fournissent un wrapper mince autour de l’API REST sous-jacente pour un service Azure correspondant. Ces méthodes mappent les paramètres d’entrée primitifs aux valeurs de requête HTTP et retournent un objet de réponse HTTP brut.
• Les méthodes pratiques fournissent une couche pratique sur la couche de protocole de niveau inférieur pour ajouter la prise en charge du système de type .NET et d’autres avantages. Les méthodes pratiques acceptent des primitives ou des types de modèle .NET comme paramètres et les mappent au corps d’une demande d’API REST sous-jacente. Ces méthodes gèrent également différents détails de la gestion des demandes et des réponses pour permettre aux développeurs de se concentrer sur l’envoi et la réception d’objets de données, au lieu de problèmes de niveau inférieur.

Modèles de dépendances de bibliothèque cliente du SDK Azure

Les méthodes de protocole et les méthodes pratiques implémentent des modèles légèrement différents en fonction de la chaîne de dépendance de package sous-jacente de la bibliothèque correspondante. Une bibliothèque cliente Azure SDK pour .NET dépend de l’une des deux bibliothèques fondamentales différentes :

• Azure.Core fournit des primitives, des abstractions et des programmes d’assistance partagés pour la création de bibliothèques clientes de SDK Azure modernes. Ces bibliothèques suivent les instructions de conception Azure SDK pour .NET et utilisent des noms de package et des espaces de noms précédés de Azure, comme Azure.Storage.Blobs.
• System.ClientModel est une bibliothèque principale qui fournit des primitives partagées, des abstractions et des programmes d’assistance pour les bibliothèques clientes de service .NET. La bibliothèque System.ClientModel est un ensemble d’outils à usage général conçu pour aider à créer des bibliothèques pour diverses plateformes et services, tandis que la bibliothèque Azure.Core est spécifiquement conçue pour la création de bibliothèques clientes Azure.

Remarque

La bibliothèque Azure.Core elle-même dépend également de System.ClientModel pour différents blocs de construction clients. Dans le contexte de cet article, le différentiateur clé pour les modèles de méthode est de savoir si une bibliothèque cliente dépend de Azure.Core ou de System.ClientModel directement, plutôt que par le biais d’une dépendance transitive.

Le tableau suivant compare certains des types de requête et de réponse utilisés par le protocole et les méthodes pratiques, selon que la bibliothèque dépend de Azure.Core ou de System.ClientModel.

Problème de demande ou de réponse	Azure.Core	System.ClientModel
Corps de la demande	RequestContent	BinaryContent
Options de demande avancées	RequestContext	RequestOptions
Réponse HTTP brute	Response	PipelineResponse
Type de retour avec le modèle de sortie	Response<T>	ClientResult<T>

Les sections à venir fournissent des exemples d’implémentation de ces concepts.

Exemples de méthodes de protocole et de méthodes pratiques

Les modèles de codage et les types utilisés par le protocole de bibliothèque cliente et les méthodes pratiques varient légèrement selon que la bibliothèque dépend de Azure.Core ou de System.ClientModel. Les différences influencent principalement les types .NET utilisés pour la gestion des données de demande et de réponse.

Bibliothèques qui dépendent d’Azure.Core

Les bibliothèques clientes du SDK Azure qui respectent les dernières instructions de conception dépendent de la bibliothèque Azure.Core. Par exemple, la bibliothèque Azure.AI.ContentSafety dépend de la bibliothèque Azure.Core et fournit une classe ContentSafetyClient qui expose les méthodes de protocole et les méthodes pratiques.

Méthode pratique

Le code suivant utilise ContentSafetyClient pour appeler la méthode pratique 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}");
}

Le code précédent illustre les modèles de méthode pratique Azure.Core suivants :

• Utilise un type primitif C# standard ou un type de modèle en tant que paramètre.
• Retourne un type C# convivial qui représente le résultat de l’opération.

Méthode de protocole

Le code suivant utilise un ContentSafetyClient pour appeler la méthode de protocole 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}");
}

Le code précédent illustre les modèles de méthode de protocole Azure.Core suivants :

1. Créez la demande en utilisant un objet RequestContent pour le corps de la demande.
2. Invoquez la méthode du protocole en utilisant un objet RequestContext pour configurer les options de la demande.
3. Gérez la réponse en lisant :
   • Le code de statut HTTP de l’objet Response pour déterminer le succès ou l’échec.
   • Les données du contenu de l’objet Response dans un type dynamique en utilisant ToDynamicFromJson. Pour en savoir plus, consultez Annonce de JSON dynamique dans la bibliothèque Azure Core pour .NET.

Remarque

Le code précédent configure le comportement ErrorOptions.NoThrow. Cette option empêche les codes d’état de réponses de service non réussies de lever une exception, ce qui signifie que le code de l’application doit gérer manuellement les vérifications du code d’état de réponse.

Bibliothèques qui dépendent de System.ClientModel

Certaines bibliothèques clientes qui se connectent à des services non Azure utilisent des modèles similaires aux bibliothèques qui dépendent de Azure.Core. Par exemple, la bibliothèque OpenAI fournit un client qui se connecte aux services OpenAI. Ces bibliothèques sont basées sur une bibliothèque appelée System.ClientModel qui présente des modèles similaires à Azure.Core.

Méthode pratique

Tenez compte du code suivant qui utilise ChatClient pour appeler la méthode pratique 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}");

Le code précédent illustre les modèles de méthode pratique System.ClientModel suivants :

• Utilise un type primitif C# standard ou un type de modèle en tant que paramètre.
• Retourne un type ClientResult qui représente le résultat de l’opération.

Méthode de protocole

Le code suivant utilise un ChatClient pour appeler la méthode de protocole 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)}");

Le code précédent illustre les modèles de méthode de protocole System.ClientModel suivants :

1. Créez la demande en utilisant un objet BinaryContent pour le corps de la demande.
2. Invoquez la méthode du protocole en utilisant un objet RequestOptions pour configurer les options de la demande.
3. Gérez la réponse en lisant :
   • Le code de statut HTTP de l’objet PipelineResponse pour déterminer le succès ou l’échec.
   • Les données du contenu de l’objet PipelineResponse en utilisant les API System.Text.Json.

Remarque

Le code précédent configure le comportement ClientErrorBehaviors.NoThrow pour RequestOptions. Cette option empêche les codes d’état de réponses de service non réussies de lever une exception, ce qui signifie que le code de l’application doit gérer manuellement les vérifications du code d’état de réponse.

Une réponse basée sur System.ClientModel peut être traitée comme un modèle pratique, si vous prenez une dépendance sur Azure.Core. Le diff suivant montre cette autre approche, qui suit la même approche illustrée dans l’onglet Méthode de protocole des bibliothèques qui dépendent d’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}");

Gérer les exceptions

Lorsqu'un appel de service échoue, le client du service lève une exception qui expose le code d'état HTTP et les détails de la réponse du service, s'ils sont disponibles. Une bibliothèque dépendante de System.ClientModel provoque un ClientResultException, tandis qu'une bibliothèque dépendante de Azure.Core provoque un RequestFailedException.

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

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

Conseils d’utilisation des méthodes de protocole et des méthodes pratiques

Bien que le SDK Azure pour les bibliothèques clientes .NET offre la possibilité d’utiliser des méthodes de protocole ou des méthodes pratiques, favorisez l’utilisation des méthodes pratiques dans la plupart des scénarios. Les méthodes pratiques sont conçues pour améliorer l’expérience de développement et offrir une flexibilité pour la création de demandes et la gestion des réponses. Toutefois, les deux types de méthode peuvent être utilisés dans votre application en fonction des besoins. Tenez compte des critères suivants pour décider du type de méthode à utiliser.

Les méthodes pratiques :

• Permettent d’utiliser des types de paramètres de méthode et de réponse plus conviviaux.
• S’occupent de diverses préoccupations et optimisations de bas niveau à votre place.

Les méthodes de protocole :

• Fournissent un accès aux types de niveau inférieur, tels que RequestContext et RequestOptions, qui ne sont pas disponibles avec les méthodes pratiques.
• Permettent un accès aux fonctionnalités des API REST sous-jacentes que les méthodes pratiques n’exposent pas.
• Vous pouvez créer vos propres méthodes pratiques autour des points de terminaison de service qui n’ont pas encore de méthodes pratiques. Cette approche nécessite de comprendre la documentation de l’API REST du service pour gérer correctement les demandes et les réponses.

Voir aussi

Présentation de la bibliothèque Azure Core pour .NET