Merge pull request #4231 from KoenZomers/ExternalConnection

Adding cmdlets to work with ExternalItems in Microsoft Graph

CHANGELOG.md

@@ -14,6 +14,8 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/).
 - Added support for `WAM` login for Windows OS to support Windows Hello, FIDO keys, Conditional Access policies and other secure authentication modes. 
 - Added `-SkipCertCreation` parameter in `Register-PnPAzureADApp` cmdlet to prevent creation and uploading of certificates in the Entra ID app.
 - Added support to `-ValidateConnection` in managed identity authentication.
+- Added `New-PnPSearchExternalConnection`, `Get-PnPSearchExternalConnection`, `Set-PnPSearchExternalConnection` and `Remove-PnPSearchExternalConnection` cmdlets to manage external connections for Microsoft Search [#4231](https://github.com/pnp/powershell/pull/4231)
+- Added `Get-PnPSearchExternalSchema` and `Set-PnPSearchExternalSchema` cmdlets to manage the schema for external connections for Microsoft Search [#4231](https://github.com/pnp/powershell/pull/4231)
 - Added `OverrideSharingCapability`, `RequestFilesLinkExpirationInDays` & `RequestFilesLinkEnabled` parameters to `Set-PnPTenantSite` cmdlet.
 
 ### Changed
@@ -42,6 +44,7 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/).
 - Giacomo Pozzoni [jackpoz]
 - Nishkalank Bezawada [NishkalankBezawada]
 - Reshmee Auckloo [reshmee011]
+- Koen Zomers [koenzomers]
 
 ## [2.10.0]
 

documentation/Get-PnPSearchExternalConnection.md

@@ -0,0 +1,90 @@
+---
+Module Name: PnP.PowerShell
+schema: 2.0.0
+applicable: SharePoint Online
+online version: https://pnp.github.io/powershell/cmdlets/Get-PnPSearchExternalConnection.html
+external help file: PnP.PowerShell.dll-Help.xml
+title: Get-PnPSearchExternalConnection
+---
+
+# Get-PnPSearchExternalConnection
+
+## SYNOPSIS
+
+**Required Permissions**
+
+  * Microsoft Graph API : One of ExternalConnection.ReadWrite.OwnedBy, ExternalConnection.Read.All,	ExternalConnection.ReadWrite.All
+
+Retrieves all connections to external datasources belonging to Microsoft Search
+
+## SYNTAX
+
+```powershell
+Get-PnPSearchExternalConnection [-Identity <String>] [-Verbose] [-Connection <PnPConnection>] 
+```
+
+## DESCRIPTION
+
+This cmdlet can be used to retrieve all connections to external datasources that are being indexed into Microsoft Search through a custom connector. Use [Set-PnPSearchExternalItem](Set-PnPSearchExternalItem.md) to add items to the index for a connector.
+
+## EXAMPLES
+
+### EXAMPLE 1
+```powershell
+Get-PnPSearchExternalConnection
+```
+
+This will return all connections to external datasources that are being indexed into Microsoft Search that exist within the tenant.
+
+### EXAMPLE 2
+```powershell
+Get-PnPSearchExternalConnection -Identity "pnppowershell"
+```
+
+This will return the connection to the external datasource with the specified identity that is being indexed into Microsoft Search.
+
+## 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](Get-PnPConnection.md).
+
+```yaml
+Type: PnPConnection
+Parameter Sets: (All)
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -Identity
+Unique identifier of the external connection in Microsoft Search. If not provided, all connections will be returned.
+
+```yaml
+Type: String
+Parameter Sets: (All)
+Required: False
+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.
+
+```yaml
+Type: SwitchParameter
+Parameter Sets: (All)
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+## RELATED LINKS
+
+[Microsoft 365 Patterns and Practices](https://aka.ms/m365pnp)

documentation/Get-PnPSearchExternalSchema.md

@@ -0,0 +1,83 @@
+---
+Module Name: PnP.PowerShell
+schema: 2.0.0
+applicable: SharePoint Online
+online version: https://pnp.github.io/powershell/cmdlets/Get-PnPSearchExternalSchema.html
+external help file: PnP.PowerShell.dll-Help.xml
+title: Get-PnPSearchExternalSchema
+---
+
+# Get-PnPSearchExternalSchema
+
+## SYNOPSIS
+
+**Required Permissions**
+
+  * Microsoft Graph API : One of ExternalConnection.ReadWrite.OwnedBy, ExternalConnection.Read.All,	ExternalConnection.ReadWrite.All
+
+Retrieves the schema set on a connection to an external datasource belonging to Microsoft Search
+
+## SYNTAX
+
+```powershell
+Get-PnPSearchExternalSchema -ConnectionId <SearchExternalConnectionPipeBind> [-Verbose] [-Connection <PnPConnection>] 
+```
+
+## DESCRIPTION
+
+This cmdlet can be used to retrieve the current schema set on a connection to an external datasource that is being indexed into Microsoft Search through a custom connector.
+
+## EXAMPLES
+
+### EXAMPLE 1
+```powershell
+Get-PnPSearchExternalSchema -ConnectionId "pnppowershell"
+```
+
+This will return the current schema being used on the external Microsoft Search connection with the specified 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](Get-PnPConnection.md).
+
+```yaml
+Type: PnPConnection
+Parameter Sets: (All)
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -ConnectionId
+Unique identifier or instance of the external connection in Microsoft Search to retrieve the schema for
+
+```yaml
+Type: String
+Parameter Sets: (All)
+Required: True
+Position: Named
+Default value: None
+Accept pipeline input: True
+Accept wildcard characters: False
+```
+
+### -Verbose
+When provided, additional debug statements will be shown while executing the cmdlet.
+
+```yaml
+Type: SwitchParameter
+Parameter Sets: (All)
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+## RELATED LINKS
+
+[Microsoft 365 Patterns and Practices](https://aka.ms/m365pnp)

documentation/New-PnPSearchExternalConnection.md

@@ -0,0 +1,128 @@
+---
+Module Name: PnP.PowerShell
+schema: 2.0.0
+applicable: SharePoint Online
+online version: https://pnp.github.io/powershell/cmdlets/New-PnPSearchExternalConnection.html
+external help file: PnP.PowerShell.dll-Help.xml
+title: New-PnPSearchExternalConnection
+---
+
+# New-PnPSearchExternalConnection
+
+## SYNOPSIS
+
+**Required Permissions**
+
+  * Microsoft Graph API : One of ExternalConnection.ReadWrite.OwnedBy, 	ExternalConnection.ReadWrite.All
+
+Creates a new connection to an external datasource for Microsoft Search
+
+## SYNTAX
+
+```powershell
+New-PnPSearchExternalConnection -Identity <String> -Name <String> -Description <String> [-AuthorizedAppIds <String[]>] [-Verbose] [-Connection <PnPConnection>] 
+```
+
+## DESCRIPTION
+
+This cmdlet can be used to create a new connection to an external datasource that needs to be indexed into Microsoft Search through a custom connector. Use [Set-PnPSearchExternalItem](Set-PnPSearchExternalItem.md) to add items to the index for this connector.
+
+## EXAMPLES
+
+### EXAMPLE 1
+```powershell
+New-PnPSearchExternalConnection -Identity "pnppowershell" -Name "PnP PowerShell" -Description "External content ingested using PnP PowerShell"
+```
+
+This will create a new external connection with the provided name and description. Any application registration with the proper permissions can add items to the index for this connection.
+
+### EXAMPLE 2
+```powershell
+New-PnPSearchExternalConnection -Identity "pnppowershell" -Name "PnP PowerShell" -Description "External content ingested using PnP PowerShell" -AuthorizedAppIds "00000000-0000-0000-0000-000000000000","11111111-1111-1111-1111-111111111111"
+```
+
+This will create a new external connection with the provided name and description. Only the application registrations of which the client Ids have been provided can add items to the index for this connection.
+
+## 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](Get-PnPConnection.md).
+
+```yaml
+Type: PnPConnection
+Parameter Sets: (All)
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -Identity
+Unique identifier of the external connection in Microsoft Search. Must be unique within the tenant. Must be between 3 and 32 characters in length. Must only contain alphanumeric characters. Cannot begin with Microsoft or be one of the following values: None, Directory, Exchange, ExchangeArchive, LinkedIn, Mailbox, OneDriveBusiness, SharePoint, Teams, Yammer, Connectors, TaskFabric, PowerBI, Assistant, TopicEngine, MSFT_All_Connectors.
+
+```yaml
+Type: String
+Parameter Sets: (All)
+Required: True
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -Name
+The display name of the connection to be displayed in the Microsoft 365 admin center. Maximum length of 128 characters.
+
+```yaml
+Type: String
+Parameter Sets: (All)
+Required: True
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -Description
+Description of the connection displayed in the Microsoft 365 admin center
+
+```yaml
+Type: String
+Parameter Sets: (All)
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -AuthorizedAppIds
+The client Ids of the application registrations that are allowed to add items to the index for this connection. If not provided, any application registration with the proper permissions can add items to the index for this connection.
+
+```yaml
+Type: String[]
+Parameter Sets: (All)
+Required: False
+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.
+
+```yaml
+Type: SwitchParameter
+Parameter Sets: (All)
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+## RELATED LINKS
+
+[Microsoft 365 Patterns and Practices](https://aka.ms/m365pnp)