Usar o Microsoft Graph API para trabalhar com o Microsoft Teams

Importante

APIs na /beta versão no Microsoft Graph estão sujeitas a alterações. Não há suporte para o uso dessas APIs em aplicativos de produção. Para determinar se uma API está disponível em v1.0, use o seletor De versão.

O Microsoft Teams é um espaço de trabalho baseado em chat no Microsoft 365 que fornece acesso interno a calendários, arquivos, anotações do OneNote, planos do Planner e muito mais.

Principais recursos no Microsoft Teams (visualização)

Resource Métodos
team Listar suas equipes, listar todas as equipes, criar, ler, atualizar, excluir, clonar, arquivar, cancelar o arquivamento
group Adicionar membro,  remover membro, adicionar proprietário,  remover proprietário, obter arquivos, obter bloco de anotações, obter planos, obter calendário
channel Listar, criar, ler, atualizar, excluir
teamsTab Listar, criar, ler, atualizar, excluir
teamsApp Listar, publicar, atualizar, remover
teamsAppInstallation Listar, instalar, atualizar, remover
chatMessage listar no canal, listar no chat, enviar, ler no canal, ler no chat
call Responder, rejeitar, redirecionar, ativar mudo, desfazer ativar mudo, alterar a função de compartilhamento de tela, listar participantes, convidar participantes
cronograma Criar ou substituir, obter, compartilhar
schedulingGroup Criar, Listar, Obter, Substituir, Excluir
activityFeedNotification Enviar notificação ao usuário no escopo de um chat, Enviar notificação ao usuário no escopo de uma equipe, Enviar notificação ao usuário no escopo pessoal
shift Criar, Listar, Obter, Substituir, Excluir
timeOff Criar, Listar, Obter, Substituir, Excluir
timeOffReason Criar, Listar, Obter, Substituir, Excluir

Limites do Microsoft Teams

As limitações de desempenho e de capacidade testadas do Microsoft Teams estão documentadas nas especificações e limites do Microsoft Teams. Esses limites aplicam-se diretamente ao usar o Microsoft Teams ou usar as APIs do Microsoft Graph. Como todas as equipes têm um grupo correspondente, e cada grupo é um objeto de diretório, limites no número de grupos e o número de objetos de diretório ("recursos") também podem ser levados em consideração.

Os arquivos dentro de canais são armazenados no SharePoint. os limites do SharePoint Online se aplicam.

Confira também redução dos limites dos serviços do Microsoft Teams.

Equipes e grupos

Na Microsoft Graph, o Microsoft Teams é representado por um recurso de grupo. Os grupos do Microsoft Teams e Microsoft 365 atendem às várias necessidades de colaboração em grupo. Quase todos os recursos baseados em grupo se aplicam aos grupos do Microsoft Teams e do Microsoft 365, como calendário de grupo, arquivos, anotações, fotos, planos e assim por diante. A principal diferença entre uma equipe e um grupo do Microsoft 365 é o modo de comunicação entre os membros. Os membros do Teams se comunicam por meio de chat persistente no contexto de uma equipe específica. Os membros do grupo do Microsoft 365 se comunicam por conversas em grupo, que são conversas de email que ocorrem no contexto de um grupo no Outlook.

Qualquer grupo que tenha uma equipe possui uma propriedade resourceProvisioningOptions que contém "Team".

Observação: a propriedade Group.resourceProvisioningOptions pode ser alterada. Não adicione ou remova "Team" dessa coleção; caso contrário, você obterá resultados incorretos ao listar todas as equipes.

Veja a seguir as diferenças no nível da API entre equipes e grupos:

Observação: Se você usar as APIs de grupo em um aplicativo Microsoft Teams, em vez de um aplicativo autônomo, por exemplo, como parte de uma guia ou um bot em execução no Microsoft Teams. Siga as orientações no artigo Uso do Microsoft Graph em suas páginas do Microsoft Teams.

Alterações de associação no Microsoft Teams

Para adicionar membros e proprietários a uma equipe, altere a associação do grupo com a mesma ID.

