Obter contexto específico do Teams para o seu agente

Um agente pode aceder a dados de contexto adicionais sobre a equipa ou o chat onde está instalado. Estas informações podem ser utilizadas para personalizar respostas e criar fluxos de trabalho mais avançados.

Buscar a lista ou perfil de usuário

O agente pode consultar a lista de membros na equipa ou chat atual e utilizar esses dados para personalizar respostas ou ações de seguimento de destino.

Utilize a API de membros de conversações do SDK do Teams para obter informações da lista.

Para obtenção de membros da conversação:

  • Tamanho mínimo da página: 50
  • Tamanho da página predefinido: 200
  • Tamanho máximo da página: 500

Não utilize a obtenção de membros não paginados em equipas e canais. Para listas grandes, as chamadas não paginadas podem ser incompletas ou limitadas.

Observação

  • A paginação está disponível em conversações de equipa e de canal.
  • A paginação não é suportada em conversações de chat. Nas conversas, a lista completa é devolvida pelo serviço.

O código de exemplo seguinte utiliza a obtenção de membros paginados:

app.OnMessage(async (context, cancellationToken) =>
{
    var membersClient = context.Api.Conversations.Members;
    var allMembers = new List<TeamsChannelAccount>();
    string? continuationToken = null;

    do
    {
        var page = await membersClient.GetPagedAsync(
            context.Conversation.Id,
            pageSize: 50,
            continuationToken: continuationToken,
            cancellationToken: cancellationToken
        );

        allMembers.AddRange(page.Members.Where(m => m is not null).Select(m => m!));
        continuationToken = page.ContinuationToken;
    }
    while (!string.IsNullOrEmpty(continuationToken));
});

app.on("message", async ({ activity, api }) => {
  const membersClient = api.conversations.members(activity.conversation.id);
  const allMembers = [];
  let continuationToken = undefined;

  do {
    const page = await membersClient.getPaged({
      pageSize: 50,
      continuationToken,
    });

    allMembers.push(...page.members);
    continuationToken = page.continuationToken;
  } while (continuationToken);
});

@app.on_message
async def list_members(ctx: ActivityContext[MessageActivity]) -> None:
    members_client = ctx.api.conversations.members(ctx.activity.conversation.id)

    all_members = []
    continuation_token: str | None = None

    while True:
        result = await members_client.get_paged(
            page_size=50,
            continuation_token=continuation_token,
        )
        all_members.extend(result.members)

        if not result.continuation_token:
            break

        continuation_token = result.continuation_token

Depois de obter a lista, pode obter detalhes para um único membro.

Obter detalhes de membro único

Pode obter detalhes de um membro específico com identificadores de utilizador do contexto de atividade.

O código de exemplo seguinte utiliza AS APIs do SDK do Teams:

app.OnMessage(async (context, cancellationToken) =>
{
    var memberId = context.Activity.From?.Id;
    if (string.IsNullOrEmpty(memberId))
    {
        return;
    }

    var member = await context.Api.Conversations.Members.GetByIdAsync(
        context.Conversation.Id,
        memberId,
        cancellationToken: cancellationToken
    );
});

app.on("message", async ({ activity, api }) => {
    const memberId = activity.from?.id;
    if (!memberId) {
        return;
    }

    const member = await api.conversations
        .member.getById(activity.conversation.id, memberId);
});

@app.on_message
async def get_member(ctx: ActivityContext[MessageActivity]) -> None:
    member_id = ctx.activity.from_.id
    member = await ctx.api.conversations.member.get_by_id(ctx.activity.conversation.id, member_id)

Depois de obter os detalhes de um membro, pode obter os detalhes da equipa.

Obter detalhes da equipe

Quando instalado numa equipa, o agente pode consultar metadados, como o ID da equipa e Microsoft Entra ID do grupo.

O código de exemplo seguinte utiliza AS APIs do SDK do Teams:

app.OnMessage(async (context, cancellationToken) =>
{
    var teamId = context.Activity.ChannelData?.Team?.Id;
    if (string.IsNullOrEmpty(teamId))
    {
        return;
    }

    var team = await context.Api.Teams.GetByIdAsync(
        teamId,
        cancellationToken: cancellationToken
    );
});

app.on("message", async ({ activity, api }) => {
    const teamId = activity.channelData?.team?.id;
    if (!teamId) {
        return;
    }

    const team = await api.teams.getById(teamId);
});

@app.on_message
async def get_team_details(ctx: ActivityContext[MessageActivity]) -> None:
    team_id = ctx.activity.channel_data.team.id
    team = await ctx.api.teams.get_by_id(team_id)

Depois de obter os detalhes da equipa, pode obter a lista de canais nessa equipa.

Obter a lista de canais em uma equipe

O agente pode consultar a lista de canais numa equipa.

Observação

  • O nome do canal geral padrão é retornado como null para permitir a localização.
  • A ID do canal para o canal Geral sempre corresponde à ID da equipe.

O código de exemplo a seguir é usado para obter a lista de canais em uma equipe:

app.OnMessage(async (context, cancellationToken) =>
{
    var teamId = context.Activity.ChannelData?.Team?.Id;
    if (string.IsNullOrEmpty(teamId))
    {
        return;
    }

    var channels = await context.Api.Teams.GetConversationsAsync(
        teamId,
        cancellationToken: cancellationToken
    );
});

app.on("message", async ({ activity, api }) => {
  const teamId = activity.channelData?.team?.id;
  if (!teamId) {
    return;
  }

  const channels = await api.teams.getConversations(teamId);
});

@app.on_message
async def list_channels(ctx: ActivityContext[MessageActivity]) -> None:
    team_id = ctx.activity.channel_data.team.id
    channels = await ctx.api.teams.get_conversations(team_id)

Se precisar de pontos finais REST do conector não processado, utilize a API do SDK do Teams para a maioria dos cenários de agente e utilize o REST diretamente para casos avançados que não são abrangidos pelas abstrações do SDK.

Próxima etapa

Enviar e receber ficheiros com o agente

Confira também

  • Last updated on