Como utilizar o Microsoft Graph com o SharePoint

Este artigo ajudará você a explorar uma das maneiras possíveis de integrar seus aplicativos com o Microsoft 365 – usando a Graph API. O Microsoft Graph é um ponto de extremidade único, fornecendo acesso a dados e serviços na nuvem da Microsoft. Ele expõe APIs REST para acessar dados em serviços do Microsoft 365 como OneDrive, Outlook, Sharepoint, Team etc. Usando-o, você pode imaginar diferentes tipos de aplicativos que permitem gerenciar suas reuniões com base em tarefas de processo, gerar arquivos Excel em seu OneDrive com o dados tratados pelos seus processos, …

Neste exemplo, focamos na integração do Sharepoint e destacaremos apenas as etapas principais. Para todos os outros cenários e detalhes, você pode visitar a documentação do Graph. Observação: você pode obter um sandbox instantâneo pré-configurado com dados de amostra se ingressar no Microsoft 365 Developer Program (assinatura gratuita renovável de 90 dias), incluindo Sharepoint.

Autenticação e autorização

Para chamar o Microsoft Graph, seu aplicativo deve primeiro gerar um token de acesso da plataforma de identidade da Microsoft. Os tokens de acesso conterão informações que permitem validar o chamador e garantir que o chamador tenha as permissões adequadas para executar a operação solicitada. Existem diferentes tipos de permissões: de aplicativo e delegada e você deve escolher a abordagem mais adequada às suas necessidades. Em nosso exemplo, utilizamos a permissão do aplicativo, pois não precisamos atuar em nome de um usuário específico.

Antes de solicitar um token, seu aplicativo deve ser registrado no portal do Azure. Acesse Azure Active Directory e escolha Registros de aplicativos. Crie um novo registro, forneça um novo nome para seu aplicativo e selecione o tipo de conta. Para seu aplicativo recém-registrado, você precisa expor uma API (adicionar um escopo e um aplicativo cliente autorizado usando seu ID de cliente). Finalmente, você precisa adicionar permissões de API. É uma boa prática adicionar apenas as permissões necessárias para limitar os riscos de segurança e decidir se apenas permissões de leitura seriam suficientes para determinados objetos ou se você precisa conceder acesso ReadWrite. Você pode usar o Graph Explorer online para ajudá-lo a determinar quais permissões você precisa adicionar. Você pode executar consultas de amostra e mostrará a lista de permissões usadas. 

Configuração do conector da API REST

Gerar token

Você pode usar o conector POST e gerar um token que pode ser usado para outras ações. A URL para chamada é:

https://login.microsoftonline.com/’ + sharepointTenant +’/oauth2/v2.0/token

onde sharepointTenant deve conter o nome do seu locatário (como abcdef.microsoft.com). Você precisa usar application/x-www-form-urlencodedcomo tipo de conteúdo, e sua carga útil pode ser a seguinte:

‘grant_type=client_credentials&client_id=’+ azureClientID + ‘&client_secret=’+ azureClientSecret +’&scope=https://graph.microsoft.com/.default’

onde grant_type deve conter “client_credentials”, client_id deve conter a ID do aplicativo que você obteve ao registrar seu aplicativo no Portal do Azure e client_secret deve conter o segredo que você gerou para seu aplicativo. Você pode usar o valor de escopo deste exemplo se quiser acessar todas as permissões de aplicativo que você configurou para seu aplicativo no portal. Você pode analisar a saída bodyAsString do seu conector para obter o token e armazená-lo em uma variável de processo ou parâmetro:

import groovy.json.JsonSlurper

def slurper = new JsonSlurper()

def object = slurper.parseText(bodyAsString)

return object.access_token

Criar pasta

Conforme descrito na documentação do Graph, existem diferentes chamadas POST que você pode fazer, dependendo do seu caso de uso. Neste exemplo, queremos criar uma nova pasta, usando uma chamada para:

/drives/{drive-id}/items/{parent-item-id}/children

Você deve usar application/jsoncomo um Content Type, e aqui está um exemplo de payload usando o script Groovy:

return ‘{“name”: “‘+ request.caseId.toString() +'”,  “folder”: {  },  “@microsoft.graph.conflictBehavior”: “rename”}’

Você precisa adicionar um cabeçalho com uma chave “Autorização” e o valor do token que você gerou anteriormente (veja acima). É útil salvar o nome da pasta recém-criada para que você possa usá-la mais tarde para carregar documentos nela.

Carregar arquivos pequenos

Se você deseja fazer upload de arquivos menores que 4 MB, pode usar um conector PUT File com um URL neste formato:

/drives/{drive-id}/items/{parent-id}:/{filename}:/content

com application/octet-streamcomo um tipo de conteúdo e selecionando um documento de processo na lista suspensa. Não se esqueça do cabeçalho de autorização. Para arquivos grandes, você deve usar um upload retomável com uma sessão. Encontre mais informações na documentação Graph REST aqui.

Continue acessando o blog da Trinapse para mais conteúdos como este.