Panoramica del protocollo e dei metodi pratici di Azure SDK per .NET

Le librerie client di Azure SDK forniscono un'interfaccia ai servizi di Azure convertendo le chiamate al metodo in messaggi inviati tramite il rispettivo protocollo di servizio. Per i servizi API REST, ciò significa inviare richieste HTTP e convertire le risposte in tipi di runtime. Questo articolo illustra i diversi tipi di metodi esposti dalle librerie client ed esplora i relativi modelli di implementazione.

Comprendere i metodi pratici e del protocollo

Una libreria client di Azure SDK per .NET può esporre due diverse categorie di metodi per effettuare richieste a un servizio di Azure:

• I metodi del protocollo forniscono un wrapper sottile intorno all'API REST sottostante per un servizio di Azure corrispondente. Questi metodi eseguono il mapping dei parametri di input primitivi ai valori delle richieste HTTP e restituiscono un oggetto risposta HTTP non elaborato.
• I metodi pratici offrono un livello pratico rispetto al livello di protocollo di livello inferiore per aggiungere il supporto per il sistema di tipi .NET e altri vantaggi. I metodi pratici accettano primitive o tipi di modello .NET come parametri ed eseguirne il mapping al corpo di una richiesta API REST sottostante. Questi metodi gestiscono anche vari dettagli della gestione delle richieste e delle risposte per consentire agli sviluppatori di concentrarsi sull'invio e la ricezione di oggetti dati, invece di problemi di livello inferiore.

Modelli di dipendenza della libreria client di Azure SDK

I metodi pratici e del protocollo implementano modelli leggermente diversi in base alla catena di dipendenze del pacchetto sottostante della rispettiva libreria. Una libreria client di Azure SDK per .NET dipende da una delle due librerie di base diverse:

• Azure.Core fornisce primitive, astrazioni e helper condivisi per la creazione di librerie client moderne di Azure SDK. Queste librerie seguono le linee guida per la progettazione di Azure SDK per .NET e usano nomi dei pacchetti e spazi dei nomi preceduti da Azure, ad esempio Azure.Storage.Blobs.
• System.ClientModel è una libreria di base che fornisce primitive condivise, astrazioni e helper per le librerie client del servizio .NET. La libreria System.ClientModel è un set di strumenti per utilizzo generico progettato per facilitare la creazione di librerie per varie piattaforme e servizi, mentre la libreria Azure.Core è progettata in modo specifico per la creazione delle librerie client di Azure.

Nota

La libreria Azure.Core stessa dipende anche da System.ClientModel per vari blocchi predefiniti client. Nel contesto di questo articolo, il differenziatore chiave per i modelli di metodo è se una libreria client dipende da Azure.Core o System.ClientModel direttamente, anziché tramite una dipendenza transitiva.

Nella tabella seguente vengono confrontati alcuni dei tipi di richiesta e risposta utilizzati dai metodi pratici e di protocollo, a seconda del fatto che la libreria dipenda da Azure.Core o da System.ClientModel.

Problema di richiesta o risposta	Azure.Core	System.ClientModel
Corpo della richiesta	RequestContent	BinaryContent
Opzioni di richiesta avanzate	RequestContext	RequestOptions
Risposta HTTP non elaborata	Response	PipelineResponse
Tipo restituito con modello di output	Response<T>	ClientResult<T>

Le sezioni successive forniscono esempi di implementazione di questi concetti.

Esempi di metodi pratici e di protocollo

I modelli di codifica e i tipi usati dalle libreria client e dai metodi pratici e del protocollo variano leggermente in base se la libreria dipende da Azure.Core o System.ClientModel. Le differenze influisce principalmente sui tipi .NET usati per la gestione dei dati di richiesta e risposta.

Librerie che dipendono da Azure.Core

Le librerie client di Azure SDK che aderiscono alle linee guida di progettazione più recenti dipendono dalla libreria Azure.Core. Ad esempio, la libreria Azure.AI.ContentSafety dipende dalla libreria Azure.Core e fornisce una classe ContentSafetyClient che espone sia i metodi pratici che del protocollo.

Metodo pratico

Il codice seguente usa un oggetto ContentSafetyClient per chiamare il metodo pratico 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}");
}

Il codice precedente illustra i modelli di metodi pratici seguenti Azure.Core:

• Usa una primitiva C# standard o un tipo di modello come parametro.
• Restituisce un tipo C# descrittivo che rappresenta il risultato dell'operazione.

Metodo del protocollo

Il codice seguente usa un oggetto ContentSafetyClient per chiamare il metodo del protocollo 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}");
}

