Azure SDK for .NET プロトコルと便利なメソッドの概要

Azure SDK クライアント ライブラリは、メソッド呼び出しをそれぞれのサービス プロトコルを介して送信されたメッセージに変換することで、Azure サービスへのインターフェイスを提供します。 REST API サービスの場合、これは HTTP 要求を送信し、応答をランタイム型に変換することを意味します。 この記事では、クライアント ライブラリによって公開されるさまざまな種類のメソッドについて説明し、その実装パターンについて説明します。

プロトコルと便利なメソッドを理解する

Azure SDK for .NET クライアント ライブラリでは、Azure サービスに要求を行うために、次の 2 つの異なるカテゴリのメソッドを公開できます。

• プロトコル メソッドは、対応する Azure サービスの基になる REST API のシン ラッパーを提供します。 これらのメソッドは、プリミティブ入力パラメーターを HTTP 要求値にマップし、生の HTTP 応答オブジェクトを返します。
• 便利なメソッドは、.NET 型システムやその他の利点にサポートを追加するために、下位レベルのプロトコル レイヤーの上に便利なレイヤーを提供します。 便利なメソッドは、プリミティブまたは .NET モデル型をパラメーターとして受け入れ、基になる REST API 要求の本文にマップします。 これらのメソッドでは、要求と応答の管理のさまざまな詳細も処理されるため、開発者は下位レベルの懸念事項ではなく、データ オブジェクトの送受信に集中できます。

Azure SDK クライアント ライブラリの依存関係パターン

プロトコルと便利なメソッドは、それぞれのライブラリの基になるパッケージ依存関係チェーンに基づいて、少し異なるパターンを実装します。 Azure SDK for .NET クライアント ライブラリは、次の 2 つの基本ライブラリのいずれかに依存します。

• Azure.Core は、最新の Azure SDK クライアント ライブラリを構築するための共有プリミティブ、抽象化、ヘルパーを提供します。 これらのライブラリは、.NET 向けの Azure SDK デザイン ガイドラインに従い、Azure.Storage.Blobs のように、Azure のプレフィックスが付いたパッケージ名と名前空間を使用します。
• System.ClientModel は、.NET サービス クライアント ライブラリの共有プリミティブ、抽象化、ヘルパーを提供するコア ライブラリです。 System.ClientModel ライブラリは、さまざまなプラットフォームやサービス用のライブラリの構築を支援するために設計された汎用ツールセットです。一方、Azure.Core ライブラリは、Azure クライアント ライブラリの構築に特化して設計されています。

Note

Azure.Core ライブラリ自体も、さまざまなクライアント構成要素の System.ClientModel に依存します。 この記事のコンテキストでは、メソッド パターンの主な差別化要因は、推移的な依存関係ではなく、クライアント ライブラリが Azure.Core または System.ClientModel に直接依存しているかどうかです。

次の表は、ライブラリが Azure.Core または System.ClientModel のどちらに依存しているかに基づいて、プロトコル メソッドと便利なメソッドで使用される要求と応答の種類の一部を比較しています。

要求または応答に関する懸念事項	Azure.Core	System.ClientModel
要求本文	RequestContent	BinaryContent
高度な要求オプション	RequestContext	RequestOptions
Raw 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 オブジェクトのコンテンツから dynamic 型へのデータ。 詳細については、「.NET 用 Azure Core ライブラリでの動的 JSON の送信」を参照してください。

Note

上記のコードでは、ErrorOptions.NoThrow 動作を構成しています。 このオプションは、成功していないサービス応答の状態コードが例外をスローするのを防ぎます。つまり、アプリ コードは応答状態コードのチェックを手動で処理する必要があります。

System.ClientModel に依存するライブラリ

Azure 以外のサービスに接続する一部のクライアント ライブラリでは、Azure.Core に依存するライブラリと同様のパターンが使用されます。 たとえば、OpenAI ライブラリには、OpenAI サービスに接続するクライアントが用意されています。 これらのライブラリは、Azure.Core のようなパターンを持つ System.ClientModel と呼ばれるライブラリに基づいています。

便利なメソッド

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 オブジェクト コンテンツからのデータ。

Note

上記のコードは、RequestOptions の ClientErrorBehaviors.NoThrow ビヘイビアーを構成します。 このオプションは、成功していないサービス応答の状態コードが例外をスローするのを防ぎます。つまり、アプリ コードは応答状態コードのチェックを手動で処理する必要があります。

System.ClientModel ベースの応答は、Azure.Core に依存していると便利なモデルのように処理できます。 次の相違は、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}");
}

プロトコルと便利なメソッドの使用に関するガイダンス

Azure SDK for .NET クライアント ライブラリには、プロトコルまたは便利なメソッドのいずれかを使用するオプションが用意されていますが、ほとんどのシナリオでは便利なメソッドを使用する方が優先されます。 便利なメソッドは、開発エクスペリエンスを向上させ、要求の作成と応答の処理に柔軟性を提供するように設計されています。 ただし、必要に応じて、両方のメソッドの種類をアプリで使用できます。 使用する方法のタイプを決定する際には、次の条件を考慮してください。

便利なメソッド:

• よりわかりやすいメソッド パラメーターと応答の種類を操作できます。
• さまざまな低レベルの懸念事項と最適化を処理します。

プロトコル メソッド:

• 便利なメソッドでは使用できない、RequestContext や RequestOptions などの下位レベルの型へのアクセスを提供します。
• 便利なメソッドが公開しない、基になる REST API の機能へのアクセスを有効にします。
• 便利なメソッドがまだないサービス エンドポイントに関する独自の便利なメソッドを作成できます。 この方法では、要求と応答を正しく処理するために、サービスの REST API ドキュメントを理解する必要があります。

関連項目

.NET 用 Azure Core ライブラリについて