Microsoft Graph

Olá amigos!

Vamos lá com mais um assunto sobre as novidades da Microsoft.

Eu estava estudando algo sobre serviços do Office Graph e foi quando entrei em uma de suas documentações e lá estava falando algo como “escolha seus endpoints“. E agora, acabou o Office Graph? Bom, eu não sei, mas já tem um tempo que não há atualizações. Então fui pesquisar e vi essa nota da Microsoft:

A funcionalidade da API do Office 365 também está disponível através do Microsoft Graph, uma API unificada que inclui APIs de outros serviços da Microsoft, como o Outlook, OneDrive, OneNote, Planner e Office Graph, acessíveis através de um único nó de extremidade e um único token de acesso. Recomendamos usar o Microsoft Graph em seus aplicativos quando possível.

Olha o Office Graph sendo citado ai, então isso quer dizer que ele faz parte dessa nova api, Microsoft Graph. Vamos aos estudos!

Algo que me deixou bastante feliz foi quando estive no Tech Summit e lá os palestrantes deram bastante ênfase ao Office 365. Eu achava que eles iriam apresentar o Office Graph, mas não, eles apresentaram o Microsoft Graph.

O que é o Microsoft Graph?

A Microsoft vem desenvolvendo vários serviços de cloud apis e juntando todos eles em um único ponto, ou seja, em uma única API. Porém, pelo que estamos vendo até o momento, é que estão focados em serviços nas nuvens e que há uma relação de produtividade entre as organizações e seus colaboradores, nesse caso, o pacote Office.

Office Developer

O mais legal é que a Microsoft cada vez mais vem expandindo esses serviços e disponibilizando em sua api unificada. Então significa que as apis que estão separadas deixaram de funcionar? Acredito que não,  mas, acredito que elas serão migradas para o Microsoft Graph, assim como vem ocorrendo com o Office Graph.

E essa única API vai nos disponibilizar que tipo de interação?

  • Acesso aos dados – É possível acessar meus dados, meu perfil, grupos ou até consultar algumas  mensagens de e-mails, através de chamadas como /me, /groups, /messages e assim por diante. Reforço que se fosse somente realizar acesso a dados isso seria mais uma API, mas isso não é tudo.
  • Dados Transversais – Essa é uma das interações que contribui para diferenciar o graph de uma simples api de consulta. Os dados tem uma ligação entre diversas outras informações – isso faz parte da teoria dos grafos. Em resumo é o fato de conseguir atravessar informações sobre as ligações entre os nós de informações conectadas. Como por exemplo, uma url /drive/items/<id>/lastModifyByUser, ou seja, estou conseguindo acessar um item no drive que irá retornar informações do usuário que realizou a última modificação em um determinado arquivo.
  • Acessando dados Inteligentes – A Microsoft também vem criando mecanismos de aprendizagem de máquina. Isso, irá permitir que as informações tenham bases em diversas esferas, sem a necessidade de acessar um caminho especifico, como por exemplo: Quando for necessário trazer todos os documentos que são tendências entre todos os usuários que eu compartilho informações. Para uma simples API de consulta, neste caso, é necessário realizar a consulta de cada documento e realizar uma lógica por trás disso. Porém o Microsoft Graph faz esse trabalho da lógica, com o conceito de acesso a dados inteligentes, disponibilizando um único caminho pode então realizar essa busca, /insigths/trends. Para quem tem o Office 365 na empresa e acessa o Delve, é uma plataforma que pode ser um ótimo exemplo da utilização de dados inteligentes através do Microsoft Graph.

graph

Quais foram as principais mudanças

Quando falamos do acesso a partir de um ponto de acesso ao usuário, é necessário realizar o login através de uma das contas da Microsoft, seja do tipo Work/School ou Microsoft Accounts. Porém, isso dificultava um pouco a consulta de informações em uma dessas contas, pois eram cenários de informações bem diferentes, ou seja, várias APIs para acessar dados e isso trazia uma certa confusão.

image

Como já conversamos antes, agora temos uma unificação de APIs e isso inclui uma camada de autenticação também unificada. Assim, ficou mais fácil de ter acesso as informações necessárias através de um determinado ponto de autenticação, seja lá qual for o tipo de conta. A figura abaixo representa bem essa consolidação entre os serviços disponíveis pelo Microsoft Graph.

image

O que essa unificação traz de benefícios para o âmbito de desenvolvimento de uma aplicação?

Vamos dizer que foi realizado uma integração com SharePoint OnLine manipulando as informações de um determinado departamento, ai chega o Product Owner e diz: Que legal, você fez a integração da nossa aplicação com o SharePoint, poderia agora fazer com o Outlook? Pois é, ai nesse momento iriamos ter que aprender a APi do Outlook. Agora com essa consolidação dos serviços não será mais necessário.

Do ponto de vista comercial, vai gerar menos custos de desenvolvimento e irá agregar mais valores para as entregas que tiverem suas integrações partindo de um único ponto.

Abaixo, alguns dos endpoints que eram necessários para realizar uma integração.