Il codice precedente illustra i modelli di metodo del protocolloi Azure.Core seguenti:

1. Creare la richiesta usando un oggetto RequestContent per il corpo della richiesta.
2. Richiamare il metodo di protocollo usando un oggetto RequestContext per configurare le opzioni di richiesta.
3. Gestire la risposta leggendo:
   • Codice di stato HTTP dall'oggetto Response per determinare l'esito positivo o negativo.
   • Dati dal contenuto dell'oggetto Response in un tipo dinamico usando ToDynamicFromJson. Per altre informazioni, vedere Annuncio di JSON dinamico nella libreria Azure.Core per .NET.

Nota

Il codice precedente configura il comportamento ErrorOptions.NoThrow. Questa opzione impedisce che i codici di stato delle risposte del servizio non riuscite generino un'eccezione, il che significa che il codice dell'app deve gestire manualmente i controlli del codice di stato della risposta.

Librerie che dipendono da System.ClientModel

Alcune librerie client che si connettono a servizi non di Azure usano modelli simili alle librerie che dipendono da Azure.Core. Ad esempio, la libreria OpenAI fornisce un client che si connette ai servizi OpenAI. Queste librerie sono basate su una libreria denominata System.ClientModel con modelli simili a Azure.Core.

Metodo pratico

Si consideri il codice seguente che usa un oggetto ChatClient per chiamare il metodo pratico 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}");

Il codice precedente illustra i modelli di metodi pratici System.ClientModel seguenti:

• Usa una primitiva C# standard o un tipo di modello come parametro.
• Restituisce un tipo ClientResult che rappresenta il risultato dell'operazione.

Metodo del protocollo

Il codice seguente usa un oggetto ChatClient per chiamare il metodo del protocollo 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)}");

Il codice precedente illustra i modelli di metodo del protocolloi System.ClientModel seguenti:

1. Creare la richiesta usando un oggetto BinaryContent per il corpo della richiesta.
2. Richiamare il metodo di protocollo usando un oggetto RequestOptions per configurare le opzioni di richiesta.
3. Gestire la risposta leggendo:
   • Codice di stato HTTP dall'oggetto PipelineResponse per determinare l'esito positivo o negativo.
   • Dati dal contenuto dell'oggetto PipelineResponse usando API System.Text.Json.

Nota

Il codice precedente configura il comportamento ClientErrorBehaviors.NoThrow per RequestOptions. Questa opzione impedisce che i codici di stato delle risposte del servizio non riuscite generino un'eccezione, il che significa che il codice dell'app deve gestire manualmente i controlli del codice di stato della risposta.

Una risposta basata su System.ClientModel può essere elaborata come un modello pratico, se si accetta una dipendenza da Azure.Core. Il diff seguente illustra questo approccio alternativo, che segue lo stesso approccio illustrato nella scheda Metodo di protocollo delle librerie che dipendono da 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}");

Gestire eccezioni

Quando una chiamata al servizio ha esito negativo, il client del servizio genera un'eccezione che espone il codice di stato HTTP e i dettagli della risposta del servizio, se disponibile. Una libreria dipendente da System.ClientModel genera una ClientResultException, mentre una libreria dipendente da Azure.Core genera una RequestFailedException.

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

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

Linee guida per l'utilizzo di metodi pratici e del protocollo

Anche se le librerie client di Azure SDK per .NET offrono la possibilità di usare metodi pratici e del protocollo, definire la priorità usando i metodi pratici nella maggior parte degli scenari. I metodi pratici sono progettati per migliorare l'esperienza di sviluppo e offrire flessibilità per la creazione di richieste e la gestione delle risposte. Tuttavia, entrambi i tipi di metodo possono essere usati nell'app in base alle esigenze. Considerare i seguenti criteri per decidere quale tipo di metodo utilizzare.

Metodi pratici:

• Consente di usare tipi di risposta e parametri di metodo più descrittivi.
• Gestire automaticamente vari problemi e ottimizzazioni di basso livello.

Metodi del protocollo:

• Fornire l'accesso a tipi di livello inferiore, ad esempio RequestContext e RequestOptions, che non sono disponibili tramite metodi pratici.
• Abilitare l'accesso alle funzionalità delle API REST sottostanti che i metodi pratici non espongono.
• Consente di creare metodi di praticità personalizzati per gli endpoint di servizio che non dispongono già di metodi pratici. Questo approccio richiede la comprensione della documentazione dell'API REST del servizio per gestire correttamente le richieste e le risposte.

Vedi anche

Informazioni sulla libreria di Azure Core per .NET