Compartilhar via

Azure Functions para webhooks do SharePoint com o azd

Azure Developer CLI (azd) é uma ferramenta open source que acelera o aprovisionamento e a implementação de recursos de aplicações no Azure.

Este artigo utiliza o modelo público da aplicação de funções do Azure para webhooks do SharePoint para implementar uma aplicação de funções do Azure que se liga ao seu inquilino do SharePoint Online, registar e gerir webhooks e processar as notificações a partir do SharePoint.

Pré-requisitos

Permissões necessárias para aprovisionar os recursos no Azure

A conta que executa o azd tem de ter, pelo menos, as seguintes funções para aprovisionar com êxito os recursos:

Implementar a aplicação de funções no Azure

  1. Execute azd init a partir de uma pasta local (raiz) vazia:

    azd init --template azd-functions-sharepoint-webhooks

    Introduza um nome de ambiente, como spofuncs-quickstart quando lhe for pedido. No azd, o ambiente é utilizado para manter um contexto de implementação exclusivo para a sua aplicação.

  2. Abra o ficheiro infra/main.parameters.json, defina as variáveis TenantPrefix e siteRelativePath para corresponder ao seu inquilino do SharePoint.

    Veja o artigo sobre Gerir variáveis de ambiente para gerir as variáveis de ambiente do azd.

  3. Por fim, execute o comando azd up para criar a aplicação, aprovisionar os recursos no Azure e implementar o pacote de aplicações.

Conceder acesso à aplicação de funções ao SharePoint Online

A autenticação no SharePoint é feita com DefaultAzureCredential, pelo que a credencial utilizada depende se a aplicação de funções é executada localmente ou no Azure.

Se nunca ouviu falar do DefaultAzureCredential, deve familiarizar-se com o conceito ao consultar a secção Utilizar DefaultAzureCredential para flexibilidade em Cadeias de credenciais na biblioteca de cliente da Identidade do Azure para JavaScript.

Utilizar a respetiva identidade gerida

DefaultAzureCredential utilizará uma identidade gerida para autenticar no SharePoint. Esta pode ser a identidade gerida atribuída pelo sistema existente do serviço de aplicações de funções ou uma identidade gerida atribuída pelo utilizador.

Este tutorial pressupõe que a identidade gerida atribuída pelo sistema é utilizada.

Conceder a permissão da API do SharePoint Sites.Selected à identidade gerida

Navegue para a sua aplicação de funções no portal do Azure> selecione Identidade e anote o ID do Objeto (principal) da identidade gerida atribuída pelo sistema.

Observação

Neste tutorial, é d3e8dc41-94f2-4b0f-82ff-ed03c363f0f8.

Em seguida, utilize um dos scripts abaixo para conceder a esta identidade a permissão apenas da aplicação Sites.Selected na API do SharePoint:

Importante

Os scripts abaixo requerem, pelo menos, a permissão AppRoleAssignment.ReadWrite.All delegada (requer consentimento do administrador)

Utilizar o SDK do PowerShell do Microsoft Graph 
# This script requires the modules Microsoft.Graph.Authentication, Microsoft.Graph.Applications, Microsoft.Graph.Identity.SignIns, which can be installed with the cmdlet Install-Module below:
# Install-Module Microsoft.Graph.Authentication, Microsoft.Graph.Applications, Microsoft.Graph.Identity.SignIns -Scope CurrentUser -Repository PSGallery -Force
Connect-MgGraph -Scope "Application.Read.All", "AppRoleAssignment.ReadWrite.All"
$managedIdentityObjectId = "d3e8dc41-94f2-4b0f-82ff-ed03c363f0f8" # 'Object (principal) ID' of the managed identity
$scopeName = "Sites.Selected"
$resourceAppPrincipalObj = Get-MgServicePrincipal -Filter "displayName eq 'Office 365 SharePoint Online'" # SPO
$targetAppPrincipalAppRole = $resourceAppPrincipalObj.AppRoles | ? Value -eq $scopeName

$appRoleAssignment = @{
    "principalId" = $managedIdentityObjectId
    "resourceId"  = $resourceAppPrincipalObj.Id
    "appRoleId"   = $targetAppPrincipalAppRole.Id
}
New-MgServicePrincipalAppRoleAssignment -ServicePrincipalId $managedIdentityObjectId -BodyParameter $appRoleAssignment | Format-List
Utilizar az cli no Bash 
managedIdentityObjectId="d3e8dc41-94f2-4b0f-82ff-ed03c363f0f8" # 'Object (principal) ID' of the managed identity
resourceServicePrincipalId=$(az ad sp list --query '[].[id]' --filter "displayName eq 'Office 365 SharePoint Online'" -o tsv)
resourceServicePrincipalAppRoleId="$(az ad sp show --id $resourceServicePrincipalId --query "appRoles[?starts_with(value, 'Sites.Selected')].[id]" -o tsv)"

