Hospedar conteúdo da Web e gerenciar o servidor HTTP do seu agente

Um agente do SDK do Teams é um servidor HTTP. Por padrão, o SDK cria esse servidor para você, registra o /api/messages ponto de extremidade e gerencia seu ciclo de vida. Você pode ir mais longe e usar o mesmo servidor para hospedar conteúdo da web ou assumir o controle do servidor completamente.

Hospedar conteúdo da Web estático

A App classe pode hospedar um aplicativo Web ao lado de seu agente. Isso proporciona um loop interno eficiente, pois você pode criar, implantar e fazer sideload de um agente e de um aplicativo de guia em uma única etapa. Também é útil na produção para experiências simples, como uma página de configuração de agente ou uma caixa de diálogo.

Hospede uma pasta que contenha um index.html arquivo; use o auxiliar de guia do SDK em TypeScript e Python ou o middleware de arquivo estático do ASP.NET Core em C#.

No SDK 2.1, use o middleware de arquivo estático do ASP.NET Core para fornecer arquivos do diretório de build da Web na rota da guia:

using Microsoft.Extensions.FileProviders;

string tabDirectory = Path.Combine(Directory.GetCurrentDirectory(), "Web", "bin");
app.UseStaticFiles(new StaticFileOptions
{
  FileProvider = new PhysicalFileProvider(tabDirectory),
  RequestPath = "/tabs/myApp"
});

app.MapGet("/tabs/myApp", () =>
{
  return Results.File(Path.Combine(tabDirectory, "index.html"), "text/html");
});

Crie o Web/bin diretório e o respectivo index.html antes de iniciar o servidor. O middleware de arquivo estático serve apenas arquivos dentro desse diretório; não crie um caminho de arquivo diretamente de um segmento de URL não confiável. A rota é hospedada durante o http://localhost:PORT/tabs/myApp desenvolvimento local e imediatamente https://BOT_DOMAIN/tabs/myApp implantada.

import path from 'path';

app.tab('myApp', path.resolve('dist/client'));

Isso registra uma rota hospedada durante http://localhost:PORT/tabs/myApp o desenvolvimento local e imediatamente https://BOT_DOMAIN/tabs/myApp implantada.

import os

app.tab("my_app", os.path.abspath("dist/client"))

Isso registra uma rota hospedada durante http://localhost:PORT/tabs/my_app o desenvolvimento local e imediatamente https://BOT_DOMAIN/tabs/my_app implantada.

Adicione o domínio do host à matriz no manifesto validDomains do aplicativo e faça referência à rota da definição da guia, da mesma forma que faria com uma guia hospedada em qualquer outro lugar. Para obter mais informações, consulte Guias Criar para o Teams.

Gerenciar o servidor HTTP por conta própria

No TypeScript e no Python, a chamada app.start() cria um servidor HTTP e gerencia seu ciclo de vida. Em C#, o ASP.NET Core é proprietário do servidor e você chama webApp.Run(). Controle o servidor por conta própria quando precisar:

  • Adicione suporte do Teams a um aplicativo que já tenha seu próprio servidor e rotas.
  • Configuração do servidor de controle, como TLS, processos de trabalho ou middleware de estrutura.
  • Use uma estrutura HTTP diferente do padrão interno do SDK.

TypeScript e Python suportam adaptadores de servidor HTTP personalizados; O C# usa o ASP.NET Core diretamente.

Como funciona

No TypeScript e no Python, o SDK divide o tratamento de HTTP em duas camadas:

  • O servidor HTTP lida com questões de protocolo do Teams: autenticação JSON Web Token (JWT), análise de atividade e roteamento para seus manipuladores.
  • O adaptador do servidor HTTP lida com questões de estrutura: traduzindo entre o modelo de solicitação e resposta da estrutura HTTP e o padrão de manipulador do SDK.

Uma solicitação de entrada do Teams passa pelo adaptador, para o servidor HTTP para autenticação e análise e, em seguida, para seus manipuladores. A resposta viaja de volta pelo mesmo caminho.

O SDK é hospedado pelo ASP.NET Core, portanto, você já possui o WebApplication e seu ciclo de vida. Registre o agente com injeção de dependência, mapeie seus pontos de extremidade para o seu próprio WebApplicatione execute o aplicativo você mesmo.

