適用於 .NET 的 Azure SDK 通訊協定和便利方法概觀

Azure SDK 用戶端程式庫會藉由將方法呼叫轉譯為透過個別服務通訊協定傳送的訊息，來提供 Azure 服務的介面。 對 REST API 服務而言，這表示傳送 HTTP 要求並將回應轉換成執行階段類型。 在本文中，您會了解用戶端程式庫所公開的不同方法類型，並探索其實作模式。

了解通訊協定和便利方法

適用於 .NET 的 Azure SDK 用戶端程式庫可以公開兩種不同的方法類別，以向 Azure 服務提出要求：

• 通訊協定方法會針對對應的 Azure 服務的基礎 REST API 提供精簡包裝函式。 這些方法會將基本輸入參數對應至 HTTP 要求值，並傳回原始 HTTP 回應物件。
• 便利方法會在較低層級通訊協定層上方提供便利層，以新增對 .NET 類型系統和其他權益的支援。 便利方法會接受基本類型或 .NET 模型類型作為參數，並將其對應至基礎 REST API 要求的主體。 這些方法也會處理要求和回應管理的各種詳細資料，讓開發人員可專注於傳送和接收資料物件，而不用顧慮較低層級。

Azure SDK 用戶端程式庫相依性模式

通訊協定和便利方法會根據個別程式庫的基礎套件相依性鏈結，實作稍微不同的模式。 適用於 .NET 的 Azure SDK 用戶端程式庫會相依於兩個不同基礎程式庫的其中一個：

• Azure.Core 會提供共用的基本類型、抽象概念和協助程式，以建置新式的 Azure SDK 用戶端程式庫。 這些程式庫會遵循適用於 .NET 的 Azure SDK 設計指引，並使用以 Azure 為前置詞的套件名稱和命名空間，例如 Azure.Storage.Blobs。
• System.ClientModel 是核心程式庫，可為 .NET 服務用戶端程式庫提供共用基本類型、抽象概念和協助程式。 System.ClientModel 程式庫是一個通用工具集，旨在協助建置各種平台和服務的程式庫，而 Azure.Core 庫是專門為建置 Azure 用戶端程式庫而設計的。

注意

Azure.Core 程式庫本身也相依於各種用戶端建置組塊的 System.ClientModel。 在本文中，方法模式的主要區別在於用戶端程式庫是否直接相依於 Azure.Core 或 System.ClientModel，而不是透過可轉移的相依性。

以下資料表根據該資料庫是否依賴於 Azure.Core 或 System.ClientModel 來比較通訊協定和便捷方法使用的一些請求和回應類型。

要求或回應顧慮	Azure.Core	System.ClientModel
要求本文	RequestContent	BinaryContent
進階要求選項	RequestContext	RequestOptions
原始 HTTP 回應	Response	PipelineResponse
傳回具有輸出模型的型別	Response<T>	ClientResult<T>

前面各節提供這些概念的實作範例。

通訊協定和便利方法範例

用戶端程式庫通訊協定所使用的程式碼模式與型別和便利方法會根據程式庫是否相依於 Azure.Core 或 System.ClientModel 而稍有不同。 差異主要會影響用於處理要求和回應資料的 .NET 類型。

相依於 Azure.Core 的程式庫

遵守最新設計指引的 Azure SDK 用戶端程式庫會依存於 Azure.Core 程式庫。 例如，程式庫相依於 Azure.AI.ContentSafety 程式庫和 Azure.Core 並提供公開通訊協定和便利方法的 ContentSafetyClient 類別。

便利方法

下列程式碼會使用 ContentSafetyClient 來呼叫 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}");
}

上述程式碼會示範下列 Azure.Core 便利方法模式：

• 使用標準 C# 基本類型或模型類型作為參數。
• 傳回表示作業結果的易記 C# 型別。

通訊協定方法

下列程式碼會使用 ContentSafetyClient 來呼叫 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}");
}

上述程式碼會示範下列 Azure.Core 通訊協定方法模式：

1. 建立請求，使用 RequestContent 物件作為要求本文。
2. 叫用通訊協定方法，使用 RequestContext 物件來設定要求選項。
3. 透過閱讀以下內容來處理回應：
   • 從 Response 物件的 HTTP 狀態碼來確定成功或失敗。
   • 使用 ToDynamicFromJson 將資料從 Response 物件的內容轉換為動態類型。 如需詳細資訊，請參閱 在適用於 .NET 的 Azure Core 資料庫中宣佈動態 JSON。

注意

先前的程式碼會設定 ErrorOptions.NoThrow 行為。 此選項可防止非成功服務回應狀態代碼擲回例外狀況，這表示應用程式程式碼應該手動處理回應狀態代碼檢查。

相依於 System.ClientModel 的程式庫

連線到非 Azure 服務的一些用戶端程式庫會使用和相依於 Azure.Core 的程式庫類似的模式。 例如，OpenAI 程式庫會提供連線至 OpenAI 服務的用戶端。 這些程式庫是以名為 System.ClientModel 的程式庫為基礎，其模式類似 Azure.Core。

便利方法

請考慮使用 ChatClient 來呼叫 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}");

上述程式碼會示範下列 System.ClientModel 便利方法模式：

• 使用標準 C# 基本類型或模型類型作為參數。
• 傳回表示作業結果的 ClientResult 型別。

通訊協定方法

下列程式碼會使用 ChatClient 來呼叫 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)}");

上述程式碼會示範下列 System.ClientModel 通訊協定方法模式：

1. 建立請求，使用 BinaryContent 物件作為要求本文。
2. 叫用通訊協定方法，使用 RequestOptions 物件來設定要求選項。
3. 透過閱讀以下內容來處理回應：
   • 從 PipelineResponse 物件的 HTTP 狀態碼來確定成功或失敗。
   • 使用 System.Text.Json API 來自 PipelineResponse 物件內容的資料。

注意

上述程式碼會設定 RequestOptions 的 ClientErrorBehaviors.NoThrow 行為。 此選項可防止非成功服務回應狀態代碼擲回例外狀況，這表示應用程式程式碼應該手動處理回應狀態代碼檢查。

如果您相依於 Azure.Core，則可以像便利模型一樣處理以 System.ClientModel 為基礎的回應。 下列差異顯示這個替代方法，其遵循相依於 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}");

處理例外狀況

當服務呼叫失敗時，服務用戶端會擲回例外狀況，以公開 HTTP 狀態碼和服務回應的詳細資訊 (如果有的話)。 System.ClientModel 相依的函式庫會擲回 ClientResultException，而 Azure.Core 相依的函式庫會擲回 RequestFailedException。

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

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

通訊協定和便利方法使用指引

雖然適用於 .NET 的 Azure SDK 用戶端程式庫會提供使用通訊協定或便利方法的選項，但在大部分情況下，請優先使用便利方法。 便利方法旨在提升開發體驗，並提供撰寫要求和處理回應的彈性。 不過，這兩種方法類型都可以視需要用於您的應用程式。 在決定使用哪種類型的方法時，請考慮以下準則。

便利方法：

• 讓您可使用更易記的方法參數和回應類型。
• 為您處理各種低層級顧慮和最佳化。

通訊協定方法：

• 提供對較低層級類型的存取權，例如 RequestContext 和 RequestOptions，這些類型無法透過便利方法取得。
• 啟用存取便利方法不會公開的基礎 REST API 功能。
• 讓您能夠針對還不具有便利方法的服務端點建立自己的便利方法。 此方法需要了解服務的 REST API 文件，才能正確處理要求和回應。

另請參閱

了解適用於 .NET 的 Azure 核心程式庫