Dados organizacionais: recuperando arquivos, chats e enviando mensagens para o Teams

2025-06-13

No ambiente digital atual, os usuários trabalham com uma ampla gama de dados organizacionais, incluindo e-mails, bate-papos, arquivos, eventos de calendário e muito mais. Isso pode levar a mudanças frequentes de contexto, alternando entre tarefas ou aplicativos, o que pode interromper o foco e reduzir a produtividade. Por exemplo, um usuário que trabalha em um projeto pode precisar alternar de seu aplicativo atual para o Outlook para encontrar detalhes cruciais em um email ou alternar para o OneDrive for Business para encontrar um arquivo relacionado. Essa ação de ida e volta interrompe o foco e desperdiça tempo que poderia ser melhor gasto na tarefa em questão.

Para aumentar a eficiência, você pode integrar dados organizacionais diretamente nos aplicativos que os usuários usam todos os dias. Ao trazer dados organizacionais para seus aplicativos, os usuários podem acessar e gerenciar informações com mais facilidade, minimizando as mudanças de contexto e melhorando a produtividade. Além disso, essa integração fornece informações e contexto valiosos, permitindo que os usuários tomem decisões informadas e trabalhem com mais eficiência.

Neste exercício, você vai:

Saiba como o componente Web mgt-search-results no Kit de Ferramentas do Microsoft Graph pode ser usado para pesquisar arquivos.
Saiba como chamar o Microsoft Graph diretamente para recuperar arquivos do OneDrive for Business e mensagens de chat do Microsoft Teams.
Entenda como enviar mensagens de chat para canais do Microsoft Teams usando o Microsoft Graph.

Usando o recurso de dados organizacionais