O SDK usa o Express como sua estrutura HTTP interna. A interface do adaptador é pequena:

interface IHttpServerAdapter {
  registerRoute(method: HttpMethod, path: string, handler: HttpRouteHandler): void;
  serveStatic?(path: string, directory: string): void;
  start?(port: number): Promise<void>;
  stop?(): Promise<void>;
}

type HttpRouteHandler = (request: { body: unknown; headers: Record<string, string | string[]> })
  => Promise<{ status: number; body?: unknown }>;

O SDK usa o FastAPI como sua estrutura HTTP interna. A interface do adaptador é pequena:

class HttpServerAdapter(Protocol):
    def register_route(self, method: HttpMethod, path: str, handler: HttpRouteHandler) -> None: ...
    def serve_static(self, path: str, directory: str) -> None: ...
    async def start(self, port: int) -> None: ...
    async def stop(self) -> None: ...

class HttpRouteHandler(Protocol):
    async def __call__(self, request: HttpRequest) -> HttpResponse: ...

Para um adaptador personalizado TypeScript ou Python, somente o registro de rota é necessário:

  • A rota de registro é necessária. O SDK registra rotas dinamicamente, como /api/messages e /api/functions/{name}.
  • Servir estático é opcional. Ele será necessário somente se você veicular guias ou páginas estáticas.
  • Iniciar e parar são opcionais. Omita-as quando você mesmo gerencia o ciclo de vida do servidor.

Adicionar o Teams a um servidor existente

Para adicionar o Teams a um servidor que você já possui:

  1. Crie seu servidor com suas próprias rotas e middleware.
  2. Envolva-o em um adaptador.
  3. Em TypeScript ou Python, chame o método do initialize() aplicativo para registrar rotas do Teams. Em C#, registre o Teams em seu aplicativo ASP.NET Core com UseTeamsBotApplication().
  4. Inicie o servidor por conta própria.
using Microsoft.Teams.Apps;

WebApplicationBuilder builder = WebApplication.CreateBuilder(args);

// 1. Register the agent alongside your own services.
builder.Services.AddTeamsBotApplication();

WebApplication webApp = builder.Build();

// 2. Map the Teams endpoints onto your own WebApplication.
TeamsBotApplication teams = webApp.UseTeamsBotApplication();

teams.OnMessage(async (context, cancellationToken) =>
{
  await context.SendAsync($"Echo: {context.Activity.Text}", cancellationToken);
});

// 3. Add your own routes and middleware.
webApp.MapGet("/health", () => Results.Json(new { status = "healthy" }));

// 4. Run the server yourself.
webApp.Run();
import express from 'express';
import http from 'http';
import { App, ExpressAdapter } from '@microsoft/teams.apps';

// 1. Create your Express app with your own routes.
const expressApp = express();
const httpServer = http.createServer(expressApp);

expressApp.get('/health', (_req, res) => {
  res.json({ status: 'healthy' });
});

// 2. Wrap it in the ExpressAdapter.
const adapter = new ExpressAdapter(httpServer);

// 3. Create the Teams app with the adapter.
const app = new App({ httpServerAdapter: adapter });

app.on('message', async ({ send, activity }) => {
  await send(`Echo: ${activity.text}`);
});

// 4. Initialize. This registers /api/messages on your Express app, but doesn't start a server.
await app.initialize();

// 5. Start the server yourself.
httpServer.listen(3978, () => console.log('Server ready on http://localhost:3978'));

Observação

app.initialize() executa o gancho de onInit cada plug-in, mas não seu onStart gancho. onStart Apenas é acionado de app.start(). Se você usar um plugin que faz sua configuração em onStart, chame app.start() e deixe que ele gerencie o servidor ou invoque você mesmo esse plugin onStart após app.initialize():

await app.initialize();
await myPlugin.onStart({ port: 3978 });
import asyncio

import uvicorn
from fastapi import FastAPI
from microsoft_teams.apps import App, FastAPIAdapter

# 1. Create your FastAPI app with your own routes.
my_fastapi = FastAPI(title="My App + Teams agent")