image

Então como ficaram essa unificação, quais são os padrões e endpoints que temos acesso?

Primeiramente, o que eu gostei dessa unificação é a fácil leitura do serviço, assim como também foi colocado a versão, como por exemplo o caminho para retornar meus dados https://graph.microsoft.com/v1.0/me. Perceberam que há o caminho da versão? Achei bem legal, porque ai podemos mudar de uma versão para outra ou até testar.

Abaixo nós temos uma tabela com alguns dos serviços que já estão disponíveis na versão 1.0 e uns da versão beta. Visite o site do Microsoft Graph na parte de documentação e lá verá essa lista de serviços.

image

Nota: Não iremos discutir todos os pontos de acesso e também não vamos entrar nesses detalhes pois para isso tem as documentações do Microsoft Graph e o nosso principal objetivo é que possamos aprender juntos sobre a utilização desta API.

Vamos começar a entender na prática

Então como começar os estudos sem a necessidade de utilizar o Graph Explorer que está disponível no site?

Bom, eu comecei primeiramente entendendo sobre a questão de autorização, ou seja, o que é de fato necessário para que a minha aplicação possa acessar os dados a partir de um ponto de autenticação. Ótimo, falamos na palavra autenticação e autorização, isso soa ao OAuth 2.0 Flow – não precisamos entrar em muitos detalhes sobre esse fluxo, pois já é bem conhecido.

Eu costumo usar um aplicativo muito bom para testar chamadas de APIs, é o Postman, vamos utilizar ele para resgatar o Authentication Token e solicitar informações ao Microsoft Graph.

Primeiro passo é configurar um Azure Active Directory para conectar com os usuários do Office 365 – este link explica direitinho. Abaixo o que já configurei:

image

Depois de configurado o Active Directory precisamos autorizar o aplicativo, neste caso o PostMan a realizar chamadas ao Graph, então é só registrar a app – serão passos simples, pois ainda não estamos construindo uma aplicação. Abaixo a forma resumida que fiz:

image

Para a próxima tela escolha a opção: “Adicionar um aplicativo que  minha organização esteja desenvolvendo”

Preencha as seguintes propriedades

image image

Criado o aplicativo agora vá para a aba de configurações e copie o Client ID e crie um Secret Client ID (guarde em algum lugar) iremos precisar deles. Também preencha a propriedade URL de Resposta com o valor: https://www.getpostman.com/oauth2/callback

image

Agora vamos autorizar a nossa aplicação a acessar o Microsoft Graph. Click no botão de adicionar aplicativo e escolha o Microsoft Graph – coloquei todas as permissões porque o intuito é estudar a maioria dos EndPoints, então liberar tudo.

image

Lembre-se de copiar os EndPoints:

Authorization OAuth 2.0: https://login.microsoftonline.com/<id>/oauth2/authorize?resource=https://graph.microsoft.com/

Token OAuth: https://login.microsoftonline.com/<id>/oauth2/token

image

Usando a aplicação Client (PostMan)

Agora vamos solicitar a nossa aplicação “Client” para fazer a parte de autenticação, receber o token e aplicar em nossos Headers, e assim ter acesso ao Microsoft Graph – lembrando que esse fluxo de autorização faz parte do Oauth Flow. Abaixo o diagrama que mostra o fluxo.

OAuth2

Abaixo a principal tela inicial do PostMan.

image

Escolha o OAuth 2.0 como o tipo de autorização que o post ira realizar e ai em Get New Acess Token tem as seguintes informações:

image

Após essa configuração, ao clicar em Request Token irá aparecer a tela de autenticação de contas da Microsoft. Realize a autenticação com um dos usuários do Active Directory que foi configurado. Tudo ok, o PostMan irá salvar esse Token, aí pedimos para adiciona-los na Header da requisição:

image

Com o endereço https://graph.microsoft.com/v1.0/me irá retornar como resposta as informações, no formato Json, do usuário autenticado.

image

Agora vamos retornar a foto desse usuário, é só colocar o endereço http://graph.microsoft.com/v1.0/me/photo/$value ou se eu quero pegar de algum usuário especifico http://graph.microsoft.com/v1.0/users/<id>/photo/$value

image

É isso ae galera, estamos agora conectados ao Microsoft Graph, para os próximos momentos vamos explorar alguns SDKS e aplicações clients para mostrar alguns exemplos legais.

Espero que tenham gostado e divirtam-se com esses serviços tão legais.

Referências:

Microsoft Graph – https://graph.microsoft.io/en-us/docs

Azure Active Directory – https://azure.microsoft.com/pt-br/services/active-directory/

PnP Office – https://github.com/OfficeDev/PnP/wiki

Autenticação do Microsoft Graph: https://graph.microsoft.io/en-us/docs/authorization/auth_overview

Thiago Holder

Sou um cara que abraça as oportunidades através dos desafios. Apaixonado pelo desenvolvimento de softwares baseado em Web. Tenho uma bagagem de 6 anos com a plataforma SharePoint.