Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
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/messagese/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:
- Crie seu servidor com suas próprias rotas e middleware.
- Envolva-o em um adaptador.
- 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 comUseTeamsBotApplication(). - 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.