演習 - キーで保護された API と API プラグインを統合する

9 分

Microsoft 365 Copilot用の API プラグインを使用すると、キーで保護された API と統合できます。 API キーをセキュリティで保護するには、Teams コンテナーに登録します。実行時に、Microsoft 365 Copilotはプラグインを実行し、コンテナーから API キーを取得し、それを使用して API を呼び出します。このプロセスに従うことで、API キーはセキュリティで保護され、クライアントに公開されることはありません。

新規プロジェクトを作成する

まず、Microsoft 365 Copilot用の新しい API プラグインを作成します。 Visual Studio Code を開きます。

Visual Studio Code で次の手順を実行します。

アクティビティバー (サイドバー) で、Microsoft 365 Agents Toolkit 拡張機能をアクティブにします。
Microsoft 365 Agents Toolkit 拡張機能パネルで、[新しいアプリの作成] を選択します。
プロジェクトテンプレートの一覧から、[ Copilot エージェント] を選択します。
アプリ機能の一覧から [ 宣言型エージェント] を選択します。
[ プラグインの追加] オプションを選択します。
[ 新しい API で開始] オプションを選択します 。
認証の種類の一覧から、[ API キー (ベアラートークン認証)] を選択します。
プログラミング言語として、[ TypeScript] を選択します。
プロジェクトを格納するフォルダーを選択します。
プロジェクトに da-repairs-key という名前を付けます。

Microsoft 365 Agents Toolkit は、宣言型エージェント、API プラグイン、およびキーで保護された API を含む新しいプロジェクトを作成します。

API キー認証の構成を調べる

続行する前に、生成されたプロジェクトの API キー認証構成を調べます。

API 定義を調べる

最初に、API キー認証が API 定義でどのように定義されているかを確認します。

Visual Studio Code で次の手順を実行します。

appPackage/apiSpecificationFile/repair.yml ファイルを開きます。このファイルには、API の OpenAPI 定義が含まれています。
components.securitySchemes セクションで、apiKey プロパティに注目してください。
```
components:
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
```
プロパティは、承認要求ヘッダーのベアラートークンとして API キーを使用するセキュリティスキームを定義します。
paths./repairs.get.security プロパティを見つけます。 apiKey セキュリティスキームを参照していることに注意してください。
```
[...]
paths:
  /repairs:
    get:
      operationId: listRepairs
      [...]
      security:
        - apiKey: []
[...] 
```

API の実装を調べる

次に、API が各要求で API キーを検証する方法について説明します。

Visual Studio Code で次の手順を実行します。

src/functions/repairs.ts ファイルを開きます。
repairs ハンドラー関数で、承認されていない要求をすべて拒否する次の行を見つけます。
```
if (!isApiKeyValid(req)) {
  // Return 401 Unauthorized response.
  return {
    status: 401,
  };
} 
```
isApiKeyValid 関数は、repairs.ts ファイルにさらに実装されます。
```
function isApiKeyValid(req: HttpRequest): boolean {
  const apiKey = req.headers.get("Authorization")?.replace("Bearer ", "").trim();
  return apiKey === process.env.API_KEY;
}
```
関数は、承認ヘッダーにベアラートークンが含まれているかどうかを確認し、 API_KEY 環境変数で定義されている API キーと比較します。

このコードは、API キーセキュリティの単純な実装を示していますが、API キーセキュリティの実際の動作を示しています。

コンテナータスクの構成を調べる

このプロジェクトでは、Microsoft 365 Agents Toolkit を使用して、API キーをコンテナーに追加します。 Microsoft 365 Agents Toolkit は、プロジェクトの構成で特別なタスクを使用して、コンテナーに API キーを登録します。

Visual Studio Code で次の手順を実行します。

./teampsapp.local.yml ファイルを開きます。
[ プロビジョニング ] セクションで、 apiKey/register タスクを見つけます。
```
# Register API KEY
- uses: apiKey/register
  with:
    # Name of the API Key
    name: apiKey
    # Value of the API Key
    primaryClientSecret: ${{SECRET_API_KEY}}
    # Teams app ID
    appId: ${{TEAMS_APP_ID}}
    # Path to OpenAPI description document
    apiSpecPath: ./appPackage/apiSpecificationFile/repair.yml
  # Write the registration information of API Key into environment file for
  # the specified environment variable(s).
  writeToEnvironmentFile:
    registrationId: APIKEY_REGISTRATION_ID
```
タスクは、env/.env.local.user ファイルに格納されているSECRET_API_KEY プロジェクト変数の値を受け取り、コンテナーに登録します。次に、コンテナーエントリ ID を受け取り、 環境ファイル env/.env.local に書き込みます。このタスクの結果は、 APIKEY_REGISTRATION_ID という名前の環境変数です。 Microsoft 365 Agents Toolkit は、この変数の値を、プラグイン定義を含む appPackages/ai-plugin.json ファイルに書き込みます。実行時に、API プラグインを読み込み、この ID を使用してコンテナーから API キーを取得し、API を安全に呼び出す宣言型エージェント。

ローカル開発用の API キーを構成する

プロジェクトをテストする前に、API の API キーを定義する必要があります。次に、API キーをコンテナーに格納し、API プラグインにコンテナーエントリ ID を記録します。ローカル開発の場合は、API キーをプロジェクトに格納し、Microsoft 365 Agents Toolkit を使用してコンテナーに登録します。

Visual Studio Code で次の手順を実行します。

[ターミナル] ウィンドウを開きます。
コマンドラインで次の手順を実行します。
1. npm installを実行して、プロジェクトの依存関係を復元します。
2. npm run keygen を実行して、新しい API キーを生成します。
3. 生成されたキーをクリップボードにコピーします。
env/.env.local.user ファイルを開きます。
SECRET_API_KEY プロパティを新しく生成された API キーに更新します。更新されたプロパティは次のようになります。
```
SECRET_API_KEY=your_key
```
変更内容を保存します。

プロジェクトをビルドするたびに、Microsoft 365 Agents Toolkit によってコンテナー内の API キーが自動的に更新され、プロジェクトがコンテナーエントリ ID で更新されます。

Microsoft 365 Copilotで API プラグインを使用して宣言型エージェントをテストする

最後の手順では、Microsoft 365 Copilotで API プラグインを使用して宣言型エージェントをテストします。

Visual Studio Code で次の手順を実行します。

アクティビティバーで、 Microsoft 365 Agents Toolkit 拡張機能をアクティブにします。
Microsoft 365 Agents Toolkit 拡張機能パネルの [アカウント] セクションで、Copilot が有効になっている Microsoft 365 テナントにサインインしていることを確認します。
アクティビティバーで、[実行] ビューと [デバッグ] ビューに切り替えます。
構成の一覧 から[Copilot (Edge)] で [デバッグ ] を選択し、再生ボタンを押してデバッグを開始します。

Visual Studio Code では、Microsoft 365 Copilotを使用して新しい Web ブラウザーが開きます。メッセージが表示されたら、Microsoft 365 アカウントを使用してサインインします。