Overzicht van Azure SDK voor .NET-protocol en gemaksmethoden

De Azure SDK-clientbibliotheken bieden een interface voor Azure-services door methodeaanroepen te vertalen naar berichten die via het respectieve serviceprotocol worden verzonden. Voor REST API-services betekent dit het verzenden van HTTP-aanvragen en het converteren van de antwoorden naar runtimetypen. In dit artikel leert u meer over de verschillende typen methoden die door de clientbibliotheken worden weergegeven en verkent u hun implementatiepatronen.

Protocol- en gemaksmethoden begrijpen

Een Azure SDK voor .NET-clientbibliotheek kan twee verschillende categorieën methoden beschikbaar maken om aanvragen te doen voor een Azure-service:

• Protocolmethoden bieden een thin wrapper rond de onderliggende REST API voor een bijbehorende Azure-service. Met deze methoden worden primitieve invoerparameters toegewezen aan HTTP-aanvraagwaarden en wordt een onbewerkt HTTP-antwoordobject geretourneerd.
• Gemaksmethoden bieden een gemakslaag boven de protocollaag op lager niveau om ondersteuning toe te voegen voor het .NET-typesysteem en andere voordelen. Gemaksmethoden accepteren primitieven of .NET-modeltypen als parameters en wijzen deze toe aan de hoofdtekst van een onderliggende REST API-aanvraag. Deze methoden verwerken ook verschillende details van aanvraag- en antwoordbeheer, zodat ontwikkelaars zich kunnen richten op het verzenden en ontvangen van gegevensobjecten, in plaats van problemen op lager niveau.

Afhankelijkheidspatronen voor Azure SDK-clientbibliotheek

Protocol- en gemaksmethoden implementeren enigszins verschillende patronen op basis van de onderliggende pakketafhankelijkheidsketen van de respectieve bibliotheek. Een Azure SDK voor .NET-clientbibliotheek is afhankelijk van een van de twee verschillende basisbibliotheken:

• Azure.Core biedt gedeelde primitieven, abstracties en helpers voor het bouwen van moderne Azure SDK-clientbibliotheken. Deze bibliotheken volgen de Ontwerprichtlijnen voor Azure SDK voor .NET en gebruiken pakketnamen en naamruimten die voorafgegaan zijn door Azure, zoals Azure.Storage.Blobs.
• System.ClientModel is een kernbibliotheek die gedeelde primitieven, abstracties en helpers biedt voor .NET-serviceclientbibliotheken. De System.ClientModel bibliotheek is een hulpmiddelenset voor algemeen gebruik die is ontworpen om bibliotheken te bouwen voor verschillende platforms en services, terwijl de bibliotheek speciaal is ontworpen voor het Azure.Core bouwen van Azure-clientbibliotheken.

Notitie

De Azure.Core bibliotheek zelf is ook afhankelijk System.ClientModel van verschillende clientbouwstenen. In de context van dit artikel is de belangrijkste differentiator voor methodepatronen of een clientbibliotheek afhankelijk is van Azure.Core of System.ClientModel rechtstreeks, in plaats van via een transitieve afhankelijkheid.

In de volgende tabel worden enkele van de aanvraag- en antwoordtypen vergeleken die worden gebruikt door protocol- en gemaksmethoden, afhankelijk van of de bibliotheek afhankelijk is van Azure.Core of System.ClientModel.

Aanvraag- of antwoordprobleem	Azure.Core	System.ClientModel
Aanvraagtekst	RequestContent	BinaryContent
Geavanceerde aanvraagopties	RequestContext	RequestOptions
Onbewerkt HTTP-antwoord	Response	PipelineResponse
Retourtype met uitvoermodel	Response<T>	ClientResult<T>

De volgende secties bevatten implementatievoorbeelden van deze concepten.

Voorbeelden van protocol- en gemaksmethode

De coderingspatronen en -typen die worden gebruikt door het clientbibliotheekprotocol en de gemaksmethoden variëren enigszins op basis van of afhankelijk van Azure.Core System.ClientModelde bibliotheek. De verschillen zijn voornamelijk van invloed op de .NET-typen die worden gebruikt voor het verwerken van aanvraag- en antwoordgegevens.

Bibliotheken die afhankelijk zijn van Azure.Core

Azure SDK-clientbibliotheken die voldoen aan de nieuwste ontwerprichtlijnen , zijn afhankelijk van de Azure.Core bibliotheek. De Azure.AI.ContentSafety bibliotheek is bijvoorbeeld afhankelijk van de Azure.Core bibliotheek en biedt een ContentSafetyClient klasse die zowel protocol- als gemaksmethoden beschikbaar maakt.

Gemaksmethode

De volgende code maakt gebruik van een ContentSafetyClient methode voor het aanroepen van de AnalyzeText gemaksmethode:

C#

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

De voorgaande code demonstreert de volgende Azure.Core gemaksmethodepatronen:

• Maakt gebruik van een standaard C#-primitieve of modeltype als parameter.
• Retourneert een vriendelijk C#-type dat het resultaat van de bewerking aangeeft.

Protocolmethode

De volgende code gebruikt een ContentSafetyClient om de AnalyzeText protocolmethode aan te roepen:

