Set-PnPSearchVertical
SYNOPSIS
Required Permissions
- Graph Connector Service (GCS) API
- Site scope: Site Administrator
- Organization scope: Search Administrator or Global Administrator
Updates a Microsoft Search vertical on the currently connected site or at the organization level.
SYNTAX
Properties (Default)
Set-PnPSearchVertical -Identity <String> [-Scope <SearchVerticalScope>] [-DisplayName <String>] [-Enabled <Boolean>] [-QueryTemplate <String>] [-IncludeConnectorResults <Boolean>] [-Verbose] [-Connection <PnPConnection>]
Payload
Set-PnPSearchVertical -Identity <String> [-Scope <SearchVerticalScope>] -Payload <SearchVerticalPayload> [-Verbose] [-Connection <PnPConnection>]
DESCRIPTION
This cmdlet updates a Microsoft Search vertical on the site you are currently connected to, or at the organization (tenant) level when using -Scope Organization. When using individual parameters (Properties parameter set), the cmdlet retrieves the current vertical configuration, merges in your changes, and performs a full update. For complete control, use the -Payload parameter to provide the full payload object. It uses the Graph Connector Service (GCS) API at gcs.office.com.
Warning
This cmdlet uses the Graph Connector Service (GCS) API, which is an internal Microsoft API that is not publicly documented or officially supported. It may change without notice.
Prerequisites
Your Entra app registration must have the ExternalConnection.ReadWrite.All delegated permission from the Graph Connector Service (GCS) API. To add this permission using Azure CLI:
az ad app permission add --id <your-app-id> --api 56c1da01-2129-48f7-9355-af6d59d42766 --api-permissions d44774bd-e26c-43b1-996d-51bb90a9078e=Scope
az ad app permission admin-consent --id <your-app-id>
Note
This cmdlet requires a delegated (interactive) connection. App-only (certificate-based) connections are not supported by the GCS API and will result in a 403 Forbidden error.
EXAMPLES
EXAMPLE 1
Set-PnPSearchVertical -Identity "1610383262385_H0RPZO96M" -DisplayName "Updated Name"
Updates the display name of the specified custom search vertical.
EXAMPLE 2
Set-PnPSearchVertical -Identity "1610383262385_H0RPZO96M" -Enabled $false
Disables the specified search vertical.
EXAMPLE 3
$vertical = Get-PnPSearchVertical -Identity "1610383262385_H0RPZO96M"
$vertical.Payload.DisplayName = "New Name"
$vertical.Payload.State = 1
Set-PnPSearchVertical -Identity "1610383262385_H0RPZO96M" -Payload $vertical.Payload
Retrieves a vertical, modifies the payload directly, and sends the full payload update.
EXAMPLE 4
Set-PnPSearchVertical -Identity "1644258966832_MFDMSIXCG" -DisplayName "Updated Name" -Scope Organization
Updates the display name of an organization-level search vertical.
EXAMPLE 5
# Get the vertical and its payload
$vertical = Get-PnPSearchVertical -Identity "1610383262385_H0RPZO96M"
$payload = $vertical.Payload
# Create a FileType filter/refiner
$refiner = [PnP.PowerShell.Commands.Model.Graph.MicrosoftSearch.SearchVerticalRefiner]@{
Id = "FileType"
DisplayName = "File Type"
State = 1
Category = 0
Layout = [PnP.PowerShell.Commands.Model.Graph.MicrosoftSearch.SearchVerticalRefinerLayout]@{
FieldName = "FileType"
Type = 0
DisplayInterface = 0
ManualEntryEnabled = $false
ShowCount = $true
Values = @()
MappedProperties = @("FileType")
}
}
# Add the refiner to the payload and link it to the first entity
$payload.Refiners.Add($refiner)
$payload.Entities[0].RefinerIds.Add("FileType")
# Push the update
Set-PnPSearchVertical -Identity "1610383262385_H0RPZO96M" -Payload $payload
Adds a "File Type" filter to a custom search vertical. Filters (refiners) allow users to narrow down search results within the vertical. The refiner must be added to both the Refiners list and to the entity's RefinerIds to be active. To discover the exact refiner format used in your environment, inspect an existing vertical that has filters: Get-PnPSearchVertical -Identity "SITEFILES" | Select-Object -ExpandProperty Payload | Select-Object -ExpandProperty Refiners | ConvertTo-Json -Depth 5.
EXAMPLE 6
Get-PnPSearchVertical -Identity "1610383262385_H0RPZO96M" | Set-PnPSearchVertical -DisplayName "Renamed Vertical"
Pipes a vertical object directly into Set-PnPSearchVertical. The LogicalId property binds automatically to -Identity.
PARAMETERS
-Connection
Optional connection to be used by the cmdlet. Retrieve the value for this parameter by either specifying -ReturnConnection on Connect-PnPOnline or by executing Get-PnPConnection.
Type: PnPConnection
Parameter Sets: (All)
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Identity
The logical ID of the search vertical to update. For site scope, built-in IDs include SITEALL, SITEFILES, SITESITES, SITENEWS, and SITEIMAGES. For organization scope, built-in IDs include ALL, FILES, SITES, NEWS, PEOPLE, IMAGES, MESSAGES, and MICROSOFTPOWERBI. Custom verticals have either a user-chosen ID or an auto-generated ID in the format {timestamp}_{randomId}.
Type: String
Parameter Sets: (All)
Required: True
Position: 0
Default value: None
Accept pipeline input: True (ByValue, ByPropertyName)
Accept wildcard characters: False
Aliases: LogicalId
-Scope
Specifies whether to update a site-level or organization-level vertical. Defaults to Site.
Type: SearchVerticalScope
Parameter Sets: (All)
Accepted values: Site, Organization
Required: False
Position: Named
Default value: Site
Accept pipeline input: False
Accept wildcard characters: False
-DisplayName
The new display name for the search vertical.
Type: String
Parameter Sets: Properties
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Enabled
Sets whether the search vertical is enabled ($true) or disabled ($false).
Type: Boolean
Parameter Sets: Properties
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-QueryTemplate
A KQL query template to filter results in the vertical. The {searchTerms} placeholder is automatically prepended if not included. For example, -QueryTemplate "IsDocument:1" becomes {searchTerms} IsDocument:1.
Type: String
Parameter Sets: Properties
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-IncludeConnectorResults
Whether to include connector results in the vertical. This setting can only be used on built-in verticals: SITEALL at site scope or ALL at organization scope. Using it on custom verticals will result in an error.
Type: Boolean
Parameter Sets: Properties
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Payload
A full SearchVerticalPayload object to replace the entire vertical configuration. The payload is sent directly via PUT without merging with the existing configuration.
Type: SearchVerticalPayload
Parameter Sets: Payload
Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Verbose
When provided, additional debug statements will be shown while executing the cmdlet.
Type: SwitchParameter
Parameter Sets: (All)
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False