Em um exercício anterior , você criou um registro de aplicativo na ID do Microsoft Entra e iniciou o servidor de aplicativos e o servidor de API. Você também atualizou os seguintes valores no .env arquivo.
```
ENTRAID_CLIENT_ID=<APPLICATION_CLIENT_ID_VALUE>
TEAM_ID=<TEAMS_TEAM_ID>
CHANNEL_ID=<TEAMS_CHANNEL_ID>
```
Verifique se você concluiu o exercício anterior antes de continuar.
Volte para o navegador (http://localhost:4200). Se você ainda não entrou, selecione Entrar no cabeçalho e entre com um usuário do seu locatário do Desenvolvedor do Microsoft 365.
Observação

Além de autenticar o usuário, o componente Web de logon mgt também recupera um token de acesso que pode ser usado pelo Microsoft Graph para acessar arquivos, chats, emails, eventos de calendário e outros dados organizacionais. O token de acesso contém os escopos (permissões), como Chat.ReadWrite, Files.Read.Alle outros que você viu anteriormente:
```
Providers.globalProvider = new Msal2Provider({
    clientId: ENTRAID_CLIENT_ID, // retrieved from .env file
    scopes: ['User.Read', 'Presence.Read', 'Chat.ReadWrite', 'Calendars.Read', 
             'ChannelMessage.Read.All', 'ChannelMessage.Send', 'Files.Read.All', 'Mail.Read']
});
```
Selecione Exibir Conteúdo Relacionado para a linha da Adatum Corporation no datagrid. Isso fará com que dados organizacionais, como arquivos, chats, emails e eventos de calendário, sejam recuperados usando o Microsoft Graph. Depois que os dados forem carregados, eles serão exibidos abaixo da grade de dados em uma interface com guias. É importante mencionar que você pode não ver nenhum dado neste momento, pois ainda não adicionou arquivos, chats, emails ou eventos de calendário para o usuário em seu locatário de desenvolvedor do Microsoft 365. Vamos corrigir isso na próxima etapa.
Seu locatário do Microsoft 365 pode não ter dados organizacionais relacionados para a Adatum Corporation neste estágio. Para adicionar alguns dados de exemplo, execute pelo menos uma das seguintes ações:
- Adicione arquivos visitando https://onedrive.com e entrando usando suas credenciais de locatário do Microsoft 365 Developer.
  - Selecione Meus arquivos na navegação à esquerda.
  - Selecione + Adicionar novo e, em seguida , carregar pasta no menu.
  - Selecione a pasta openai-acs-msgraph/customer documents do projeto clonado.
- Adicione mensagens de chat e eventos de calendário visitando https://teams.microsoft.com e entrando usando suas credenciais de locatário do Microsoft 365 Developer.
  - Selecione o Teams na navegação à esquerda.
  - Selecione uma equipe e um canal.
  - Selecione Iniciar uma postagem.
  - Insira novo pedido colocado para a Adatum Corporation para o assunto e qualquer texto adicional que você gostaria de adicionar no corpo da mensagem. Selecione o botão Postar .
    
    Fique à vontade para adicionar mensagens de chat adicionais que mencionam outras empresas usadas no aplicativo, como Adventure Works Cycles, Contoso Pharmaceuticals e Tailwind Traders.
  - Selecione Calendário na navegação à esquerda.
  - Selecione Nova reunião.
  - Digite "Reunir-se com a Adatum Corporation sobre o cronograma do projeto" para o título e o corpo.
  - Clique em Salvar.
- Adicione emails visitando https://outlook.com e entrando usando suas credenciais de locatário do Microsoft 365 Developer.
  - Selecione Novo email.
  - Insira seu endereço de email pessoal no campo Para .
  - Insira novo pedido feito para a Adatum Corporation para o assunto e qualquer coisa que você gostaria para o corpo.
  - Selecione Enviar.
Volte para o aplicativo no navegador e atualize a página. Selecione Exibir Conteúdo Relacionado novamente para a linha da Adatum Corporation . Agora você deve ver os dados exibidos nas guias, dependendo de quais tarefas você executou na etapa anterior.
Vamos explorar o código que habilita o recurso de dados organizacionais no aplicativo. Para recuperar os dados, a parte do lado do cliente do aplicativo usa o token de acesso recuperado pelo componente de logon mgt que você examinou anteriormente para fazer chamadas às APIs do Microsoft Graph.

Explorando o código de pesquisa de arquivos

Dica

Se você estiver usando o Visual Studio Code, poderá abrir arquivos diretamente selecionando:

Windows/Linux: Ctrl + P
Mac: Cmd + P

Em seguida, digite o nome do arquivo que deseja abrir.

Vamos começar examinando como os dados de arquivo são recuperados do OneDrive for Business. Abra files.component.html e reserve um momento para analisar o código. O caminho completo para o arquivo é client/src/app/files/files.component.html.
Localize o componente mgt-search-results e observe os seguintes atributos:
```
<mgt-search-results 
    class="search-results" 
    entity-types="driveItem" 
    [queryString]="searchText"
    (dataChange)="dataChange($any($event))" 
/>
```
O componente mgt-search-results faz parte do Kit de Ferramentas do Microsoft Graph e, como o nome indica, ele é usado para exibir os resultados da pesquisa do Microsoft Graph. O componente usa os seguintes recursos neste exemplo:
- O class atributo é usado para especificar que a search-results classe CSS deve ser aplicada ao componente.
- O entity-types atributo é usado para especificar o tipo de dados a serem pesquisados. Nesse caso, o valor é driveItem usado para pesquisar arquivos no OneDrive for Business.
- O queryString atributo é usado para especificar o termo de pesquisa. Nesse caso, o valor é associado à searchText propriedade que é passada para o componente de arquivos quando o usuário seleciona Exibir Conteúdo Relacionado para uma linha no datagrid. Os colchetes ao redor queryString indicam que a propriedade está associada ao searchText valor.
- O dataChange evento é acionado quando os resultados da pesquisa são alterados. Nesse caso, uma função de cliente nomeada dataChange() é chamada no componente de arquivos e os dados do evento são passados para a função. Os parênteses indicam dataChange que o evento está vinculado à dataChange() função.
- Como nenhum modelo personalizado é fornecido, o modelo padrão integrado mgt-search-results é usado para exibir os resultados da pesquisa.
Uma alternativa ao uso de componentes como mgt-search-results é chamar as APIs do Microsoft Graph diretamente usando o código. Para ver como isso funciona, abra o arquivo graph.service.ts e localize a searchFiles() função. O caminho completo para o arquivo é client/src/app/core/graph.service.ts.
- Você notará que um query parâmetro é passado para a função. Esse é o termo de pesquisa passado à medida que o usuário seleciona Exibir Conteúdo Relacionado para uma linha no datagrid. Se nenhum termo de pesquisa for passado, uma matriz vazia será retornada.
```
async searchFiles(query: string) {
    const files: DriveItem[] = [];
    if (!query) return files;

    ...
}
```
- Em seguida, é criado um filtro que define o tipo de pesquisa a ser executada. Nesse caso, o código está procurando arquivos no OneDrive for Business, portanto, driveItem é usado exatamente como você viu anteriormente com o mgt-search-results componente. Isso é o mesmo que passar driveItem para entity-types o componente mgt-search-results que você viu anteriormente. O query parâmetro é então adicionado ao queryString filtro junto com ContentType:Document.
```
const filter = {
    "requests": [
        {
            "entityTypes": [
                "driveItem"
            ],
            "query": {
                "queryString": `${query} AND ContentType:Document`
            }
        }
    ]
};
```
- Em seguida, uma chamada é feita para a API do /search/query Microsoft Graph usando a Providers.globalProvider.graph.client.api() função. O filter objeto é passado para a post() função que envia os dados para a API.
```
const searchResults = await Providers.globalProvider.graph.client.api('/search/query').post(filter);
```
- Os resultados da pesquisa são então iterados para localizar hits. Cada hit um contém informações sobre um documento que foi encontrado. Uma propriedade chamada resource contém os metadados do documento e é adicionada à files matriz.
```
if (searchResults.value.length !== 0) {
    for (const hitContainer of searchResults.value[0].hitsContainers) {
        if (hitContainer.hits) {
            for (const hit of hitContainer.hits) {
                files.push(hit.resource);
            }
        }
    }
}
```
- A files matriz é então retornada ao chamador.
```
return files;
```
Examinando esse código, você pode ver que o componente web mgt-search-results que você explorou anteriormente faz muito trabalho para você e reduz significativamente a quantidade de código que você precisa escrever! No entanto, pode haver cenários em que você deseja chamar o Microsoft Graph diretamente para ter mais controle sobre os dados enviados para a API ou como os resultados são processados.
Abra o arquivo files.component.ts e localize a search() função. O caminho completo para o arquivo é client/src/app/files/files.component.ts.

Embora o corpo dessa função seja comentado devido ao componente mgt-search-results sendo usado, a função pode ser usada para fazer a chamada para o Microsoft Graph quando o usuário seleciona Exibir Conteúdo Relacionado para uma linha no datagrid. A search() função chama searchFiles() em graph.service.ts e passa o query parâmetro para ele (o nome da empresa neste exemplo). Os resultados da pesquisa são então atribuídos à data propriedade do componente.
```
override async search(query: string) {
    this.data = await this.graphService.searchFiles(query);
}
```
O componente de arquivos pode usar a data propriedade para exibir os resultados da pesquisa. Você pode lidar com isso usando associações HTML personalizadas ou usando outro controle do Microsoft Graph Toolkit chamado mgt-file-list. Aqui está um exemplo de associação da data propriedade a uma das propriedades do componente nomeada files e manipulação do itemClick evento à medida que o usuário interage com um arquivo.
```
<mgt-file-list (itemClick)="itemClick($any($event))" [files]="data"></mgt-file-list>
```
Se você optar por usar o componente mgt-search-results mostrado anteriormente ou gravar código personalizado para chamar o Microsoft Graph dependerá do seu cenário específico. Neste exemplo, o componente mgt-search-results é usado para simplificar o código e reduzir a quantidade de trabalho que você precisa fazer.

Explorando o código de pesquisa de mensagens de chat do Teams

Volte para graph.service.ts e localize a searchChatMessages() função. Você verá que é semelhante à searchFiles() função que você examinou anteriormente.
- Ele posta dados de filtro na API do /search/query Microsoft Graph e converte os resultados em uma matriz de objetos que têm informações sobre o teamId, channelIde messageId que correspondem ao termo de pesquisa.
- Para recuperar as mensagens do canal do Teams, uma segunda chamada é feita para a /teams/${chat.teamId}/channels/${chat.channelId}/messages/${chat.messageId} API e o teamId, channelIde messageId são passados. Isso retorna os detalhes completos da mensagem.
- Tarefas de filtragem adicionais são executadas e as mensagens resultantes são retornadas para searchChatMessages() o chamador.

Abra o arquivo chats.component.ts e localize a search() função. O caminho completo para o arquivo é client/src/app/chats/chats.component.ts. A search() função chama searchChatMessages() em graph.service.ts e passa o query parâmetro para ele.

override async search(query: string) {
    this.data = await this.graphService.searchChatMessages(query);
}

Os resultados da pesquisa são atribuídos à data propriedade do componente e a vinculação de dados é usada para iterar por meio da matriz de resultados e renderizar os dados. Este exemplo usa um componente do cartão Material Angular para exibir os resultados da pesquisa.

@if (this.data.length) {
    <div>
        @for (chatMessage of this.data;track chatMessage.id) {
            <mat-card>
                <mat-card-header>
                    <mat-card-title [innerHTML]="chatMessage.summary"></mat-card-title>
                    <!-- <mat-card-subtitle [innerHTML]="chatMessage.body"></mat-card-subtitle> -->
                </mat-card-header>
                <mat-card-actions>
                    <a mat-stroked-button color="basic" [href]="chatMessage.webUrl" target="_blank">View Message</a>
                </mat-card-actions>
            </mat-card>
        }
    </div>
}

Exibir chats do Teams

Enviando uma mensagem para um canal do Microsoft Teams

Além de pesquisar mensagens de bate-papo do Microsoft Teams, o aplicativo também permite que um usuário envie mensagens para um canal do Microsoft Teams. Isso pode ser feito chamando o /teams/${teamId}/channels/${channelId}/messages ponto de extremidade do Microsoft Graph.

No código a seguir, você verá que uma URL é criada que inclui os teamId valores e channelId . Os valores de variável de ambiente são usados para a ID da equipe e a ID do canal neste exemplo, mas esses valores também podem ser recuperados dinamicamente usando o Microsoft Graph. A body constante contém a mensagem a ser enviada. Uma solicitação POST é feita e os resultados são retornados ao chamador.

async sendTeamsChat(message: string): Promise<TeamsDialogData> {
    if (!message) new Error('No message to send.');
    if (!TEAM_ID || !CHANNEL_ID) new Error('Team ID or Channel ID not set in environment variables. Please set TEAM_ID and CHANNEL_ID in the .env file.');

    const url = `https://graph.microsoft.com/v1.0/teams/${TEAM_ID}/channels/${CHANNEL_ID}/messages`;
    const body = {
        "body": {
            "contentType": "html",
            "content": message
        }
    };
    const response = await Providers.globalProvider.graph.client.api(url).post(body);
    return {
        id: response.id,
        teamId: response.channelIdentity.teamId,
        channelId: response.channelIdentity.channelId,
        message: response.body.content,
        webUrl: response.webUrl,
        title: 'Send Teams Chat'
    };
}

Aproveitar esse tipo de funcionalidade no Microsoft Graph fornece uma ótima maneira de aprimorar a produtividade do usuário, permitindo que os usuários interajam com o Microsoft Teams diretamente do aplicativo que já estão usando.

Próxima Etapa

Dados organizacionais: recuperando emails e eventos de calendário

Compartilhar via