Added Get-PnPSearchExternalItem (#4375)

* Added implementeion for Get-PnPSearchExternalItem

* Added changelog entry

* Added PR reference

---------

Co-authored-by: Gautam Sheth <[email protected]>

CHANGELOG.md

@@ -21,6 +21,7 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/).
 - Added `-X509KeyStorageFlags` parameter to `Connect-PnPOnline` cmdlet which allows setting of how private keys are to be imported. [#4324](https://github.com/pnp/powershell/pull/4324)
 - Added `-RestrictContentOrgWideSearch` parameter to `Set-PnPSite` which allows for applying the Restricted Content Discoverability (RCD) setting to a site [#4335](https://github.com/pnp/powershell/pull/4335)
 - Added `-LaunchBrowser` parameter to `Register-PnPEntraIDAppForInteractiveLogin` and `Register-PnPEntraIDApp` cmdlets to open browser and continue app registration in the browser. [#4347](https://github.com/pnp/powershell/pull/4347) & [#4348](https://github.com/pnp/powershell/pull/4348)
+- Added `Get-PnPSearchExternalItem` which allows retrieving the current external items for a specific external connection [#4375](https://github.com/pnp/powershell/pull/4375)
 - Added `Remove-PnPSearchExternalItem` which allows for removal of an external item from the Microsoft Search index [#4378](https://github.com/pnp/powershell/pull/4378)
 - Added `-Scopes` parameter to `Get-PnPAccessToken` cmdlet to retrieve access token with specific scopes.
 

documentation/Get-PnPSearchExternalItem.md

@@ -0,0 +1,105 @@
+---
+Module Name: PnP.PowerShell
+schema: 2.0.0
+applicable: SharePoint Online
+online version: https://pnp.github.io/powershell/cmdlets/Get-PnPSearchExternalItem.html
+external help file: PnP.PowerShell.dll-Help.xml
+title: Get-PnPSearchExternalItem
+---
+
+# Get-PnPSearchExternalItem
+
+## SYNOPSIS
+
+**Required Permissions**
+
+  * Microsoft Graph API: One of ExternalItem.ReadWrite.OwnedBy, ExternalItem.Read.All, ExternalItem.ReadWrite.All under a delegated context. Application context is not supported.
+
+Returns the external items indexed for a specific connector in Microsoft Search
+
+## SYNTAX
+
+```powershell
+Get-PnPSearchExternalItem -ConnectionId <SearchExternalConnectionPipeBind> [-Identity <String>] [-Verbose] [-Connection <PnPConnection>] 
+```
+
+## DESCRIPTION
+
+This cmdlet can be used to retrieve a list of indexed external items for a specific Microsoft Search external connector. The cmdlet will return all indexed external items for the specified connector. If you want to retrieve a specific external item, you can use the Identity parameter to specify the unique identifier of the external item. It uses a Microsoft Graph query in the background to retrieve the external items. This is why it will be unable to return the Access Control Lists (ACLs) information in the external items and the properties to contain more properties than you ingested yourself.
+
+It is only possible to run this cmdlet under a delegated context, application context is not supported by the Microsoft Graph search API endpoint for this type of query.
+
+## EXAMPLES
+
+### EXAMPLE 1
+```powershell
+Get-PnPSearchExternalItem -ConnectionId "pnppowershell" -ItemId "12345"
+```
+
+This will return the external item with the unique identifier "12345" for the custom connector with the Connection ID "pnppowershell".
+
+### EXAMPLE 2
+```powershell
+Get-PnPSearchExternalItem -ConnectionId "pnppowershell"
+```
+
+This will return all external items for the custom connector with the Connection ID "pnppowershell".
+
+## 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.
+
+```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 item in Microsoft Search. You can provide any identifier you want to retrieve or check for a specific item in the index. If you omit it, all external items for the specified connector will be returned.
+
+```yaml
+Type: String
+Parameter Sets: (All)
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -ConnectionId
+The Connection ID or connection instance of the custom connector to use. This is the ID that was entered when registering the custom connector and will indicate for which custom connector the external items will be returned from the Microsoft Search index.
+
+```yaml
+Type: SearchExternalConnectionPipeBind
+Parameter Sets: (All)
+Required: True
+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)
+[Microsoft Graph documentation](https://learn.microsoft.com/graph/search-concept-custom-types#example-1-retrieve-items-using-azure-sql-built-in-connector)

resources/PnP.PowerShell.Format.ps1xml

@@ -3016,5 +3016,35 @@
         </TableRowEntries>
       </TableControl>
     </View>
+    <View>
+      <Name>ExternalItem</Name>
+      <ViewSelectedBy>
+        <TypeName>PnP.PowerShell.Commands.Model.Graph.MicrosoftSearch.ExternalItem</TypeName>
+      </ViewSelectedBy>
+      <TableControl>
+        <TableHeaders>
+          <TableColumnHeader>
+            <Label>Id</Label>
+            <Alignment>left</Alignment>
+          </TableColumnHeader>
+          <TableColumnHeader>
+            <Label>Content</Label>
+            <Alignment>left</Alignment>
+          </TableColumnHeader>
+        </TableHeaders>
+        <TableRowEntries>
+          <TableRowEntry>
+            <TableColumnItems>
+              <TableColumnItem>
+                <PropertyName>Id</PropertyName>
+              </TableColumnItem>
+              <TableColumnItem>
+                <ScriptBlock>$_.Content.Value</ScriptBlock>
+              </TableColumnItem>
+            </TableColumnItems>
+          </TableRowEntry>
+        </TableRowEntries>
+      </TableControl>
+    </View>    
   </ViewDefinitions>
 </Configuration>

src/Commands/Base/InvokeQuery.cs

@@ -1,7 +1,6 @@
 using System.Management.Automation;
 using Microsoft.SharePoint.Client;
 
-
 namespace PnP.PowerShell.Commands.Base
 {
     [Cmdlet(VerbsLifecycle.Invoke, "PnPQuery")]

src/Commands/Model/Graph/MicrosoftSearch/SearchHit.cs

@@ -0,0 +1,40 @@
+using System.Text.Json.Serialization;
+
+namespace PnP.PowerShell.Commands.Model.Graph.MicrosoftSearch;
+
+/// <summary>
+/// Defines a hit in a search result from Microsoft Graph
+/// </summary>
+/// <seealso cref="https://learn.microsoft.com/en-us/graph/api/search-query?view=graph-rest-1.0&tabs=http" />
+public class SearchHit
+{
+    /// <summary>
+    /// Unique identifier of the search result
+    /// </summary>
+    [JsonPropertyName("hitId")]
+    public string Id { get; set; }
+
+    /// <summary>
+    /// Name of the source of the content
+    /// </summary>
+    [JsonPropertyName("contentSource")]
+    public string ContentSource { get; set; }
+
+    /// <summary>
+    /// The rank of the search result
+    /// </summary>
+    [JsonPropertyName("rank")]
+    public short Rank { get; set; }
+
+    /// <summary>
+    /// A summary of the search result
+    /// </summary>
+    [JsonPropertyName("summary")]
+    public string Summary { get; set; }
+
+    /// <summary>
+    /// The resource properties of the search result
+    /// </summary>
+    [JsonPropertyName("resource")]
+    public SearchResultResource Resource { get; set; }
+}

src/Commands/Model/Graph/MicrosoftSearch/SearchHitsContainer.cs

@@ -0,0 +1,17 @@
+using System.Collections.Generic;
+using System.Text.Json.Serialization;
+
+namespace PnP.PowerShell.Commands.Model.Graph.MicrosoftSearch;
+
+/// <summary>
+/// Defines a hitcontainer in a search result from Microsoft Graph
+/// </summary>
+/// <seealso cref="https://learn.microsoft.com/en-us/graph/api/search-query?view=graph-rest-1.0&tabs=http" />
+public class SearchHitsContainer
+{
+    /// <summary>
+    /// Collection with search hits
+    /// </summary>
+    [JsonPropertyName("hits")]
+    public List<SearchHit> Hits { get; set; }
+}

src/Commands/Model/Graph/MicrosoftSearch/SearchRequest.cs

@@ -0,0 +1,28 @@
+using System.Collections.Generic;
+using System.Text.Json.Serialization;
+
+namespace PnP.PowerShell.Commands.Model.Graph.MicrosoftSearch;
+
+/// <summary>
+/// Defines the body for a single search request to Microsoft Graph
+/// </summary>
+public class SearchRequest
+{
+    /// <summary>
+    /// The types of entities to query, i.e. externalItem
+    /// </summary>
+    [JsonPropertyName("entityTypes")]
+    public List<string> EntityTypes { get; set; }
+
+    /// <summary>
+    /// The names of the content sources to query, i.e. /external/connections/<externalconnectionname>
+    /// </summary>
+    [JsonPropertyName("contentSources")]
+    public List<string> ContentSources { get; set; }
+
+    /// <summary>
+    /// The search query to execute
+    /// </summary>
+    [JsonPropertyName("query")]
+    public SearchRequestQuery Query { get; set; }
+}

src/Commands/Model/Graph/MicrosoftSearch/SearchRequestQuery.cs

@@ -0,0 +1,15 @@
+using System.Text.Json.Serialization;
+
+namespace PnP.PowerShell.Commands.Model.Graph.MicrosoftSearch;
+
+/// <summary>
+/// Defines the query for  request to Microsoft Graph
+/// </summary>
+public class SearchRequestQuery
+{
+    /// <summary>
+    /// The search query to execute
+    /// </summary>
+    [JsonPropertyName("queryString")]
+    public string QueryString { get; set; }
+}

src/Commands/Model/Graph/MicrosoftSearch/SearchRequests.cs

@@ -0,0 +1,16 @@
+using System.Collections.Generic;
+using System.Text.Json.Serialization;
+
+namespace PnP.PowerShell.Commands.Model.Graph.MicrosoftSearch;
+
+/// <summary>
+/// Defines the body for a collection of search requests to Microsoft Graph
+/// </summary>
+public class SearchRequests
+{
+    /// <summary>
+    /// Collection of search request items
+    /// </summary>
+    [JsonPropertyName("requests")]
+    public List<SearchRequest> Requests { get; set; }
+}

src/Commands/Model/Graph/MicrosoftSearch/SearchResult.cs

@@ -0,0 +1,17 @@
+using System.Collections.Generic;
+using System.Text.Json.Serialization;
+
+namespace PnP.PowerShell.Commands.Model.Graph.MicrosoftSearch;
+
+/// <summary>
+/// Defines a search result from Microsoft Graph
+/// </summary>
+/// <seealso cref="https://learn.microsoft.com/en-us/graph/api/search-query?view=graph-rest-1.0&tabs=http" />
+public class SearchResult
+{
+    /// <summary>
+    /// Unique identifier of the search result
+    /// </summary>
+    [JsonPropertyName("hitsContainers")]
+    public List<SearchHitsContainer> HitsContainers { get; set; }
+}

src/Commands/Model/Graph/MicrosoftSearch/SearchResultResource.cs

@@ -0,0 +1,17 @@
+using System.Collections.Generic;
+using System.Text.Json.Serialization;
+
+namespace PnP.PowerShell.Commands.Model.Graph.MicrosoftSearch;
+
+/// <summary>
+/// Defines the resources within a search result from Microsoft Graph
+/// </summary>
+/// <seealso cref="https://learn.microsoft.com/en-us/graph/api/search-query?view=graph-rest-1.0&tabs=http" />
+public class SearchResultResource
+{
+    /// <summary>
+    /// The properties of the search result
+    /// </summary>
+    [JsonPropertyName("properties")]
+    public Dictionary<string, object> Properties { get; set; }
+}

src/Commands/Search/GetSearchExternalConnection.cs

@@ -6,7 +6,9 @@
 namespace PnP.PowerShell.Commands.Search
 {
     [Cmdlet(VerbsCommon.Get, "PnPSearchExternalConnection")]
-    [RequiredApiApplicationPermissions("graph/ExternalConnection.ReadWrite.OwnedBy")]
+    [RequiredApiDelegatedOrApplicationPermissions("graph/ExternalConnection.ReadWrite.OwnedBy")]
+    [RequiredApiDelegatedOrApplicationPermissions("graph/ExternalConnection.Read.All")]
+    [RequiredApiDelegatedOrApplicationPermissions("graph/ExternalConnection.ReadWrite.OwnedBy")]
     [OutputType(typeof(IEnumerable<Model.Graph.MicrosoftSearch.ExternalConnection>))]
     [OutputType(typeof(Model.Graph.MicrosoftSearch.ExternalConnection))]
     public class GetSearchExternalConnection : PnPGraphCmdlet