Compartir a través de

Azure Functions para webhooks de SharePoint mediante azd

Azure Developer CLI (azd) es una herramienta de código abierto que acelera el aprovisionamiento y la implementación de recursos de aplicaciones en Azure.

En este artículo se usa la plantilla pública aplicación de funciones de Azure para webhooks de SharePoint para implementar una aplicación de funciones de Azure que se conecta al inquilino de SharePoint Online, para registrar y administrar webhooks y procesar las notificaciones de SharePoint.

Requisitos previos

Permisos necesarios para aprovisionar los recursos en Azure

La cuenta que ejecuta azd debe tener al menos los siguientes roles para aprovisionar correctamente los recursos:

  • Colaborador de rol de Azure: para crear todos los recursos necesarios
  • Administrador de Access Control basado en roles de Azure: para asignar roles (para acceder a la cuenta de almacenamiento y Application Insights) a la identidad administrada de la aplicación de funciones

Implementación de la aplicación de funciones en Azure

  1. Ejecute azd init desde una carpeta local (raíz) vacía:

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

    Escriba un nombre de entorno, como spofuncs-quickstart cuando se le solicite. En azd, el entorno se usa para mantener un contexto de implementación único para la aplicación.

  2. Abra el archivo infra/main.parameters.json y establezca las variables TenantPrefix y siteRelativePath para que coincidan con el inquilino de SharePoint.

    Revise el artículo Sobre la administración de variables de entorno para administrar las variables de entorno de azd.

  3. Por último, ejecute el comando azd up para compilar la aplicación, aprovisionar los recursos en Azure e implementar el paquete de la aplicación.

Concesión de acceso a la aplicación de funciones a SharePoint Online

La autenticación en SharePoint se realiza mediante DefaultAzureCredential, por lo que la credencial usada depende de si la aplicación de funciones se ejecuta localmente o en Azure.

Si nunca ha oído hablar de DefaultAzureCredential, debe familiarizarse con su concepto haciendo referencia a la sección Uso de DefaultAzureCredential para obtener flexibilidad en cadenas de credenciales en la biblioteca cliente de Azure Identity para JavaScript.

Uso de su identidad administrada

DefaultAzureCredential usará una identidad administrada para autenticarse en SharePoint. Puede ser la identidad administrada existente asignada por el sistema del servicio de aplicación de funciones o una identidad administrada asignada por el usuario.

En este tutorial se supone que se usa la identidad administrada asignada por el sistema.

Concesión del permiso de API de SharePoint Sites.Selected a la identidad administrada

Vaya a la aplicación de funciones en el Azure Portal> seleccione Identidad y anote el identificador de objeto (entidad de seguridad) de la identidad administrada asignada por el sistema.

Nota:

En este tutorial, es d3e8dc41-94f2-4b0f-82ff-ed03c363f0f8.

A continuación, use uno de los scripts siguientes para conceder a esta identidad el permiso Solo aplicación Sites.Selected en la API de SharePoint:

Importante

Los scripts siguientes requieren al menos el permiso AppRoleAssignment.ReadWrite.All delegado (requiere el consentimiento del administrador)

Uso del SDK de PowerShell de 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
Uso de az cli en 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 a la identidad administrada acceso efectivo a un sitio de SharePoint

Vaya a Aplicaciones >empresariales Establezca el filtro Tipo de aplicación en Identidades administradas> seleccione la identidad administrada y anote su identificador de aplicación.

Nota:

En este tutorial, es 3150363e-afbe-421f-9785-9d5404c5ae34.

A continuación, use uno de los scripts siguientes para concederle la administración de permisos de solo aplicación (mínimo necesario para registrar un webhook) en un sitio de SharePoint específico:

Importante

El registro de la aplicación que se usa para ejecutar esos scripts debe tener al menos los permisos siguientes:

  • Permiso delegado Application.ReadWrite.All en el Graph API (requiere consentimiento del administrador)
  • Permiso delegado AllSites.FullControl en la API de SharePoint (requiere el consentimiento del administrador)
Uso de PowerShell de PnP

PowerShell de 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
Uso de la CLI de m365 en Bash

Cli de m365

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

Llamada a la aplicación de funciones

Por motivos de seguridad, al ejecutarse en Azure, la aplicación de funciones requiere una clave de aplicación para pasar el código de parámetro de cadena de consulta. Las claves de aplicación se encuentran en la página Claves de aplicación de Function App Service.

La mayoría de las funciones HTTP toman parámetros opcionales TenantPrefix y siteRelativePath. Si no se especifican, se usan los valores de las variables de entorno de la aplicación.

A continuación se muestra un script de ejemplo en PowerShell para llamar a la aplicación de funciones:

# 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}"

Limpieza de los recursos en Azure

Puede eliminar todos los recursos creados por este proyecto en Azure mediante la ejecución del comando azd down.

Como alternativa, puede eliminar el grupo de recursos, que tiene el nombre del entorno azd de forma predeterminada.

Vea también