azd を使用した SharePoint Webhook のAzure Functions

Azure Developer CLI (azd) は、Azure でのアプリ リソースのプロビジョニングとデプロイを高速化するオープンソース ツールです。

この記事では、 SharePoint Webhooks パブリック テンプレート用の Azure 関数アプリ を使用して、SharePoint Online テナントに接続する Azure 関数アプリをデプロイし、 Webhook を登録および管理し、SharePoint からの通知を処理します。

前提条件

• Node.js 20
• Azure Functions Core Tools
• Azure Developer CLI (azd)
• SharePoint テナントと同じMicrosoft Entra ID ディレクトリを信頼する Azure サブスクリプション

Azure でリソースをプロビジョニングするために必要なアクセス許可

azd を実行しているアカウントは、リソースを正常にプロビジョニングするために、少なくとも次のロールを持っている必要があります。

• Azure ロール 共同作成者: 必要なすべてのリソースを作成するには
• Azure ロール ロールベースのAccess Control管理者: ロールを (ストレージ アカウントと Application Insights にアクセスするために) 関数アプリのマネージド ID に割り当てるには

関数アプリを Azure にデプロイする

1. 空のローカル (ルート) フォルダーから azd init を実行します。

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

   プロンプトが表示されたら、 spofuncs-quickstart などの環境名を入力します。 azd では、環境を使用してアプリの一意のデプロイ コンテキストを維持します。

2. ファイル infra/メイン.parameters.jsonを開き、SharePoint テナントと一致するようにTenantPrefix変数とsiteRelativePathを設定します。

   azd の環境変数を管理するには、「 環境変数 の管理」の記事を参照してください。

3. 最後に、 azd up コマンドを実行してアプリをビルドし、Azure でリソースをプロビジョニングし、アプリ パッケージをデプロイします。

関数アプリに SharePoint Online へのアクセス権を付与する

SharePoint への認証は DefaultAzureCredentialを使用して行われます。そのため、使用される資格情報は、関数アプリがローカルで実行されるか、Azure で実行されるかによって異なります。

DefaultAzureCredentialについて聞いたことがない場合は、「JavaScript 用 Azure Identity クライアント ライブラリの資格情報チェーンの柔軟性のために DefaultAzureCredential を使用する」セクションを参照して、その概念について理解する必要があります。

マネージド ID の使用

DefaultAzureCredential はマネージド ID を使用して SharePoint に対する認証を行います。 これは、関数アプリ サービスの既存のシステム割り当てマネージド ID またはユーザー割り当てマネージド ID です。

このチュートリアルでは、システム割り当てマネージド ID が使用されていることを前提としています。

SharePoint API アクセス許可 Sites.Selected にマネージド ID を付与する

Azure portalで関数アプリに移動し>[ID] を選択し、システム割り当てマネージド ID のオブジェクト (プリンシパル) ID をメモします。

注:

このチュートリアルでは、 d3e8dc41-94f2-4b0f-82ff-ed03c363f0f8 です。

次に、次のいずれかのスクリプトを使用して、この ID にアプリのみのアクセス許可 Sites.Selected を SharePoint API で付与します。

重要

以下のスクリプトでは、少なくとも委任されたアクセス許可 AppRoleAssignment.ReadWrite.All が必要です (管理者の同意が必要です)

Microsoft Graph PowerShell SDK の使用

# 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

Bash での az cli の使用

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

マネージド ID に SharePoint サイトへの効果的なアクセス権を付与する

[エンタープライズ アプリケーション] に移動し>[アプリケーションの種類] フィルターを [マネージド ID] に設定します>マネージド ID を選択し、そのアプリケーション ID をメモします。

注:

このチュートリアルでは、 3150363e-afbe-421f-9785-9d5404c5ae34 です。

次に、次のいずれかのスクリプトを使用して、特定の SharePoint サイトでアプリのみのアクセス許可 管理 (Webhook を登録するために最低限必要) を付与します。

重要

これらのスクリプトの実行に使用されるアプリの登録には、少なくとも次のアクセス許可が必要です。

• Graph APIの委任されたアクセス許可 Application.ReadWrite.All (管理者の同意が必要)
• SharePoint API での委任されたアクセス許可 AllSites.FullControl (管理者の同意が必要)

PnP PowerShell の使用

PnP PowerShell

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

Bash での m365 cli の使用

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

関数アプリを呼び出す

セキュリティ上の理由から、Azure で実行する場合、関数アプリでは、クエリ文字列パラメーター コードを渡すアプリ キーが必要です。 アプリ キーは、関数アプリ サービスの [ アプリ キー] ページにあります。

ほとんどの HTTP 関数は、省略可能なパラメーター TenantPrefix と siteRelativePathを受け取ります。 指定されていない場合は、アプリの環境変数の値が使用されます。

関数アプリを呼び出す PowerShell のサンプル スクリプトを次に示します。

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

Azure でリソースをクリーンアップする

このプロジェクトが Azure で作成したすべてのリソースを削除するには、 azd down コマンドを実行します。

または、既定で azd 環境の名前を持つリソース グループを削除することもできます。

関連項目

• SharePoint webhook の概要