メッセージ拡張機能を作成する

5 分

このユニットでは、メッセージ拡張機能を作成する方法について説明します。また、Teams Toolkit を使用して、Microsoft Teamsでメッセージ拡張機能を実行してデバッグする方法についても説明します。

メッセージ拡張機能を作成するには、次のコンポーネントが必要です。

Bot Framework に Web サービスをボットとして登録するための Azure Bot リソース
メッセージ拡張機能を使用したユーザー操作を処理する Web サービス
Microsoft Teamsでメッセージ拡張機能を定義するアプリマニフェスト

Azure Bot リソースを構成する

Azure Bot リソースは、Web サービスを Bot Framework にボットとして登録するために使用されます。 Azure Bot リソースを作成するには、Microsoft Entra アプリの登録が必要です。アプリの登録により、ボットを認証および承認するための安全な方法が提供されます。 Web サービスは、Microsoft Entra アプリ登録資格情報を使用して、ボットサービスで認証します。

次のコードスニペットは、Bicep を使用して Azure Bot リソースを作成する方法を示しています。

resource botService 'Microsoft.BotService/botServices@2021-03-01' = {
  kind: 'azurebot'
  location: 'global'
  name: 'botService'
  properties: {
    displayName: 'Bot Service'
    endpoint: 'https://webservice.contoso.com/api/messages'
    msaAppId: '00000000-0000-0000-0000-000000000000'
  }
  sku: {
    name: botServiceSku
  }
}

endpoint プロパティは、ユーザーがメッセージ拡張機能と対話するときにボットサービスが要求を送信するために使用する Web サービスで公開されるメッセージングエンドポイントを指定します。 msaAppId プロパティは、Web サービスでボットサービスを認証するために使用されるMicrosoft Entraアプリ登録 ID を指定します。

チャネルは、ボットサービスを、Microsoft Teams、Slack、Facebook Messenger などのメッセージングプラットフォームに接続するために使用されます。

次のコードスニペットは、Azure Bot リソースでMicrosoft Teamsと Microsoft 365 (Outlook とMicrosoft 365 Copilot) チャネルを構成する方法を示しています。

resource botServiceMsTeamsChannel 'Microsoft.BotService/botServices/channels@2021-03-01' = {
  parent: botService
  location: 'global'
  name: 'MsTeamsChannel'
  properties: {
    channelName: 'MsTeamsChannel'
  }
}

resource botServiceM365ExtensionsChannel 'Microsoft.BotService/botServices/channels@2022-06-15-preview' = {
  parent: botService
  location: 'global'
  name: 'M365Extensions'
  properties: {
    channelName: 'M365Extensions'
  }
}

Web サービスを構成する

Web サービスは、メッセージ拡張コードを含む Web アプリです。 Web サービスは、メッセージ拡張機能とのユーザー操作を処理する役割を担い、Bot Framework SDK を使用してボットサービスと通信します。

ユーザー操作を処理するには、次を実装します。

メッセージングエンドポイント
ボットアダプター
ボットアクティビティハンドラー

メッセージングエンドポイントは、ボットサービスから要求を受信するために使用されます。メッセージングエンドポイントは Web サービスで公開され、処理のために Bot Adapter に要求を渡します。

次のコードスニペットは、メッセージングエンドポイントを構成する方法を示しています。

// Create HTTP server.
const server = restify.createServer();
server.use(restify.plugins.bodyParser());
server.listen(process.env.port || process.env.PORT || 3978, () => {
  console.log(`\nBot Started, ${server.name} listening to ${server.url}`);
});

// Listen for incoming requests.
server.post("/api/messages", async (req, res) => {
  await adapter.process(req, res, async (context) => {
    await searchApp.run(context);
  });
});

ボットアダプターは、ボットサービスを Web サービスに接続するために使用されます。 Bot Adapter は、ボットサービスからの受信要求を処理し、ボットアクティビティハンドラーを呼び出す役割を担います。 Web サービスは、Azure Bot リソースを Bot Framework に登録するために使用されるMicrosoft Entra アプリ登録資格情報を使用して、ボットサービスで認証します。

次のコードスニペットは、Web サービスで Bot Adapter を構成する方法を示しています。

const credentialsFactory = new ConfigurationServiceClientCredentialFactory(config);

const botFrameworkAuthentication = new ConfigurationBotFrameworkAuthentication(
  {},
  credentialsFactory
);

const adapter = new CloudAdapter(botFrameworkAuthentication);

ユーザー検索クエリを処理して検索結果を返すには、Bot Framework SDK によって提供される TeamsActivityHandler クラスを継承し、 handleTeamsMessagingExtensionQuery メソッドをオーバーライドする Bot Activity Handler を実装します。

次のコードスニペットは、Web サービスで Bot Activity Handler を構成する方法を示しています。

export class SearchApp extends TeamsActivityHandler {

  public async handleTeamsMessagingExtensionQuery(
    context: TurnContext,
    query: MessagingExtensionQuery
  ): Promise<MessagingExtensionResponse> {

    const text = query.parameters[0]?.value as string ?? "";
    var template = new ACData.Template(card);

    return {
      composeExtension: {
        type: 'result',
        attachmentLayout: AttachmentLayoutTypes.List,
        attachments: [
          {
            contentType: 'application/vnd.microsoft.card.adaptive',
            content: template.expand({ $root: { text } }),
            preview: CardFactory.thumbnailCard(text)
          },
        ],
      },
    };
  }
}

検索コマンドの構成

アプリマニフェストは、アプリのメタデータと構成を定義する JSON ファイルです。アプリが提供する機能 (メッセージ拡張機能など) を定義します。アプリマニフェストは、アプリパッケージに含まれています。アプリパッケージは、アプリをインストールするためにMicrosoft Teamsにアップロードする ZIP ファイルです。

次のコードスニペットは、アプリマニフェストで検索コマンドを定義する方法を示しています。

"composeExtensions": [
  {
    "botId": "4cc3ac43-d581-403d-8bbf-ff9c0fbf3fb2",
    "commands": [
      {
        "id": "Search",
        "context": [
          "compose",
          "commandBox"
        ],
        "description": "Find products by name or by target audience",
        "title": "Products",
        "type": "query",
        "parameters": [
          {
            "name": "ProductName",
            "title": "Product name",
            "description": "The name of the product as a keyword",
            "inputType": "text"
          }
        ]
      }
    ]
  }
]

コマンドには、1 つ以上のパラメーターを含めることができます。パラメーターは、ユーザーインターフェイスに表示されるフィールドです。この例では、コマンドに ProductName という名前の 1 つのパラメーターがあります。パラメーターは、ユーザーが検索する製品の名前を入力するテキストフィールドです。

Visual Studio Code 用 Teams ツールキット

Teams Toolkit for Visual Studio Code は、Microsoft Teams アプリを作成、デバッグ、デプロイするためのツールを提供する拡張機能です。 Teams Toolkit は Visual Studio Code と統合され、開発プロセスを合理化し、Microsoft Teams アプリを構築するためのシームレスなエクスペリエンスを提供します。

Teams Toolkit は、Microsoft Teams アプリをビルドするために必要なファイルと依存関係を含む Node.js プロジェクトをスキャフォールディングします。

Teams Toolkit は、Dev トンネル CLI と統合され、ボットサービスとローカルで実行されている Web サービス間の通信を可能にします。開発トンネルは、ボットサービスが到達できるように、コンピューターを超えて Web サービスを公開します。

フィードバック

このページはお役に立ちましたか?