C#

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

De voorgaande code demonstreert de volgende Azure.Core protocolmethodepatronen:

1. Maak de aanvraag met behulp van een RequestContent object voor de aanvraagbody.
2. Roep de protocolmethode aan met behulp van een RequestContext object om aanvraagopties te configureren.
3. Het antwoord verwerken door het volgende te lezen:
   • De HTTP-statuscode van het object om te bepalen of het Response is gelukt of mislukt.
   • Gegevens van de inhoud van het Response object in een dynamisch type met behulp van ToDynamicFromJson. Zie Aankondiging van dynamische JSON in de Azure Core-bibliotheek voor .NET voor meer informatie.

Notitie

De voorgaande code configureert het gedrag ErrorOptions.NoThrow . Met deze optie voorkomt u dat statuscodes voor niet-geslaagde serviceantwoorden een uitzondering genereren. Dit betekent dat de app-code de controles van de antwoordstatuscode handmatig moet afhandelen.

Bibliotheken die afhankelijk zijn van System.ClientModel

Sommige clientbibliotheken die verbinding maken met niet-Azure-services gebruiken patronen die vergelijkbaar zijn met de bibliotheken die afhankelijk Azure.Corezijn van. De bibliotheek biedt bijvoorbeeld OpenAI een client die verbinding maakt met de OpenAI-services. Deze bibliotheken zijn gebaseerd op een bibliotheek System.ClientModel die patronen bevat die vergelijkbaar zijn met Azure.Core.

Gemaksmethode

Houd rekening met de volgende code die gebruikmaakt van een ChatClient methode voor het aanroepen van de CompleteChat gemaksmethode:

C#

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

De voorgaande code demonstreert de volgende System.ClientModel gemaksmethodepatronen:

• Maakt gebruik van een standaard C#-primitieve of modeltype als parameter.
• Retourneert een ClientResult type dat het resultaat van de bewerking aangeeft.

Protocolmethode

De volgende code gebruikt een ChatClient om de CompleteChat protocolmethode aan te roepen:

C#

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

De voorgaande code demonstreert de volgende System.ClientModel protocolmethodepatronen:

1. Maak de aanvraag met behulp van een BinaryContent object voor de aanvraagbody.
2. Roep de protocolmethode aan met behulp van een RequestOptions object om aanvraagopties te configureren.
3. Het antwoord verwerken door het volgende te lezen:
   • De HTTP-statuscode van het object om te bepalen of het PipelineResponse is gelukt of mislukt.
   • Gegevens uit de inhoud van het PipelineResponse object met behulp van System.Text.Json API's.

Notitie

De voorgaande code configureert het gedrag ClientErrorBehaviors.NoThrow voor de RequestOptions. Met deze optie voorkomt u dat statuscodes voor niet-geslaagde serviceantwoorden een uitzondering genereren. Dit betekent dat de app-code de controles van de antwoordstatuscode handmatig moet afhandelen.

Een System.ClientModelantwoord op basis van een antwoord kan worden verwerkt als een gemaksmodel, als u afhankelijk bent Azure.Corevan . De volgende diff toont deze alternatieve benadering, die volgt op dezelfde benadering die wordt weergegeven op het tabblad Protocolmethode van bibliotheken die afhankelijk zijn van Azure.Core.

diff

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

Uitzonderingen verwerken

Wanneer een serviceaanroep mislukt, genereert de serviceclient een uitzondering die de HTTP-statuscode en de details van het serviceantwoord weergeeft, indien beschikbaar. Een System.ClientModel-afhankelijke bibliotheek genereert een ClientResultException, terwijl een Azure.Coreafhankelijke bibliotheek een RequestFailedException.

System.ClientModel-uitzonderingen

C#

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

Azure.Core-uitzonderingen

C#

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

Richtlijnen voor protocol- en gemaksmethodegebruik

Hoewel de Azure SDK voor .NET-clientbibliotheken de mogelijkheid bieden om protocol- of gemaksmethoden te gebruiken, kunt u prioriteit geven aan het gebruik van gemaksmethoden in de meeste scenario's. Gemaksmethoden zijn ontworpen om de ontwikkelervaring te verbeteren en flexibiliteit te bieden voor het ontwerpen van aanvragen en het verwerken van reacties. Beide methodetypen kunnen echter indien nodig in uw app worden gebruikt. Houd rekening met de volgende criteria bij het bepalen welk type methode u wilt gebruiken.

Handige methoden:

• Hiermee kunt u werken met meer beschrijvende methodeparameter- en antwoordtypen.
• Verschillende problemen en optimalisaties op laag niveau voor u afhandelen.

Protocolmethoden:

• Toegang bieden tot typen op lager niveau, zoals RequestContext en RequestOptions, die niet beschikbaar zijn via gemaksmethoden.
• Toegang tot functies van de onderliggende REST API's inschakelen die niet beschikbaar zijn voor gemaksmethoden.
• U kunt uw eigen gemaksmethoden maken rond service-eindpunten die nog geen handige methoden hebben. Voor deze aanpak moet u de REST API-documentatie van de service begrijpen om aanvragen en antwoorden correct te verwerken.

Zie ook

Informatie over de Azure Core-bibliotheek voor .NET