【ITニュース解説】Build an Aspire API Using Microsoft OpenAI, Scalar, OpenRouter, Structured Output, and Custom Headers

AspireというMicrosoftが提供する新しいフレームワークを活用し、AI機能を組み込んだAPIを効率的に構築する方法について解説する。システムエンジニアを目指す初心者でも、最新の技術トレンドを理解し、実際にAIを利用したアプリケーション開発に取り組むきっかけとなるだろう。

まず、Aspireとは、クラウドネイティブなアプリケーション開発を支援するためにMicrosoftが開発したフレームワークである。分散システムにおける複数のサービス間の連携やデプロイを容易にし、開発者がアプリケーションの構築に集中できる環境を提供する。この記事では、Aspireソリューションを新しく作成し、その中にAI機能とAPIドキュメントツールを導入する手順を追う。

最初のステップとして、アプリケーションのAPIサービスを担うプロジェクトにAI機能のためのパッケージをインストールする。「Microsoft.Extensions.AI.OpenAI」は、OpenAI互換のAIサービスと連携するための基盤を提供し、「Microsoft.Extensions.AI」は、AIとのより高度なインタラクション、例えばAIからの応答を特定のデータ構造にマッピングする「構造化出力」といった機能を提供する。これらをインストールすることで、AIの力をアプリケーションに組み込む準備が整う。

次に、APIの仕様を分かりやすく表示するためのドキュメントツールを導入する。APIを開発する際、その機能や使い方を記述した仕様書（OpenAPIドキュメントとも呼ばれる）は非常に重要だ。Microsoftは、OpenAPI形式のドキュメントを自動生成する機能を提供しているが、その情報を視覚的に表示するユーザーインターフェースは別途用意する必要がある。ここで「Scalar」が登場する。Scalarは、APIドキュメントを美しく、かつ分かりやすく表示するためのオープンソースのツールであり、Aspireプロジェクトに簡単に組み込むことができる。「Scalar.Aspire」パッケージを、アプリケーション全体の起動を管理する「AppHost」プロジェクトにインストールし、基本的な設定を行うことで、開発中のAPIの設計書をウェブブラウザ上で確認できるようになる。

Scalarを導入する上で特に注目すべきは、その組み込みプロキシ機能である。ウェブアプリケーションが異なるドメインにあるAPIを呼び出す場合、ウェブブラウザのセキュリティ機能により「CORS（Cross-Origin Resource Sharing）」という問題が発生し、通信がブロックされることがある。しかし、Scalar for Aspireにはデフォルトでプロキシ機能が組み込まれており、これによりCORS問題を気にすることなく、開発中のAPIにアクセスし、ドキュメントを閲覧できる。このプロキシは、Microsoftが提供する高性能なリバースプロキシ「YARP（Yet Another Reverse Proxy）」を内部で利用している。

APIの基盤とドキュメント環境が整ったら、いよいよAI機能をアプリケーションに組み込む。この記事では、AIサービスとして「OpenRouter」を利用する。OpenRouterは、Groq、Gemini、Claudeなど、様々な大規模言語モデル（LLM）を単一のインターフェースを通じて利用できる便利なゲートウェイサービスだ。開発者はOpenRouterでアカウントを作成し、APIキーを取得するだけで、複数のAIモデルを切り替えて試すことができる。これにより、各AIサービスごとにアカウントを作成したり、複数のAPIキーを管理したりする手間が省け、開発効率が向上する。

取得したAPIキーは、アプリケーションのコードに直接書き込むのではなく、「ユーザーシークレット」という安全な方法で管理する。これは、APIキーなどの機密情報が公開リポジトリなどに誤って含まれるリスクを防ぐための重要なセキュリティ対策である。

アプリケーションでOpenRouterを利用するためには、AIチャットクライアントを設定する必要がある。Microsoft.Extensions.AIライブラリに含まれる「IChatClient」インターフェースを通じて、AIモデルとの対話を行う。この際、必要に応じてHTTPリクエストにカスタムヘッダーを追加する設定も可能だ。例えば、OpenRouterに対して、API呼び出し元のサイトURLやタイトルをHTTPヘッダーとして伝えることで、OpenRouter側での統計情報やランキングに役立てられることがある。このようなカスタムヘッダーの追加は、標準的なHTTP処理メカニズムである「DelegatingHandler」を利用して実装される。

最終的に、このAIチャットクライアントを使って、既存のAPIエンドポイントをAIが生成するデータに置き換える。具体的な例として、天気予報を提供する「/weatherforecast」エンドポイントをAIが生成するデータで更新する。このエンドポイントは、指定された日付に対して、OpenRouterのAIモデルに、その日の天気データ（気温や天気の状態）を生成するよう指示する。AIに対して、「摂氏温度と、他の惑星や宇宙でしか存在しないようなユーモアあふれる奇妙な天気の状態を生成してほしい」といった具体的なプロンプト（指示文）を与える。

ここで特に重要なのが「構造化出力」という機能だ。AIモデルに特定の形式で情報を生成させることで、AIからの応答をC#のクラス（例えば「WeatherData」というクラス）に直接マッピングできるようになる。これにより、AIが生成した自由形式のテキストから必要な情報を手動で解析する手間が省け、コードがより簡潔で堅牢になる。AIは、与えられたプロンプトと、期待される出力の構造を理解し、その定義されたC#オブジェクトの構造に合わせて内容を生成する。

これらの手順を通じて、Aspireフレームワーク上で、Scalarによる優れたAPIドキュメント表示機能を持ち、OpenRouterを介して多様なAIモデルを柔軟に利用し、さらにAIからの応答を構造化されたC#オブジェクトとして効率的に受け取れる、モダンで強力なAPIを構築できる。システムエンジニアを目指す初心者にとって、このような実践的な経験は、最新のIT技術の理解を深め、自身の開発スキルを向上させる上で非常に価値のあるものとなるだろう。