Create and Publish SharePoint Pages API with the Microsoft Graph PowerShell SDK

In April 2024, Microsoft announced the General availability for the Graph API for SharePoint Pages (also in message center notification MC789609 and Microsoft 365 roadmap item 101166). Despite Microsoft proclaiming that they were thrilled with the new API, I never got around to looking at it, largely because other work got in the way.

Given the period since general availability, it is no surprise that cmdlets for the SharePoint Pages API are available in the Microsoft Graph PowerShell SDK. However, some functionality is missing, and the Get- cmdlet to fetch pages for a site doesn’t work very well. Let’s discuss.

Get SharePoint Pages for a Site

The Get-MgSitePageAsSitePage cmdlet retrieves details of the pages for a site. You’ll need to fetch the site identifier for the target site first. The site identifier is not the site URL. A full site identifier looks something like this:

office365itpros.sharepoint.com,8e0a5589-b91d-496e-a5be-3473a75f2fe2,22d7a59d-d93c-498e-a806-6c9475717c88

If you know the URL for a site, you can compute a form of the site identifier that SharePoint will accept to lookup a site like this:

$Uri = "https://office365itpros.sharepoint.com/sites/BlogsAndProjects"
$SiteId = $Uri.Split('//')[1].split("/")[0] + ":/sites/" + $Uri.Split('//')[1].split("/")[2]

$Site = Get-MgSite -SiteId $SiteId

With the site identifier, you can run Get-MgSitePageAsSitePage. Here’s how to return the set of site pages sorted in date created order:

[array]$Posts = Get-MgSitePageAsSitePage -SiteId $Site.Id -All | Sort-Object {$_.CreatedDateTime -as [datetime]} -Descending

Unfortunately, the cmdlet doesn’t return values for many interesting properties, such as createdByUser. Better results are obtained by using the Graph API request:

$Uri = ("https://graph.microsoft.com/V1.0/sites/{0}/pages/microsoft.graph.sitepage" -f $Site.Id)
$Data = Invoke-MgGraphRequest -Uri $Uri -Method Get
$Pages = $Data.Value

Create a Page (a News Post) with the SharePoint Pages API

The example of creating a SharePoint page features see a large JSON structure composed of many properties. I wanted to simplify things to create a simple News Post page by running the New-MgSitePage cmdlet.

In PowerShell terms, the JSON structure is represented by a set of hash tables and arrays. It’s usually easier to manipulate the contents of hash tables and arrays programmatically, so that’s what I do here to create a page with a news item about a recent Office 365 for IT Pros article featuring the top five SharePoint features shipped in 2024.

$PostTitle = 'Microsoft Describes Top Five SharePoint Features Shipped in 2024'
$PostName = ("News Post {0}.aspx" -f (Get-Date -format 'MMddyyy-HHmm'))
$PostImage = "https://i0.wp.com/office365itpros.com/wp-content/uploads/2025/01/Top-Five-SharePoint-Features.png"
$PostContent = '<p> An interesting article by Mark Kashman, a Microsoft marketing manager, lists his top five SharePoint features shipped in 2024. Four of the five features involve extra cost. Is the trend of Microsoft charging extra for most new features likely to continue in 2025? The need to generate additional revenues from the Microsoft 365 installed base probably means that this is the new normal.</p><a href="https://office365itpros.com/2025/01/07/top-five-sharepoint-features-2024" target="_blank">Read full article</a>'

# The title area
$TitleArea = @{}
$TitleArea.Add("enableGradientEffect", $true)
$TitleArea.Add("imageWebUrl", $PostImage)
$TitleArea.Add("layout", "imageAndTitle")
$TitleArea.Add("showAuthor",$true)
$TitleArea.Add("showPublishedDate", $true)
$TitleArea.Add("showTextBlockAboveTitle", $true)
$TitleArea.Add("textAboveTitle", $PostTitle)
$TitleArea.Add("textAlignment", "center")
$TitleArea.Add("imageSourceType", $null)
$TitleArea.Add.("title", "News Post")

# A news item only needs one web part to publish the content
$WebPart1 = @{}
$WebPart1.Add("id", "6f9230af-2a98-4952-b205-9ede4f9ef548")
$WebPart1.Add("innerHtml", $PostContent)
$WebParts = @($WebPart1)

# The webpart is in a single column
$Column1 = @{}
$Column1.Add("id", "1")
$Column1.Add("width", "12")
$Column1.Add("webparts", $webparts)

$Columns = @($Column1)
$Section1 = @{}
$Section1.Add("layout", "oneColumn") 
$Section1.Add("id", "1")
$Section1.Add("emphasis", "none")
$Section1.Add("columns", $Columns)

$HorizontalSections = @($Section1)
$CanvasLayout = @{}
$CanvasLayout.Add("horizontalSections", $HorizontalSections)

# Bringing all the creation parameters together
$Params = @{}
$Params.Add("@odata.type", "#microsoft.graph.sitePage")
$Params.Add("name", $PostName)
$Params.Add("title", $PostTitle)
$Params.Add("pagelayout", "article")
$Params.Add("showComments", $true)
$Params.Add("showRecommendedPages", $false)
$Params.Add("titlearea", $TitleArea)
$Params.Add("canvasLayout", $CanvasLayout)

$Post = New-MgSitePage -SiteId $site.Id -BodyParameter $Params
If ($Post) { Write-Host ("Post {0} successful" -f $PostTitle) }

Update (Promote) a SharePoint Page to be a News Post

After creating a page, we might need to update it. In this case, I update the page to promote it to be a news post so that it will appear in the News section of the site. I also add a description to appear under the title in the card shown for the item in the News section.

The Update-MgSitePage cmdlet reported an “API not found” error, so I used the Graph API request:

$UpdateBody = ‘{
  "@odata.type": "#microsoft.graph.sitePage",
  "promotionKind": "newsPost",
  "description": "Microsoft Lists Top Five SharePoint Online features shipped in 2024"
}’
$Uri = ("https://graph.microsoft.com/V1.0/sites/{0}/pages/{1}/microsoft.graph.sitePage" -f $Site.Id, $Post.Id)
$Status = Invoke-MgGraphRequest -Uri $Uri -Method Patch -Body $UpdateBody
If ($Status) { Write-Host 'Post Updated'}

Publish the News with the SharePoint Pages API

The news item that’s created is in a draft state. It must be published to make it visible to other site members. I couldn’t find a cmdlet to publish a news item, so I used the Graph API request:

$Uri = ("https://graph.microsoft.com/V1.0/sites/{0}/pages/{1}/microsoft.graph.sitePage/publish" -f $Site.Id, $Post.Id)
Invoke-MgGraphRequest -Uri $Uri -Method Post

If an error isn’t reported, we can assume that SharePoint has published the page. Figure 1 shows how the page appears as a news item. I still have some bugs to figure out because the image I selected isn’t visible. There’s always something to do!

Acceptable SharePoint Pages API but Problematic Cmdlets

As far as I can tell, the SharePoint Pages Graph API works pretty well but the Microsoft Graph PowerShell SDK cmdlets generated from the API isn’t in great shape. I admit that some of the issues might be due to my lack of experience with SharePoint pages, but you do expect to be successful when you follow the documentation. I expect things to improve over time. At least, I hope improvement comes…

Need more help to write and manage PowerShell scripts for Microsoft 365? Get a copy of the Automating Microsoft 365 with PowerShell eBook, available standalone or as part of the Office 365 for IT Pros eBook bundle.