Caso de uso Verbo URL
Adicionar membro POST /groups/{id}/members/$ref
Remover membro DELETE /groups/{id}/members/{userId}/$ref
Adicionar proprietário POST /groups/{id}/owners/$ref
Remover proprietário DELETE /groups/{id}/owners/{userId}/$ref
Atualizar equipe PATCH /teams/{id}

Recomendamos que, ao adicionar um proprietário, você também adicione esse usuário como membro. Se uma equipe tiver um proprietário que também não seja um membro, as alterações de propriedade e associação talvez não sejam imediatamente exibidas no Microsoft Teams. Além disso, aplicativos e APIs diferentes tratam disso de maneira diferente. Por exemplo, o Microsoft Teams mostrará equipes das quais o usuário é membro ou proprietário, enquanto os cmdlets do PowerShell do Microsoft Teams e a API /me/joinedTeams mostrarão apenas as equipes das quais o usuário é membro. Para evitar confusão, adicione também todos os proprietários à lista de membros.

Problema conhecido: quando DELETE /groups/{id}/owners é chamado, o usuário também é removido da lista /groups/{id}/members. Para contornar isso, recomendamos que você remova o usuário dos proprietários e membros, espere 10 segundos e adicione-os novamente aos membros.

Ao adicionar e remover membros e proprietários, não coloque chaves { } ao redor da ID.

Velocidade Sintaxe
Rápida https://graph.microsoft.com/beta/groups/02bd9fd6-8f93-4758-87c3-1fb73740a315/members/48d31887-5fad-4d73-a9f5-3c356e68a038/$ref
Lento https://graph.microsoft.com/beta/groups/{02bd9fd6-8f93-4758-87c3-1fb73740a315}/members/{48d31887-5fad-4d73-a9f5-3c356e68a038}/$ref

Da mesma forma, se o userId na URL ou no conteúdo for expresso como um UPN, e não como um GUID, o desempenho será mais lento.

Velocidade Sintaxe
Rápida 48d31887-5fad-4d73-a9f5-3c356e68a038
Lento vitor@example.com

Quando o caminho mais lento é executado, se um membro ou membro da equipe atual estiver conectado ao aplicativo/site do Microsoft Teams, a alteração será refletida em uma hora. Se nenhum desses usuários estiver conectado ao aplicativo/site do Microsoft Teams, a alteração não será refletida até uma hora depois que um deles se conectar.

Observação

Os convidados do locatário sempre são processados pelo caminho lento.

Requisitos de sondagem

Se seu aplicativo sonda para ver se um recurso foi alterado, você só poderá fazer isso uma vez por dia. (teamsAsyncOperation é uma exceção no sentido de que é foi desenvolvida para ser sondada frequentemente.) Se você precisar saber sobre mudanças com mais frequência que esta, você deve criar uma assinatura para esse recurso e receber notificações de alteração (webhooks). Caso não encontre suporte para o tipo de assinatura necessária, recomendamos que você faça comentários por meio do Fórum de ideias da Plataforma para Desenvolvedores do Microsoft 365 .

Ao pesquisar novas mensagens, você deve especificar um intervalo de datas onde isso for possível. Para obter detalhes, consulte obter mensagens de canal delta.

As sondagem está executando uma operação OBTER em um recurso repetidamente para ver se o recurso foi alterado. Você tem permissão para obter o mesmo recurso várias vezes por dia, desde que não seja uma sondagem. Por exemplo, está tudo bem se você usar OBTER /me/joinedTeams toda vez que o usuário visita/atualiza sua página da web, mas não é certo usar OBTER /me/joinedTeams em um loop a cada 30 segundos para atualizar essa página da web.

Os aplicativos que não seguem esses requisitos de sondagem serão considerados violações de termos de uso das APIs da Microsoft. A violação destes Termos da API pode resultar suspensãoou no cancelamento do uso das APIs da Microsoft.

Novidades

Saiba mais sobre os novos recursos e atualizações mais recentes para este conjunto de APIs.

Confira também