@my_fastapi.get("/health")
async def health():
    return {"status": "healthy"}

# 2. Wrap it in the FastAPIAdapter.
adapter = FastAPIAdapter(app=my_fastapi)

# 3. Create the Teams app with the adapter.
app = App(http_server_adapter=adapter)

@app.on_message
async def handle_message(ctx):
    await ctx.send(f"Echo: {ctx.activity.text}")

async def main():
    # 4. Initialize. This registers /api/messages on your FastAPI app, but doesn't start a server.
    await app.initialize()

    # 5. Start the server yourself.
    config = uvicorn.Config(app=my_fastapi, host="0.0.0.0", port=3978)
    server = uvicorn.Server(config)
    await server.serve()

asyncio.run(main())

Usar uma estrutura diferente

O SDK do C# é hospedado pelo ASP.NET Core e não fornece um adaptador de estrutura HTTP conectável. Para hospedar o agente em uma pilha diferente, coloque um aplicativo ASP.NET Core na frente dele ou encaminhe solicitações para o /api/messages ponto de extremidade que UseTeamsBotApplication() se registra.

Para usar uma estrutura diferente do padrão interno, implemente a interface do adaptador para essa estrutura. A maior parte do trabalho está no registro de rota: traduza a solicitação de entrada em um par de corpo e cabeçalhos, chame o manipulador e escreva a resposta de volta.

Como você mesmo gerencia o ciclo de vida do servidor, não precisa dos métodos iniciar e parar. Implemente o método estático de servidor somente se você servir guias ou páginas estáticas.

O seguinte adaptador Restify implementa apenas o registro de rota:

import assert from 'node:assert/strict';
import restify from 'restify';
import { HttpMethod, IHttpServerAdapter, HttpRouteHandler } from '@microsoft/teams.apps';

class RestifyAdapter implements IHttpServerAdapter {
  constructor(private server: restify.Server) {
    this.server.use(restify.plugins.bodyParser());
  }

  registerRoute(method: HttpMethod, path: string, handler: HttpRouteHandler): void {
    // Teams sends only POST requests to your agent endpoint.
    assert(method === 'POST', `Unsupported method: ${method}`);
    this.server.post(path, async (req: restify.Request, res: restify.Response) => {
      const response = await handler({
        body: req.body,
        headers: req.headers as Record<string, string | string[]>,
      });
      res.send(response.status, response.body);
    });
  }
}

Para usá-lo:

const server = restify.createServer();
const adapter = new RestifyAdapter(server);
const app = new App({ httpServerAdapter: adapter });
await app.initialize();
server.listen(3978);

Para usar uma estrutura diferente do padrão interno, implemente o protocolo do adaptador para essa estrutura. A maior parte do trabalho está em register_route: traduza a solicitação recebida em um HttpRequest, chame o manipulador e escreva o HttpResponse retorno.

Como você mesmo gerencia o ciclo de vida do servidor, não precisa do start e stop. Implemente serve_static somente se você servir guias ou páginas estáticas.

O seguinte adaptador Starlette implementa apenas register_route:

from starlette.applications import Starlette
from starlette.requests import Request
from starlette.responses import JSONResponse, Response
from starlette.routing import Route
from microsoft_teams.apps.http.adapter import HttpMethod, HttpRequest, HttpResponse, HttpRouteHandler

class StarletteAdapter:
    def __init__(self, app: Starlette):
        self._app = app

    def register_route(self, method: HttpMethod, path: str, handler: HttpRouteHandler) -> None:
        # Teams sends only POST requests to your agent endpoint.
        async def starlette_handler(request: Request) -> Response:
            body = await request.json()
            headers = dict(request.headers)
            result: HttpResponse = await handler(HttpRequest(body=body, headers=headers))
            if result.get("body") is not None:
                return JSONResponse(content=result["body"], status_code=result["status"])
            return Response(status_code=result["status"])

        route = Route(path, starlette_handler, methods=[method])
        self._app.routes.insert(0, route)

Para usá-lo:

starlette_app = Starlette()
adapter = StarletteAdapter(starlette_app)
app = App(http_server_adapter=adapter)
await app.initialize()
# Start Starlette with uvicorn yourself.

Confira também