az rest --method POST --uri "https://graph.microsoft.com/v1.0/servicePrincipals/${managedIdentityObjectId}/appRoleAssignments" --headers 'Content-Type=application/json' --body "{ 'principalId': '${managedIdentityObjectId}', 'resourceId': '${resourceServicePrincipalId}', 'appRoleId': '${resourceServicePrincipalAppRoleId}' }"

Conceder à identidade gerida acesso efetivo a um site do SharePoint

Navegue para as Aplicações empresariais> Definir o filtro Tipo de aplicação para Identidades Geridas> selecione a identidade gerida e anote o ID da Aplicação.

Observação

Neste tutorial, é 3150363e-afbe-421f-9785-9d5404c5ae34.

Em seguida, utilize um dos scripts abaixo para lhe conceder a gestão de permissões apenas da aplicação (mínimo necessário para registar um webhook) num site específico do SharePoint:

Importante

O registo de aplicações utilizado para executar esses scripts tem de ter, pelo menos, as seguintes permissões:

  • Permissão delegada Application.ReadWrite.All no API do Graph (requer consentimento do administrador)
  • Permissão delegada AllSites.FullControl na API do SharePoint (requer consentimento do administrador)
Utilizar o PowerShell do PnP

PowerShell PnP

Connect-PnPOnline -Url "https://YOUR_SHAREPOINT_TENANT_PREFIX.sharepoint.com/sites/YOUR_SHAREPOINT_SITE_NAME" -Interactive -ClientId "YOUR_PNP_APP_CLIENT_ID"
Grant-PnPAzureADAppSitePermission -AppId "3150363e-afbe-421f-9785-9d5404c5ae34" -DisplayName "YOUR_FUNC_APP_NAME" -Permissions Manage
Utilizar a cli m365 no Bash

m365 cli

targetapp="3150363e-afbe-421f-9785-9d5404c5ae34"
siteUrl="https://YOUR_SHAREPOINT_TENANT_PREFIX.sharepoint.com/sites/YOUR_SHAREPOINT_SITE_NAME"
m365 spo site apppermission add --appId $targetapp --permission manage --siteUrl $siteUrl

Chamar a aplicação de funções

Por motivos de segurança, ao executar no Azure, a aplicação de funções requer uma chave de aplicação para transmitir o código do parâmetro da cadeia de consulta. As chaves da aplicação encontram-se na página chaves de Aplicações do serviço de aplicações de funções.

A maioria das funções HTTP assume parâmetros opcionais TenantPrefix e siteRelativePath. Se não forem especificados, são utilizados os valores nas variáveis de ambiente da aplicação.

Segue-se um script de exemplo no PowerShell para chamar a aplicação de funções:

# Edit those variables to match your environment
$funchost = "YOUR_FUNC_APP_NAME"
$code = "YOUR_HOST_KEY"
$listTitle = "YOUR_SHAREPOINT_LIST"
$notificationUrl = "https://${funchost}.azurewebsites.net/api/webhooks/service?code=${code}"

# List all the webhooks registered on a list
Invoke-RestMethod -Method GET -Uri "https://${funchost}.azurewebsites.net/api/webhooks/list?code=${code}&listTitle=${listTitle}"

# Register a webhook in a list
Invoke-RestMethod -Method POST -Uri "https://${funchost}.azurewebsites.net/api/webhooks/register?code=${code}&listTitle=${listTitle}&notificationUrl=${notificationUrl}"

# Show this webhook registered on a list
Invoke-RestMethod -Method GET -Uri "https://${funchost}.azurewebsites.net/api/webhooks/show?code=${code}&listTitle=${listTitle}&notificationUrl=${notificationUrl}"

# Remove the webhook from a list
# Step 1: Call the function /webhooks/show to get the webhook id
$webhookId = $(Invoke-RestMethod -Method GET -Uri "https://${funchost}.azurewebsites.net/api/webhooks/show?code=${code}&listTitle=${listTitle}&notificationUrl=${notificationUrl}").Id
# Step 2: Call the function /webhooks/remove and pass the webhook id
Invoke-RestMethod -Method POST -Uri "https://${funchost}.azurewebsites.net/api/webhooks/remove?code=${code}&listTitle=${listTitle}&webhookId=${webhookId}"

Limpar os recursos no Azure

Pode eliminar todos os recursos que este projeto criou no Azure ao executar o comando azd down.

Em alternativa, pode eliminar o grupo de recursos que tem o nome do ambiente azd por predefinição.

Confira também